nOSh Orchestration

Accepted — this is the architecture. The standalone cartridge model is retired.

Version: 1.0
Date: April 2, 2026
Author: Josh Schairbaum / KN-86 Build Team
Related: docs/adr/ADR-0019-cartridge-storage-and-form-factor.md (cartridge form factor — full-size SD card in custom two-piece clamshell sled, read via USB mass storage through the internal hub bridge IC; supersedes ADR-0013); docs/adr/ADR-0013-cartridge-physical-format.md (superseded by ADR-0019 on 2026-04-24; retained for design history); docs/adr/ADR-0015-cipher-line-auxiliary-display.md (Cipher voice surface + Universal Deck State schema additions). Scope split on this file: the deck-state schema is Embedded Systems' scope (ADR-0015); the Cipher-voice grammar framework (nOSh runtime meta-grammar + cartridge-contributed fragment productions) is Gameplay Design's scope and is revised in its own pass.
Companion: KN-86-Pi-Zero-Build-Specification.md (hardware and low-level nOSh runtime)
Source: docs/software/runtime/orchestration.md

Engine-tier naming (ADR-0040, 2026-06-18). The “nOSh orchestrator” described here is the DeckRunner engine tier of nOSh — the layer that owns the run loop and contains Mission Control and Mission Runner. The Platform floor (renderer, audio, input mechanism, host seam) is a separate tier. This doc’s high-level claims (nOSh owns the board / economy / phase chain / CIPHER) remain accurate; “the orchestrator” now has a name. See deckrunner-engine-architecture.md and ADR-0040.

Design Intent

The KN-86 Deckline uses the capability model. This is not an alternative under consideration — it is the architecture.

The standalone cartridge model (each cartridge is an independent self-contained program, the nOSh runtime is a bootloader with peripheral drivers) is retired. The capability model means: the nOSh runtime is the orchestrator. It owns the mission board, the economy, the reputation system, the phase chain, and the Cipher voice. Cartridges are capability modules that expand what the deck can do. They carry program code, mission templates, behavior tables, generation data, domain vocabulary, and per-cartridge save data. The nOSh runtime cannot run a mission phase without the relevant cartridge physically present, because the content lives on the cartridge’s SD card filesystem. Cartridges are not optional. They are not decorative. They are architecturally necessary.

This document covers the software model, the economy, and the fiction layer. The product spec (KN-86-Pi-Zero-Build-Specification.md) covers hardware and low-level nOSh runtime. They are separate documents that reference each other.

Note on Bare Deck State: When the device powers on without a capability module inserted, the nOSh runtime displays the Bare Deck Terminal HUD—a fully specified runtime-level interface featuring Universal Deck State management, runtime bounties, macro recording, link protocol, and Cipher voice interaction. The bare deck is not a loading screen; it is a genuine operational environment. See KN-86-Bare-Deck-Terminal-Spec.md for complete specification.

Note on Gameplay Mechanics: ICE Breaker, the pack-in title, uses the OODA loop (Observe-Orient-Decide-Act) as its atomic unit of play. The operator cycles through tempo-driven decision-making as the network, threat system, and toolkit run their own OODA loops in parallel. Hot Swap (mid-run cartridge swaps) is a core decision framework within this loop. See KN-86-ICE-Breaker-Gameplay-Spec.md for detailed mechanics.

Universal Deck State
The Mission Board
Multi-Phase Missions & Cartridge Swapping
Software Library as Capability Modules
Cross-Program Integration
The Capability Curve
The Cipher Voice
C Cartridge Grammar
Relay Module
Cartridge Provenance
Cartridge SD Card Layout
Graceful Degradation

Universal Deck State

The persistent identity of the deck — operator handle, credits, reputation, cartridge history, phase chain, Cipher voice state. Lives on the Pi’s microSD (/home/shared partition per ADR-0011), shared across every cartridge.

Schema and field semantics extracted to deck-state.md. This doc references deck-state fields by name (e.g., phase_chain, cartridge_history, coherence_stack); see deck-state.md for the C struct definition and per-field documentation.

The Mission Board

Authoritative spec extracted to mission-control.md. This section retains only the one-paragraph framing; the full architecture (Capability Registry, schema-driven contract generation, TTL/decay, Opportunity Contracts, Mission Runner handoff) lives in that doc.

The mission board is the operator-facing surface of Mission Control — the nOSh runtime subsystem responsible for capability registration, procedural contract generation, and contract acceptance. The board presents 3–5 live contracts at any time; each is synthesized at runtime from a defcontract-schema form (registered by an inserted or previously-loaded cartridge), seeded by Universal Deck State (reputation, credit_balance, cartridge_history, cipher_seed). Contracts carry a TTL and decay off the board if not accepted. On [EVAL], control transfers to the Mission Runner — a Lisp REPL/nEmacs environment with current-mission, mission-params, phase-chain, and load-capability bound. See mission-control.md and ADR-0028 / ADR-0029.

The MISSIONS tab in the Bare Deck Terminal hub (bare-deck-terminal.md) is the primary entry point.

Multi-Phase Missions & Cartridge Swapping (Hot Swap)

Contracts that span multiple capability domains are multi-phase missions. Each phase requires a specific capability module. Under Mission Control (see mission-control.md §5), the Mission Runner — not the runtime directly — drives phase progression by issuing (load-capability ...) calls; the runtime serializes inter-phase state into the UDS phase_chain between calls. Mid-mission cartridge swaps are formalized as Hot Swap — a tactical pause where the operator physically exchanges modules to gain new capabilities in response to changing mission state. Hot Swap mechanics are detailed in software/cartridges/modules/ice-breaker.md where they serve as a core decision framework.

Cart insert / swap / remove protocols extracted to cartridge-lifecycle.md. That doc covers udev events, header validation, grammar merge, phase-chain serialization, swap timeout, save-file handling, and the diegetic swap surface — the complete state machine from ABSENT through ACTIVE and back. This section retains only the orchestrator’s view of phase-chain protocol; consult cartridge-lifecycle.md for the runtime mechanics.

Phase Chain Protocol

The flow below is the orchestrator’s view; the operator-facing program is a Mission Runner Lisp form (see mission-control.md §5.3).

Mission Runner accepts contract → emits :mission-start
  ↓ (load-capability :ice-breaker :seed (mission-params :network-seed))
Phase 1: ICE BREAKER (NETWORK INTRUSION)
  ↓ capability completes → returns {:outcome :success :trace 22 :extracted ...}
  ↓ Mission Runner serializes intermediate state to phase_chain via NoshAPI
  ↓ Mission Runner displays / CIPHER emits: PHASE 2 REQUIRES: FORENSIC ACCOUNTING
  ↓                                          INSERT: BLACK LEDGER
  ↓ operator physically swaps cartridge → see cartridge-lifecycle.md
  ↓ (load-capability :black-ledger :input (extracted-from result))
Phase 2: BLACK LEDGER (FORENSIC ACCOUNTING)
  ↓ capability completes → returns result
  ↓ Mission Runner: (complete-mission current-mission)
  ↓ runtime: PAYOUT: 4,800 ¤ / REPUTATION: +12
Debrief: Cipher voice summary on CIPHER-LINE (event type :mission-end)

Software Library as Capability Modules

The KN-86 software library consists of 14 programs organized into six categories. Each program is a capability module — a cartridge that registers capabilities with the nOSh runtime, provides mission templates, contributes Cipher domain vocabulary, and maintains its own save data.

Operations Modules

Module	Capability	Description
ICE Breaker	NETWORK INTRUSION	Network penetration, data extraction, system compromise
Depthcharge	MARITIME RECONNAISSANCE	Sonar-based exploration, salvage, evasion
Shellfire	ELECTRONIC WARFARE	Signal jamming, communications intercept, EW countermeasures
Takezo	TACTICAL ANALYSIS	Pattern recognition training, strategic planning

Commerce Modules

Module	Capability	Description
Black Ledger	FORENSIC ACCOUNTING	Financial forensics, transaction tracing, evidence chains
SynthFence	MARKET OPERATIONS	Commodity trading, arbitrage, market manipulation detection

Module	Capability	Description
Drift	SIGNAL TRACKING	Radio frequency location, dead-drop protocols
Pathfinder	ROUTE PLANNING	Logistics, route optimization under constraints

Strategy Modules

Module	Capability	Description
Nodespace	NETWORK STRATEGY	Abstract territory control, adversarial node capture
NeonGrid	SPATIAL OPERATIONS	Grid navigation, pattern avoidance, spatial reasoning

Passive Enhancement Modules

Module	Capability	Description
The Vault	KNOWLEDGE INDEX	Encrypted reference database; loading increases `knowledge_index` in deck state
Cipher Garden	CRYPTOGRAPHIC TOOLS	Cipher practice, key generation, encrypted messaging

System Modules

Module	Capability	Description
Null	DIAGNOSTIC	Deck diagnostic, state inspection, Cipher voice direct access
Relay	UPDATE CHANNEL	Writable cartridge for receiving content updates via USB (Phase 2)

Module Registration

When a cartridge is inserted, the nOSh runtime:

