Keyring: main-grid key operations

First-party on-device program #9 (ADR-0042).

v1.1 | 2026-07-18

Canonical per ADR-0042. Keyring is the main-grid operations surface; the CIPHER voice narrates on the OLED CIPHER-LINE via an event handoff (see Engine reuse). Carts overlay crack difficulty / locks + cipher archetypes. See the program roster.

Tier 1 — Treatment

Gate: draft (stub). Basics from the ADR-0042 charter and the Tier 2 spec; the treatment pass has not been written and this stub invents no design.

The hook

The deck’s main-grid cryptographic key-operations surface: generate, revoke, inspect, crack. The visible, operable face of crypto work. Cracking a lock is a resolution you watch, not a minigame you twitch: recon you banked shortens or skips the crack; a wrong method fast-fails. The CIPHER voice narrates the crack, but only on the OLED.

What the operator does

GENERATE and manage your own keys, then SELECT a lock + method and EVAL a crack that runs against the clock. The repeating decision: which method to try, and whether banked recon has de-risked it enough to commit under heat.

Feel

Owed to the treatment pass.

Feasibility verdict

• Reuses: the knEmacs application engine (ui/select-row, ui/peek, minibuffer, a single major-mode), the soft-glyph animation plane + idle-timer (ADR-0052 + GWP-644) for the in-mode crack, the CIPHER event handoff (ADR-0015), and the World Engine’s key-material model.
• New surface required: none; the crack animates in-mode without a cell-API passenger.

Open questions

• Deferred to the tiers below (see Open / deferred in Tier 3).

Tier 2 — Operator spec

Gate: approved (the v1 design; merged through PR review).

Identity

Keyring is the deck’s main-grid cryptographic key-operations surface: generate, revoke, inspect, crack. The visible, operable face of crypto work.

• Operator program #9 (ADR-0042). First-party, always-present, bare-launchable, never superseded.
• HARD CONSTRAINT (ADR-0015): zero CIPHER glyphs on the main grid. The CIPHER voice (the cryptographic personality) narrates on the OLED CIPHER-LINE via an event handoff; Keyring is the main-grid operations surface only (see Engine reuse in Tier 3).
• Generic verb floor (ships, bare-launchable): GENERATE, INSPECT, REVOKE, list; CRACK (select lock + method + EVAL, a timed, animated operation). Carts overlay crack difficulty / locks + cipher archetypes.

The keystore: own + captured keys

The keystore is a durable inventory holding both the operator’s GENERATEd keys and keys captured by a crack. Both persist cross-mission, and a captured key is reusable: it opens a future matching lock or skips a future crack (the de-risk in Tier 3). A successful crack RESOLVE therefore does two things: (a) the captured key → the keystore (:origin :cracked, :owner :target, a reusable asset), and (b) (dossier-commit host:<id>:cred) → DOSSIER (the knowledge that gates / de-risks). Target locks stay volatile (cart :world); the key you pull persists. The keystore is the bare-launch content (own + captured keys, real, persistent).

Bare-launch default world

Per the global bare-launch default-world policy (enrich-never-gate, ADR-0042), genuinely useful here: bare Keyring shows the operator’s real keystore, the keys they’ve generated and captured (both genuinely persistent on the deck; see The keystore).

• A true utility: GENERATE / INSPECT / REVOKE your own keys (and inspect keys you’ve captured from prior cracks), day one. It teaches the management grammar. Bare also carries one self-test / diagnostic lock, the operator’s own practice lock (honest tutorial content, not faked mission data): cracking it teaches the SELECT→RUN→RESOLVE grammar and yields a throwaway diagnostic key (it commits no mission cred). There are no mission locks bare (nothing real to crack until a cart supplies one).
• Enrich-never-gate: insert a cart and target locks appear in scope; CRACK now has something to break.

What Keyring does NOT own

Keyring is the main-grid key-operations surface. It does not own:

