Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Plan: Paperclips Showcase

Overview

Expand the clean-room Paperclips client/server showcase. Authoritative Paperclips server owns generated content, game state, regular timer cadence, proof controls, unlock checks, command discovery, structured plain-status snapshots, project lists, and – in this plan – broader structured state/events, command facets behind server-issued capabilities, capability transfer/revocation ergonomics, and the future web-shell client path. Terminal and web clients should consume server-issued capabilities instead of reimplementing game rules.

Long-form decomposition: docs/backlog/paperclips.md. Clean-room mechanics baseline: docs/research/paperclips-clean-room-functional-spec.md. Demo description: docs/demos/paperclips.md. This plan must not copy source-game implementation identifiers, text, assets, generated tables, exact balance, CSS, or code.

Conflict Surface

Owned by this plan:

  • demos/paperclips/ (the binary crate hosting both the authoritative server roles and the terminal client) and any new demos/paperclips-* crates introduced by this plan
  • demos/paperclips-content/ (content crate, including demos/paperclips-content/content/paperclips.cue)
  • tools/paperclips-content-gen/ only when the generated-content shape changes
  • system-paperclips.cue and the matching make run-paperclips target (Makefile recipe lines for the Paperclips demo only)
  • schema/paperclips-content.capnp and any new Paperclips-specific schema (demo-specific, not part of the shared serial surface)
  • Paperclips-shared types in schema/capos.capnp (PaperclipsGame, PaperclipsStatusSnapshot, PaperclipsCommandSpec, PaperclipsCommandList, related project/event types) when the iteration extends them. These edits use the shared serial surface – see docs/plans/README.md Concurrency Notes; only one plan at a time may change schema/capos.capnp, and make generated-code-check must pass before the next plan picks it up.
  • docs/demos/paperclips.md, docs/backlog/paperclips.md

Do not touch from this plan:

  • Kernel-side cap tables outside Paperclips schema additions
  • tools/remote-session-client/ (owned by remote-session plan)
  • demos/adventure-* (owned by Aurelian plan)
  • Repo-root system-*.cue migration-to-defaults work (owned by system-config slice 3 plan), except direct edits inside system-paperclips.cue for new Paperclips services

Validation Commands

  • make fmt-check
  • make generated-code-check
  • cargo build --features qemu
  • cargo test-config
  • cargo test-lib
  • cargo build-demos-capos
  • make run-paperclips

Success Criteria

A reviewed showcase iteration ships when the focused QEMU proof keeps exercising one-at-a-time manual production, the autonomous and cosmic phase transitions, structured help/projects/status/status --json, and a new slice from the task list below. WORKPLAN.md’s Paperclips ad-hoc note stays in sync; record commit hashes there.

Task 1: Structured state and event surface beyond status snapshot

  • Extend the server-side status snapshot with structured event/log entries for production cadence, project completion, autonomous-phase crossings, and proof transitions. Keep status --json proof-only and server-gated; render plain-text events for normal terminal sessions.
  • Cover the new fields with paperclips-content-test host tests and at least one focused QEMU assertion in make run-paperclips.
  • Update docs/demos/paperclips.md and the proposal (if any) to describe the structured event channel.

Task 2: Command facets behind server-issued capabilities

  • Move the unlocked-command facets that today live in the terminal client behind server-issued capabilities. Each facet (production, market, projects, autonomous, cosmic, completion) should be a typed cap the server hands the client only after the corresponding unlock.
  • Refactor the terminal client so it discovers facets through the cap surface rather than text. Keep raw text command execution for backwards compatibility, but route it through the facet caps.
  • Add a focused proof that revoking a facet stops further command use from that client without crashing the server or the client.

Task 3: Capability transfer and revocation ergonomics

  • Add a proof slice that demonstrates server-driven facet revocation (e.g. when the cosmic phase ends or a proof control closes) without reaching for kernel-level revoke.
  • Show the terminal client surfacing a clean error when a facet is revoked mid-command, and the server preserving game state across the revocation.
  • Document the resulting transfer/revocation contract in docs/demos/paperclips.md so later web-shell clients implement the same shape.

Task 4: Web-shell client preflight slice

  • Sketch a remote-session DTO surface for Paperclips (status snapshot, project list, command list, single-command execution) that the future remote/web client will call. Do not yet wire the real remote-session client; this is a contract slice.
  • Add a host-side test that drives the server through the DTO surface and matches paperclips-client rendering for at least the manual, autonomous, and cosmic phases.
  • Note the wiring follow-up in docs/backlog/paperclips.md and link it from docs/backlog/remote-session-capset-client.md so the remote-session plan picks it up cleanly.

Task 5: Update doc and changelog records

  • Update docs/demos/paperclips.md with the new structured event, facet, and DTO contract.
  • Add a docs/changelog.md entry referencing the commit that lands the showcase iteration.
  • Refresh WORKPLAN.md’s Paperclips ad-hoc bullet to reflect what is now landed and what is still planned.