Reads the cartridge header (capability_bits field)
Sets the corresponding bit in cartridge_history if not already set — this is the persistent backing of the Capability Registry (mission-control.md §2)
Reads schema definitions (defcontract-schema forms) and capability metadata (:provides, :affinities, :seeds) from the cart’s static-data block (per ADR-0006 §Cart-Capabilities Block)
Parses the cartridge’s cipher-grammar block (vocabulary pools, production fragments, mode-weight biases) and merges into the active CIPHER-LINE grammar tables — see docs/software/runtime/cipher-voice.md for merge rules.
Registers the module’s phase handlers with the nOSh runtime’s dispatch table — these are now invoked by (load-capability ...) from the Mission Runner, not by the runtime’s main loop directly (see ADR-0029)
Mission Control regenerates the board’s available schema pool

Cartridge Contribution Model

A cartridge contributes data blocks to nOSh. The nOSh runtime consumes the blocks; cart code does not own the runtime loop for any of them. The declarable blocks are:

Block	Purpose	Consumer
Program code (Lisp on Fe)	Cell handlers, phase handlers, mission logic	nOSh cell runtime (ADR-0001, ADR-0004); phase handlers invoked by Mission Runner via `(load-capability ...)` (ADR-0029)
Capability registration (`:provides :affinities :seeds`)	Capability Registry metadata; recovered on each insertion	Mission Control (`mission-control.md` §2; ADR-0028)
Contract schemas (`defcontract-schema` forms)	Schema-driven contract synthesis (replaces the older “static mission templates” model)	Mission Control contract generator (`mission-control.md` §3; ADR-0028)
Behavior tables	Enemy logic, market curves, patrol patterns, etc.	Cart program code via NoshAPI reads
Generation data	Sprites, PSG patterns, text tables, seeds	Cart program code, nOSh runtime audio/display
Domain vocabulary	Terms bound to capability-specific slots (legacy main-grid Cipher vocabulary is deprecated; vocabulary contribution now flows through `cipher-grammar`)	Obsolete path — superseded by `cipher-grammar`
`cipher-grammar`	Vocabulary pools, production fragments, mode-weight biases, style deltas, event-type registrations for the CIPHER-LINE auxiliary output surface	nOSh runtime CIPHER-LINE engine
`mission-contributions`	Phase verb vocabulary, affinity tag set, modifier flags, sanctioned transition overrides, payout/threat biases for procedural multi-phase contract composition	nOSh runtime Mission Composition Grammar (working spec: `docs/plans/post-v0.1/2026-04-25-mission-composition-grammar.md`)
Per-cartridge save data	Tool inventory, mission history, discovered patterns	Cart code; file on the cartridge’s own SD card filesystem (ADR-0019, supersedes ADR-0013)

The cipher-grammar block is the cart’s sole interface to the Cipher voice. Carts do not render Cipher text to the main grid (Spec Hygiene Rule 6); they do not write pixels to CIPHER-LINE (nOSh-runtime-owned render loop); they contribute data blocks that the Cipher engine consumes during its tick. Full syntax and merge rules in the CIPHER-LINE Grammar Framework §7 and §10.

CIPHER-LINE as First-Class Platform Output Surface

The KN-86 ships with two rendering surfaces: the main 80×25 grid and CIPHER-LINE. Both are first-class. The capability model treats CIPHER-LINE as a nOSh-runtime-owned output surface that every cartridge may contribute to (via cipher-grammar) but none may commandeer.

The nOSh runtime owns: the Cipher engine (mode selector, grammar expansion, coherence stack, memory store, deck-state fields that back it), the OLED rendering loop, and the four-row layout (see UI Design System §3A).
Cartridges contribute: grammar fragments, vocabulary, mode biases, style deltas, and event pushes. Nothing more.
Operators use: CIPHER-LINE as a peripheral awareness surface. They never navigate the OLED directly; it narrates them.

Cross-cartridge coherence is load-bearing. The coherence stack (5 slots) persists across cartridge swaps in Universal Deck State. When the operator pulls one cart and inserts another, the Cipher voice remembers what it just said — fragments chain across the swap. This is the cockpit-voice-recorder effect carried through a capability change. Implementation details live in ADR-0015 (Embedded Systems ownership: deck-state schema, OLED rendering budget, hardware wiring).

Cross-Program Integration

The cartridge history bitfield enables grace notes across programs. These are not gates, not locks — just richer behavior when the deck knows more.

How It Works

When a cartridge’s phase handler or display code runs, it can read the cartridge_history bitfield from deck state. If certain bits are set (meaning the operator has loaded those modules before), the behavior can vary:

Examples

ICE Breaker + Black Ledger: When both bits are set, ICE Breaker’s SABOTAGE contracts against FINANCIAL targets generate an optional Phase 2 that routes to Black Ledger for audit trail analysis. Without Black Ledger history, the SABOTAGE contract is single-phase — the financial data is destroyed, not analyzed.

ICE Breaker + Depthcharge: When both bits are set, Depthcharge’s waterfront salvage contracts can include a Phase 2 where recovered hardware contains encrypted network maps that ICE Breaker can exploit. The Depthcharge contract becomes a lead-in to a network penetration.

NeonGrid + ICE Breaker: NeonGrid’s patrol avoidance algorithms train spatial reasoning. When both bits are set, ICE Breaker’s network map generation produces slightly more complex topologies — the mission board assumes the operator can handle more spatial complexity.

Black Ledger + SynthFence: Cross-domain forensic accounting. Market manipulation evidence from SynthFence can be analyzed in Black Ledger. Multi-phase contracts trace the money from market to books.

The Vault + Any Module: Loading The Vault increases knowledge_index in deck state. Every other module reads this value. Higher knowledge index means: more detailed INFO displays, richer Cipher commentary, additional context in mission briefs. The Vault doesn’t change gameplay — it changes information density.

Design Principle

Cross-program integration is always additive, never subtractive. No mission, no feature, no capability is locked behind another module. The single-cartridge experience is complete. Integration adds texture, not prerequisites.

Scaling beyond hand-authored pairs

The examples above are hand-authored cartridge pairs. At the four-cart launch library this is tractable (six pairs); at the 14-cart full library it is not (91 pairs, 364 triples, 1,001 quads). The Mission Composition Grammar (working draft: docs/plans/post-v0.1/2026-04-25-mission-composition-grammar.md) generalizes hand-authored cross-pairs into a procedural grammar — a 10-verb vocabulary, an 11-tag affinity system with sanctioned cross-affinity transitions, and a new mission-contributions cart contribution block. Hand-authored pairs become seed corpus for the genre template library; the composition algorithm covers the long tail. WORKING tier; will graduate to DEFINITIVE via this section’s Cartridge Contribution Model table when the algorithm sub-task lands.

The Capability Curve

One Cartridge

A single cartridge is a complete career. The operator inserts ICE Breaker and has: a full mission board of network intrusion contracts, threat levels 1–6, tool acquisition, reputation progression, linked play, and hundreds of hours of procedurally generated content. Nothing is missing. Nothing feels gated.

Four Cartridges (The Launch Library)

With all four launch titles loaded (ICE Breaker, NeonGrid, Black Ledger, Depthcharge), the mission board begins generating multi-phase contracts that span capability domains. The operator’s career becomes cross-disciplinary. A network penetration leads to financial forensics. A maritime salvage produces encrypted hardware that requires intrusion tools. The payout ceiling rises. The threat ceiling rises. The missions become more complex and more interesting.

Full Library (14 Modules)

The full library transforms the deck into a private intelligence firm’s workstation. Every domain is covered. Multi-phase contracts can chain 3–4 capabilities. The economy is deep. The reputation curve is long. Cross-program integration produces emergent contract types that no single module could generate.

The Curve Is Not a Gate

At every point on the curve, the operator has a complete, satisfying experience. One cartridge is not a demo. Four cartridges are not the “real” experience. The curve is about expanding capability, not unlocking it.

The Cipher Voice

The Cipher voice is a sentence grammar engine embedded in the nOSh runtime. It produces contextual text — the deck has a voice. It is never called AI. It is never explained. It speaks as though the deck is an onboard system quietly narrating itself.

Output surface. The Cipher voice renders to CIPHER-LINE, the auxiliary OLED above the keyboard. It does not appear on the main 80×25 grid. See docs/software/runtime/cipher-voice.md for the authoritative engine specification (event stream, memory store, five utterance modes, coherence stack, cartridge contribution model, NoshAPI primitives).

Legacy note (2026-04-24). Earlier revisions of this section depicted Cipher utterances as full sentences on the main grid (> OPERATOR KINOSHITA. 2,400 CREDITS...). That is superseded. Cipher now speaks in clipped fragments on CIPHER-LINE (kinoshita online. / 2,400 in the account. on separate ticks). The aesthetic target is cockpit voice recorder, not chatbot. Every gameplay spec in docs/gameplay-specs/ has been revised to reflect this.

Grammar Engine (Summary)

Full specification lives in the CIPHER-LINE Grammar Framework. In summary:

Event stream. Cartridges and the nOSh runtime push structured event records (:event :type ... :affect ...).
Memory store. 128-entry ring buffer with decay; :anomalous / :significant events stick.
Five utterance modes. observe, annotate, reflect, drift, silent. Silence is first-class.
Mode selector. Weighted distribution by beat parameter, cart biases, affect, repetition penalty.
S-exp grammar. Weighted productions. Non-terminals for slots (:subject, :object, etc.) and memory fragments.
Style controls. terseness, certainty, temporal-blur.
Coherence stack. 5-slot FIFO of recent utterances. Persists across cartridge swaps in Universal Deck State.