• The CIPHER voice / any main-grid CIPHER glyphs. Per ADR-0015, the cryptographic personality is OLED-exclusive: it renders on the CIPHER-LINE auxiliary display, never on the main 128×75 grid. Keyring shows only the operations (the key list, the crack progress bar); the voice speaks on the OLED via the event handoff (see Engine reuse).
• The lock difficulty / cipher archetypes. What’s encrypted, how hard, and what cracking yields is the cart’s world-archetype, not a Keyring concept.
• Access / sessions / the wire. Riding the host the cred opens is CONDUIT (conduit.md); probing for the credential fragment is bzbx (bzbx.md). Keyring breaks the lock; the chain continues elsewhere.
• Missions / economy / the durable record. Contracts, the objective graph, credits / reputation, and the persistent intel store are mission-layer + DOSSIER (dossier.md). Durable consequence is the engine’s via the sanctioned outcome path (ADR-0040).

Tier 3 — Detailed design

Gate: approved (the v1 design; merged through PR review).

Implementation seam (GWP-629): file names, FFI signatures, node schemas, animation primitives, and ADR contracts appear from here down.

The world it reads (:world)

Keyring’s :world is its slice of the central World Engine’s generated world (see ../runtime/world-engine.md): key material in scope. It is coherent with the rest: a cracked lock yields the cred for the host bzbx found / the message kn9 holds. Types:

Node	Key fields	DOSSIER-discoverable key, or flavor?
key	:id · :kind (:symmetric / :public / :private / :passphrase) · :owner (:self / :target) · :origin (:generated / :cracked) · :state (:held / :revoked / :unknown) · :strength · :fingerprint	the operator’s own keys are real / persistent; a key captured by a crack is a persistent, reusable asset (lands in the keystore); mission target locks are flavor until cracked
lock / cipher (the crack target)	:id · :protects (what it gates: a host:<id>:cred, an fs-node, a message) · :difficulty · :method-required · :known-plaintext? (a recon clue)	the lock’s existence / difficulty = flavor; cracking it yields a key (see Export to DOSSIER)
crack-job	:target · :method · :progress · :cost (difficulty vs. your keys / recon)	the in-progress crack (volatile run-state)

The world region is the single shared mission world-region (run-state): one region per mission (enrichment-contract.md §2, §4). The cart’s world-archetype seeds the locks (what’s encrypted, how hard, what cracking yields).

Tick-aware: a crack under wall-clock heat races a :hold (trace timer): the mission owns the timer; CIPHER narrates the urgency on OLED.

Scope-line: construction (clean knEmacs mode)

Verdict: a single clean knEmacs major-mode (keyring-mode), like RIPSAW / bzbx / CONDUIT / kn9, no split, no cell-API passenger. This supersedes the earlier SPLIT verdict (knEmacs mode + a thin cell-API animation). The “crack smells real-time” flag on the ADR-0046 scope line (ADR-0046) is resolved in-mode: the crack’s input is grammar (completing-read + EVAL), and its output animates within the mode via the soft-glyph plane + the idle-timer, never a drop to the cell API. Keyring is the worked example of the ADR-0046 scope-line softening: the animation plane (ADR-0052 soft-glyph + GWP-644 idle-timer) lets one major-mode hold a timed, moving operation without leaving the grammar surface.

The crack is a small state machine, SELECT → RUN → RESOLVE, cancellable, one at a time:

• SELECT: pick a lock + a :method via completing-read; EVAL fires the crack (crack-begin).
• RUN: crack-ticks counts down on the idle-timer; the soft-glyph dither-ramp loader animates the crack panel (one slot regenerated per frame, render/soft-filled, O(1)/frame); density ramps sparse→dense toward RESOLVE. Recon sets the starting tick count. Cancellable (BACK / NIL aborts → no commit).
• RESOLVE: ticks→0. success → a glyph-cycle reveal materializes the recovered key’s fingerprint cell-by-cell, the captured key lands in the keystore, (dossier-commit host:<id>:cred) fires, and key-cracked fires (→ OLED); fail (wrong method, or a heat-trace landed) → crack-failed fires. Fail = free-retry (heat is the only cost).

