Cartridge Interface

Spec hygiene (CLAUDE.md rule 1). This document does not restate canonical values (shell dimensions, save location, interface class). Those live in CLAUDE.md’s Canonical Hardware Specification. Any value inline is a bug — fix it.

Role

A KN-86 cartridge is a standard full-size SD card carried in a custom two-piece clamshell shell. The shell is the operator-facing artifact (ritual, collectibility, label surface, tactile mass); the SD card is the underlying storage. The Pi reads the cartridge as USB mass storage through a card reader bridge IC on the internal hub planned in ADR-0018. Per-cartridge save data lives as a file on the cartridge’s own SD filesystem.

For canonical shell dimensions, interface class, and save model, see CLAUDE.md Canonical Hardware Specification — Cartridge interface, Cartridge shell, and Per-cartridge save rows.

ADR-0019 supersedes the earlier ADR-0013 (DMG 32-pin pinout + MBC5 mapper + CR2032-backed on-cart SRAM). It also partially supersedes ADR-0017 by removing the cartridge-bus role from the Pico 2 — the Pico no longer touches cartridges. See coprocessor.md.

Why SD-sled (not DMG)

Two days after ADR-0013 committed to a literal Game Boy DMG cartridge, the team noticed: KN-86 cartridges are not ROMs. They are files — Lisp source addressed by a loader. Every .kn86 (ADR-0006) is Lisp source + tagged static data, tree-walked by the Fe interpreter (no bytecode — see ADR-0004 2026-06-14 amendment). The cart is indifferent to whether it loaded from MBC5 ROM, microSD, USB-MSC, or a TCP socket. ADR-0013’s expensive answers (MBC5 silicon, CR2032 cells, custom cartridge PCBs, edge connector tooling) were paying for benefits the cart did not need.

The cartridge’s real job in the product is ritual, collectibility, tactile identity, and homebrew-friendliness — not “be hardware.” Storage is a commodity implementation detail. Once that frame is taken seriously: shell at GBA dimensions for the slot ceremony, commodity SD card inside for the bytes, USB-MSC bridge IC behind the slot for the read path, file on filesystem for per-cartridge save.

Components

Element	Choice	Notes
Storage medium	Full-size SD card	Full-size (not microSD) chosen for tactile grip — the operator handles the shell, but a slipped-out card needs to feel like an artifact, not a sliver. Capacity floor TBD (ADR-0019 Open Q §5).
SD socket	Full-size, push-push, surface-mount, with card-detect switch	Candidate part families: Hirose DM1, Molex full-size SD push-push. Specific part TBD during bring-up (CART-01 / CART-02).
Bridge IC	USB-to-SD card reader bridge IC	Candidate IC families: Genesys GL3224 / GL3232, Realtek RTS5129. Specific part TBD during breadboard prototype (CART-01).
Internal cartridge-interface PCB	Small PCB hosting SD socket + bridge IC + USB pigtail to internal hub	Custom-fab item; design lands as CART-01.
Cartridge shell	Two-piece clamshell, screw-closed, ABS injection (production) / FDM PLA / PETG (prototype)	~58 × 65 × 8 mm (GBA-sweet-spot footprint per `CLAUDE.md`). Wall thickness 1.5–2.5 mm production / 2–3 mm prototype. SD card lateral tolerance ±0.3 mm. Reloadable — the operator can open the shell to replace or re-flash the SD card.

The SD card is held by the socket’s push-push mechanism, not by the shell. When the operator inserts the shell, the SD card’s contacts engage the socket inside the device. Removal pushes the shell out the same way — the socket springs back, the user retrieves the shell.

Interface

Signal	From	To	Notes
USB	Bridge IC USB upstream	Internal USB hub downstream port	Hub topology per ADR-0018.
USB	Internal hub upstream	Pi Zero 2 W OTG	Same hub that fans out to the keyboard controller.
SD bus	Bridge IC	SD socket	Internal to the cartridge-interface PCB.
Card-detect	SD socket switch	Bridge IC and/or Pi GPIO	Signaling path TBD (ADR-0019 Open Q §9 — USB-MSC device-disappear event alone vs. separate GPIO).

Pi-side, the cartridge surfaces as a standard block device (/dev/sd*) with a vfat / exfat filesystem. The cartridge loader becomes a read() against the mounted filesystem. Zero custom driver code on the Pi side — udev surfaces insertion / removal events, USB-MSC is the most-tested storage path in the Linux kernel.

Hot-swap semantics

Physical insertion / removal generates udev events; the nOSh runtime subscribes and handles them as the capability-model Hot Swap entry point.

Event	Pi sees	nOSh runtime does
Operator pushes shell out	USB-MSC device disappears (`udev` remove event)	Cart state preserved in phase chain (Universal Deck State); current module unloaded cleanly.
Operator inserts new shell	USB-MSC device appears (`udev` add event)	Pi mounts the cart, validates `.kn86` header, loads the new module.