Vocabulary Registration

Cartridges contribute domain vocabulary via their cipher-grammar block (see Cartridge Contribution Model above). The legacy “Cipher Domain region” of cartridge flash (a discrete word-table section) is retired; vocabulary now flows through the named CIPHER_GRAMMAR container section (ADR-0006). Domain examples:

ICE Breaker: (:subject "ice" "trace" "node" "packet" "relay"), (:verb-past-participle "compromised" "extracted" "burned" "mirrored")
Black Ledger: (:subject "transaction" "subsidiary" "shell" "audit"), (:memory-keyword "paper trail" "shell" "audit")
Depthcharge: (:subject "contact" "bearing" "hull"), (:affect-word "cold" "deep" "quiet" "thin")
NeonGrid: (:subject "grid" "sentry" "packet"), (:verb-present "patrols" "routes" "hums")

When the Cipher Voice Speaks

Cipher ticks per rendering frame of CIPHER-LINE activity or per idle second (whichever comes first). Beat parameter drives the mode distribution:

Boot screen / bare deck. Beat :bare-deck. Drift-heavy. Fragments like back online. / same handle. / low count today. over many seconds, interleaved with silence.
Mission board. Beat :mission-brief. Observe-heavy. Fragments tied to the selected contract: threat three. / clean work, maybe. / seen harder.
Active phase. Beat :active-hack. Observe + silence. Fragments at event-triggered cadence; silence on tense beats.
Phase completion / debrief. Beat :debrief. Annotate + reflect. Fragments chain the phase’s outcome to past mission memory.
Cartridge swap. Beat :cart-swap-lull. Drift-dominant. The voice drifts about the cart just removed while the new one loads.
Null (diagnostic module). A first-class surface for extended Cipher review — reads the memory store and coherence stack into a main-grid panel. This is Null’s superpower and the only module where the operator “listens” to Cipher at length. Still clipped; still fragments; the density is what changes.

Tone

The Cipher voice is clipped, observational, occasionally dry. No exclamation marks. No full-sentence narration. It observes events and drifts through memory. It has opinions about risk but does not moralize. It speaks in fragments that the operator reads in peripheral vision. Silence is part of the voice, not an absence of it.

C Cartridge Grammar

The authoring framework for capability modules. Full specification in companion document: KN-86-Cartridge-Grammar-Spec.md.

Three Layers

⚠️ Cartridge authoring note (2026-04-14; framing corrected 2026-06-14). Per ADR-0001 and ADR-0004, cartridges are now authored in Lisp, parsed and tree-walked by the Fe interpreter (no bytecode — see the ADR-0004 2026-06-14 amendment). The C grammar below describes the runtime handler-registration contract — the surface that Lisp cartridges bind to inside nOSh — not the authoring surface. See adr/ADR-0001-embedded-lisp-scripting-layer.md for the canonical authoring reference.

nosh_cart.h — The runtime handler contract. Macros for CELL_TYPE, ON_CAR, ON_CDR, ON_EVAL, DECK_TITLE, CAPABILITY_DECLARE, TEMPLATE_DEFINE, PHASE_HANDLER, etc.
nosh_runtime.c — The runtime. Input dispatch, cell pool, navigation stack, quote/lambda integration. In the capability model, the runtime is nOSh runtime code — it is the bridge between the nOSh runtime’s mission board and the cartridge’s event handlers.
nosh_stdlib.c — Standard library. drill_into(), next_sibling(), navigate_back(), spawn_cell(), LFSR helpers, sound wrappers, display helpers.

Capability Model Extensions

The cartridge grammar adds these macros for the capability model:

/* Declare what this cartridge provides */
CAPABILITY_DECLARE(NETWORK_INTRUSION, 0x01)

/* Define a mission template structure */
TEMPLATE_DEFINE(penetration) {
    TEMPLATE_FIELDS {
        uint8_t base_threat;
        uint8_t max_threat;
        uint8_t min_phases;
        uint8_t phase_variance;
        uint16_t base_payout;
    };
    TEMPLATE_GENERATOR { /* procedural contract generation logic */ }
}

/* Register a phase handler — called by the nOSh runtime when this module's
   capability is needed during a multi-phase mission */
PHASE_HANDLER(network_intrusion) {
    ON_PHASE_START { /* initialize from phase chain context */ }
    ON_PHASE_TICK  { /* per-frame logic during active phase */ }
    ON_PHASE_END   { /* serialize results back to phase chain */ }
}

/* Cipher domain vocabulary registration — SUPERSEDED.
   The C CIPHER_DOMAIN macro is retired. Cartridge vocabulary now
   ships in the cartridge's `cipher-grammar` Lisp block and targets
   CIPHER-LINE (the auxiliary OLED output surface). See
   docs/software/runtime/cipher-voice.md. */

Cartridge–nOSh Runtime Interface

The cartridge does not own its main loop. The nOSh runtime runs the mission board, accepts bids, and — under Mission Control (ADR-0028, ADR-0029) — hands an accepted contract to the Mission Runner (a Lisp REPL/nEmacs environment) which in turn invokes cartridge phase handlers via (load-capability ...). When a capability call returns, control returns to the Mission Runner, which decides what to do next (advance phase, branch on result, complete the mission, etc.).

nOSh runtime main loop:
  1. Read input events
  2. If on mission board → handle board navigation (CAR/CDR/EVAL/INFO); Mission Control owns generation
  3. If Mission Runner active → run Lisp evaluation step or pump active capability call
  4. If capability call active → tick cart phase handler; on return, marshal result struct back to runner
  5. If runner calls (complete-mission ...) → serialize phase chain, debrief, payout, return to board
  6. Render display
  7. Loop

The cartridge interface is bidirectional. The nOSh runtime reads templates and data from the cartridge SD filesystem. The cartridge’s event handlers are called by the nOSh runtime. The cartridge writes to its own save file and the nOSh runtime writes to the provenance file on the SD card.

Relay Module

Phase 2 feature. The Relay module is a writable cartridge for receiving content updates via USB. No wireless. No network stack. No over-the-air updates.

How It Works

The operator connects the deck to a computer via USB.
A desktop utility writes update data to the Relay cartridge’s SD card (new mission templates, Cipher vocabulary expansions, balance patches, community-created content).
The operator inserts the Relay cartridge into the deck.
The nOSh runtime reads the update manifest from the Relay’s SD card filesystem.
Updates are applied: new templates are merged into the nOSh runtime’s template database, Cipher vocabulary is expanded, economy parameters are adjusted.
The Relay cartridge’s provenance file records every update applied.

What It Cannot Do

It cannot modify nOSh runtime code (the nOSh runtime region is write-protected).
It cannot modify other cartridges’ save data or provenance chains.
It cannot add new capabilities — only expand existing template pools and vocabulary.
It has no wireless radio. Content arrives via USB cable, physically.

Cartridge Provenance

Every cartridge carries a sequential hash chain on its SD card filesystem — the cartridge remembers everything that has happened to it. This is not save data. It is a separate, nOSh runtime managed system stored as an append-only file (e.g., /.provenance.bin) on the cartridge’s SD card. Per ADR-0019, the provenance chain moved from a dedicated flash region to this filesystem path; the 32-byte block format and append-only semantics are unchanged.

Provenance Chain Structure

Each block in the chain is 32 bytes:

typedef struct {
    uint8_t  prev_hash[8];  /* Truncated SHA-256 of the previous block */
    uint8_t  event_type;    /* REGISTRATION, MISSION, RELAY_UPDATE, LINK_SESSION */
    uint8_t  reserved;
    uint16_t event_id;      /* Sequential counter */
    uint32_t timestamp;     /* Seconds since first registration (relative clock) */
    char     deck_handle[8]; /* Which deck produced this event (truncated) */
    uint8_t  payload[8];    /* Event-specific data */
} ProvenanceBlock; /* 32 bytes */

Event Types

REGISTRATION (0x01): Recorded the first time a cartridge is inserted into a new deck. Payload contains the first 8 bytes of the deck’s operator handle hash. A cartridge that has been in 12 decks has 12 registration blocks.

MISSION (0x02): Recorded on every mission completion (success or failure). Payload contains: threat level, payout, outcome code, phase count. A well-used ICE Breaker cartridge accumulates hundreds of mission blocks — the cartridge’s career history.

RELAY_UPDATE (0x03): Recorded when the Relay module applies an update that affects this cartridge’s template pool. Payload contains the update manifest hash.

LINK_SESSION (0x04): Recorded when this cartridge participates in a linked play session. Payload contains the remote deck’s handle hash and session outcome.

Properties

The chain is append-only. The nOSh runtime never modifies or deletes existing blocks.
Cartridge code cannot write to the provenance file. Only the nOSh runtime writes provenance blocks.
The chain is readable by any deck the cartridge is inserted into. A new deck can inspect the cartridge’s full history.
The 32-byte block size is an in-runtime convention (matching the original flash-page-alignment design), not a storage constraint — the underlying SD filesystem has no alignment requirement.
The provenance file path on the SD card is /.provenance.bin by convention; the .kn86 container header (see ADR-0006) does not carry a chain_offset field — the filesystem path is the locator.

Why It Matters