Two-style choreography (ADR-0052): RUN uses soft-glyph (the uniform dither-ramp loader); RESOLVE uses glyph-cycle (the per-cell fingerprint dissolve-in). Both idle-timer-driven and guarded on (provided? 'editor/timer): a timer-less host degrades to an instant static result and never raises.

De-risk (recon is decisive): base crack-ticks = a tier of :difficulty. (dossier-has? <lock>:plaintext) (a known-plaintext / bzbx-sniffed fragment) shortens it; (dossier-has? key:<id>) or a keystore hit (you already hold a matching key) skips (instant); a wrong :method fast-fails (the method is itself a recon target). Exact tick numbers are deferred tuning.

This is grammar input + in-mode animated output, with CIPHER narration → OLED only (see The Keyring ↔ CIPHER coordination contract). No arcade input loop; the crack is a resolution you watch, not a minigame you twitch.

:payload

Small by-value params only, never the key material (that arrives via :world):

(launch-app :keyring
  :world   relay-7-locks                       ; opaque live handle to the in-scope key material
  :payload '(:targets (lock-3 lock-7)           ; which locks/keys are in scope
             :method-hint :brute))               ; an initial crack approach

• :targets / :method-hint: which locks are in scope + a starting method. The key material is in :world; the operator’s own keys are always present (bare or not).
• Bare (no :world) ⇒ the operator’s real keystore (see Bare-launch default world in Tier 2).

Export to DOSSIER

Keyring emits durable facts only through the sanctioned (dossier-commit <key>) primitive, never a raw write (ADR-0049, ADR-0005). Fact-node fields per dossier-data-model.md §3:

Key	When	Carries
host:<id>:cred	a crack yields a host credential	:conf :verified: enables CONDUIT pre-auth
key:<id>:cracked	a lock is broken	the recovered key / access (the captured key itself also lands in the keystore as a reusable asset)

Reads ((dossier-has? <key>), the recon → crack de-risk, the bridge that makes recon decisive):

• (dossier-has? <lock>:plaintext): a known-plaintext or a recon-found fragment lowers the crack difficulty (de-risk).
• (dossier-has? key:<id>): a key you already hold skips the crack.
• This is the bzbx → Keyring → CONDUIT chain: bzbx sniffs a credential fragment → de-risks Keyring’s crack → yields the full cred → CONDUIT pre-auths. The recon you banked pays off here.

Objective-graph ties

Which Keyring verbs fire goal verbs (ADR-0043):

