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

Paperclips Terminal Demo Backlog

This backlog tracks future expansion of the clean-room Paperclips terminal demo described in Paperclips Terminal Demo. It is not the current selected milestone.

The clean-room mechanics baseline is recorded in docs/research/paperclips-clean-room-functional-spec.md. Use that note as the planning source for gameplay behavior. Do not copy source-game implementation identifiers, text, assets, generated tables, exact balance, CSS, or code when expanding content.

Current runnable status: the focused Paperclips manifest now boots an authoritative Paperclips server and a terminal client. The server owns generated content, resources, GameState, proof-command gating, unlock checks, and game-rule mutation. The server owns regular timer cadence and exposes the current command list and unlocked projects as structured data so server-mode terminal clients render plain help and projects from server state. Server-mode terminal clients also render plain status from the server’s PaperclipsStatusSnapshot, while status --json remains proof-only and server-gated. Follow-up work should move unlocked command facets behind server-issued capabilities so later terminal and web clients do not reimplement rules.

Design grounding for the client/server, structured command-list, structured plain-status, and structured project-list slices: docs/demos/paperclips.md, docs/research/paperclips-clean-room-functional-spec.md, docs/architecture/ipc-endpoints.md, docs/architecture/capability-ring.md, docs/proposals/session-bound-invocation-context-proposal.md, and docs/proposals/system-info-proposal.md. No other research note applies directly because this slice uses the existing endpoint/ring transport and does not introduce a new external OS/runtime protocol.

Current Baseline

Implemented:

  • Clean-room terminal implementation inspired by the public Paperclips premise without copying original game code or assets.
  • make run-paperclips boots a focused manifest, launches Paperclips server services plus a terminal client through the shell, grants explicit StdIO plus a PaperclipsGame endpoint to the terminal client, grants Timer to the server, drives the first production loop, proves project chains and proof gating, and exits cleanly.
  • In the focused manifest, game state is local to the Paperclips server process and disappears when that server exits. Direct standalone launches without a game endpoint retain the older in-process fallback.
  • The default system.cue manifest still advertises the standalone fallback launch with run "paperclips" with { stdio: client @stdio, timer: @timer } because it does not start the Paperclips server. The structured command-list, status-snapshot, and project-list methods only change server-mode client rendering, so no MOTD/default-manifest text change is needed for this slice.
  • The pure rules layer lives in demos/paperclips-content and is host-testable separately from the terminal adapter.
  • Paperclips content is authored in CUE, converted through pinned mkmanifest cue-to-capnp into the Paperclips-specific Cap’n Proto schema, checked in as generated Rust bytes, then deserialized through typed Paperclips schema bindings at runtime.
  • Core game balance and content live in CUE: initial state, purchases, projects, unlock effects, production rates, millisecond intervals, currency formatting, price limits, trust thresholds, and phase transition values.
  • Manual make produces one clip only; counted manual make requests are rejected.
  • Automation advances from the Timer capability in real time, while run <ms> is reserved for focused proof launches with an explicit proof_accelerator cap.
  • Opening business loop has dynamic demand plus CUE-owned raw-material bundle pricing, slower market updates, purchase pressure, and generated content freshness checks.
  • Business-phase explicit sales are time-aware: successful sales start a CUE-owned cooldown, repeated immediate sell <n> commands are refused without mutating state, and Timer/proof time advancement clears the cooldown.
  • Focused QEMU transcript now demonstrates manual work and explicit sales funding Autoclipper License, one repeatable economic choice, one wire purchase, and completion of precision-rollers with a visible autoclipper-count effect.
  • Focused QEMU transcript now also demonstrates representative Stage 1 refusal output: an early locked buy autoclipper, an insufficient-funds buy wire 1000, pending manual work, bulk manual rejection, and locked project survey-drones, plus a high-price sell 1 demand refusal and a sell 2 requested-count sale capped by one available clip, plus a no-wire manual production refusal after automation drains the available wire.
  • Focused QEMU transcript now proves a Stage 2 project chain after repeatable marketing investment and scaled business-phase production: autoclipper-license, precision-rollers, design-search, forecast-engine, and survey-drones, ending at == autonomous phase ==.
  • Stage 3 autonomous rules now use CUE-owned millisecond intervals for drone local-matter conversion, factory wire consumption, probe cosmic matter conversion, and probe replication caps. Host tests cover the resource caps, scaling projects, cosmic replication, completion gating, and validation for the new rule fields.
  • Focused QEMU transcript now continues after == autonomous phase == to complete material-harvesters and foundry-lines, run milliseconds, and assert visible drone/factory counts plus local-matter conversion and additional clip production.
  • Focused QEMU transcript now closes the representative late-game proof: after the autonomous/factory proof it completes mesh-coordination, transitions through seed-probes into == cosmic phase ==, asserts visible probe replication plus cosmic-matter conversion and clip production, then leaves final-conversion locked. make run-paperclips is a representative transcript, not an exhaustive playthrough.
  • Public player launches no longer expose fast-forward. run <ms> is hidden from normal help output and refused unless the launched process receives the explicit proof_accelerator capability used by the focused QEMU proof manifest. The shell rejects attempts to mint that authority by renaming an ordinary @timer grant.
  • Player-facing project ids, labels, title text, completion text, and Strategy resource wording have been renamed away from distinctive source-game terms.
  • Active schema, CUE content, Rust rules, generated-content guardrails, and focused smoke assertions use clean-room Strategy internals rather than source-game resource identifiers.
  • Purchase parsing treats omitted counts as one and rejects explicit zero counts without mutating game state.

