nOSh Orchestration

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 flash. 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.

---

Table of Contents

1. Universal Deck State
2. The Mission Board
3. Multi-Phase Missions & Cartridge Swapping
4. Software Library as Capability Modules
5. Cross-Program Integration
6. The Capability Curve
7. The Cipher Voice
8. C Cartridge Grammar
9. Relay Module
10. Cartridge Provenance

---

Universal Deck State

The persistent identity of the deck — operator handle, credits, reputation, cartridge history, phase chain, Cipher voice state. Lives in device flash, 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

The mission board is a nOSh runtime feature, not a cartridge feature. It is the primary tab the operator sees after boot (the MISSIONS tab within the Bare Deck Terminal hub — see KN-86-Bare-Deck-Terminal-Spec.md; supersedes the archived KN-86-Home-Screen-Design.md). The nOSh runtime generates contracts from cartridge-provided mission template structures, seeded by Universal Deck State values (reputation, credit balance, cartridge history bitfield, LFSR state).

How It Works

1. On boot (or cartridge insertion), the nOSh runtime reads mission template structures from the loaded cartridge’s template region in flash.
2. The nOSh runtime’s contract generator combines templates with deck state to produce a board of 4–8 available contracts.
3. Each contract specifies: description, threat level, payout, required phases, required capabilities per phase, bonus conditions, and Cipher commentary.
4. The operator navigates the board with CAR/CDR, inspects contracts with INFO, and bids on a contract with EVAL.
5. When a contract is accepted, the nOSh runtime initiates the first phase.

Contract Generation

The contract generator uses a seeded LFSR (the Cipher seed from deck state) combined with template parameters:

contract_seed = lfsr_advance(cipher_seed, template_id)
threat_level  = base_threat + reputation_modifier(reputation)
payout        = base_payout × threat_multiplier × economy_modifier(credit_balance)
phase_count   = template.min_phases + lfsr_range(contract_seed, template.phase_variance)

Reputation affects threat range. Low-reputation operators see threat 1–3 contracts. As reputation climbs, the board generates threat 4–6 contracts with higher payouts and multi-phase requirements. The operator cannot grind easy contracts forever — the economy pushes upward.

Credit balance affects payout scaling. When the operator is flush, payouts compress slightly. When broke, the board is more generous with single-phase, quick-payout contracts. The economy self-corrects without being punitive.

Cartridge history affects template availability. Single-capability contracts are always available. Multi-phase contracts (requiring cartridge swaps) only appear when the cartridge history bitfield shows the operator has loaded the required modules at least once. The nOSh runtime will not generate a contract the operator cannot complete.

Board Refresh

The mission board refreshes when:

• A contract is completed (the completed contract is replaced)
• A contract is abandoned (the abandoned contract is replaced with a lower-threat alternative)
• A new cartridge is inserted (new templates are parsed, board regenerates with expanded template pool)
• The operator explicitly requests a refresh (SYS → Refresh Board — costs a small reputation penalty)

---

Multi-Phase Missions & Cartridge Swapping (Hot Swap)

Contracts that span multiple capability domains are multi-phase missions. Each phase requires a specific capability module. The nOSh runtime manages the phase chain — the sequence of phases, the required capability for each, and the serialized state between phases. 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

Phase 1: ICE BREAKER (NETWORK INTRUSION)
  ↓ phase completes → runtime serializes intermediate state to phase_chain
  ↓ runtime displays: > PHASE 2 REQUIRES: FORENSIC ACCOUNTING
  ↓                   > INSERT: BLACK LEDGER
  ↓ operator physically swaps cartridge → see cartridge-lifecycle.md
Phase 2: BLACK LEDGER (FORENSIC ACCOUNTING)
  ↓ runtime reads phase_chain, passes context to cartridge handler
  ↓ phase completes → runtime updates phase_chain
  ↓ runtime displays: > CONTRACT COMPLETE
  ↓                    > PAYOUT: 4,800 ¤
  ↓                    > REPUTATION: +12
Debrief: Cipher voice summary

---

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

Navigation Modules

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:

1. Reads the cartridge header (capability_bits field)
2. Sets the corresponding bit in cartridge_history if not already set
3. Reads mission template structures from the template region
4. 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.
5. Registers the module’s phase handlers with the nOSh runtime’s dispatch table
6. Generates the mission board using the combined template 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)
Mission templates	Procedural contract generation structures	nOSh runtime mission board
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
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.

---

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). Per ADR-0001 and ADR-0004, cartridges are now authored in Lisp, compiled to Fe bytecode. The C grammar below describes the runtime handler-registration contract — the surface that Lisp-compiled cartridges bind to inside nOSh — not the authoring surface. See adr/ADR-0001-embedded-lisp-scripting-layer.md for the canonical authoring reference.

1. 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.

2. 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.

3. 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, initiates phases, and calls into cartridge handlers when a phase is active. When a phase completes, control returns to the nOSh runtime for phase chain updates, debrief, and the next phase or payout.

