KN-86 NoshAPI Reference

Auto-generated by kn86 docs ffi from docs/adr/ADR-0005-ffi-surface.md. Do not edit by hand — changes will be overwritten. Update the ADR instead.

Total primitives documented: 88 (NoshAPI v1).

Capability tiers

• Tier 1: All-carts — available in every cartridge, every event.
• Tier 2: Mission-context — available only inside an active mission phase.
• Tier 3: REPL-read-only — inspection-only; mutations rejected.

---

Tier 1: All-Carts Primitives (Available Always)

Display API

Text mode

text-clear

Signature: () → nil

C reference: nosh_text_clear()

Semantics: Clear text framebuffer (80x25 cells). Does not affect split-view bitmap area.

Raises: —

; Example
(text-clear ...)

---

text-putc

Signature: (col row char) → nil

C reference: nosh_text_putc(uint8_t col, uint8_t row, char c)

Semantics: Place a single character at (col, row) in text grid. col: 0–79, row: 0–24. char: ASCII 0–127.

Raises: :out-of-range if col ≥ 80 or row ≥ 25

; Example
(text-putc ...)

---

text-puts

Signature: (col row string) → nil

C reference: nosh_text_puts(uint8_t col, uint8_t row, const char *str)

Semantics: Print a null-terminated string at (col, row), left-aligned. Stops at grid boundary.

Raises: :out-of-range if col ≥ 80

; Example
(text-puts ...)

---

text-printf

Signature: (col row format-string arg1 arg2 ...) → nil

C reference: (Synthesized: formatted text-puts via snprintf + text-puts)

Semantics: Printf-style formatted string at (col, row). Format specifiers: %d, %u, %x, %c, %s. Max 128 bytes output.

Raises: :format-error if format string is invalid; :out-of-range if col ≥ 80

; Example
(text-printf ...)

---

text-scroll

Signature: (lines) → nil

C reference: nosh_text_scroll(int8_t lines)

Semantics: Scroll text up (positive) or down (negative). lines: -25 to +25.

Raises: :out-of-range if abs(lines) > 25

; Example
(text-scroll ...)

---

text-cursor

Signature: (col row visible) → nil

C reference: nosh_text_cursor(uint8_t col, uint8_t row, bool visible)

Semantics: Show/hide text cursor at (col, row). visible: #t or #f.

Raises: :out-of-range if col ≥ 80 or row ≥ 25

; Example
(text-cursor ...)

---

text-invert

Signature: (col row len) → nil

C reference: nosh_text_invert(uint8_t col, uint8_t row, uint8_t len)

Semantics: Invert (XOR) text color for len characters starting at (col, row). For emphasis.

Raises: :out-of-range if col + len > 80

; Example
(text-invert ...)

---

Graphics mode (bitmap, 960×600)

gfx-clear

Signature: () → nil

C reference: nosh_gfx_clear()

Semantics: Clear bitmap framebuffer (all pixels off).

Raises: —

; Example
(gfx-clear ...)

---

gfx-pixel

Signature: (x y on) → nil

C reference: nosh_gfx_pixel(uint16_t x, uint16_t y, bool on)

Semantics: Set or clear a pixel at (x, y). x: 0–959, y: 0–599. on: #t (on) or #f (off).

Raises: :out-of-range if x ≥ 960 or y ≥ 600

; Example
(gfx-pixel ...)

---

gfx-line

Signature: (x0 y0 x1 y1) → nil

C reference: nosh_gfx_line(uint16_t x0, uint16_t y0, uint16_t x1, uint16_t y1)

Semantics: Draw line from (x0, y0) to (x1, y1) using Bresenham.

Raises: :out-of-range if any coord out of bounds

; Example
(gfx-line ...)

---

gfx-rect

Signature: (x y w h filled) → nil

C reference: nosh_gfx_rect(uint16_t x, uint16_t y, uint16_t w, uint16_t h, bool filled)

Semantics: Draw rectangle at (x, y) with size (w, h). filled: #t → solid, #f → outline.

Raises: :out-of-range if x+w > 960 or y+h > 600

; Example
(gfx-rect ...)

---

gfx-circle

Signature: (cx cy r) → nil

C reference: nosh_gfx_circle(uint16_t cx, uint16_t cy, uint16_t r)