Known limits:

  • There is no save/load path; process exit discards game state.
  • The focused QEMU proof stops at the cosmic production milestone. It does not prove a compact full win; host coverage checks that the final conversion cost exceeds a generous one-hour normal-play creativity upper bound.

Clean-Room Gameplay Stages

Stage 1, opening business loop:

  • Add host rules tests for manual production pacing, wire depletion, explicit sales, price-sensitive demand, marketing/demand investment, and automation intervals.
  • Extend the focused transcript so existing early progression shows manual work, one economic decision, one automation purchase, and one project unlock without copying external balance values.
  • Keep representative refusal output legible in the focused QEMU transcript for missing funds, pending manual work, bulk manual production, locked purchases, and locked projects.
  • Add focused transcript cases for missing wire and demand/sale refusals. The QEMU proof now asserts No wire available. and No demand at current price. without changing game balance.
  • Add any remaining Stage 1 sale-limit cases that need end-to-end transcript proof. The QEMU proof now asserts the unique sell 2 window starts with one available clip, ends with zero available clips, and increments Sold from 1 to 2.

Stage 2, data-driven project chain:

  • Expand original CUE project content around generic effects: production multiplier/resource grant, demand policy change, compute-resource generation, strategy resource unlock, capacity grant, and stage transition. Generated CUE content now covers production/resource grants, public-demand grants, operations grants, Strategy unlock/resource grants, processor/memory capacity grants, and stage transitions. Direct trust grants remain unsupported because available trust is recomputed from clip milestones minus spent trust.
  • Replace per-project Rust effect variants with one generic CUE-backed loader/evaluator. Project completion now applies generic production and resource grants, public-demand grants, compute and strategy-resource grants, design/Strategy unlock flags, capacity grants through processors/memory, and one-step stage transitions without matching gameplay on project ids or effect kinds. Direct trust grants remain unsupported because available trust is recomputed from clip-count milestones and trust spent; adding a trust field would be misleading without changing that invariant. Generated-content tests now verify the checked-in CUE payload exercises every currently supported generic category that fits the model.
  • Add current-model validation for project graph bounds before adding more content. Host tests now reject invalid/empty ids, duplicate ids, too many projects for the completion bitset, zero-cost projects, no-op or zero grant effects, out-of-stage effects, stage-transition regressions, and missing transition paths from business to autonomous, cosmic, and complete.
  • Add explicit prerequisite and cyclic unlock-chain validation after the project schema grows named prerequisite/unlock edges. Project now carries data-only named prerequisites from CUE through the typed schema; generated content records the intended business, autonomous, cosmic, and completion unlock chain; runtime availability requires completed prerequisites in addition to stage and cost gates; and host validation rejects missing, malformed, self-referential, duplicate, and cyclic prerequisite edges.
  • Add focused smoke coverage for at least one project unlock chain after repeatable demand investment, including a phase transition out of the business phase.

