Program Enrichment Contract: carts, the simulated world, and DOSSIER keys

Cross-program companion to the first-party programs (ADR-0042).

v1.2 | 2026-08-23

Single-tier companion (Tier-3 detailed design). Defines how a cart enriches a first-party program and how recon programs emit DOSSIER keys: the cross-program mechanism ADR-0042 left per-program-open. Where this and an ADR disagree, the ADR wins. Date: 2026-06-21 Deciders: Josh; Gameplay Design Related:

ADR-0042 — the thirteen programs; “a cart may enrich a program’s data but never gates access”
ADR-0040 — the UDS write boundary (durable state is write-only via sanctioned outcome) that key deposits must respect
ADR-0005 — NoshAPI; gains launch-app + dossier-commit (amendments owed, §8)
../runtime/economy-model.md — DOSSIER facts: earned knowledge, never bought or spent
../gameplay-framework.md — fills gap D of its ledger
README.md + the dossier.md / bzbx.md / conduit.md stubs whose open questions this resolves

1. The frame: a program is a lens; the cart supplies the world

A first-party program is a generic lens — bzbx reads a wire, CONDUIT runs a session, Kommander walks a filesystem, AmberCalc crunches a table. It ships always-present and content-free. A cart enriches a program by supplying the world the lens looks at. ICE BREAKER doesn’t contain CONDUIT; it hands CONDUIT a target to open a session against. Black Ledger hands AmberCalc a ledger to crunch.

This gives two enrichment directions, and they are the whole contract:

   cart  ──(the simulated world)──▶  program        (§3–§4: enrichment)
   program  ──(authored facts found)──▶  DOSSIER     (§5: key emission)

The program is independent and always launchable bare; the cart only populates what it sees — never gates access (ADR-0042).

2. The world is always simulated / in-world

No program does real I/O. bzbx does not ping a real host; CONDUIT does not open a real socket. They operate on a mission-provided in-world model of a network / host / ledger / filesystem. This resolves the “real vs. in-world” open question in the bzbx and CONDUIT stubs — always in-world — and it’s what makes the device deterministic, offline, and authorable. “We’re not giving them ping; it’s simulated gameplay”: the simulation is the authored world the cart installs.

3. Enrichment delivery — hybrid (`launch-app`)

A cart/mission launches a program with the router-switch verb, carrying two kinds of context:

(launch-app :conduit
  :payload '(:endpoint "fin-relay-07" :protocol :ssh :cred key-handle-3)   ; small params
  :world   ledger-net-handle)                                              ; handle to a world-region

:payload — small, self-contained parameters for this launch: a scan target, a protocol + credential handle, a dataset name. A snapshot.
:world — a handle to a mission-data region (§4) holding the structured, possibly large world the program reads and navigates live. The handle, not a copy.

A program launched bare (operator opens it from the router, no cart context) gets an empty/default world — it still runs, it just has nothing authored to look at. Enrichment never gates (ADR-0042).

4. The mission-data region (the world model)

Structured worlds — a 16-node network, a shell-company ledger, a filesystem tree — are too large and too live to ship as a payload blob. The cart installs a world model into a mission-data region (volatile run state, not UDS — it resets at the mission-instance boundary like the rest of run state, per DeckRunner §6). launch-app passes a handle to it; the program reads/navigates it and sees mission-state changes live (a node bzbx revealed stays revealed when CONDUIT opens it).

The region is run-state, never durable — nothing a program does to the world model touches UDS. Durable consequence flows through two sanctioned engine paths (ADR-0064): key emission (§5), the operator-knowledge path a program can invoke, and engine-applied record writes into the persistent record store at mission resolution, the world-consequence path reachable from no program or cart (../runtime/persistent-record-store.md). The region references the store where it overlaps it.

The region’s readership includes the cart at mission activation (ADR-0063). One region per mission, and every reader launched during that mission reads the same one: the programs while the mission runs, and the cart when its game surface activates. The cart resolves its attack target from the region when the region holds one (a host the programs revealed and the mission flags as the breach target), with contract-seed generation as the fallback. The region survives the cart-load edge (engine-owned run-state, reset only at the mission-instance boundary). Control flows the other way only: no program starts, launches, or switches into a cart surface; a cart is entered by physical insertion and the operator’s own screen switching.

5. Authored keys → DOSSIER (the sanctioned write)