Semantics: Draw circle centered at (cx, cy) with radius r.

Raises: :out-of-range if circle exceeds bounds

; Example
(gfx-circle ...)

---

gfx-blit

Signature: (x y bitmap-bytes w h) → nil

C reference: nosh_gfx_blit(uint16_t x, uint16_t y, const uint8_t *bitmap, uint16_t w, uint16_t h)

Semantics: Blit packed bitmap (1 bit per pixel, rows left-to-right, top-to-bottom) at (x, y). bitmap-bytes: byte array of (w*h+7)/8 bytes.

Raises: :out-of-range if x+w > 960 or y+h > 600; :invalid-bitmap if bytes insufficient

; Example
(gfx-blit ...)

---

Display mode control

split-view

Signature: (bitmap-rows) → nil

C reference: nosh_split(uint16_t bitmap_rows)

Semantics: Set split-view mode: top bitmap-rows pixels are graphics, remainder is text. bitmap-rows: 0–599. 0 = all text, 600 = all graphics.

Raises: :out-of-range if bitmap-rows > 600

; Example
(split-view ...)

---

display-mode

Signature: () → symbol

C reference: (Synthesized from internal state)

Semantics: Query current display mode: :text, :graphics, or :split. Read-only.

Raises: —

; Example
(display-mode ...)

---

Cart draw tier

Cells

cell-set

Signature: (col row ch fg bg) → nil

C reference: cell_set

Semantics: Write one cell. Chrome rows drop + count; out-of-range columns clip silently.

Raises: —

; Example
(cell-set ...)

---

cell-print

Signature: (col row fg bg str) → nil

C reference: cell_print

Semantics: Write a string left-to-right, clipped at the right edge (no wrap). Chrome rows drop + count once.

Raises: —

; Example
(cell-print ...)

---

cell-clear-cart-region

Signature: () → nil

C reference: cell_clear_cart_region

Semantics: Clear Rows 1–73. Never touches chrome; not a violation.

Raises: —

; Example
(cell-clear-cart-region ...)

---

cell-cols

Signature: () → 128

C reference: cell_cols

Semantics: Grid width. Query this rather than hard-coding 128.

Raises: —

; Example
(cell-cols ...)

---

cell-rows-usable

Signature: () → 73

C reference: cell_rows_usable

Semantics: Cart-usable row count (Rows 1–73).

Raises: —

; Example
(cell-rows-usable ...)

---

Half-block vectors

half-block-set

Signature: (x y on) → nil

C reference: half_block_set

Semantics: Light or clear one sub-pixel on the 128×146 canvas. Out-of-canvas ignored, no violation; chrome is unreachable by construction.

Raises: —

; Example
(half-block-set ...)

---

half-block-rect

Signature: (x y w h on) → nil

C reference: half_block_rect

Semantics: Filled sub-pixel rectangle, clipped to the canvas.

Raises: —

; Example
(half-block-rect ...)

---

half-block-line

Signature: (x0 y0 x1 y1 on) → nil

C reference: half_block_line

Semantics: Added 2026-07-27. Integer Bresenham between two sub-pixels; the cart-tier peer of render/half-block-line. Both endpoints inclusive; a zero-length line lights the single endpoint. on nil clears, so the same call erases a stroke. Routed through half_block_set per pixel, so an off-canvas run draws only its visible part and cannot over-run the buffer.

Raises: —

; Example
(half-block-line ...)

---

half-block-clear

Signature: () → nil

C reference: half_block_clear

Semantics: Clear the sub-pixel canvas only; the cell grid is untouched.

Raises: —

; Example
(half-block-clear ...)

---

Soft-glyph plane

soft-slots

Signature: () → 8

C reference: cell_soft_slots

Semantics: Added 2026-07-27. Cart-addressable slot count.

Raises: —

; Example
(soft-slots ...)

---

soft-define

Signature: (slot b0 b1 b2 b3 b4 b5 b6 b7) → nil

C reference: cell_soft_define

Semantics: Added 2026-07-27. Overwrite cart slot 0–7 with 8 MSB-first row bytes (same layout as a kn86_font glyph). Eight positional bytes mirror render/soft-define, so (apply soft-define (cons slot bytes)) carries across tiers. Out-of-range slot ignored.