Provenance makes cartridges into artifacts. A cartridge that has been through 50 decks and 300 missions is not the same object as a fresh cartridge, even though the code is identical. In linked play, operators can inspect each other’s cartridge provenance during the handshake — reputation backed by a verifiable chain. In the fiction, this is the cartridge’s service record.

Cartridge SD Card Layout

Per ADR-0019, cartridges are full-size SD cards carried in a custom two-piece clamshell shell. The Pi Zero 2 W reads the card as USB mass storage via a card reader bridge IC on the internal USB hub. The .kn86 container format (see ADR-0006) is the authoritative byte-level spec for the cart’s code (Lisp source) and static data. This section describes the SD filesystem layout that nOSh expects when it mounts a cartridge.

SD Filesystem Layout

/<cart_id>/                    ← cart-id directory (e.g., /icebreaker_v1.3/)
    cart.kn86                  ← the .kn86 container — Lisp source + static data (ADR-0006)
    save/
        <cart_id>.sav          ← per-cartridge save data (ADR-0019 §6)
    .provenance.bin            ← append-only provenance chain (32-byte blocks)
    assets/                    ← sprites, PSG patterns, attract clips (runtime-opaque)

The .kn86 container (at /<cart_id>/cart.kn86) holds the cart’s Lisp source (tree-walked; no bytecode), mission templates, behavior tables, generation data, cipher-grammar block, and mission-contributions block. Its internal header carries capability_bits, requires_bits, lfsr_seed, and the section layout — see ADR-0006 for the authoritative byte-level spec. The orchestration doc does not restate the container header fields (Spec Hygiene Rule 1).

The save/ directory holds per-cartridge save state as a file. The cart_save / cart_load NoshAPI contract is unchanged at the FFI surface; the implementation writes to this filesystem path rather than to MBC5-mapped SRAM. Cart code does not observe the difference.

The .provenance.bin file is the append-only provenance chain. See §Cartridge Provenance above for the 32-byte block format and event taxonomy.

The assets/ directory is a cart-author convention for static data that the .kn86 container references but that the runtime treats as opaque blobs (attract-mode clips, large sprite sheets, audio samples). Not required for all titles.

The capability_bits and requires_bits fields inside the .kn86 container header are uint16_t — 16 capability slots, matching the 14-module launch library with 2 reserved bits. These are primary architectural fields, not metadata. They drive mission board generation and phase chain routing. The cartridge_history bitfield in DeckState is uint32_t (wider than per-cartridge capability_bits) to support future expansion beyond the initial 16-slot module namespace.

Graceful Degradation

The KN-86 doctrine for partial-hardware failure is show what you have, label what you don’t, never panic. It is a runtime-internal rule, not a per-cartridge concern. The runtime is the one component that knows whether a subsystem is healthy, and the runtime is the one component cart authors trust to behave predictably when one isn’t.

Source: influences/synthesis.md §2 L4 (resilience as doctrine, not feature), §3 item 4 (promote-to-spec list), §6 item 8 (sprint queue).

Per-FFI error contract is cross-referenced from software/api-reference/nosh-api/primitives-by-category.md §“Degradation contracts” — cart authors land in the FFI reference first, find a one-line note on each affected primitive, and follow the back-pointer here for the full mode behavior.

This section enumerates four degradation modes. For each: the trigger (what the runtime observes), the runtime behavior (what the runtime does autonomously), the cart-facing contract (how affected FFI primitives behave from cart Lisp), and the recovery path (what restores normal operation, if anything).

1. Coprocessor offline

Trigger. The Pi-side coprocessor bridge (coprocessor-bridge.md §5.3) raises KN86_LINK_DEGRADED after 3 consecutive missed 5-second heartbeats (~15 s of no response), or escalates to KN86_LINK_FAILED after the §5.4 full-restart escalation window (default 120 s). The bridge’s heartbeat / hard-fail logic owns the detection; the runtime owns the operator-facing response.

Runtime behavior.

PSG / audio: every psg-*, sound-*, and sfx-* call drops at the vtable seam (coproc.c); the runtime does not enqueue further frames for the bridge to drop. The audio path is silent for the duration.
CIPHER-LINE: the auxiliary OLED goes blank. The runtime suspends aux-* and cipher-emit writes; the bridge would refuse them anyway per coprocessor-bridge §5.3. Coherence stack and event ring continue accumulating in UDS — Cipher voice state survives the link outage, it just can’t render.
Row 0 status indicator: the firmware status bar (Row 0 of the primary 80×25 grid, owned by the runtime per CLAUDE.md Canonical Hardware Specification) renders a LINK? or [LINK] glyph adjacent to the existing status fields. The exact glyph and column live with the Row 0 spec; what is non-negotiable is that the operator sees a visible indicator on the primary display the moment audio + OLED disappear, with no in-fiction theatre and no panic.
Row 24 firmware action bar: the bridge’s COPROCESSOR LINK DEGRADED text (per coprocessor-bridge.md §5.3) is the canonical Row 24 string. Mirrored on the primary display Row 24, not on CIPHER-LINE (which is gone).
Mission flow: unaffected. Missions continue. Phase advancement, mission completion, deck-state mutation, and cartridge lifecycle are all Pi-local and do not depend on the coprocessor.

Cart-facing contract: silent no-op. Every coprocessor-routed FFI primitive returns its declared Unit (or no-op success value) when the link is degraded. Carts are not notified; no :coprocessor-unavailable error is raised. Justification: silent no-op is the simpler contract for v0.1. Raising would force every cart to wrap every psg-tone, sfx-keyclick, cipher-emit, aux-* call in error handling, which (a) bloats every cart, (b) means a partial-hardware failure causes cart-side cascade failures, and (c) violates the doctrine — the cart is doing the right thing, the hardware is the thing that’s broken, the cart should not be punished for it. The runtime is the layer that already knows; the runtime carries the indicator. Carts that want to behave specifically when audio is unavailable (a rare authoring choice — e.g., the diagnostic Null cart) can poll an explicit (link-status) primitive added in a later FFI revision; that primitive is not in v0.1 and no cart in the launch library needs it.

Affected primitives (each gets a one-line “degradation: silent no-op when LINK_DEGRADED” note in the FFI reference): psg-write, psg-read (returns 0), sound-tone, sound-noise, sound-envelope, sound-silence, sfx-keyclick, sfx-boot, sfx-select, sfx-confirm, sfx-error, sfx-alert, cipher-emit, cipher-push-event (still mutates the UDS event ring — only the OLED render path is gone), aux-timer-start (returns a valid handle; timer accounting continues runtime-side, the OLED render of any expiry is suppressed), aux-timer-stop, aux-show-seed, aux-status-render.

Recovery path. Automatic. When the bridge resumes heartbeats (coprocessor-bridge.md §5.3 last paragraph), it re-issues VERSION_QUERY, re-populates CIPHER-LINE from the runtime’s OLED shadow buffer, clears the Row 0 indicator, and resumes normal command flow. Cart code observes no transition — the next psg-tone after recovery just plays. The shadow buffer that the bridge replays is the existing nOSh OLED shadow, not a new piece of state.

2. microSD absent

Trigger. Either: (a) no cartridge inserted at boot or after an eject (udev reports no mass-storage device at the cart slot), or (b) the cartridge filesystem fails to mount, or (c) header validation rejects the inserted cart (.kn86 magic mismatch, version skew, CRC failure — see cartridge-lifecycle.md §“Insertion” step 6). All three drop the runtime into the same handling.

Runtime behavior.

Cart load: the runtime does not enter the cart-bound ACTIVE state. The lifecycle FSM stays in ABSENT (case a) or MOUNTED with an error flag (cases b/c). See cartridge-lifecycle.md for the canonical FSM.
Bare Deck Terminal: the runtime presents the Bare Deck Terminal HUD as its primary surface (bare-deck-terminal.md). The bare deck is a complete operational environment — STATUS / LAMBDA / LINK / SYS tabs, runtime bounties, macro recording, deck-state inspection — and is the canonical “no cart inserted” state, not an error state. The doctrine: the operator who never inserts a cart still has a functioning device.
Row 0 indicator: for cases (b) and (c) only — a CART? glyph in the firmware status bar indicates a mounted-but-rejected cart. Case (a), no cart inserted, is the resting state and gets no special indicator (the bare deck itself is the signal). Pulling out the cart in case (b)/(c) returns to case (a) and clears the glyph.
Operator-facing error string (cases b/c): the bare-deck status line carries the canonical strings from cartridge-lifecycle.md — > CARTRIDGE FORMAT NOT RECOGNIZED for header rejection, > CARTRIDGE FILESYSTEM UNREADABLE for mount failure. Diegetic, in-fiction, terse.
Universal Deck State: UDS lives on the device’s own microSD (/home/shared partition per ADR-0011), not on the cart SD. UDS is unaffected by cart-side filesystem failure. The cart-absent state writes to UDS normally — credits accrued from bare-deck bounties, lambda macro recordings, link handshake history.

Universal Deck State fallback (device microSD failure — distinct from cart microSD). If the device’s own microSD becomes unreadable (a much rarer failure — the device microSD is internal and not handled by the operator), the runtime degrades UDS to in-memory defaults for the boot session. Operator handle defaults to OPERATOR; credits, reputation, cartridge_history, coherence_stack reset to zero. The deck remains operational on the bare-deck surface. On the next save attempt (SYS → Save, mission completion, cart swap, low-voltage interrupt — see deck-state.md Persistence), the runtime surfaces > DECK STATE STORAGE UNAVAILABLE — SESSION ONLY on the bare-deck status line and writes nothing. The operator’s session work is real but transient.