Stage 3, autonomous and completion mechanics:

  • Model later-stage autonomous production with independently authored labels and bounded rules for resource conversion, factory/drone-style scaling, exploration or replication capacity, and completion progress.
  • Add host tests for stage transition predicates, autonomous production cadence, trust/capacity limits, and the completion condition.
  • Keep QEMU coverage representative rather than exhaustive: prove one transition and one timer-driven later-stage action, then rely on host rules tests for full playthrough cases. The transcript now covers one autonomous timer-driven conversion, one cosmic transition/probe interval, and locked completion-stage availability without scripting every late-game purchase.
  • Split proof acceleration from player gameplay. Normal interactive Paperclips sessions should advance only from the granted Timer capability; run <ms> should either be removed from the player-visible command set or gated behind an explicit harness-only authority that normal shell users cannot mint accidentally. help and docs should stop presenting fast-forward as a regular player command. Implemented by requiring the proof_accelerator cap for terminal fast-forward and by proving the normal launch refusal before the accelerated QEMU proof path.
  • Rebalance the completion path after fast-forward is no longer public. A normal player should not be able to reach == complete phase == within one real-time hour. Keep the smoke proof representative by stopping at selected milestones or by using a clearly test-only acceleration path, rather than shrinking late-game matter and project costs until a full win fits in the QEMU transcript. Implemented by increasing seed-probes cosmic matter/wire scale, raising final-conversion clip and creativity costs, adding host coverage for the one-hour creativity bound, and changing the focused QEMU proof to stop after cosmic probe replication/production with final-conversion still locked.
  • Add coverage for the gameplay/test-mode split: host rules should still test bounded millisecond advancement directly, but the terminal adapter should prove that normal player input cannot invoke fast-forward. If a harness-only accelerator remains, the focused QEMU proof must demonstrate that it is tied to an explicit proof capability or proof manifest, not ambient player authority. The focused QEMU proof first launches Paperclips with StdIO plus the normal PaperclipsGame endpoint, asserts run <ms> is refused, asserts a forged proof_accelerator: @timer grant is rejected, then relaunches against the proof server endpoint with proof_accelerator for the accelerated transcript.
  • Make business-phase sales time-aware. Repeated immediate sell <n> commands should not bypass demand cadence; model a replenishing demand budget, outstanding orders, or a sell cooldown backed by Timer advancement, and keep host/QEMU coverage for sale-limit refusals. Implemented with a CUE-owned sale cooldown and QEMU coverage for the immediate repeat-sale refusal.
  • Tighten clean-room naming. Replace player-facing names and text that mirror the source game’s title or distinctive project labels with independently authored names while preserving the generic paperclip maximizer premise.

Stage 4, persistence and assertions:

  • Add a compact status --json or equivalent machine-readable command only if future smoke tests need stronger assertions than the human transcript. status --json now emits one deterministic compact JSON object with numeric game-state fields, and the focused QEMU proof asserts a late-game machine-readable status line without dropping the human transcript checks.

Blocked on platform persistence:

  • Add save/load or restart-resume behavior after capOS has a durable user storage path appropriate for spawned demos.
  • Keep saved state scoped to this child process or an explicitly designed storage capability; do not introduce ambient filesystem or service state.

Schema-Aware Content Migration

Completed:

  • Defined schema/paperclips-content.capnp as a bounded data-only schema for initial state, rules, purchases, trust milestones, projects, costs, and project effects. It contains no live capOS capabilities or interface objects.
  • Kept demos/paperclips-content/content/paperclips.cue as the authoring source, now matching the PaperclipsContent schema root directly.
  • Converted generated content with pinned tools through mkmanifest cue-to-capnp, then rendered checked-in aligned Rust bytes from the schema-validated binary.
  • Updated paperclips-content runtime loading to deserialize the typed Paperclips Cap’n Proto message instead of capos_config::CueValue.
  • Wired the freshness check into make generated-code-check through generated-paperclips-content-check.