Raises: —

; Example
(soft-define ...)

---

soft-set

Signature: (col row slot fg bg) → nil

C reference: cell_soft_set

Semantics: Added 2026-07-27. Show a soft slot in one cell; the soft-plane mirror of cell-set, same chrome gate. Out-of-range slot draws nothing.

Raises: —

; Example
(soft-set ...)

---

soft-fill

Signature: (col row cols rows slot fg bg) → nil

C reference: cell_soft_fill

Semantics: Added 2026-07-27. Tile a soft slot across a cell block; one call paints a whole animated field. Clips to the grid; chrome rows inside the block drop + count.

Raises: —

; Example
(soft-fill ...)

---

Frame control

present

Signature: () → nil

C reference: present

Semantics: Advisory frame marker. The runtime may auto-present at frame end.

Raises: —

; Example
(present ...)

---

yield

Signature: () → nil

C reference: yield

Semantics: Return control to the runtime.

Raises: —

; Example
(yield ...)

---

Sound API

PSG Control (YM2149 registers)

psg-write

Signature: (reg val) → nil

C reference: nosh_psg_write(uint8_t reg, uint8_t val)

Semantics: Write to PSG register reg (0–14) with value val (0–255). Directly controls 3 tone generators, noise, envelope. Use with caution.

Raises: :invalid-register if reg > 14; :invalid-value if val > 255

; Example
(psg-write ...)

---

psg-read

Signature: (reg) → integer

C reference: nosh_psg_read(uint8_t reg)

Semantics: Read current value of PSG register reg (0–14). Returns 0–255.

Raises: :invalid-register if reg > 14

; Example
(psg-read ...)

---

Higher-level sound abstractions

sound-tone

Signature: (channel freq vol) → nil

C reference: nosh_sound_tone(uint8_t channel, uint16_t frequency, uint8_t volume)

Semantics: Play tone on channel (0–2) at frequency (1–50000 Hz) at volume (0–15). Clamps to PSG limits.

Raises: :invalid-channel if channel > 2; :invalid-freq if freq = 0; :invalid-volume if vol > 15

; Example
(sound-tone ...)

---

sound-noise

Signature: (period) → nil

C reference: nosh_sound_noise(uint8_t period)

Semantics: Set noise period (0–31). 0 = off, higher = lower pitch/slower clock.

Raises: :invalid-period if period > 31

; Example
(sound-noise ...)

---

sound-envelope

Signature: (shape period) → nil

C reference: nosh_sound_envelope(uint8_t shape, uint16_t period)

Semantics: Set envelope shape (0–15, bits 0–3 = hold/alternate/attack/hold) and period. PSG-native.

Raises: :invalid-shape if shape > 15

; Example
(sound-envelope ...)

---

sound-silence

Signature: () → nil

C reference: nosh_sound_silence()

Semantics: Mute all sound (set all channels vol to 0, turn off noise).

Raises: —

; Example
(sound-silence ...)

---

Sound Effects (pre-mixed SFX)

sfx-keyclick

Signature: () → nil

C reference: nosh_sfx_keyclick()

Semantics: Play short click sound (key confirmation). ~50 ms, 1000 Hz.

Raises: —

; Example
(sfx-keyclick ...)

---

sfx-boot

Signature: () → nil

C reference: nosh_sfx_boot()

Semantics: Play boot sequence (ascending tones). ~300 ms.

Raises: —

; Example
(sfx-boot ...)

---

sfx-select

Signature: () → nil

