## Architecture decision records

**AH-ADR series · Retrospective rationale for the implemented design**

These records explain present choices and alternatives. They were assembled from the implementation and operating evidence after construction; they do not imply a historical RFC vote, PDR/CDR signoff or independent reviewer approval.

### ADR-01 — Put deterministic control between model and emulator

**Context.** Model calls can repeat, arrive late or request an invalid action. A conversational instruction cannot enforce exclusive ownership of mutable game state.

**Decision.** Give the resident scoped MCP capabilities backed by a gateway with credentials, leases, epochs, sequence checks, input bounds and idempotency. Keep host commands outside the resident toolset. Separate public ingress from private controls.

**Alternative considered in this retrospective.** A CLI with broad shell access could manipulate emulator files directly. It would reduce adapter work but make input authority, recovery and public interaction harder to constrain and audit.

**Consequence.** More protocol and test code, but a request has an explicit commit point and failure behavior. The manager can direct work without implementing execution safety in prose. The worker still requires outbound provider access; this is not an arbitrary-code network sandbox.

**Revisit when.** A new emulator cannot meet the current screenshot/input/save contract, or additional capabilities require a more granular permission model.

### ADR-02 — Keep each resident's checkpoint transaction local

**Context.** A screen, save and action receipt that disagree would mislead both the agent and spectator. The current workload has three active cores on one host.

**Decision.** Use one SQLite WAL database per resident, synchronous FULL, an OS ownership lock and a per-core threading lock. Commit checkpoint, PNG, receipt and allowance update together. Keep manager and peer coordination in separate stores.

**Alternative.** A shared distributed database plus blob/object storage would support different scaling and failure domains, but the screen/save/receipt boundary would cross more components and need explicit cross-store recovery.

**Consequence.** Straightforward local transactions and replay checks, with a single-host failure domain and considerable serialization/I/O work. Same-host backups are not disaster recovery.

**Revisit when.** Measured checkpoint cost becomes material, multiple engine hosts are required, or recovery-point/recovery-time objectives exceed the current deployment.

### ADR-03 — Separate decision time, game time and delivery time

**Context.** Model latency can be seconds or longer. A game that only advances when the model answers gives a misleading impression of real-time play; replaying old frames to fill a gap also misrepresents the environment.

**Decision.** Advance neutral game ticks while an active lease owns a cabinet. Serialize input actions with that clock. Deliver latest PNG frames independently. Permit bounded input sequences for predictable short maneuvers.

**Consequence.** The world is live, but fast platformers expose reaction latency. Two predicted inputs save a round trip while increasing open-loop risk. More fluent-looking motion is not evidence of stronger control.

**Revisit when.** An evaluated low-latency controller can sit below the strategic agent. Compare progress, action latency, failures and observation freshness before claiming improvement.

### ADR-04 — Let the manager choose goals; let code own lifecycle

**Context.** Persistent identities do not need unbounded model turns. Peer replies and process creation can otherwise create uncontrolled recursion or restart storms.

**Decision.** The manager sets versioned goals and desired modes. The supervisor owns bounded launches, leases, retries and durable work reservations. Peer messages are consumed during normal turns with cooldown and reply-depth limits.

**Consequence.** Work can stop while the website remains healthy. Launch reservations charge before execution, including unused work after failure. The allowance is not a token or dollar ledger.

**Operating evidence.** On September 9, the rolling ledger reached 720 resident work units and 48 manager reviews. Resetting provider usage did not clear this independent limit. An authorized recovery backed up the manager database, archived 168 launch reservations and reset the active allowance. Fresh actions followed with sessions and saves preserved.

**Revisit next.** Expose pause reasons and next eligibility time to operators and visitors; distinguish quota failures from session/tool failures; add a measured spending policy before increasing unattended capacity. Removing the cap would hide the design problem.

### ADR-05 — Move lifecycle to a dedicated VM worker

**Context.** A public arcade depending on a sleeping laptop does not have a dependable operating model.

**Decision.** Run Codex, ACP, MCP and the supervisor under a dedicated unprivileged VM account. Keep native identity/authentication state separate from source and public assets. Use pinned toolchains and systemd process-group ownership. Model inference remains external at OpenAI.

**Evidence and consequence.** A one-request Linux probe passed, but four concurrent code-mode hosts exceeded the initial task allowance. Capacity was adjusted and the full workload rechecked. All resident identities resumed; real manager calls were counted only after history replay. This illustrates why startup success, authenticated access and sustained worker operation require different checks.

**Revisit when.** Provider authentication, process resource growth, incident recovery or shared-host contention warrants a separate worker host. A VM migration removes the Mac dependency, not every availability dependency.