Sprint 4 Design Pack — GWP-261

Story narrative

docs/software/runtime/orchestration.md is the (renamed) Capability Model Spec — the load-bearing architecture doc that every cart author and every nOSh-runtime engineer reads first. It still ships several pre-ADR-0019 / pre-ADR-0017 / pre-ADR-0001 surfaces in its body even though the ADRs that obsoleted them landed and ticked their own Documentation Updates boxes. Three drift sites identified during the wave-1 read of the file:

1. Cartridge Flash Layout (L429–467 in current file) — the table still describes a flash-region offset model (Header @ 0x0000, Code @ 0x0100, Templates @ template_offset, Save @ save_size, Provenance Chain @ chain_offset) and the C CartridgeHeader struct with chain_offset/save_size/template_offset fields. ADR-0019 moved cartridge storage to a USB-MSC SD card with a filesystem layout (/save/<cart_id>.sav, no flash regions, no MBC5-style offsets). The flash layout is now a stale fiction.
2. Cartridge Provenance section (L385–425) — describes provenance as “a separate, nOSh runtime managed system with its own flash region and wear-leveling strategy.” Post-ADR-0019, the provenance chain is a file on the SD card filesystem (e.g., /.provenance.bin per the task body’s recommendation) — same data, same append-only semantics, different storage backend.
3. Cartridge Code Execution Model + PUBLISHER_SPLASH C macro (L685–745, L673–680) — the section still describes dlopen of compiled shared libraries with a C NoshAPI vtable and the publisher splash example uses a C PUBLISHER_SPLASH { ON_SPLASH_INIT { ... } } macro form. ADR-0001 (Accepted & Shipped 2026-04-14) moved cartridge authoring to embedded Lisp on the Fe VM. The vtable indirection still exists internally (it’s how the FFI bridges Lisp to C), but cartridge authors never see it — the public surface is Lisp lambdas registered through NoshAPI primitives. ADR-0017’s coprocessor seam (Pi compute brain + Pico realtime I/O) is also unmentioned in this section; the vtable description should note that audio + OLED calls now route through the coprocessor on the prototype path while remaining in-process for the desktop emulator.

This is pure documentation maintenance — no code, no design changes. The task’s own AC list is well-formed and the source paragraphs are localized; an editor agent should knock this out in a single PR.

Acceptance criteria expanded (≥4 testable items with file paths)

1. L429–467 Cartridge Flash Layout table replaced with an ADR-0019-aligned filesystem layout. Recommended structure:
   • SD card root → cart-id directory (e.g., /icebreaker_v1.3/)
   • /icebreaker_v1.3/cart.kn86 — the bytecode container per ADR-0006
   • /icebreaker_v1.3/save/<cart_id>.sav — per-cartridge save data per ADR-0019 §6
   • /icebreaker_v1.3/.provenance.bin — append-only provenance chain (file replacing the flash region)
   • /icebreaker_v1.3/assets/ — sprites, PSG patterns, attract clips (cart-author convention; runtime-opaque) The CartridgeHeader C struct (L444–466) is deleted, not modified — the .kn86 container header (per ADR-0006) is the authoritative format and the orchestration doc should reference ADR-0006 rather than restate the header bytes. Spec Hygiene Rule 1 (don’t duplicate specs) applies.