C reference: stdlib_sfx_select() (via nosh_cart.h)`

Semantics: Play selection sound (short beep).

Raises: —

; Example
(sfx-select ...)

---

sfx-confirm

Signature: () → nil

C reference: stdlib_sfx_confirm()

Semantics: Play confirmation sound (higher tone).

Raises: —

; Example
(sfx-confirm ...)

---

sfx-error

Signature: () → nil

C reference: stdlib_sfx_error()

Semantics: Play error buzz (low, harsh).

Raises: —

; Example
(sfx-error ...)

---

sfx-alert

Signature: () → nil

C reference: stdlib_sfx_alert()

Semantics: Play alert ping (high tone).

Raises: —

; Example
(sfx-alert ...)

---

Cell Pool & Navigation

Cell spawning and lifecycle

spawn-cell

Signature: (type-symbol) → cell

C reference: runtime_spawn_cell(SystemState *state, uint16_t type_id)

Semantics: Allocate a new cell of the given type (e.g., ‘contract, ‘datum, ‘link). Type must be registered in cartridge CART_INIT. Returns cell object or nil if pool exhausted.

Raises: :unknown-type if type not registered; :pool-exhausted if no more cells available

; Example
(spawn-cell ...)

---

destroy-cell

Signature: (cell) → nil

C reference: runtime_destroy_cell(SystemState *state, void *cell)

Semantics: Return cell to the free pool. Cell object becomes invalid after this call.

Raises: :invalid-cell if cell is null or corrupted

; Example
(destroy-cell ...)

---

Navigation stack

drill-into

Signature: (target-cell) → nil

C reference: runtime_drill_into(SystemState *state, CellBase *target)

Semantics: Push target onto nav stack. Calls ON_EXIT on current cell, ON_ENTER on target.

Raises: :invalid-cell if target is null; :nav-stack-overflow if depth exceeds 32

; Example
(drill-into ...)

---

navigate-back

Signature: () → nil

C reference: runtime_navigate_back(SystemState *state)

Semantics: Pop nav stack. Calls ON_EXIT on leaving cell, ON_ENTER on returning cell. Fails if stack is at root.

Raises: :nav-stack-underflow if already at root

; Example
(navigate-back ...)

---

current-cell

Signature: () → cell

C reference: runtime_current_cell(SystemState *state)

Semantics: Return the cell at the top of the nav stack. Returns nil if stack is empty.

Raises: —

; Example
(current-cell ...)

---

set-root

Signature: (root-cell) → nil

C reference: runtime_set_root(SystemState *state, CellBase *root_cell)

Semantics: Reset nav stack: clear all, push root-cell. Usually called once at cartridge init.

Raises: :invalid-cell if root-cell is null

; Example
(set-root ...)

---

Navigation helpers

next-sibling

Signature: () → nil

C reference: stdlib_next_sibling(SystemState *state)

Semantics: Move cursor to next sibling (CDR direction) in current list. No-op if already at last sibling.

Raises: —

; Example
(next-sibling ...)

---

prev-sibling

Signature: () → nil

C reference: stdlib_prev_sibling(SystemState *state)

Semantics: Move cursor to previous sibling. No-op if already at first sibling.

Raises: —

; Example
(prev-sibling ...)

---

List Operations (via sibling chains)

list-push

Signature: (parent cell) → nil

C reference: stdlib_list_push(CellBase *parent, CellBase *cell)

Semantics: Append cell as child of parent. cell is linked into parent’s child chain.

Raises: :invalid-cell if parent or cell is null

; Example
(list-push ...)

---

list-get

Signature: (parent index) → cell

C reference: stdlib_list_get(CellBase *parent, int index)

Semantics: Get Nth child of parent (0-indexed). Returns nil if index out of range.

Raises: —

; Example
(list-get ...)

---

list-length

Signature: (parent) → integer

C reference: stdlib_list_length(CellBase *parent)

Semantics: Count children of parent. Returns 0 if parent is a leaf.

Raises: :invalid-cell if parent is null

; Example
(list-length ...)

---

is-leaf

Signature: (cell) → bool

C reference: stdlib_is_leaf(CellBase *cell)

Semantics: Test if cell has no children. Returns #t or #f.

Raises: —

; Example
(is-leaf ...)

---

link-cells

Signature: (parent child) → nil

C reference: stdlib_link_cells(CellBase *parent, CellBase *child)

Semantics: Create explicit parent-child relation. Equivalent to list-push.

Raises: :invalid-cell if parent or child is null

; Example
(link-cells ...)

---

unlink-cell

Signature: (cell) → nil

C reference: stdlib_unlink_cell(CellBase *cell)

Semantics: Remove cell from its parent and sibling chain. Cell becomes orphaned but not destroyed.

Raises: :invalid-cell if cell is null or has no parent

; Example
(unlink-cell ...)

---

Procedural Generation (LFSR)

lfsr-seed

Signature: (seed) → nil

C reference: stdlib_lfsr_seed(SystemState *state, uint32_t seed)

Semantics: Initialize the LFSR with a 32-bit seed (typically seeded from deck state or mission parameters).

Raises: —

; Example
(lfsr-seed ...)

---

lfsr-next

Signature: () → integer

C reference: stdlib_lfsr_next(SystemState *state)

Semantics: Advance LFSR, return next pseudo-random 32-bit value (0–4294967295).

Raises: —

; Example
(lfsr-next ...)

---

lfsr-range

Signature: (min max) → integer

C reference: stdlib_lfsr_range(SystemState *state, uint32_t min, uint32_t max)

Semantics: Return pseudo-random integer in [min, max] inclusive. Accepts negative ranges.

Raises: :invalid-range if min > max

; Example
(lfsr-range ...)

---

lfsr-shuffle

Signature: (list) → list

C reference: lisp_lfsr_shuffle (bridge wrapper over stdlib_lfsr_range)`

