# Shared-Service Demo Backlog

Detailed decompositions and design notes for chat, adventure, and federated
service demos. `WORKPLAN.md` links here but should not inline these subtasks.

## Design Notes

Multi-process userspace applications exercise the resident-server plus
shell-spawned-client pattern on top of the completed boot-to-shell, `Endpoint`,
`ProcessSpawner`, and legacy endpoint receiver-metadata substrate. Chat lands
first as the simpler base and forcing function for federation; the text
adventure reuses the same harness with NPCs-as-processes. Reuse is extracted
after the second service lands, not speculatively. Federation is blocked on
network transparency.

The authoritative migration gates for removing caller-selected shared-service
identity live in `docs/backlog/service-object-identity-migration.md`. This file
only records chat/adventure application follow-ups that must be updated when
those gates land.

The first slice keeps chat and adventure usable as ordinary spawned commands
over generic `Endpoint` grants plus explicit `StdIO` for terminal I/O. The
shared `demos/capos-chat` crate owns typed request/response DTOs for the
prototype bridge, while the top-level `shell/` crate owns generic process
commands such as `spawn`, blocking `run`, `wait`, and grant parsing. The
`StdIO` clients are a smoke harness and compatibility path, not the target
capOS-native command boundary; native interactive apps should later expose
command surfaces as described in
`docs/proposals/interactive-command-surface-proposal.md`.

Room-scoped MUD speech (`say`, `tell`) maps naturally onto chat channels, so
adventure should consume the chat service rather than reimplementing pub/sub.
Keep the `Adventure` schema for world state and verbs that are not speech;
route `say`/`tell`/NPC dialog through `Chat` subscriptions scoped to room
channels.

## Chat Follow-Ups

Completed context:
- [x] MVP `Chat` endpoint interface, legacy receiver selectors, and event
      variants.
- [x] Public chat lobby stays `#lobby`; adventure room speech uses
      hierarchical `#room/<world>/<room>` channels, with the demo world under
      `#room/demo/<room>`.
- [x] Client `poll()` is used for MVP event delivery; foreground client drains
      queued events before prompting again.
- [x] `demos/chat-server/` scaffold with capos-rt entry and bounded
      per-channel history ring.
- [x] `join`/`leave`/`send`/`who` plus fan-out for the legacy endpoint-metadata
      MVP.
- [x] `demos/chat-client/` over explicit capos-rt `StdIO` plus chat endpoint
      client.
- [x] Chat stays out of native shell builtins and runs as a spawned command
      with `stdio: client @stdio` and `chat: client @chat` grants.
- [x] `make run-chat` smoke: shell-spawned client sends a line through the
      resident service, resident bot observes it and replies, foreground
      client prints the reply.

Remaining:
- [ ] Migrate chat from legacy endpoint receiver-metadata identity to service object
      capabilities. Introduce a `ChatRoot` or equivalent factory that returns
      `ChatParticipant` caps; participant state, inboxes, history replay, and
      audit subject binding should key off the service-created object, not a
      caller-selected selector.
- [ ] Add per-principal state keyed by `UserSession.info`, admin-only verbs,
      typed denial results, and redacted audit records per join/leave/send.
- [ ] Defer a distinct `Subscription` interface until federation or native
      command surfaces need a separate event authority object.

## Adventure Follow-Ups

Completed context:
- [x] MVP `Adventure` interface for non-speech verbs and room views.
- [x] Legacy receiver-selector layout distinguishes player from NPC authority
      on both a future `PlayerSession` and room chat channels. MVP manifests
      reserve low selectors for shell players (`chat=1`, `adventure=2`) and
      service/NPC authority at `100+`.
- [x] Rooms map to chat channels as `#room/<world>/<room-id>`, with the demo
      world under `demo`.
- [x] `demos/adventure-server/` scaffold with a small room graph, typed world
      verbs, per-selector player state, and chat channel metadata.
- [x] `demos/adventure-client/` as a spawned command over explicit `StdIO`,
      `adventure`, and `chat` endpoint grants.
- [x] Adventure `StdIO` parser remains prototype-scoped and should later be
      replaced with a command surface exposing nested paths such as `go`,
      `take`, `drop`, `inventory`, `say`, and `chat join`.
- [x] `make run-adventure` smoke: scripted player moves rooms, completes one
      state-changing world action, and exits cleanly through the shell-spawned
      client.
- [x] NPC-as-process fleet: one process per NPC, each holding manifest-issued
      legacy player/adventure receiver metadata plus chat endpoint authority
      for room dialog.
- [x] At least two concrete NPCs ship with liveness asserted in the adventure
      smoke.
- [x] NPC process exit surfaces as `ProcessHandle` completion on the server
      side.

Game-depth follow-up:
- [x] Decompose the Aurelian Frontier proposal through
      `docs/backlog/aurelian-frontier.md` rather than expanding this shared
      service harness backlog with content, combat, economy, and multiplayer
      details.

Object-capability follow-up:
- [ ] Migrate adventure player and NPC authorities from legacy
      receiver-selected endpoint clients to service object caps such as
      `AdventurePlayer` and `AdventureNpc`. Room speech should cross into chat
      through migrated chat object caps such as `ChatParticipant`; chat must
      not depend on adventure-specific interfaces.

## Shared Harness Extraction

Completed context:
- [x] Extract duplicated legacy endpoint receive/release/return loop used by
      chat and adventure resident services into `demos/service-common/`.
- [x] Defer a shared bounded event queue until chat history/inbox and
      adventure/NPC event needs converge. Current evidence: only
      `chat-server` has bounded history/inbox queues; adventure room state and
      NPC polling do not expose a matching queue abstraction.
- [x] Extract bot/NPC client scaffolding shared by chat bot and adventure NPC
      processes.
- [x] Extract shared chat actor polling loop used by chat-bot, wanderer, and
      shopkeeper while keeping each actor's cap validation, join/greeting,
      reply text, and exit logging local.
- [x] Extract shared chat actor bootstrap for required `console` and `chat`
      caps plus the single-owner ring client, while preserving actor-specific
      failure text and behavior setup.

## Federated Chat Milestone

Blocked on network transparency.

Extend chat across hosts once cap transport crosses machines. This integration
test exercises networking, TLS, OIDC, key-management, and audit proposals
together.

- [ ] Define cross-host addressing (`@user@host`, `#room@host`) and record it
      in schema.
- [ ] First cross-VM channel smoke: two QEMU instances, one message delivered
      across TLS.
- [ ] Federated audit: per-host records plus signed cross-host event trail.