Recon is discovering the authored facts in the world. The cart tags which facts are discoverable keys (typed: RELAY-7-TOPOLOGY, TANAKA-CREDENTIALS, BANK-ROUTING). A program surfaces them as the operator explores; discovering one commits it to DOSSIER:

(dossier-commit 'RELAY-7-TOPOLOGY)   ; sanctioned — the engine commits; not a raw write

Because DOSSIER keys are durable earned knowledge (economy-model.md), the deposit routes through the engine’s sanctioned-write path — the same boundary mission outcomes use (ADR-0040 §6). A program (or player script) cannot raw-write DOSSIER; it reports a discovery and the engine commits it. This is the recon → knowledge bridge: keys earned here hard-gate or de-risk missions elsewhere. (Whether a discovery also costs attention/exposure is the recon-phase tuning — gap C, deferred.)

6. Program → program (the “send to DOSSIER” flow)

Programs compose through the same two mechanisms:

CONDUIT pulls a credential from Keyring — a :world/handle read, not a special case.
AmberCalc / RIPSAW / Kommander “send to DOSSIER” — this is just dossier-commit (sanctioned). There is no separate program-to-program write channel; everything durable a program can cause goes through dossier-commit, everything transient through the world-region. (The second durable path, the engine’s record writes into the persistent record store at mission resolution, is reachable from no program; ADR-0064.)

7. Per-program enrichment (the recon/data programs)

Program	The world a cart supplies	`:payload` (params)	Keys it can emit
bzbx (recon)	in-world network: hosts, ports, services, links	scan target / seed	discovered hosts, open ports, service banners, topology fragments
CONDUIT (access)	a target host model (filesystem + command/response)	endpoint, protocol, credential handle	files seen, validated creds, session findings
RIPSAW (org recon)	org / LDAP tree: people, accounts, ownership	root node	org-chart facts, beneficial owners, shell links
Kinoshita Kommander (file hub)	mountable filesystems (device SD, cart SD, remote via CONDUIT)	mount set	located mission files
AmberCalc (forensic analytics)	a transaction / ledger dataset	dataset handle	flagged anomalies, reconciliations (feeds BLACK LEDGER)
Keyring (crypto ops)	key material in scope	target keys / handles	cracked keys → access / knowledge
DOSSIER (intel store)	is the sink — the operator’s accumulated keys	records to add	— (receives `dossier-commit`)
knSALK (defense)	the operator’s own deck threat state (incoming trace / ICE)	active-contract threat context	defense events, not DOSSIER keys — the inverse direction (gap F)

8. New primitives (flagged for ADR-0005 amendment — not written here)

(launch-app :prog :payload … :world <handle>) — the router-switch + enrichment verb (the primitive ADR-0042 already owes ADR-0005). This doc fixes its :payload + :world shape.
(dossier-commit <key>) — the sanctioned key-deposit primitive; routes through the engine’s write path, never raw.
The mission-data region (the world-model handle) — a run-state region a cart installs and launch-app hands out; likely an ADR-0006 / runtime-spec item.

Landed (2026-06-21): launch-app (Tier 1, with the :payload + :world shape) and dossier-commit (Tier 2, sanctioned) are added to NoshAPI in the ADR-0005 Amendment Log (2026-06-21 entry). The mission-data world-region remains a runtime-spec item; exact signatures finalize with the engineering spike.

9. Open / deferred

Recon attention/exposure cost — discovering a key may cost exposure; the cost model is the recon phase (gap C), not this plumbing.
Per-program world schemas — the exact shape of each world model (network, ledger, filesystem, org tree) is per-program design (the ten pending program specs).
One region or many — settled: one shared world-region per mission (../runtime/world-engine.md §1), and its readership includes the cart at mission activation (ADR-0063; §4 above).
Bare-launch default world — what an un-enriched program shows (empty vs. a sandbox/demo world).
knSALK is the inverse direction (defense, not recon) — its world is the operator’s own threat state; specified under gap F, not here.

Migration notes

2026-08-21 (v1.1): §4 extends the shared-region readership to the cart at mission activation, and the “one region or many” item in §9 is annotated settled, per ADR-0063. No mechanics changed.
2026-08-23 (v1.2): §4 and §6’s single-durable-path claims widen to the two-path model per ADR-0064: dossier-commit stays the one durable verb a program or cart can invoke; engine-applied record writes into the persistent record store at mission resolution are the second sanctioned path, reachable from no Lisp tier. No program-side mechanics changed.