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: 60 (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 ...)

---

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

---

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

---

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

---

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

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: Mark mission complete, award payout, advance deck state. Pops mission context, returns to mission board.

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

---