• CRACK a lock that gates access → (goal-complete 'crack-<lock>); the yielded cred may (goal-reveal) a CONDUIT-access path (the chain to Export to DOSSIER).
• GENERATE a key for a mission (sign / encrypt a payload) → (goal-complete 'forge-<key>).
• REVOKE → a defensive / cleanup goal (e.g. burn a compromised key, ties to knSALK’s defensive side).
• Tick-aware: a crack under wall-clock heat runs against a :hold (trace timer): the animation races the trace; the mission owns the :hold, CIPHER narrates urgency on OLED.

Engine reuse

Keyring is a single keyring-mode on the knEmacs application engine (built, kec-lisp ADR-0004; see ADR-0046). It consumes:

• ui/select-row: the key list (id / kind / owner / state), the inverted-selection row (a feed-pattern + ui/peek consumer).
• ui/peek: the INSPECT detail (fingerprint / kind / strength / owner / origin).
• minibuffer completing-read: pick a lock / method by name (the crack SELECT step; command-by-name).
• define-major-mode: keyring-mode.
• The crack animates in-mode via the soft-glyph plane + the idle-timer (ADR-0052 + GWP-644), guarded on (provided? 'editor/timer), no cell-API passenger, input stays grammar (see Scope-line).

The Keyring ↔ CIPHER coordination contract: events, not glyph-sharing

Keyring renders zero CIPHER glyphs on the main grid (ADR-0015, hard). Instead it fires events, crack-progress, key-cracked, crack-failed, and the CIPHER engine renders the voice on the OLED CIPHER-LINE. The main grid shows only the operations (the key list, the crack progress bar); the personality speaks on the OLED. This keeps OLED-exclusivity intact while letting a main-grid op trigger an OLED utterance. CIPHER stays OLED-exclusive, full stop.

Interfaces

• Launch: (launch-app :keyring :world <key-material-handle> :payload '(:targets … :method-hint …)) — NoshAPI Tier 1 (ADR-0049, ADR-0005). :world is the live in-scope key material; :payload is small params only.
• Export: (dossier-commit <key>) — sanctioned fact-node deposit; read: (dossier-has? <key> &key min-conf) (ADR-0049, ADR-0005).
• CIPHER handoff: Keyring fires crack-begin / crack-progress (at ¼/½/¾ milestones, not every tick) / key-cracked / crack-failed events; the CIPHER engine renders the voice on the OLED CIPHER-LINE, never main-grid CIPHER glyphs (ADR-0015).
• In-mode crack animation: the crack RUN loader is soft-glyph (render/soft-define + render/soft-fill) and the RESOLVE reveal is glyph-cycle (render/glyph per cell), both driven by the idle-timer (run-with-timer) and guarded on (provided? 'editor/timer), no cell-API drop; input stays grammar (ADR-0052).
• Display: draws on the cartridge / content rows (1–73) per the canonical grid (see the Canonical Hardware Specification); grid queried via the cell-API getters.
• Authored in KEC Lisp. Program source lives at runtime/programs/keyring/ (ADR-0042).

Open / deferred

• The keystore durable-store home. The captured-keys keystore model + capture + reuse ship in the program’s run-state; a durable cross-mission storage home (beyond run-state) is a noted follow-on, mirroring DOSSIER’s storage-home deferral. (Update 2026-07-18: the keystore has a durable home in DeckState per ADR-0040/ADR-0056; own + captured keys persist cross-mission via keystore_commit. See worked-mission-walkthrough.md, Seam 1.)
• The opaque live :world handle. A crack racing a live :hold (a trace advancing mid-crack under heat) needs the opaque live handle to see mission-state changes live. (Update 2026-07-18: the ADR-0049 amendment landed, 2026-06-28; the live handle is built and tested.)
• The shared list library. The key list reuses ui/select-row (the same row bzbx / RIPSAW / kn9 / Kommander want); a further shared-table extraction is engine work, not a Keyring blocker.
• The World Engine spec. The generator + clock + typed-event bus the tick-awareness above depends on is specified in ../runtime/world-engine.md.
• Crack animation tuning. The exact in-mode crack visualization (the soft-glyph dither-ramp density curve / the glyph-cycle reveal cadence + base ticks per difficulty tier) is on-glass tuning; the contract (RUN = soft-glyph loader, RESOLVE = glyph-cycle reveal, both idle-timer-driven + guarded, input grammar, voice on OLED) is settled.
• Recon heat / exposure is a mission-layer concern, deferred for v1 (../runtime/recon-mode.md).

Migration notes

• 2026-07-18 tier migration: content re-cut under tier headings from the v1 design; no mechanics changed. World schema, scope-line, crack state machine, and FFI moved behind the Tier 3 seam; identity, keystore concept, and bare-launch behavior stayed at Tier 2. The keystore durable-home and live-:world “follow-on / forthcoming” notes were stale (the keystore durable home shipped per ADR-0056; the ADR-0049 live handle landed 2026-06-28); annotated in place.

References

• enrichment-contract.md — lens / world / shared-region / dossier-commit contract (§1–§6).
• dossier-data-model.md — the fact-node schema a cracked cred commits as (§3).
• dossier.md — the durable intel store Keyring emits into.
• conduit.md · bzbx.md — the bzbx → Keyring → CONDUIT crack-and-access chain.
• ../runtime/world-engine.md — the central World Engine (generator + World Clock + typed-event bus) Keyring’s :world slice reads.
• ../gameplay-framework.md — the gameplay framework the World Engine serves as world model for.
• ../../plans/2026-06-27-keyring-crack-design.md (deleted 2026-07-29; recover from git history) — the converged crack + keystore design (the brainstorm record this spec implements).
• ADR-0015 — CIPHER-LINE OLED exclusivity (the zero-main-grid-CIPHER hard constraint).
• ADR-0042 — first-party programs; carts enrich, never gate.
• ADR-0046 — the knEmacs application engine (major modes + minibuffer command-by-name).
• ADR-0052 — the soft-glyph animation plane + the two-style choreography the in-mode crack uses.
• ADR-0049 · ADR-0005 — the NoshAPI FFI surface (launch-app / dossier-commit / dossier-has?).
• ADR-0043 — the mission objective model Keyring’s verbs fire.
• ADR-0040 — the UDS sanctioned-write boundary dossier-commit respects.