Cart-facing contract. When the runtime is in cart-absent state, no cart code is running and no FFI surface is exposed — the question of cart-facing degradation does not arise. For cart-side I/O specifically:

cart_save / cart_load: in normal operation these write to the cart’s SD (/save/<cart_id>.sav per cartridge-lifecycle.md §“Per-cart save data”). If the cart’s filesystem becomes unreadable mid-session (cart pulled mid-write, filesystem corruption), cart_save returns #f (already specified at the FFI signature — Bool return). cart_load returns #f on read failure. Cart authors check the return value as they always have; the contract does not change. Corrupted save handling already lives in cartridge-lifecycle.md §“Edge cases” — runtime renames to .sav.corrupt and offers a fresh save.
deck-state and the read accessors (get-handle, get-credits, get-reputation, has-capability): always succeed against the in-memory UDS struct, whether or not the device microSD is reachable. Persistence is the runtime’s problem; reads are always served.

Recovery path. Cart insert (case a) → cart insert with a valid cart (cases b/c) → udev add → normal lifecycle. Device microSD failure recovery requires power-cycle plus filesystem repair off-device; this is a service event, not an operator-recoverable mode.

3. Low battery

Trigger. The battery-monitor path described in device/hardware/power.md §“Low-battery behaviour” reads pack voltage/current/power from the UPS module’s onboard INA219 over I²C at ~1 Hz (per ADR-0038). Two thresholds:

Warning threshold. Initial value: 15% remaining capacity (estimated from the 3S pack voltage curve, 9.0–12.6 V). Final value confirmed at bring-up Stage 4 (device/hardware/power.md §Bring-up) — this is the operator-observable threshold and is tunable per real measurement against the 18650 pack. The number above is the v0.1 starting point, not a fixed design constant.
Critical threshold. Initial value: 5% remaining capacity (well above the UPS module’s S-8254AA protection cut). Same bring-up tuning applies.

Final thresholds land in /home/shared/nosh-config.toml alongside the existing accelerometer ambient-glitch setting (per ADR-0023), as [power] battery_warning_pct and [power] battery_critical_pct.

Runtime behavior.

At warning threshold:
- Row 0 indicator: the firmware status bar renders a low-battery glyph (per device/hardware/power.md §“Low-battery behaviour” item 1) plus a remaining-percentage readout. Glyph + readout persist until the operator charges or the deck powers off.
- CIPHER-LINE dim: the auxiliary OLED contrast register drops to a reduced level (suggested initial value: 40% of normal — tuned at bring-up). CIPHER voice continues; the surface is just dimmer to save the OLED’s contribution to draw.
- Animation cap: the display render loop’s animation frame rate caps at 15 fps (down from the runtime’s normal 30 fps event-driven cap; nOSh runtime is event-idle most of the time anyway, see software/cartridges/authoring/lisp-paradigm.md on event-driven redraw). Idle CPU draw drops; animated cart UI degrades visibly but legibly. The 15 fps value is the v0.1 starting point; bring-up may adjust.
At critical threshold:
- Cart notification (opt-in): if the active cart has subscribed (see cart-facing contract below), the runtime pushes a synthetic event (low-battery-event :level :critical :remaining-pct N) to the cart’s event handler via the standard event-dispatch path. Cart has one render tick (~67 ms at the capped 15 fps) to commit phase state, write a save snapshot via cart_save, and return.
- Best-effort deckstate checkpoint: the runtime writes UDS to the device microSD per device/hardware/power.md §“Low-battery behaviour” item 2. Phase chain is serialized so missions can resume on next boot.
- Clean shutdown: the runtime issues a SIGTERM-equivalent shutdown (see device/hardware/power.md §“Low-battery behaviour” item 3) before the UPS module’s S-8254AA protection cut fires.

Cart-facing contract: subscribed events, not exceptions. Carts that want to handle low-battery proactively (e.g., a long-form Null diagnostic, a Cipher Garden encryption session) subscribe at cart-init time via the existing event-handler registration pattern. Events delivered:

(low-battery-event :level :warning :remaining-pct N) — fired once on the warning-threshold crossing. Carts may update internal UI or pre-commit state. Not authoritative — the runtime has already started showing the Row 0 glyph and dimmed CIPHER-LINE before the event fires.
(low-battery-event :level :critical :remaining-pct N) — fired once on the critical-threshold crossing. Cart has one render tick to checkpoint; runtime then proceeds to clean shutdown whether or not the cart returned.

Carts that do not subscribe see no change in their event stream. Their cart_save writes during normal flow already get flushed at UNMOUNTING per cartridge-lifecycle.md, and a power-off cleanly drives UNMOUNTING the same way an eject does.

Recovery path. Plug in the 12.6 V barrel-jack charger. The Waveshare UPS Module 3S charges the 18650 pack and, as a true UPS (charge + output simultaneously per device/hardware/power.md §“Power path”), continues to power the rail without interruption. As the INA219 sees pack voltage rise above the warning threshold + hysteresis margin, the runtime clears the Row 0 glyph, restores CIPHER-LINE contrast, and uncaps the frame rate. No cart-facing event on recovery — the cart sees only the absence of further low-battery-event pushes.

4. Window below 80×25 cells (emulator only)

Trigger. The SDL window is resized below the runtime’s required minimum (logical 960×600 pixels per the canonical 80×25 grid at 12×24 cells; emulator default scale is 3× — see the hosts/emulator/ README if needed). This path exists exclusively on the desktop emulator. The device firmware boots into kiosk mode with a fixed Elecrow 7” IPS at 1024×600 and physically cannot reach a sub-spec resolution.

Runtime behavior.

Refuse to draw. The emulator does not attempt to render a smaller-than-spec frame. No degraded layout, no scrollbars, no partial grid. The doctrine: the 80×25 grid is the contract; sub-spec rendering is a worse failure than not rendering.

Stderr message. Clear human-readable error written to stderr with the actual and required dimensions, e.g.:

kn86emu: window 800x500 below required 960x600 (80x25 cells at 12x24 px)
kn86emu: see CLAUDE.md Canonical Hardware Specification + docs/software/runtime/orchestration.md §Graceful Degradation

Exit cleanly with non-zero status. Process exit code 2 (or any documented non-zero — actual value is the emulator implementation’s call). No SDL panic, no segfault, no half-torn surface. SDL teardown runs through the normal shutdown path.

Cart-facing contract. Inapplicable — no cart code runs in this state. The emulator exits before reaching the cart-load path.

Recovery path. The operator resizes the window above the minimum and re-launches. There is no in-process recovery; resize-back-up is not a supported transition. The constraint exists exclusively to prevent silent rendering of an out-of-spec grid.

Device-side note. On the prototype hardware, the framebuffer is fixed at the Elecrow 7” IPS’s native 1024×600 (with the 32 px horizontal letterbox per side that the canonical spec accounts for). The kiosk-mode systemd unit (device/os/ per Platform Engineering) configures the framebuffer dimension at boot and the operator cannot resize it. This degradation mode is emulator-only by construction; device firmware never reaches this state.

Per-mode summary

Mode	Trigger	Runtime indicator	Cart-facing contract	Recovery
Coprocessor offline	3× missed heartbeats per coprocessor-bridge.md §5.3	Row 0 `LINK?` glyph; Row 24 `COPROCESSOR LINK DEGRADED`	Silent no-op on every `psg-` / `sound-` / `sfx-` / `cipher-` / `aux-*` call	Automatic on heartbeat resume; OLED shadow replay; no cart-observable transition
microSD absent	No cart in slot, mount failure, or header rejection	Bare Deck Terminal HUD is the surface; `CART?` glyph on Row 0 for rejected-cart cases	`cart_save` / `cart_load` return `#f`; deck-state reads always served from in-memory UDS	Cart insert with a valid cart
Low battery	ADC ~1 Hz pack-voltage sample crosses 15% warning / 5% critical (thresholds tunable at bring-up)	Row 0 low-battery glyph + percentage; CIPHER-LINE dim; 15 fps cap	Opt-in `(low-battery-event :level :warning/:critical :remaining-pct N)` events to subscribed carts only	Plug in USB-C charging
Window < 80×25 (emulator only)	SDL window resize below logical 960×600	stderr error message	Inapplicable — exits before cart loads	Resize window, re-launch

Cart-author guidance — what to assume

Hardware can disappear; the cart does not. If audio goes silent or CIPHER-LINE blanks mid-session, the cart keeps running. The runtime is hiding broken hardware so the cart doesn’t have to. Don’t write defensive wrappers around psg-* / aux-* calls for v0.1.
Save-failure is the one I/O failure carts handle directly. cart_save returns Bool; that has always been the contract. A #f return means the cart’s filesystem write failed (cart pulled mid-write, filesystem corruption, write-protected media). Surface it through your own UI; the runtime owns the bare-deck-level error string but does not interpose on a cart’s save flow.
Low-battery is opt-in. Most carts don’t need to react. The runtime handles the dimming, the indicator, and the shutdown. Subscribe to low-battery-event only if you have state worth checkpointing inside a render tick — most launch-library carts (NeonGrid, ICE Breaker, the puzzle / mission modules) checkpoint at phase boundaries which the runtime drives on shutdown anyway, and they don’t need the event.
Bare-deck-state is genuine state. A cart-absent device is not “between sessions” — it is a complete operating mode with its own bounties, macro slots, and link surface. Carts that interact with bare-deck (relay updates per the Relay module section, link-handshake carts) treat the bare-deck UDS fields as authoritative.