Remaining guardrails:

  • Keep generated content as schema-validated binary data; do not add runtime CUE parsing to the demo.
  • Keep the focused QEMU transcript representative: one launch, one production loop, one automation purchase, one early project unlock/effect, and clean exit. Cover larger rule validation with host tests.
  • Continue using the Rust validator for semantic bounds that Cap’n Proto cannot encode directly, such as project count, id shape, graph reachability, and nonzero costs/effects.

Client/Server Architecture Backlog

Goal: migrate Paperclips from one terminal process into an authoritative server plus thin clients. The terminal client should render output, parse player commands, and invoke server capabilities; it should not own GameState, timer advancement, proof acceleration, unlock checks, or game-rule mutation.

Staged tasks:

  • Define the first coarse Paperclips server/client schema. The initial PaperclipsGame endpoint covers initial text, command text, command results, proof-only explicit time advancement, and the first structured command-list and plain-status queries. Regular automation is driven by the server’s own timer capability. Session creation, broader structured state/events, project/purchase listings, and capability transfer points remain future protocol work.
  • Add the first Paperclips server process. It owns GameState, generated content, proof-command gating, unlock checks, and mutation rules while preserving current clean-room mechanics and host rules coverage.
  • Convert the terminal Paperclips process into a client when a game endpoint is present. The client keeps stdio, blank-command repeat, and transcript handling, then routes commands to the server. It still accepts server-rendered text in this first slice.
  • Move regular game timer cadence into the Paperclips server. Server-mode terminal clients still receive a timer grant so they can poll and display server-generated status messages while the player is idle at the prompt.
  • Add a structured command-list protocol method. The Paperclips server reports the commands available for the current state/session, including proof-only and later-stage commands only when they are actually available, and server-mode terminal clients render help from those command specs. Command execution remains the existing text request path in this slice.
  • Add a structured status snapshot protocol method. PaperclipsGame.status returns PaperclipsStatusSnapshot with the fields needed to render the existing plain status transcript, and server-mode terminal clients format that snapshot locally instead of relying on server-formatted status text. status --json remains proof-only instrumentation decided by server-side authority and is not exposed through normal structured status.
  • Add a structured project-list protocol method. PaperclipsGame.projects returns unlocked project entries with id, label, description, rendered cost, and status markers so server-mode terminal clients render plain projects locally from server-provided state. project <id> execution remains the existing text request path and still mutates server-owned game state.
  • Split command parsing and presentation more cleanly. The terminal client can now render help from structured server command specs, plain status from structured server snapshots, and plain projects from structured server project lists, but it should eventually parse player command syntax and render broader structured server state/events instead of sending raw command strings and displaying server-formatted command results.
  • Model unlocks as server-issued facets or command capabilities. Early stages may expose coarse play, project, purchase, and proof facets; later stages should narrow toward facet-per-command authorities once capability transfer ergonomics are ready.
  • Keep proof acceleration explicit. The server, not the client, should decide whether proof-only commands such as millisecond advancement and machine-readable status are available for a session.
  • Update make run-paperclips to prove the first split in QEMU: shell launches server services plus terminal clients, normal and proof sessions use different server endpoints, proof-only commands remain gated by server authority, and the existing representative transcript still exits cleanly.
  • Extend make run-paperclips after command facets land: prove the client cannot mutate state locally beyond server-granted facets and that unlock/facet changes are visible.
  • Add the later web shell/client path after the server protocol is stable. A browser-facing client or gateway should share the same Paperclips game capabilities as the terminal client instead of reimplementing game logic.

Deferred:

  • Add durable save/load only after capOS has a durable user storage capability appropriate for spawned demos.
  • Split every gameplay command into a distinct transferred capability only when the platform has ergonomic capability transfer and revocation patterns for short-lived command facets.