2. L385–425 Cartridge Provenance section retains the event-type taxonomy (REGISTRATION / MISSION / RELAY_UPDATE / LINK_SESSION) and the 32-byte block format (still useful as a runtime data structure spec), but rewrites every “flash region” / “wear-leveling” / “chain_offset field in the cartridge header” reference to the SD filesystem path. Add a one-paragraph note that the 32-byte block size is now an in-runtime convention rather than a flash-page-alignment constraint.
3. L673–680 PUBLISHER_SPLASH C macro example replaced with the Lisp form that ADR-0001 makes canonical:

   (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 narrative around it (3-second budget, 30 fps, time-out clamp) is preserved — only the code surface changes. Cross-reference GWP-256 (publisher_splash hook implementation) so a future reader of orchestration.md sees the engineering ticket alongside the spec.
4. L685–745 Cartridge Code Execution Model section gains a 2-paragraph subsection titled “Coprocessor seam (per ADR-0017)” stating that on the prototype:
   • Audio (psg-*, sound-*, sfx-*) primitives marshal over UART to the Pico 2 which owns YM2149 synthesis + I2S out
   • OLED (cipher-emit, aux-*) primitives marshal over UART to the Pico 2 which owns the SSD1322 SPI driver
   • The vtable / FFI surface is unchanged; the Pi-side CoprocessorAPI (kn86-emulator/src/coproc.c, GWP-250) is the marshaling layer
   • Desktop emulator routes the same calls in-process for parity
5. Spec hygiene grep included in PR description with zero hits outside _archive/ for: MBC5, battery-backed SRAM, chain_offset, template_offset, flash region, on-cart flash, CR2032. The grep belongs in the PR body, not in the doc itself.
6. One-line entry added to docs/_meta/platform-design-master-index.md logging the doc-update audit (date, ADRs swept, file touched).

Edge cases (≥2)

1. cipher-grammar and mission-contributions cart contribution blocks (L182–184) are correct as-written and should not be touched. They’re post-ADR-0001 and post-CIPHER-LINE additions, not legacy. Double-check before editing the surrounding table — the row immediately above (Domain vocabulary) is already marked “Obsolete path — superseded by cipher-grammar,” so the doc is partially aware of its own drift in this area.
2. The “Per-cartridge save data” row in the Cartridge Contribution Model table (L184) is already correctly post-ADR-0019: “file on the cartridge’s own SD card filesystem (ADR-0019, supersedes ADR-0013).” Confirm during the sweep — this row was updated as part of the ADR-0019 PR’s documentation sweep (per the ADR’s documentation-updates checklist) and should not be re-edited. The drift is in the deeper sections (Flash Layout, Provenance, Code Execution Model), not this top-level table.
3. The “What Does NOT Change” closing list (L767–777) contains stale lines: Physical cartridge hardware (W25Q128 SPI flash on card-edge PCB) is wrong post-ADR-0019, and Key layout (31-key layout with ATOM/EQ, 14 function + 16 numpad + 1 TERM) mentions ATOM/EQ keys that ADR-0022’s keycap-legend manifest replaced (right-column primaries are now / ; - with " : + shifts). Sweep both — these are easy misses because the section reads as boilerplate.

Engineering hand-off notes

• File touched: docs/software/runtime/orchestration.md (sole edited file per the task constraint).
• File added-to: docs/_meta/platform-design-master-index.md (one audit row).
• Files NOT touched: ADR docs (per task constraint), kn86-emulator/ source (per task constraint).
• Expected PR size: ~150 lines changed in orchestration.md (delete + replace, not pure additive); +1 line in master index. Single-file diff, easy review.
• Test strategy: No code tests. The PR description carries the grep -r "MBC5\|battery-backed SRAM\|chain_offset\|template_offset\|on-cart flash\|CR2032" docs/ | grep -v _archive output as proof the sweep is complete. Visual review of the new Flash Layout table + Provenance rewrite + PUBLISHER_SPLASH Lisp example.
• Dispatch shape: single doc-writing agent (or Marketing/Product agent in writing mode), ~2-hour task. Independent of all other Sprint 4 work — no ordering constraints.
• Watch for: the file is 779 lines and the three drift sections are deep in the body; an editor agent unfamiliar with the architecture might miss subtle stale references in the “What Does NOT Change” block (edge case #3 above) — flag this in the brief.

Open questions

None — the task’s AC list is well-bounded and the ADRs cited are all Accepted with their own documentation-updates checklists already ticked. This is mop-up.