The ~5-second Hot Swap timing in the ICE BREAKER gameplay spec still applies — it is now “how long the physical swap actually takes,” driven by socket push-push mechanics + udev enumeration latency rather than cartridge-firmware-managed state migration. Bring-up characterizes end-to-end physical-eject → physical-insert → cart-loaded latency.

Per-cartridge save

Save data lives as a file on the cartridge’s own SD filesystem (e.g., /save/<cart_id>.sav) — supersedes ADR-0013’s battery-backed on-cart SRAM. Universal Deck State (operator handle, credits, reputation, cartridge history bitfield, phase chain) remains on the Pi’s microSD per ADR-0011. Save payload format continues to be ADR-0006 tagged static data.

The cart_save / cart_load NoshAPI contract is unchanged at the FFI surface. The implementation moves from MBC5 SRAM bank-switching to filesystem read/write underneath. Cartridge code does not observe the difference.

What does NOT change

The .kn86 container (ADR-0006) — header, code section (Lisp source), tagged static data subsections, CART_CAPABILITIES block, debug section, CRC-32. See software/api-reference/grammars/cartridge-format.md.
The NoshAPI FFI surface (ADR-0005).
The Fe interpreter and cart code (ADR-0001, ADR-0004) — tree-walked Lisp source; no bytecode.
The capability model — mission board, phase chain, deck state, cartridge history bitfield, Cipher voice, hot-swap-as-designed-mechanic.
Sister-deck inheritance — Toneline, Statline, Gridline inherit the SD-sled cartridge format the same way they would have inherited DMG carts.
Pi Pico 2’s audio + CIPHER-LINE OLED responsibilities (coprocessor.md). Only the cart-bus role moved off the Pico.

Mechanical

The Pelican 1170 inset’s base panel carries a cartridge slot opening sized for the shell (~60 × 10 mm). The SD socket mounts on an internal PCB at the back of the slot. Slot depth budget: shell depth (~65 mm) + SD socket depth + PCB clearance, against the 80 mm Pelican interior depth — verify against battery, speaker, amp, Pi mounting pocket, and CIPHER-LINE module during bring-up. Dust-door mechanism is deferred (ADR-0019 Open Q §8). See enclosure.md.

Bring-up

v0.1 bench rigs run cartridges as filesystem entries on the Pi’s boot microSD — the SD-sled interface is queued for a future bring-up wave. The CART tasks in ADR-0019:

Task	Owner	Deliverable
CART-01	Hardware	Breadboard the bridge IC + SD socket + USB hub harness. Working USB-MSC enumeration. Resolves Open Q §1 + §2.
CART-02	Hardware	Industrial design pass on the two-piece clamshell shell (wall thickness, screw count, internal locating features). STEP file + assembly drawing + first FDM print. Resolves Open Q §3 + §6.
CART-03	Hardware	Pelican 1170 inset panel revision — slot cutout, SD-socket-PCB mounting pocket, dust-door provision.
CART-04	Platform Engineering	`udev` rule + nOSh subscriber for SD-cart insertion / removal. Hot-swap event flow into the phase chain. Resolves Open Q §9 if breadboard reveals USB-event-only is insufficient.
CART-05	C Engineer	Migrate `cart_save` / `cart_load` from the MBC5-SRAM stub to the filesystem path. FFI signatures stay; only the storage backend changes.
CART-06	Gameplay Design + PM	Decision on `ghost_cartridge` (legacy DMG-read easter-egg) disposition. Owns Open Q §10.
CART-07	PM + Marketing	Decide whether the Launch-4 cartridges ship as physical SD-sleds or pre-installed on the device.

Sourcing

BOM lines in sourcing-guide.md:

5d — USB-to-SD card reader bridge IC (Genesys GL3224 / GL3232, Realtek RTS5129) + passives, $2–$4. LCSC / Mouser / Digi-Key / Arrow.
5e — Full-size SD push-push surface-mount socket with card-detect (Hirose DM1, Molex full-size SD push-push), 2× ($1–$3 ea). Digi-Key / Mouser / LCSC.
5f — Custom internal cartridge-interface PCB (mounts SD socket + bridge IC + pigtail to internal USB hub), 5-board batch min, $20–$40. JLCPCB / OshPark / PCBWay.
5g — Cartridge SD card (full-size, ≥ TBD GB) for first-party launch carts. Per-cart provisioning is a packaging task, not a v0.1 BOM line.

First-cycle bring-up should order line 5e (a couple of candidate sockets) and 5d (a candidate bridge IC) for the breadboard prototype before committing to a fabbed cartridge-interface PCB.

Open questions (deferred)

ADR-0019 §Open Questions catalogs them. Headline items:

Card reader bridge IC selection — CART-01.
SD socket specific part — CART-01.
Shell closure hardware (screw type, count, size) — CART-02.
Production shell material (ABS / PC/ABS / PC) — CART-02.
Minimum SD capacity floor.
Label / artwork system — CART-02.
Launch-4 on-board vs. physical carts — separate ADR.
Dust-door mechanism — CART-03.
Cartridge-present detect signaling path — CART-04.
ghost_cartridge disposition — CART-06.