nOSh runtime main loop:
  1. Read input events
  2. If on mission board → handle board navigation (CAR/CDR/EVAL/INFO)
  3. If phase active → call cartridge phase handler tick
  4. If phase complete → serialize phase chain, run debrief, advance to next phase or payout
  5. Render display
  6. Loop

The cartridge interface is bidirectional. The nOSh runtime reads templates and data from the cartridge. The cartridge’s event handlers are called by the nOSh runtime. The cartridge writes to its own save region and the nOSh runtime writes to the provenance chain region.

---

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

1. The operator connects the deck to a computer via USB.
2. A desktop utility writes update data to the Relay cartridge’s flash (new mission templates, Cipher vocabulary expansions, balance patches, community-created content).
3. The operator inserts the Relay cartridge into the deck.
4. The nOSh runtime reads the update manifest from the Relay’s template region.
5. Updates are applied: new templates are merged into the nOSh runtime’s template database, Cipher vocabulary is expanded, economy parameters are adjusted.
6. The Relay cartridge’s provenance chain 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 flash — the cartridge remembers everything that has happened to it. This is not save data. It is a separate, nOSh runtime managed system with its own flash region and wear-leveling strategy.

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 region. 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 chain region has its own wear-leveling, independent of the save region.
• The chain_offset field in the cartridge header identifies where the provenance region begins in flash.

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 Flash Layout

The updated flash layout for capability model cartridges:

Region	Offset	Size	Contents
Header	0x0000	256 bytes	Cartridge identity, capability declaration, region offsets
Code	0x0100	Variable	Program code (cell definitions, event handlers, phase logic)
Data	Variable	Variable	Behavior tables, tool definitions, generation parameters
Templates	template_offset	template_size	Mission template structures (parsed by nOSh runtime for board generation)
Cipher Domain	Variable	Variable	Domain-specific word tables for the Cipher voice
Save	Variable	save_size	Per-cartridge save data (tool inventory, mission history, discovered patterns)
Provenance Chain	chain_offset	Remaining	Sequential hash chain blocks (32 bytes each, nOSh runtime managed)

Updated Cartridge Header

typedef struct {
    char     magic[4];           /* "KN86" — identifies valid cartridge */
    uint8_t  version;            /* Header format version (2 for capability model) */
    char     program_name[16];   /* e.g., "ICE_BREAKER" */
    char     display_name[24];   /* e.g., "ICE Breaker v1.3" */
    char     module_class[16];   /* e.g., "NETWORK INTRUSION" */
    uint16_t capability_bits;    /* Bitfield: capabilities this module provides (PRIMARY) */
    uint16_t requires_bits;      /* Bitfield: capabilities needed for full experience (PRIMARY) */
    uint32_t code_offset;        /* Byte offset where executable code begins */
    uint32_t code_size;          /* Size of executable code in bytes */
    uint32_t data_offset;        /* Byte offset where game data begins */
    uint32_t data_size;          /* Size of game data */
    uint32_t template_offset;    /* Byte offset where mission templates begin */
    uint32_t template_size;      /* Size of mission template section */
    uint32_t chain_offset;       /* Byte offset where provenance chain begins */
    uint32_t save_size;          /* How many bytes this cartridge needs for save data */
    uint8_t  lfsr_seed[4];       /* Default LFSR seed for procedural generation */
    char     glyph_map[94];      /* Glyph-to-domain-verb reference text (reduced 2 bytes for uint16_t fields) */
    uint8_t  reserved[16];       /* Future expansion */
    uint16_t checksum;           /* CRC-16 of header */
} CartridgeHeader; /* 256 bytes */

The capability_bits and requires_bits fields 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.

---

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 cartridge grammar:

PUBLISHER_SPLASH {
    ON_SPLASH_INIT  { /* seed animation state */ }
    ON_SPLASH_FRAME { /* draw one frame; return false when done, true to continue */ }
    ON_SPLASH_AUDIO { /* PSG register writes for the audio sting */ }
}

The nOSh runtime calls ON_SPLASH_FRAME at 30fps 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

On both the desktop emulator and the Pi Zero 2 W device, cartridge code is compiled to a shared library and loaded via dlopen (or compiled into the host binary for closed builds). The nOSh runtime and cartridge communicate through a well-defined function table rather than direct symbol resolution, so nOSh runtime versions and cartridge binaries can evolve independently.

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.

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, per CLAUDE.md Canonical Hardware Specification)
• Display spec (Elecrow 7” IPS 1024×600, 80×25 text mode, amber #E6A020 on black)
• Key layout (30-key layout with ATOM/EQ, 14 function + 16 numpad)
• Audio architecture (YM2149F PSG emulation)
• C cartridge grammar (nosh_cart.h macros, nosh_runtime.c dispatcher, nosh_stdlib.c standard library)
• Platform abstraction layer (nosh_platform.h with linux/sdl2 implementations — now includes platform_link_* for UART abstraction)
• Physical cartridge hardware (W25Q128 SPI flash on card-edge PCB)
• Link protocol (UART serial over TRRS)
• Enclosure approach (3D-printed PETG, GBA SP hinges)

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.