Semantics: Fisher-Yates shuffle over a Fe list. Returns a freshly-allocated list; input list is not mutated. Empty and single-element lists return without advancing LFSR. Capped at 256 elements (returns nil if exceeded). Cost: O(n) arena cons cells. Prefer to call once per phase. (Amended 2026-04-26 per GWP-247 — see Amendment Log)

Raises: nil if n > 256

; Example
(lfsr-shuffle ...)

---

Pointing / Trackpoint

cursor-position

Signature: () → (col row)

C reference: nosh_cursor_position() (synthesized; reads from runtime cursor-state record)`

Semantics: Query current cursor cell on the main 128×75 grid. Returns a 2-element list (col row) where col: 0–127 and row: 1–73 (cursor clamped to cartridge content area). Position is logical and independent of visibility — a hidden cursor still has a position. O(1); never raises.

Raises: —

; Example
(cursor-position ...)

---

on-trackpoint-move

Signature: (handler) → nil

C reference: nosh_on_trackpoint_move(...) (synthesized; registers Lisp lambda in runtime cursor-state)`

Semantics: Register handler invoked when the cursor crosses a cell boundary. Handler signature: (handler col row delta-col delta-row). delta-col / delta-row are integer cell deltas from the previous position (can be negative; magnitude > 1 if motion exceeds per-tick sampling). One handler per cart; re-register replaces; pass nil to unregister. Sustained against-boundary push does not re-fire the handler. Handler runs on the runtime event loop; exceptions are silently logged.

Raises: :invalid-handler if handler is non-nil and not a callable lambda

; Example
(on-trackpoint-move ...)

---

on-trackpoint-click

Signature: (handler) → nil

C reference: nosh_on_trackpoint_click(...) (synthesized)`

Semantics: Register handler invoked on click. Handler signature: (handler col row). v0.1 fires exactly when the QMK PS/2-mouse driver emits a primary-button click (tap-vs-drag threshold is firmware-defined per ADR-0032 §4 and not re-specified here). One handler per cart; re-register replaces; pass nil to unregister. Right-click / middle-click deferred to v0.2 — no button-index argument in v0.1.

Raises: :invalid-handler if handler is non-nil and not a callable lambda

; Example
(on-trackpoint-click ...)

---

cursor-visible!

Signature: (visible) → nil

C reference: nosh_cursor_visible(bool visible) (synthesized)`