Cross-references

FFI reference: software/api-reference/nosh-api/primitives-by-category.md §“Degradation contracts” carries a per-primitive note (“silent no-op when LINK_DEGRADED”, “returns #f on filesystem failure”, etc.) with a back-pointer to this section.
Coprocessor link state machine: coprocessor-bridge.md §5 (frame resync, command-timeout handling, degraded state, full-restart escalation).
Cartridge lifecycle (mount / unmount / corrupt save / unsafe pull): cartridge-lifecycle.md §“Edge cases”.
Universal Deck State persistence: deck-state.md §“Persistence”.
Panic recovery (cart-internal faults, distinct from these subsystem degradations): panic-recovery.md. Panic recovery handles cart-side SIGSEGV / fe_error / (panic); graceful degradation handles hardware-side subsystem failure. They are complementary, not overlapping.
Power topology + low-battery glyph spec: device/hardware/power.md §“Low-battery behaviour”.

Software Publishers & Loading Screens

The KN-86 software library was not developed by a single studio. Like the real 1980s computing ecosystem, Kinoshita Electronics licensed the Deckline platform to outside software firms. Each publisher brought a different origin, reputation, and aesthetic. The publisher’s identity is the first thing the operator sees when a cartridge loads — before the nOSh runtime parses templates, before the mission board appears, the publisher makes their mark.

The Loading Sequence

When the nOSh runtime detects a new cartridge insert and completes header parsing, it calls the cartridge’s publisher_splash() function. This function has exclusive access to the display and PSG for up to 3 seconds. It draws the publisher’s animated logo and plays an audio sting. Then control returns to the nOSh runtime for mission board generation.

The loading screen is stored in the cartridge’s code section. It is the publisher’s signature — the moment the operator knows who made this software and what world they are entering. In the emulator, loading screens play identically. In linked play, both operators see their own cartridge’s publisher splash during the handshake.

The Publishers

EDGEWARE SYSTEMS CO., LTD. — Tokyo

Founded: 1980, as KEC’s captive software development division. Published: NeonGrid, The Vault, Null, Relay. Reputation: First-party. Professional. Safe. Edgeware titles are the ones you give to a new operator.

Edgeware is KEC’s own studio — the software arm of the hardware maker. Their modules are polished, documented, and conservative. NeonGrid ships as the introductory title because Edgeware knows how to teach. The Vault is a reference tool. Null is a diagnostic suite. The Relay module is an infrastructure play. Nothing Edgeware publishes will get anyone in trouble.

Loading screen: The Edgeware wordmark assembles character by character across the center of the screen, left to right, in the standard 8x8 monospace font. Each character appears with a soft keyclick on Channel C (1ms, 800Hz). When the last character lands, a single clean tone sounds on Channel A (440Hz, 200ms decay). Below the wordmark: A KINOSHITA ELECTRONICS COMPANY. The whole sequence takes 2 seconds. Restrained. Corporate. Exactly what you’d expect from first-party software.

                    ╔══════════════════════════════╗
                    ║                              ║
                    ║     E D G E W A R E          ║
                    ║     SYSTEMS CO., LTD.        ║
                    ║                              ║
                    ║  A KINOSHITA ELECTRONICS CO.  ║
                    ║                              ║
                    ╚══════════════════════════════╝

ZAIBATSU DIGITAL — Osaka (no listed address)

Founded: 1985. Three expelled Osaka University computer science students. Published: ICE Breaker, Shellfire. Reputation: Notorious. Brilliant. Possibly criminal. The best software on the platform.

Nobody knows how Zaibatsu secured an official KEC publishing license. Rumors range from a personal connection to KEC’s CTO to outright blackmail involving security vulnerabilities they discovered in the nOSh runtime. Their cartridges were sold in black shrink-wrap with no box — just a folded sheet of key mappings on matte black paper with white ink. No customer support number. No mailing address. ICE Breaker is the best-selling Deckline title of all time and the reason most operators bought the hardware. Zaibatsu’s two employees (three, if you count the one who went to prison in 1990) understood network topology better than anyone in Japan’s software industry.

Loading screen: A rapid hex dump fills the entire 80x25 screen from top-left, scrolling upward at high speed — actual bytes from the cartridge’s code section, rendered as hex pairs. The PSG plays harsh white noise (Channel A: noise period 3, full volume). After 1.5 seconds, the hex dump freezes. The center 12 lines dissolve into the Zaibatsu mark — a blocky, angular glyph that suggests a stylized kanji character but isn’t one. The noise cuts to dead silence. The mark holds for 1 second. Operators who have seen it never forget the sound of the hex dump stopping.

    4F 2A 7B 1C 00 FF A3 8D 2E 71 B4 C0 55 19 E6 3A
    D7 88 03 4C F1 9A 6E 22 B0 5D 8F 47 C3 1B 76 A9
    ...
                    ┌────────────────┐
                    │  ██  ████  ██  │
                    │  ██  █  █  ██  │
                    │  ████████████  │
                    │  ██  █  █  ██  │
                    │  ██  ████  ██  │
                    └────────────────┘
                      ZAIBATSU DIGITAL

BUREAU 9 TECHNICAL SERVICES — (no address on record)

Founded: Unknown. First Deckline title published 1989. Published: Black Ledger, Cipher Garden. Reputation: Government. The cartridge labels have no phone number, no logo, no address. Just “B9TS” in the copyright line.

Bureau 9 Technical Services does not have a website, a storefront, or a customer support line. Their cartridges appeared in KEC’s catalog in 1989 with no announcement and no press coverage. Black Ledger’s forensic accounting tools are suspiciously sophisticated — the transaction pattern matching algorithms are more advanced than anything available in commercial software at the time. Cipher Garden’s cryptographic toolkit includes cipher modes that were not publicly documented until 1991. The prevailing theory in the operator community is that Bureau 9 is a front for Japan’s Public Security Intelligence Agency, and these modules are declassified (or semi-classified) analytical tools repackaged for the Deckline platform. Nobody has confirmed this. Nobody has denied it either.

Loading screen: Dead silence. No PSG output at all. The screen is blank for 0.5 seconds. Then, in the top-left corner, text begins typing at a deliberate, mechanical pace — one character every 80ms:

    BUREAU 9 TECHNICAL SERVICES
    CLASSIFICATION: UNCLASSIFIED
    DISTRIBUTION: AUTHORIZED OPERATORS
    ────────────────────────────────────
    MODULE: BLACK LEDGER v2.1
    CLASS:  FORENSIC ACCOUNTING
    ────────────────────────────────────
    READY.

No animation. No logo. No sound. The absence is the signature. Operators describe Bureau 9’s loader as “the one that makes the room feel colder.” The classification header is fiction, but the operators who use Black Ledger at 2 AM in a dark room forget that.

PACIFIC RIM DYNAMICS — Yokohama

Founded: 1971. Defense electronics contractor. Published: Depthcharge, Drift, Pathfinder. Reputation: Military-industrial. Legitimate. Their sonar equipment is installed on JMSDF destroyers.

Pacific Rim Dynamics manufactures hydroacoustic sensors, signal processing hardware, and navigation systems for Japan’s Maritime Self-Defense Force. Their Deckline software division was a public relations experiment — “civilian applications of defense signal processing technology” — approved by their board in 1987 as a way to recruit engineering graduates who thought defense work was boring. It worked. Depthcharge’s sonar model is a simplified version of PRD’s actual target classification algorithm. The simplified version is still more sophisticated than anything else on the platform. PRD’s three Deckline modules share a common aesthetic: clean wireframe graphics, precise audio design, and an unmistakable sense that this software was made by people who build things that go underwater.

Loading screen: The bitmap display shows a sonar sweep — a single radial line rotates clockwise from a center point, leaving a fading trail. Channel A plays a sonar ping on each rotation (descending tone: 2000Hz to 400Hz, 150ms, with 50ms of reverb on Channel B). On the third sweep, the company name resolves letter by letter in the center of the sweep area, timed to the ping. Below: DEFENSE SIGNAL PROCESSING DIVISION. The sweep continues for one more rotation after the text appears, then fades. Total duration: 2.5 seconds. The ping sound becomes permanently associated with Depthcharge in the operator’s memory.

TAKEZO INSTITUTE — Kyoto

Founded: 1983. Kyoto University AI research lab spin-off. Published: Takezo, Nodespace. Reputation: Academic. Serious. Named after Miyamoto Musashi (born Shinmen Takezo). Their modules teach you to think.

The Takezo Institute started as a pattern recognition research group at Kyoto University’s Department of Intelligence Science and Technology. Their commercial arm was funded by a MITI grant to develop “applied cognitive training software for emerging personal computing platforms.” The grant paperwork lists the Deckline as the target platform. Takezo’s modules are the most cerebral in the library — tactical analysis and abstract strategy, both designed around the thesis that structured pattern recognition improves decision-making across all domains. The institute’s two founders are Go players (4-dan and 5-dan). This shows.

Loading screen: The bitmap display seeds a cellular automaton (a glider gun variant) in the top-left corner. Gliders propagate across the screen, leaving trails. Channel A plays a clean ascending major scale, one note per glider generation (C4, D4, E4, F4, G4 — each 100ms). After 8 generations (~1.5 seconds), the automaton halts. The living cells rearrange into the Takezo mark — a pattern that resembles a Go board position (a group of stones with two eyes). Below: TAKEZO INSTITUTE / KYOTO. A final clean tone (C5, 300ms) sounds. The whole sequence is mathematical and unhurried.

KOKAN SYSTEMS — Kobe

Founded: 1986. Grey-market software house. Published: SynthFence. Reputation: Port city hustle. The commerce people. “Kokan” means “exchange.”

Kokan Systems operates out of Kobe’s port district, two blocks from the commodity exchange. Their founder worked the Kobe trading floor before writing SynthFence as a personal tool to model commodity arbitrage. The tool was too good to keep private. Kokan’s one-module catalog makes them the smallest publisher on the platform, but SynthFence is the highest-revenue cartridge per operator — traders use it for real pattern analysis and the in-fiction economy is a thinly veiled model of actual commodity dynamics. Kokan’s aesthetic is pure commerce: no elegance, no philosophy, just the numbers.

Loading screen: A scrolling ticker tape of fictional commodity prices streams across the screen in text mode — four rows of rapidly updating prices (AU 847.20 +2.1 | AG 12.44 -0.3 | CU 1.82 +0.1 | ...). Channel C plays a rhythmic ticking sound like a stock ticker (8Hz clicks, 1ms each, very quiet). After 2 seconds, the ticker freezes. The prices dim (inverse video off) and the Kokan mark appears in the negative space: a simple rectangle with KOKAN inside, centered. Below: KOBE / EST. 1986. One final tick sound. Commercial. No pretension.

Outside Tier: Unlicensed Publishers

The six publishers above are all licensed — they hold a formal KEC publishing agreement and ship through KEC’s distribution network with KEC LICENSED badging on the cartridge label. A parallel outside tier exists for cartridges that reach operators through underground channels: pirate pressings, faction-run distribution, hand-to-hand exchange at operator meetups. Outside-tier publishers do not hold a license, do not appear in KEC’s official catalog, and cannot ship through licensed retail. Their cartridges carry the disclaimer UNLICENSED — KEC NOT RESPONSIBLE where a license badge would normally sit.

Outside-tier cartridges still use the standard .kn86 format and the full cartridge grammar. They register a PUBLISHER_SPLASH like any other cartridge. The nOSh runtime does not refuse to load them — the platform is open in this sense. But they are visibly and audibly distinct from licensed software, and operators who run them are making a choice about what kind of deck they want to carry.

SETEC ASTRONOMY — (no listed address; rumored Pacific Rim dual-node)

Founded: Unknown. First Deckline title circulated 1992. Published: Marty Glitch (outside-cart overlay). Reputation: Pirate label. Broadcast-piracy–adjacent. Widely suspected to be a Terminal Transmissions front rather than an independent publisher. The name is an obvious codeword — operators who recognize it don’t mention it out loud.

Setec Astronomy is not a studio in the conventional sense. There is no office, no staff roster, no bank account tied to the name. Cartridges bearing the Setec Astronomy imprint began appearing at operator meetups in late 1992 — first in Kobe, then Osaka, then a trickle westward across the Pacific. The distribution pattern suggests a single pressing run of a few hundred units, later copied informally by operators onto blank cartridges. The label’s only known release, Marty Glitch, is a parasitic overlay cartridge that hijacks the Cipher voice layer rather than providing its own operational capabilities; this fits no commercial software model and strongly implies Setec Astronomy exists solely to distribute Terminal Transmissions’s persona carts. The name itself — rearrangeable to a more honest thirteen-letter phrase — is considered by operators who have noticed to be either a wink or a warning, depending on mood. Officially, KEC has issued no statement regarding Setec Astronomy. Unofficially, two Edgeware engineers have reportedly said, on separate occasions, “we don’t know who they are and we’d rather not find out.”

Loading screen: A three-beat hijack animation, 3.000 seconds total (90 frames at 30 fps). Beat 1 mimics an Edgeware-style clean wordmark assembly — SETEC ASTRONOMY with the subline A KINOSHITA ELECTRONICS COMPANY — for 40 frames, with standard 800 Hz keyclicks on Channel C. Beat 2 begins with a scanline tear and a burst of white noise on Channel A (noise period 3, full volume); the subline shatters off the bottom of the screen, and the thirteen glyphs of the wordmark rearrange in place along choreographed linear paths to read TOO MANY SECRETS, held for 25 frames against a wobbling detuned C5 on Channel B (±15 Hz FM at 4 Hz). Beat 3 tears again and rearranges the letters back to SETEC ASTRONOMY, replacing the fake subline with a mechanical typeout of UNLICENSED — KEC NOT RESPONSIBLE at 12 ms per character. The splash is deliberately structured to read as a malfunction on first viewing and an anagram reveal on second. No other cartridge in the library — licensed or outside — performs a letter-rearrangement animation.

                    ┌──────────────────────────────┐
                    │                              │
                    │      SETEC ASTRONOMY         │
                    │    (anagram rearranges to)   │
                    │      TOO MANY SECRETS        │
                    │         (and back)           │
                    │                              │
                    │  UNLICENSED — KEC NOT RESP.  │
                    │                              │
                    └──────────────────────────────┘

(The above schematic shows the resolution states; see the Marty Glitch Gameplay Spec §“Publisher Splash” for the full frame-by-frame animation.)

Publisher Distribution Across the Full Library

Licensed Tier

Module	Publisher	Publisher Type
ICE Breaker	Zaibatsu Digital	Underground collective (licensed)
NeonGrid	Edgeware Systems	KEC first-party
Black Ledger	Bureau 9 Technical Services	Shadow government
Depthcharge	Pacific Rim Dynamics	Defense contractor
Shellfire	Zaibatsu Digital	Underground collective (licensed)
Takezo	Takezo Institute	University research
SynthFence	Kokan Systems	Grey-market commerce
Nodespace	Takezo Institute	University research
Drift	Pacific Rim Dynamics	Defense contractor
Pathfinder	Pacific Rim Dynamics	Defense contractor
The Vault	Edgeware Systems	KEC first-party
Cipher Garden	Bureau 9 Technical Services	Shadow government
Null	Edgeware Systems	KEC first-party
Relay	Edgeware Systems	KEC first-party

Outside Tier (Unlicensed)

Module	Publisher	Publisher Type
Marty Glitch	Setec Astronomy	Pirate label / Terminal Transmissions front

Why Publishers Matter

The publisher layer does three things:

First, it makes cartridges feel like they came from somewhere. The Deckline is not a monolithic KEC product — it is a platform with an ecosystem. Six licensed publishers plus an outside tier, each with different motivations for writing software for a cyberdeck. This parallels real 1980s computing, where Broderbund, Activision, and LucasArts each had unmistakable identities — and where pirate pressings and unlicensed carts circulated alongside the licensed catalog.

Second, it gives operators something to notice and develop opinions about. “Zaibatsu’s loader is so harsh.” “Bureau 9 gives me the creeps — why is there no sound?” “Pacific Rim’s ping is the best sound on the platform.” These micro-responses build attachment to the fiction.

Third, it creates worldbuilding questions that pull operators deeper. Why does a defense contractor publish Deckline software? Why does Bureau 9 have no address? What happened to the Zaibatsu member who went to prison? These questions are never answered in the software. They are answered in the lore — in build logs, cartridge labels, KEC history documents, and the Edgeware expanded universe. The loading screen is the hook. The fiction is the line.

Technical Implementation

The publisher splash is stored in the cartridge’s code section and registered via the Lisp authoring surface (ADR-0001). Cart authors use the publisher-splash NoshAPI primitive, passing a lambda that receives the frame counter and returns non-nil when the splash is complete. Cross-reference GWP-256 (publisher_splash hook implementation).

(publisher-splash
  (lambda (frame)
    (text-puts 30 12 "EDGEWARE SYSTEMS CO., LTD.")
    (when (< frame 60) (sfx-keyclick))
    (>= frame 60)))  ; return non-nil to signal "done"

The nOSh runtime calls the splash lambda at 30 fps for up to 3 seconds (90 frames maximum). The cartridge controls the animation. The nOSh runtime enforces the time limit — after 3 seconds, it cuts to the mission board regardless. Most publishers use 2–2.5 seconds. Bureau 9 uses exactly 2.8 seconds. Zaibatsu uses the full 3. Setec Astronomy also uses the full 3 — the only outside-tier publisher, and the only publisher whose splash executes a choreographed letter-rearrangement animation.

Cartridge Code Execution Model

Cartridge code is Lisp source, parsed and tree-walked by the Fe interpreter (ADR-0001, ADR-0004; AOT bytecode deferred), packaged in the .kn86 container (ADR-0006). The nOSh runtime loads the source from the cartridge’s SD card filesystem and evaluates it in a KEC Lisp context (the kec-lisp language, fetched at build per ADR-0041; mark-sweep GC over a fixed arena — no heap growth; arena resets at cart-load and mission-instance boundaries). Cart authors write .lsp s-expressions and never touch C — the NoshAPI FFI (ADR-0005) binds the device primitives onto the Fe context as Lisp builtins.

The vtable / function-table architecture described below is the internal runtime mechanism that bridges Lisp FFI calls to C implementations. It is invisible to cart authors. The nosh_cart.h C macro surface (CELL_TYPE, ON_CAR, etc.) is an internal handler-registration contract, not the authoring surface — the C Cartridge Grammar section below describes this internal seam for runtime engineers.

nOSh Runtime Function Table (vtable)

Cartridge code calls nOSh runtime functions through a pointer table provided at load time. This decouples nOSh runtime versions from cartridge binaries — the nOSh runtime can be updated without recompiling cartridges, and cartridges compiled against any nOSh runtime version that supports the vtable ABI will work.

typedef struct {
    /* Display */
    void (*text_puts)(uint8_t col, uint8_t row, const char *str);
    void (*text_putc)(uint8_t col, uint8_t row, char c);
    void (*text_clear)(void);
    void (*gfx_pixel)(uint16_t x, uint8_t y, bool on);
    void (*gfx_line)(uint16_t x0, uint8_t y0, uint16_t x1, uint8_t y1);
    void (*gfx_rect)(uint16_t x, uint8_t y, uint16_t w, uint8_t h, bool filled);
    void (*gfx_circle)(uint16_t cx, uint8_t cy, uint8_t r);
    void (*gfx_blit)(uint16_t x, uint8_t y, const uint8_t *bitmap, uint16_t w, uint8_t h);
    void (*gfx_clear)(void);

    /* Sound */
    void (*psg_write)(uint8_t reg, uint8_t val);
    void (*sound_tone)(uint8_t ch, uint16_t freq, uint8_t vol);
    void (*sound_silence)(void);

    /* Economy */
    void (*credit_add)(int32_t amount);
    void (*credit_deduct)(int32_t amount);
    void (*rep_modify)(int16_t delta);

    /* Navigation */
    void (*drill_into)(CellBase *target);
    void (*navigate_back)(void);
    void (*next_sibling)(void);
    CellBase *(*current_cell)(void);
    void (*set_root)(CellBase *root);

    /* Cell pool */
    void *(*spawn_cell)(uint16_t type_id);
    void (*destroy_cell)(void *cell);

    /* LFSR */
    uint32_t (*lfsr_next)(void);
    uint32_t (*lfsr_range)(uint32_t min, uint32_t max);

    /* Deck state */
    DeckState *(*deck_state)(void);
    bool (*has_capability)(uint8_t bit);

    /* Save */
    bool (*cart_save)(const void *data, uint32_t size);
    bool (*cart_load)(void *data, uint32_t size);

    /* Version */
    uint16_t api_version;           /* Increments on breaking changes */
} NoshAPI;

The nOSh runtime passes a pointer to NoshAPI when calling the cartridge’s init function. The nosh_cart.h macro layer hides this indirection — cartridge authors write nosh_text_puts(...) which expands to _nosh_api->text_puts(...). This is the standard pattern for embedded plugin systems (BIOS call tables, EFI boot services, dynamic linking without an OS loader).

On both emulator and device (where cartridge code loads via dlopen), the vtable is populated with direct function pointers to the nOSh API. The vtable eliminates the need for a nOSh runtime symbol table — cartridge binaries never contain nOSh runtime addresses, and the ABI contract is explicit at the function-table level.

Coprocessor Seam (per ADR-0017)

On the prototype hardware, the Pi Zero 2 W delegates two categories of I/O to the Raspberry Pi Pico 2 (RP2350) coprocessor over a UART command link (GPIO14/15, 1 Mbps). The vtable / FFI surface is unchanged — cart authors call psg-reg, sfx-keyclick, cipher-emit, etc. exactly as documented in ADR-0005. The Pi-side CoprocessorAPI (implemented in runtime/src/coproc.c, landed in GWP-250) is the marshaling layer between the NoshAPI call sites and the UART wire.

Audio (psg-*, sound-*, sfx-* primitives): marshaled over UART to the Pico 2, which owns the full YM2149 register state and generates 44.1 kHz mono PCM via I2S out to the MAX98357A. The Pi sends register-write commands; the Pico synthesizes.
OLED (cipher-emit, aux-* primitives): marshaled over UART to the Pico 2, which owns the SSD1322 SPI driver and runs the CIPHER-LINE ticker animation autonomously on its own timer.
Desktop emulator path: the coproc.c stub routes the same calls in-process to psg.c and oled.c for full parity without real hardware. Cart authors and the emulator are identically served.

The coprocessor does not see the cartridge — cartridge loading, cart code execution, and SD card access all remain on the Pi (ADR-0019). The Pico 2 is a realtime I/O front-end, not a compute participant.

Platform Abstraction Layer — Link Protocol

The nosh_platform.h HAL includes link/UART abstraction alongside the existing display, audio, input, storage, and time groups:

/* Link protocol — UART serial over TRRS */
bool platform_link_init(void);
bool platform_link_send(const uint8_t *data, uint32_t len);
uint32_t platform_link_recv(uint8_t *buf, uint32_t max_len);
bool platform_link_connected(void);

Implementations: platform_linux.c uses /dev/ttyUSB* on the device; platform_sdl2.c provides a loopback stub for testing.

What Does NOT Change

The capability model is a software architecture decision. It changes what the nOSh runtime does and how cartridges relate to it. It does not change:

Hardware architecture (Pi Zero 2 W + Pico 2 coprocessor, per CLAUDE.md Canonical Hardware Specification)
Display spec (Elecrow 7” IPS 1024×600 surface, per-region cell density via integer-scaled 8×8 glyphs with 128×75 as the 1× cell ceiling, AMBER #E6A020 on black with WHITE / GREEN selectable per ADR-0036 and ADR-0034)
Key layout (34 physical keys on a Ferris Sweep split: 14 Lisp primitives (incl. EVAL on left inner thumb) + 1 LSHIFT on left outer thumb + 13 right-half digit/punctuation primaries + 0 on right inner thumb + TERM on right outer thumb + 2 v2 spares + ENT — finalized in ADR-0031, function-block keycap legends preserved from ADR-0022 §1)
Audio architecture (YM2149 PSG synthesis, owned by Pico 2 coprocessor on device; in-process on emulator)
C cartridge grammar (nosh_cart.h macros, nosh_runtime.c dispatcher, nosh_stdlib.c standard library — internal runtime seam; cart authoring surface is Lisp per ADR-0001)
Platform abstraction layer (nosh_platform.h with linux/sdl2 implementations — now includes platform_link_* for UART abstraction)
Cartridge physical format (full-size SD card in two-piece clamshell shell, read via USB mass storage — ADR-0019)
Link protocol (UART serial over TRRS)
Enclosure (Pelican 1170 Protector Case with custom 3D-printed inset panels — per CLAUDE.md Canonical Hardware Specification)

The game logic, key mappings, data structures, sound design, and interaction patterns for each title remain the same. What changes is their relationship to the nOSh runtime — they are modules called by nOSh, not programs that nOSh launches and hands off to.

nOSh Orchestration

Design Intent

Table of Contents

Universal Deck State

The Mission Board

Multi-Phase Missions & Cartridge Swapping (Hot Swap)

Phase Chain Protocol

Software Library as Capability Modules

Operations Modules

Commerce Modules

Navigation Modules

Strategy Modules

Passive Enhancement Modules

System Modules

Module Registration

Cartridge Contribution Model

CIPHER-LINE as First-Class Platform Output Surface

Cross-Program Integration

How It Works

Examples

Design Principle

Scaling beyond hand-authored pairs

The Capability Curve

One Cartridge

Four Cartridges (The Launch Library)

Full Library (14 Modules)

The Curve Is Not a Gate

The Cipher Voice

Grammar Engine (Summary)

Vocabulary Registration

When the Cipher Voice Speaks

Tone

C Cartridge Grammar

Three Layers

Capability Model Extensions

Cartridge–nOSh Runtime Interface

Relay Module

How It Works

What It Cannot Do

Cartridge Provenance

Provenance Chain Structure

Event Types

Properties

Why It Matters

Cartridge SD Card Layout

SD Filesystem Layout

Graceful Degradation

1. Coprocessor offline

2. microSD absent

3. Low battery

4. Window below 80×25 cells (emulator only)

Per-mode summary

Cart-author guidance — what to assume

Cross-references

Software Publishers & Loading Screens

The Loading Sequence

The Publishers

EDGEWARE SYSTEMS CO., LTD. — Tokyo

ZAIBATSU DIGITAL — Osaka (no listed address)

BUREAU 9 TECHNICAL SERVICES — (no address on record)

PACIFIC RIM DYNAMICS — Yokohama

TAKEZO INSTITUTE — Kyoto

KOKAN SYSTEMS — Kobe

Outside Tier: Unlicensed Publishers

SETEC ASTRONOMY — (no listed address; rumored Pacific Rim dual-node)

Publisher Distribution Across the Full Library

Why Publishers Matter

Technical Implementation

Cartridge Code Execution Model

nOSh Runtime Function Table (vtable)

Coprocessor Seam (per ADR-0017)

Platform Abstraction Layer — Link Protocol

What Does NOT Change