Semantics: Show (#t) or hide (#f) the cursor for the lifetime of the cart load. Overrides the manifest :pointer-hidden default. Independent of position — toggling visibility does not move the cursor. Cart unload restores the runtime default (visible) for the next cart.

Raises: :invalid-bool if visible is not #t or #f

; Example
(cursor-visible! ...)

---

Deck State Access (Read-only in this tier; mutations in Mission-context tier)

deck-state

Signature: () → deck-state-object

C reference: stdlib_deck_state(SystemState *state)

Semantics: Get reference to universal deck state. Object has fields: :handle, :credits, :reputation, :cartridge-history, :phase-chain.

Raises: —

; Example
(deck-state ...)

---

get-handle

Signature: () → string

C reference: (Synthesized: deck_state()->handle)

Semantics: Get operator’s handle (callsign). Max 16 chars. Read-only.

Raises: —

; Example
(get-handle ...)

---

get-credits

Signature: () → integer

C reference: (Synthesized: deck_state()->credit_balance)

Semantics: Get current credit balance. Read-only.

Raises: —

; Example
(get-credits ...)

---

get-reputation

Signature: () → integer

C reference: (Synthesized: deck_state()->reputation)

Semantics: Get current reputation points. Read-only.

Raises: —

; Example
(get-reputation ...)

---

has-capability

Signature: (bit-index) → bool

C reference: stdlib_has_capability(SystemState *state, uint8_t bit)

Semantics: Test if cartridge capability bit is set (0–31). cartridge_history is a 32-bit bitmask tracking which modules have been completed.

Raises: :invalid-bit if bit ≥ 32

; Example
(has-capability ...)

---

get-aesthetic-mode

Signature: () → symbol

C reference: stdlib_get_aesthetic_mode(SystemState *state)

Semantics: Get the active aesthetic mode. Returns one of :amber, :white, :green (the runtime-locked phosphor roster per ADR-0034 §1 as amended 2026-06-13 per ADR-0036; previous :amber / :amber / :cipher retired). Read-only — carts cannot mutate the mode. Cheap (single SystemState field read). Default if nosh-config.toml [aesthetic].mode is missing or invalid: :amber.

Raises: —

; Example
(get-aesthetic-mode ...)

---

Display Helpers (stdlib)

draw-threat-bar

Signature: (level max-level col row) → nil

C reference: stdlib_draw_threat_bar(uint8_t level, uint8_t max_level, uint8_t col, uint8_t row)

Semantics: Draw threat bar: level/max_level filled blocks (■) out of max_level total. Max 16 blocks. Placed at (col, row) in text grid.

Raises: :out-of-range if max_level > 16 or col+max_level > 80

; Example
(draw-threat-bar ...)

---

draw-progress-bar

Signature: (percentage col row width) → nil

C reference: stdlib_draw_progress_bar(uint8_t pct, uint8_t col, uint8_t row, uint8_t width)

Semantics: Draw progress bar: pct% filled (0–100). width: 1–32 chars. Placed at (col, row) in text grid.

Raises: :invalid-percentage if pct > 100; :invalid-width if width > 32 or col+width > 80

; Example
(draw-progress-bar ...)

---

draw-bordered-box

Signature: (col row w h title) → nil

C reference: stdlib_draw_bordered_box(uint8_t col, uint8_t row, uint8_t w, uint8_t h, const char *title)

Semantics: Draw a box outline with optional title. w, h: 3–77, 2–24. title: optional, centered.

Raises: :out-of-range if col+w > 80 or row+h > 25; :invalid-size if w < 3 or h < 2

; Example
(draw-bordered-box ...)

---

Reveal animation primitives

reveal

Signature: (surface :style style-sym &key duration rate trail from) → handle

C reference: nosh_reveal(...) (synthesized)`

Semantics: Start an animated reveal on the surface (cell handle). :style is one of the symbols in reveal-styles.md §3. Returns an opaque reveal handle. Lifecycle is async per reveal-styles.md §5. Out-of-range scalar params (:duration, :rate, :trail, :from) silently clamp per the silent-clamp convention.

Raises: :reveal-style-not-implemented if a deferred style (:random, :diagonal, :fft) is passed in v0.1; :reveal-unknown-style if the symbol is not in the enum; :invalid-surface if surface is nil; :reveal-too-many-active if > 4 handles already active for the current cart

; Example
(reveal ...)

---

reveal-cancel

Signature: (handle) → nil

C reference: nosh_reveal_cancel(...) (synthesized)`

Semantics: Interrupt the animation, snap surface to final state. Idempotent on completed handles.

Raises: —

; Example
(reveal-cancel ...)

---

reveal-complete?

Signature: (handle) → bool

C reference: nosh_reveal_complete_p(...) (synthesized)`

Semantics: Non-blocking poll; returns #t once the reveal has finished or been cancelled.

Raises: —

; Example
(reveal-complete? ...)

---

unreveal

Signature: (surface :style style-sym &key duration) → handle

C reference: nosh_unreveal(...) (synthesized)`

Semantics: Inverse — animate removal of a surface. Same style enum as reveal minus :char-flicker / :no-more-secrets (which don’t compose as inverses).

Raises: Same as reveal minus the char-flicker-specific paths

; Example
(unreveal ...)

---

Tier 2: Mission-Context Primitives (Active phase handler or Mission Runner)

Mission progression

phase-advance

Signature: () → nil

C reference: nosh_phase_advance() (synthesized)`

Semantics: Advance to next phase in the mission phase chain. Triggers ON_EXIT in current phase, ON_ENTER in next. If this is the last phase, calls mission_complete.

Raises: :not-in-mission if not in active phase context; :no-next-phase if already at last phase

; Example
(phase-advance ...)

---

mission-complete

Signature: () → nil

C reference: nosh_mission_complete() (synthesized)`

Semantics: Alias for complete-mission when called from a cart phase handler with no explicit struct argument.

Raises: :not-in-mission if not in active phase context

; Example
(mission-complete ...)

---

award-credits

Signature: (amount) → nil

C reference: stdlib_credit_add()

Semantics: Add credits to deck balance. amount can be negative (penalty).

Raises: —

; Example
(award-credits ...)

---

modify-reputation

Signature: (delta) → nil

C reference: stdlib_rep_modify(SystemState *state, int16_t delta)

Semantics: Modify reputation by delta (positive = gain, negative = loss). Clamped at [0, 32767].

Raises: —

; Example
(modify-reputation ...)

---

Mission Runner — capability calls (added 2026-05-03 per ADR-0029)

load-capability

Signature: (:module module-symbol &key seed input) → result-struct

C reference: nosh_load_capability(...) (synthesized)`

Semantics: Invoke the named cart’s gameplay loop. If the cart is registered but not currently inserted, emit a Hot Swap prompt and block until inserted (or aborted). On return, marshal the cart’s outcome into a result struct. See ADR-0029 §3 and mission-control.md §5.3.

Raises: :capability-not-registered if the module’s bit is not set in cartridge_history; :capability-aborted if operator aborted Hot Swap; :not-in-mission if no contract is active; :nested-capability-call if invoked from a cart phase handler already running under load-capability

; Example
(load-capability ...)

---

complete-mission

Signature: (mission-struct) → nil

C reference: nosh_complete_mission(...) (synthesized)`

Semantics: Resolve the active contract: calculate final payout from accumulated phase outcomes, apply reputation delta, write the cartridge provenance MISSION block, unbind Mission Runner symbols, return to the mission board.

Raises: :not-in-mission if no contract is active

; Example
(complete-mission ...)

---

abandon-mission

Signature: () → nil

C reference: nosh_abandon_mission() (synthesized)`

Semantics: Resolve the active contract as :result-failure, apply the reputation penalty, refresh the board with a lower-threat alternative for the abandoned slot, unbind Mission Runner symbols.

Raises: :not-in-mission if no contract is active

; Example
(abandon-mission ...)

---

Mission phase metadata

set-phase-data

Signature: (key value) → nil

C reference: (Synthesized: mission context dict)

Semantics: Set arbitrary key-value pair in current phase’s persistent data. Survives phase boundaries within a multi-phase mission.

Raises: :not-in-mission if not in active phase context

; Example
(set-phase-data ...)

---

get-phase-data

Signature: (key) → value

C reference: (Synthesized: mission context dict)

Semantics: Retrieve phase data by key. Returns nil if not set.

Raises: :not-in-mission if not in active phase context

; Example
(get-phase-data ...)

---

set-capability

Signature: (bit-index) → nil

C reference: stdlib_set_capability(SystemState *state, uint8_t bit)

Semantics: Set cartridge capability bit (0–31). Marks this module as completed.

Raises: :invalid-bit if bit ≥ 32; :not-in-mission if not in active phase context

; Example
(set-capability ...)

---

Tier 3: REPL-Read-Only Primitives (Player-facing Lisp REPL, ADR-0002)

2026-06-07 — Tier 1 aesthetic-mode introspection primitive (ADR-0034)

get-aesthetic-mode

Signature: () → symbol

C reference: stdlib_get_aesthetic_mode(SystemState *state)

Semantics: One of :amber, :white, :green (per ADR-0034 §1 as amended 2026-06-13 per ADR-0036; previous :amber / :amber / :cipher retired). Default fallback (missing or invalid nosh-config.toml value) is :amber.

Raises: —

; Example
(get-aesthetic-mode ...)

---