LithosAnanake/docs/lithosananke/DICTIONARY.md

# LithosAnanke / StarForth — Word Dictionary Reference

**Status:** Living reference document, generated 2026-08-12. Keep it up to date as words
are added, removed, or re-registered — see "Keeping this current" at the bottom.

**Scope: core C primitives only.** This covers every word registered via `register_word()`
(and the one file that uses `vm_create_word()` directly, `physics_pipelining_diagnostic_words.c`)
across `src/word_source/*.c` and `src/starkernel/capsule/mama_forth_words.c` — roughly 470
words. It does **not** cover the ~330 FORTH-defined words living inside `.4th` capsules
(`ACL.4th`, `zuse.4th`, `doe.4th`, workload capsules, etc.) — those are experiment/workload/
policy definitions layered on top of this vocabulary, not the language itself, and change
per-capsule rather than per-build. If a capsule-word reference is wanted later, it belongs in
a separate document — the two have very different lifecycles.

**Source of truth.** Every entry below was extracted directly from source: the word name as
passed to `register_word()`, the stack effect and description from the doc comment
immediately above the implementing function (or inferred from the function body where no
comment exists, marked `(inferred)`). Registration order within each file is preserved
(rather than alphabetized) because related words are grouped together at the call site.

**Two name collisions exist in the live dictionary.** FORTH dictionary lookup walks the
definition chain newest-first (`vm->latest` backward via `->link`), so when two files
register the same name, **the file registered later in `register_forth79_words()`
(`src/word_registry.c`) wins** — the earlier registration becomes permanently unreachable by
name (though still present in the chain). Both cases are noted at point of use below:
- `[`, `]`, `STATE` — registered by `dictionary_manipulation_words.c` (Module 13), then again
  by `defining_words.c` (Module 17). **`defining_words.c`'s versions are live.**
- `MOD`, `/MOD`, `*/`, `*/MOD` — registered by `arithmetic_words.c` (Module 4), then again by
  `mixed_arithmetic_words.c` (Module 6). **`mixed_arithmetic_words.c`'s versions are live.**

---

## Stack (`stack_words.c`)

| Word | Stack Effect | Description |
|---|---|---|
| `DROP` | `( n -- )` | Removes the top stack item. |
| `DUP` | `( n -- n n )` | Duplicates the top stack item. |
| `?DUP` | `( n -- n n \| n -- 0 )` | Duplicates the top item only if it is non-zero. |
| `SWAP` | `( n1 n2 -- n2 n1 )` | Exchanges the top two stack items. |
| `OVER` | `( n1 n2 -- n1 n2 n1 )` | Copies the second stack item to the top. |
| `ROT` | `( n1 n2 n3 -- n2 n3 n1 )` | Rotates the top three stack items, moving the third to the top. |
| `-ROT` | `( n1 n2 n3 -- n3 n1 n2 )` | Reverse-rotates the top three stack items. |
| `DEPTH` | `( -- n )` | Pushes the current number of items on the data stack. |
| `PICK` | `( n -- stack[n] )` | Copies the nth stack item (0-indexed from top, after popping `n`) to the top. |
| `ROLL` | `( n -- )` | Moves the nth stack item to the top, shifting intermediate items down. |

## Return Stack (`return_stack_words.c`)

FORTH-79 compliance, stated in this file's own header: only `>R`/`R>`/`R@` are provided — no
direct return-stack addressing (`RP!`/`RP@`), which FORTH-79 forbids.

| Word | Stack Effect | Description |
|---|---|---|
| `>R` | `( x -- )` | Moves x from the data stack to the return stack. |
| `R>` | `( -- x )` | Moves x from the return stack back to the data stack. |
| `R@` | `( -- x )` | Copies the top of the return stack to the data stack without removing it. |

## Memory (`memory_words.c`)

| Word | Stack Effect | Description |
|---|---|---|
| `@` | `( addr -- n )` | Fetches a cell from VM memory at `addr`. |
| `!` | `( n addr -- )` | Stores cell `n` at VM memory address `addr`. |
| `C@` | `( addr -- c )` | Fetches a byte from VM memory at `addr`. |
| `C!` | `( c addr -- )` | Stores byte `c` at VM memory address `addr`. |
| `+!` | `( n addr -- )` | Adds `n` to the cell currently at `addr`. |
| `-!` | `( n addr -- )` | Subtracts `n` from the cell currently at `addr`. |
| `2@` | `( addr -- x_low x_high )` | Fetches two consecutive cells starting at `addr`. |
| `2!` | `( x_low x_high addr -- )` | Stores two consecutive cells starting at `addr`. |
| `FILL` | `( addr len c -- )` | Fills `len` bytes starting at `addr` with byte value `c`. |
| `MOVE` | `( addr1 addr2 len -- )` | Copies `len` bytes from `addr1` to `addr2`, handling overlap correctly. |
| `ERASE` | `( addr len -- )` | Zeroes `len` bytes starting at `addr`. |
| `CELLS` | `( n -- n' )` | Multiplies `n` by the cell size in bytes. |

## Arithmetic (`arithmetic_words.c`)

`MOD`, `/MOD`, `*/`, `*/MOD` below are **shadowed** — see the collision note at the top of
this document; `mixed_arithmetic_words.c`'s versions are the ones actually live.

| Word | Stack Effect | Description |
|---|---|---|
| `+` | `( n1 n2 -- n3 )` | Adds `n1` and `n2`. |
| `-` | `( n1 n2 -- n3 )` | Subtracts `n2` from `n1`. |
| `*` | `( n1 n2 -- n3 )` | Multiplies `n1` by `n2`. |
| `/` | `( n1 n2 -- n3 )` | Divides `n1` by `n2`; errors on division by zero. |
| `MOD` *(shadowed)* | `( n1 n2 -- n3 )` | `n1` modulo `n2`; errors on division by zero. |
| `/MOD` *(shadowed)* | `( n1 n2 -- n3 n4 )` | Pushes `n1 MOD n2` (remainder) then `n1 / n2` (quotient). |
| `*/` *(shadowed)* | `( n1 n2 n3 -- n4 )` | Computes `n1 * n2 / n3` using a 64-bit intermediate to avoid overflow. |
| `*/MOD` *(shadowed)* | `( n1 n2 n3 -- n4 n5 )` | Computes `n1 * n2 / n3`, pushing remainder then quotient, via a 64-bit intermediate. |
| `1+` | `( n -- n+1 )` | Adds 1. |
| `1-` | `( n -- n-1 )` | Subtracts 1. |
| `2+` | `( n -- n+2 )` | Adds 2. |
| `2-` | `( n -- n-2 )` | Subtracts 2. |
| `2*` | `( n -- n*2 )` | Multiplies by 2 (left shift). |
| `2/` | `( n -- n/2 )` | Divides by 2 (right shift). |
| `ABS` | `( n -- \|n\| )` | Absolute value. |
| `NEGATE` | `( n -- -n )` | Two's-complement negation. |
| `MIN` | `( n1 n2 -- n3 )` | Pushes the smaller of `n1` and `n2`. |
| `MAX` | `( n1 n2 -- n3 )` | Pushes the larger of `n1` and `n2`. |

## Logical & Comparison (`logical_words.c`)

| Word | Stack Effect | Description |
|---|---|---|
| `AND` | `( n1 n2 -- n3 )` | Bitwise AND. |
| `OR` | `( n1 n2 -- n3 )` | Bitwise OR. |
| `XOR` | `( n1 n2 -- n3 )` | Bitwise XOR. |
| `NOT` | `( flag -- flag )` | FORTH-79 logical NOT: 0 → true (-1), non-zero → false (0). |
| `INVERT` | `( n1 -- n2 )` | Bitwise complement (FORTH-83 extension). |
| `LSHIFT` | `( x1 u -- x2 )` | Logical left shift by `u` bits. |
| `RSHIFT` | `( x1 u -- x2 )` | Logical right shift by `u` bits. |
| `0=` | `( n -- flag )` | True if `n` is zero. |
| `0<` | `( n -- flag )` | True if `n` is negative. |
| `0>` | `( n -- flag )` | True if `n` is positive. |
| `0<>` | `( n -- flag )` | True if `n` is non-zero. |
| `=` | `( n1 n2 -- flag )` | True if equal. |
| `<>` | `( n1 n2 -- flag )` | True if not equal. |
| `<` | `( n1 n2 -- flag )` | True if `n1 < n2` (signed). |
| `>` | `( n1 n2 -- flag )` | True if `n1 > n2` (signed). |
| `>=` | `( n1 n2 -- flag )` | True if `n1 >= n2` (signed). |
| `<=` | `( n1 n2 -- flag )` | True if `n1 <= n2` (signed). |
| `U<` | `( u1 u2 -- flag )` | True if `u1 < u2` (unsigned). |
| `U>` | `( u1 u2 -- flag )` | True if `u1 > u2` (unsigned). |
| `WITHIN` | `( n low high -- flag )` | True if `low <= n < high`. |
| `TRUE` | `( -- flag )` | Pushes -1. |
| `FALSE` | `( -- flag )` | Pushes 0. |

## Mixed Arithmetic (`mixed_arithmetic_words.c`)

`MOD`, `/MOD`, `*/`, `*/MOD` here are the **live** versions — see the collision note at the
top of this document.

| Word | Stack Effect | Description |
|---|---|---|
| `M+` | `( d_high d_low n -- d_high' d_low' )` | Adds single-cell signed `n` to double-cell `d`, with carry propagation. |
| `M-` | `( d_high d_low n -- d_high' d_low' )` | Subtracts single-cell signed `n` from double-cell `d`, with carry propagation. |
| `M*` | `( n1 n2 -- d_low d_high )` | Multiplies two single-cell signed integers into a double-cell result (TOS = high cell). |
| `M/MOD` | `( d_high d_low n -- remainder quotient )` | Divides double-cell dividend `d` by single-cell divisor `n`; TOS = quotient. |
| `MOD` | `( n1 n2 -- remainder )` | Computes `n1 % n2`; errors on division by zero. |
| `/MOD` | `( n1 n2 -- remainder quotient )` | Divides `n1` by `n2`, leaving both remainder and quotient (TOS = quotient). |
| `*/` | `( n1 n2 n3 -- quotient )` | Computes `(n1 * n2) / n3` using a wider intermediate to avoid overflow. |
| `*/MOD` | `( n1 n2 n3 -- remainder quotient )` | Computes `(n1 * n2) / n3`, leaving both remainder and quotient. |

## Double-Precision (`double_words.c`)

A double is represented on the stack as `dlow dhigh` (high cell on top).

| Word | Stack Effect | Description |
|---|---|---|
| `S>D` | `( n -- d )` | Converts a single-precision number to double, sign-extending into the high cell. |
| `D+` | `( d1 d2 -- d3 )` | Double-precision addition with carry propagation. |
| `D-` | `( d1 d2 -- d3 )` | Double-precision subtraction with borrow propagation. |
| `DNEGATE` | `( d1 -- d2 )` | Double-precision two's-complement negation. |
| `DABS` | `( d1 -- d2 )` | Double-precision absolute value. |
| `DMAX` | `( d1 d2 -- d3 )` | Maximum of two double-precision numbers. |
| `DMIN` | `( d1 d2 -- d3 )` | Minimum of two double-precision numbers. |
| `D<` | `( d1 d2 -- flag )` | True if `d1 < d2` (double-precision signed compare). |
| `D=` | `( d1 d2 -- flag )` | True if `d1 = d2`. |
| `2DROP` | `( d -- )` | Drops a double (two cells). |
| `2DUP` | `( d -- d d )` | Duplicates a double. |
| `2SWAP` | `( d1 d2 -- d2 d1 )` | Swaps two doubles. |
| `2OVER` | `( d1 d2 -- d1 d2 d1 )` | Copies the second double to the top. |
| `2ROT` | `( d1 d2 d3 -- d2 d3 d1 )` | Rotates three doubles. |
| `2>R` | `( d -- ) ( R: -- d )` | Moves a double to the return stack (nesting-aware: preserves the resume IP above it when inside a colon-word executor). |
| `2R>` | `( -- d ) ( R: d -- )` | Moves a double from the return stack back to the data stack. |
| `2R@` | `( -- d ) ( R: d -- d )` | Copies a double from the return stack without removing it. |
| `D0=` | `( d -- flag )` | True if the double is zero. |
| `D0<` | `( d -- flag )` | True if the double is negative. |
| `D2*` | `( d1 -- d2 )` | Double-precision left shift by 1 (multiply by 2), carrying across cells. |
| `D2/` | `( d1 -- d2 )` | Double-precision arithmetic right shift by 1 (divide by 2), preserving sign, carrying across cells. |

## Format & Numeric Output (`format_words.c`)

| Word | Stack Effect | Description |
|---|---|---|
| `.` | `( n -- )` | Prints `n` in the current base, followed by a space. |
| `.R` | `( n width -- )` | Prints `n` right-justified in a field of `width` characters. |
| `U.` | `( u -- )` | Prints `u` as unsigned, followed by a space. |
| `U.R` | `( u width -- )` | Prints `u` as unsigned, right-justified in a field of `width`. |
| `D.` | `( d -- )` | Prints double-cell `d` as signed decimal (or `DOUBLE-OVERFLOW` if it doesn't fit a single cell). |
| `D.R` | `( d width -- )` | Prints double-cell `d` right-justified in a field of `width`. |
| `.S` | `( -- )` | Prints the entire data stack contents non-destructively, prefixed with the depth. |
| `?` | `( addr -- )` | Fetches and prints the cell at `addr`. |
| `DUMP` | `( addr u -- )` | Prints a hex/ASCII memory dump of `u` bytes starting at `addr`. |
| `<#` | `( -- )` | Begins pictured numeric output conversion; resets the hold buffer. |
| `#` | `( ud \| n -- ud2 )` | Converts one digit of the number (in the current base) into the hold buffer. |
| `#S` | `( ud \| n -- 0 0 )` | Converts all remaining digits of the number into the hold buffer. |
| `#>` | `( [ud] -- addr u )` | Ends pictured numeric conversion; pushes the address and length of the formatted string. |
| `HOLD` | `( c -- )` | Prepends character `c` to the pictured-numeric hold buffer. |
| `SIGN` | `( n -- )` | If `n` is negative, holds a `-` character for pictured output. |
| `BASE` | `( -- addr )` | Pushes the VM address of the `BASE` variable (current numeric conversion radix). |
| `DECIMAL` | `( -- )` | Sets `BASE` to 10. |
| `HEX` | `( -- )` | Sets `BASE` to 16. |
| `OCTAL` | `( -- )` | Sets `BASE` to 8. |

## String & Text Processing (`string_words.c`)

| Word | Stack Effect | Description |
|---|---|---|
| `COUNT` | `( addr1 -- addr2 u )` | Converts a counted string (length-prefixed) at `addr1` into an address/length pair. |
| `EXPECT` | `( addr u -- )` | Reads a line from stdin into the buffer at `addr` (max `u` bytes) and updates `SPAN` with the actual length read. |
| `SPAN` | `( -- addr )` | Pushes the address of the `SPAN` variable, holding the character count from the last `EXPECT`/`QUERY`. |
| `QUERY` | `( -- )` | Reads a line from stdin into the terminal input buffer (TIB), resetting `>IN` to 0 and updating `SPAN`. |
| `TIB` | `( -- addr )` | Pushes the address of the terminal input buffer. |
| `WORD` | `( c -- addr )` | Parses the next word from the input stream delimited by character `c`, returning the address of a counted-string scratch buffer. |
| `(s")` | `( -- c-addr u )` | Runtime for compiled `S"` — reads an inline length-prefixed string from the threaded-code stream and pushes its address/length, advancing past it. |
| `S"` | `( "ccc<quote>" -- c-addr u )` | Parses a quoted string literal. Interpret mode: stores it at `HERE` and pushes address/length. Compile mode: compiles `(s")` plus the inline string data. Immediate. |
| `>IN` | `( -- addr )` | Pushes the address of the `>IN` input-stream-position variable. |
| `SOURCE` | `( -- addr u )` | Pushes the address and length of the current input source (the TIB). |
| `BL` | `( -- c )` | Pushes the ASCII code for space (32). |
| `[']` | `( -- xt )` | Parses the next word from the input stream and pushes (or compiles as a literal) its execution token. Immediate. |
| `LITERAL` | `( -- )` | Placeholder/no-op in this implementation. |
| `[LITERAL]` | `( -- )` | Placeholder/no-op in this implementation (delegates to `LITERAL`). |
| `CONVERT` | `( d1 addr1 -- d2 addr2 )` | Converts digit characters starting at `addr1` into a running double-precision accumulator `d1`→`d2` (simplified, base 10 only), returning the address just past the converted digits. |
| `NUMBER` | `( addr -- n flag )` | Converts a counted string at `addr` to a number (base 10 only); flag is 1 on success, 0 on failure. |
| `ENCLOSE` | `( addr c -- addr1 n1 n2 n3 )` | Parses a delimited field: `n1` = leading-delimiter count, `n2` = end offset of the field, `n3` = offset past trailing delimiters. |
| `-TRAILING` | `( addr u -- addr u' )` | Trims trailing ASCII spaces from a string (direct or counted-string form auto-detected), returning the trimmed length. |
| `CMOVE` | `( addr1 addr2 u -- )` | Copies `u` bytes from `addr1` to `addr2`, ascending address order (correct for overlap when `addr2 >= addr1`). |
| `CMOVE>` | `( addr1 addr2 u -- )` | Copies `u` bytes from `addr1` to `addr2`, descending address order (correct for overlap when `addr2 < addr1`). |
| `COMPARE` | `( addr1 u1 addr2 u2 -- n )` | Lexicographically compares two strings (direct or counted-string form), returns -1/0/+1. |
| `SEARCH` | `( addr1 u1 addr2 u2 -- addr3 u3 flag )` | Finds the first occurrence of string 2 within string 1; returns the matching tail and a found flag. |
| `SCAN` | `( addr u char -- addr' u' )` | Finds the first occurrence of `char` in the string, returning the tail starting there (or end-of-string if not found). |
| `SKIP` | `( addr u char -- addr' u' )` | Skips leading occurrences of `char` in the string, returning the remaining tail. |
| `BLANK` | `( addr u -- )` | Fills `u` bytes at `addr` with ASCII space (auto-detects counted-string form). |

## I/O & Terminal (`io_words.c`)

| Word | Stack Effect | Description |
|---|---|---|
| `EMIT` | `( c -- )` | Outputs the character `c` to the terminal. |
| `CR` | `( -- )` | Outputs a newline character. |
| `KEY` | `( -- c )` | Reads one character from the terminal and pushes it. |
| `?TERMINAL` | `( -- flag )` | Pushes whether input is available (stub implementation, always pushes false). |
| `TYPE` | `( addr u -- )` | Outputs `u` characters from VM memory starting at `addr`. |
| `SPACE` | `( -- )` | Outputs a single space character. |
| `SPACES` | `( n -- )` | Outputs `n` space characters. |
| `(do-string)` | `( -- )` | Runtime helper compiled by `."` — reads an inline length-prefixed string from the threaded code and prints it, advancing IP past it. Not meant to be called directly. |
| `."` | `( "ccc<quote>" -- )` | Immediate. Interpretation: parses and prints a string up to the closing `"` directly. Compilation: compiles `(do-string)` plus the inline string data. |

## Block & Mass Storage (`block_words.c`)

| Word | Stack Effect | Description |
|---|---|---|
| `BLOCK` | `( u -- addr )` | Returns the VM address of block `u`'s content, loading it if needed (does not mark dirty). |
| `BUFFER` | `( u -- addr )` | Returns the VM address of block `u`'s buffer without reading its content; marks it dirty. |
| `UPDATE` | `( -- )` | Marks the currently-loaded block (per `SCR`) dirty and syncs it to the underlying block-subsystem buffer. |
| `BLK-CONFIRM-FORMAT` | `( lbn -- )` | Commits the low-level disk container format for the slot owning block `lbn`; until called, writes to that disk slot are refused. Must be called only by the disk's owner after classifying its content as safe. |
| `SAVE-BUFFERS` | `( -- )` | Writes back every dirty block window slot to the block subsystem. |
| `EMPTY-BUFFERS` | `( -- )` | Invalidates all block window slots and zeroes all user blocks, without writing back. |
| `FLUSH` | `( -- )` | Same as `SAVE-BUFFERS` — syncs and invalidates all buffers. |
| `LOAD` | `( u -- )` | Sets `SCR` to `u` and interprets block `u`'s content as FORTH source. |
| `LIST` | `( u -- )` | Sets `SCR` to `u` and prints the block's content formatted as 16 lines of 64 characters with line numbers. |
| `THRU` | `( u1 u2 -- )` | Executes `LOAD` on every block from `u1` to `u2` inclusive. |
| `SCR` | `( -- addr )` | Pushes the VM address of the `SCR` (current block) variable. |
| `-->` | `( -- )` | Continues interpretation on the next sequential block after the current `SCR`. |

## Dictionary & Compilation (`dictionary_words.c`)

| Word | Stack Effect | Description |
|---|---|---|
| `HERE` | `( -- addr )` | Returns the dictionary pointer. |
| `ALIGN` | `( -- )` | Aligns the dictionary pointer to a cell boundary. |
| `ALLOT` | `( n -- )` | Allocates `n` bytes in the dictionary; `n` may be negative to deallocate. |
| `,` | `( n -- )` | Compiles a single cell value into the dictionary at `HERE`. |
| `C,` | `( c -- )` | Compiles a single byte value into the dictionary at `HERE`. |
| `2,` | `( d -- )` | Compiles a double-cell value into the dictionary at `HERE`, low cell first. |
| `PAD` | `( -- addr )` | Returns the VM address of the 512-byte scratch text buffer at top of memory. |
| `SP!` | `( sp -- )` | Sets the data stack pointer; can only shrink the stack, never grow it. |
| `SP@` | `( -- sp )` | Returns the current data stack-pointer index (top is 0). |
| `LATEST` | `( -- addr )` | Returns the VM address near the most recent compiled definition (end of dictionary). |

## Dictionary Manipulation (`dictionary_manipulation_words.c`)

`[`, `]`, `STATE` below are **shadowed** — see the collision note at the top of this
document; `defining_words.c`'s versions are the ones actually live.

| Word | Stack Effect | Description |
|---|---|---|
| `[` *(shadowed)* | `( -- )` | Enters interpretation mode. |
| `]` *(shadowed)* | `( -- )` | Enters compilation mode. |
| `STATE` *(shadowed)* | `( -- addr )` | Pushes the address of this file's own `state_variable` (a separate static, not the VM's `vm->state_addr` used by `defining_words.c`'s `STATE`). |
| `SMUDGE` | `( -- )` | Compile-only: intended to toggle the hidden/smudge bit of the latest word (function body is a stub/placeholder in the current source). |
| `HIDDEN` | `( -- )` | Compile-only: sets the hidden flag on the most recently defined word. |
| `>BODY` | `( xt -- addr )` | Converts an execution token to its data-field (body) address. |
| `>NAME` | `( xt -- addr )` | Converts an execution token to the address of its name field. |
| `NAME>` | `( addr -- xt )` | Converts a name-field address back to its execution token, by linear search of the dictionary. |
| `>LINK` | `( addr -- addr )` | Pushes the address of a dictionary entry's link field. |
| `LINK>` | `( addr -- addr )` | Dereferences a link-field address to get the next dictionary entry. |
| `CFA` | `( addr -- xt )` | Returns the code-field address of an entry — in this implementation, the entry pointer itself. |
| `LFA` | `( addr -- addr )` | Alias for `>LINK` — returns the link-field address. |
| `NFA` | `( addr -- addr )` | Returns the name-field address of a dictionary entry. |
| `PFA` | `( addr -- addr )` | Returns the parameter-field (body) address of a dictionary entry. |
| `TRAVERSE` | `( addr n -- addr )` | Moves forward or backward across a name field by `n`. |
| `INTERPRET` | `( -- )` | Sets interpret mode; actual interpretation is driven by the VM's own `vm_interpret()`, not this word's body. |
| `FIND` | `( "name" -- xt \| 0 )` | Parses the next word and pushes its dictionary entry pointer, or 0 if not found (a miss is not an error). |
| `'` | `( "name" -- xt )` | FORTH-79 tick: parses the next word and pushes its execution token; errors if not found. Non-immediate — the compiler compiles a call to it in compile mode. |

## Vocabulary System (`vocabulary_words.c`)

| Word | Stack Effect | Description |
|---|---|---|
| `VOCABULARY` | `( -- )` | Creates a new vocabulary; executing the created word selects itself as CONTEXT. |
| `DEFINITIONS` | `( -- )` | Sets CURRENT to CONTEXT, so new words are defined into the CONTEXT vocabulary. |
| `CONTEXT` | `( -- addr )` | Returns the VM address of the cell holding the CONTEXT vocabulary pointer. |
| `CURRENT` | `( -- addr )` | Returns the VM address of the cell holding the CURRENT vocabulary pointer. |
| `FORTH` | `( -- )` | Makes FORTH the CONTEXT vocabulary. |
| `ORDER` | `( -- )` | Prints the current search order (CONTEXT then FORTH) and CURRENT. |
| `(FIND)` | `( addr -- addr flag )` | Primitive finder: searches CONTEXT then FORTH vocabularies for the counted string at `addr`. |

## System & Environment (`system_words.c`)

| Word | Stack Effect | Description |
|---|---|---|
| `(` | `( -- )` | Begins a comment; skips input up to the matching `)`, honoring nested parens. Immediate. |
| `\` | `( -- )` | Line comment; skips input to the end of the current line. Immediate. |
| `COLD` | `( -- )` | Performs a cold start: resets VM state and rewinds `HERE` toward the base dictionary. |
| `WARM` | `( -- )` | Performs a warm restart: resets stacks/mode/error without rewinding `HERE`. |
| `BYE` | `( -- )` | Halts the VM, signalling the REPL to stop. (Overridden for Hera — see Kernel: Capsule Birth & Tripod Fleet below.) |
| `REBOOT` | `( addr len -- )` | Sets boot arguments from the given string and performs a cold reset (kernel target) or prints a hosted-stub message and halts. Interpret-only. |
| `SAVE-SYSTEM` | `( -- )` | Writes a trivial snapshot of VM memory (up to `HERE`) to `forth_system.img`. |
| `WORDS` | `( -- )` | Lists every word name currently in the dictionary, 8 per line, with a total count. |
| `VLIST` | `( -- )` | Lists every dictionary entry with its name, address, and flags byte. |
| `SEE` | `( "name" -- )` | Decompiles and prints the named word's definition (threaded code, or `<primitive>` for C words). |
| `PAGE` | `( -- )` | Clears the terminal screen via an ANSI escape sequence. |
| `EXECUTE` | `( xt -- )` | Executes the word whose execution token is on the stack. |
| `NOP` | `( -- )` | Does nothing. |
| `79-STANDARD` | `( -- flag )` | Prints and pushes whether FORTH-79 standard-compliance mode is active (-1) or not (0). |
| `QUIT` | `( -- )` | Clears the return stack and returns to the interpreter, without treating it as an error. Immediate. |
| `ABORT` | `( -- )` | Clears both stacks and returns to the interpreter; not treated as an error condition. |
| `(ABORT")` | `( flag addr len -- )` | Runtime helper for `ABORT"`: if `flag` is nonzero, prints the message at `addr len` and performs `ABORT` semantics. |
| `ABORT"` | `( flag -- )` | Parses a message up to the next `"`; if `flag` is nonzero (interpret mode) or at run time (compiled), prints it and aborts. Immediate. |

## Line Editor (`editor_words.c`)

Non-standard (not FORTH-79).

| Word | Stack Effect | Description |
|---|---|---|
| `L` | `( u -- )` | Prints line `u` (0-15) of the current SCR block. |
| `S` | `( c-addr len u -- )` | Sets line `u` of the current SCR block from a buffer, padding with spaces to 64 chars. |
| `SHOW` | `( -- )` | Prints the whole 16x64 current screen with line numbers. |
| `EDIT` | `( u -- )` | Enters a tiny interactive line-editor shell (stdin/stdout) on block `u`. |

## Defining Words (`defining_words.c`)

`[`, `]`, `STATE` here are the **live** versions — see the collision note at the top of this
document.

| Word | Stack Effect | Description |
|---|---|---|
| `:` | `( "name" -- )` | Begins a colon definition; parses the name and enters compile mode. Immediate. |
| `;` | `( -- )` | Ends a colon definition, compiling an implicit `EXIT` and returning to interpret mode. Immediate. |
| `CREATE` | `( "name" -- )` | Defines a new word whose runtime pushes its data-field address (FORTH-79: allocates no data itself). |
| `VARIABLE` | `( "name" -- )` | Defines a new word that allocates one cell (initialized to 0) and whose runtime pushes that cell's address. |
| `CONSTANT` | `( n "name" -- )` | Defines a new word whose runtime pushes the fixed value `n`. |
| `IMMEDIATE` | `( -- )` | Marks the most recently defined word as IMMEDIATE (executes during compilation instead of being compiled in). |
| `STATE` | `( -- addr )` | Pushes the VM address of the `STATE` variable (0 = interpreting, nonzero = compiling). |
| `[` | `( -- )` | Enters interpret state (sets `STATE` to 0). Immediate. |
| `]` | `( -- )` | Enters compile state (sets `STATE` to -1). |
| `FORGET` | `( "name" -- )` | Removes the named word and every word defined after it from the dictionary, rewinding `HERE`. |
| `COMPILE` | `( "word" -- )` | Legacy immediate word: parses the next word and compiles a call to it. Immediate. |
| `[COMPILE]` | `( "word" -- )` | Compiles the next word even if it is itself IMMEDIATE. Immediate. |
| `LIT` | `( -- n )` | Runtime primitive: fetches the next cell from threaded code (via the return-stack IP) and pushes it as a literal. |
| `LITERAL` | `( n -- )` | Compiles `n` as a literal into the current definition (via `LIT`). Immediate. |
| `does_rt` | `( -- )` *(inferred)* | Internal helper: patches the just-created child word to use the `DOES>` runtime and records the `DOES>` body address in its parameter field. Not meant to be called directly from FORTH. |
| `DOES>` | `( -- )` | Finalizes a defining word's CREATE-part and compiles the following code as the DOES>-body run by every word the defining word subsequently creates. Immediate, compile-only. |
| `DEFER` | `( "name" -- )` | Creates a deferred word with an empty execution-token slot; errors if executed before `IS` sets it. |
| `IS` | `( xt "name" -- )` | Stores execution token `xt` into a word previously created with `DEFER`. |
| `DEFER@` | `( "name" -- xt )` | Fetches the execution token currently stored in a deferred word. |

## Control Flow (`control_words.c`)

| Word | Stack Effect | Description |
|---|---|---|
| `(BRANCH)` | `( -- )` | Runtime: unconditional branch — reads a relative byte offset from the inline thread and adjusts the return-stack IP by it. |
| `(0BRANCH)` | `( f -- )` | Runtime: conditional branch — pops a flag; if zero, branches by the inline relative offset, otherwise skips it. |
| `(?DO)` | `( limit index -- )` | Runtime for `?DO` — if index equals limit the loop body is skipped entirely (branches past it); otherwise pushes (limit, index) onto the return stack as the loop frame. |
| `(DO)` | `( limit index -- )` | Runtime for `DO` — unconditionally pushes (limit, index) onto the return stack as the loop frame. |
| `(LOOP)` | `( -- )` | Runtime for `LOOP` — increments the loop index; if still less than the limit, branches back to the loop body, else drops the loop frame and falls through. |
| `(+LOOP)` | `( n -- )` | Runtime for `+LOOP` — adds `n` to the loop index; continues looping while the (signed-direction-aware) index hasn't crossed the limit, else exits. |
| `(LEAVE)` | `( -- )` | Runtime for `LEAVE` — forces the current loop to exit at the next `LOOP`/`+LOOP` by setting index equal to limit. |
| `IF` | `( f -- )` *(compile-time)* | Compiles a conditional branch (`0BRANCH`) with a placeholder target, pushed for later patching by `ELSE`/`THEN`. Immediate. |
| `ELSE` | `( -- )` *(compile-time)* | Patches the matching `IF`'s branch to land here, compiles an unconditional branch past the else-clause, pushed for `THEN` to patch. Immediate. |
| `THEN` | `( -- )` *(compile-time)* | Patches the matching `IF` or `ELSE` branch to land here, closing the conditional. Immediate. |
| `BEGIN` | `( -- )` *(compile-time)* | Marks the start of a loop (target for `UNTIL`/`AGAIN`/`REPEAT`). Immediate. |
| `WHILE` | `( f -- )` *(compile-time)* | Compiles a conditional exit branch inside a `BEGIN...REPEAT` loop, patched by `REPEAT`. Immediate. |
| `REPEAT` | `( -- )` *(compile-time)* | Compiles an unconditional branch back to `BEGIN` and patches `WHILE`'s exit branch to land after it. Immediate. |
| `AGAIN` | `( -- )` *(compile-time)* | Compiles an unconditional branch back to the matching `BEGIN` (infinite loop unless exited via `LEAVE`/`EXIT`). Immediate. |
| `UNTIL` | `( f -- )` *(compile-time)* | Compiles a conditional branch back to the matching `BEGIN`; loop repeats while the flag is false. Immediate. |
| `?DO` | `( limit index -- )` *(compile-time)* | Compiles the `(?DO)` runtime call plus loop-frame bookkeeping for `LOOP`/`LEAVE`. Immediate. |
| `DO` | `( limit index -- )` *(compile-time)* | Compiles the `(DO)` runtime call plus loop-frame bookkeeping for `LOOP`/`LEAVE`. Immediate. |
| `LOOP` | `( -- )` *(compile-time)* | Compiles the `(LOOP)` runtime call, patches the back-edge to `DO`/`?DO` and any pending `LEAVE` sites. Immediate. |
| `+LOOP` | `( n -- )` *(compile-time)* | Compiles the `(+LOOP)` runtime call, patches the back-edge to `DO`/`?DO` and any pending `LEAVE` sites. Immediate. |
| `LEAVE` | `( -- )` *(compile-time)* | Compiles the runtime leave-flag plus a forward branch out of the enclosing loop, patched at the next `LOOP`/`+LOOP`. Immediate. |
| `I` | `( -- i )` | Pushes the index of the innermost active `DO`/`?DO` loop. |
| `J` | `( -- j )` | Pushes the index of the next-outer `DO`/`?DO` loop (requires nested loops). |
| `UNLOOP` | `( -- )` | Discards the current loop's (limit, index) frame from the return stack without branching — used before an early `EXIT` from inside a loop. |
| `EXIT` | `( -- )` | Marks the current colon definition for a one-shot early return. |
| `CASE` | `( n -- n )` *(compile-time)* | Marks the start of a `CASE...OF...ENDOF...ENDCASE` selector statement. Immediate. |
| `OF` | `( n1 n2 -- \| n1 )` *(compile-time)* | Compiles a compare-and-branch (`OVER = 0BRANCH DROP`) for one `CASE` clause. Immediate. |
| `ENDOF` | `( -- )` *(compile-time)* | Ends one `OF` clause: patches its branch, compiles a jump to `ENDCASE`. Immediate. |
| `ENDCASE` | `( n -- )` *(compile-time)* | Ends the `CASE` statement: compiles a `DROP` for the selector and patches all `ENDOF` branches to land here. Immediate. |

## StarForth Extensions (`starforth_words.c`)

Each word is registered twice — once into the root vocabulary, once again into the
`STARFORTH` vocabulary context (`ENTROPY@`/`ENTROPY!` only registered the second time).
Listed once below.

| Word | Stack Effect | Description |
|---|---|---|
| `ENTROPY@` | `( addr -- n )` | Fetches the execution-heat counter for the `DictEntry` at `addr` (validated against the live dictionary chain). |
| `ENTROPY!` | `( n addr -- )` | Sets the execution-heat counter for the `DictEntry` at `addr`. |
| `WORD-ENTROPY` | `( -- )` | Prints execution-heat statistics (per word, total, average) for every word in the dictionary. |
| `RESET-ENTROPY` | `( -- )` | Resets every word's execution-heat counter and compudynamics metadata (temperature, latency, last-active) to zero. |
| `TOP-WORDS` | `( n -- )` | Prints the `n` most frequently executed words, sorted descending by execution heat. |
| `(-` | `( -- )` | Comment word: consumes input up to a balanced closing `)` — used for `init.4th` metadata markers. |
| `INIT` | `( -- )` | Reads `./capsules/core/init.4th`, remaps and copies its numbered blocks sequentially starting at block 1, executes them via `LOAD`, then zeroes the init blocks for userspace reuse. |
| `VERSION` | `( -- )` | Prints the StarForth version string (`STARFORTH_VERSION_FULL`). |
| `SEED` | `( n -- )` | Seeds the internal PRNG (LCG) with `n` (forces non-zero state). |
| `RANDOM` | `( lo hi -- n )` | Returns a pseudo-random integer in the inclusive range `[lo, hi]`. |
| `WAIT` | `( n -- )` | Waits `n` heartbeat ticks (calls `vm_tick()` n times) — architecture-independent, no wall-clock dependency. |
| `ZUSE-AUTHENTICATE` | `( -- )` | Sets `vm->zuse_session = 1` — C-only superuser bypass, no FORTH-level authentication logic. |

## Word-Level ACL (`acl_words.c`)

| Word | Stack Effect | Description |
|---|---|---|
| `ACL-MODE@` | `( xt -- mode )` | Fetches the ACL enforcement mode of the word `xt`: 0 = STRICT (permanent), 1 = TTL (expires after countdown). |
| `ACL-PINNED?` | `( xt -- flag )` | Pushes -1 if the word `xt` is pinned (its ACL fields are immutable), 0 otherwise. |
| `ACL-TTL@` | `( xt -- n )` | Fetches the current TTL countdown of the word's ACL entry. |
| `ACL-ALLOW@` | `( xt -- flag )` | Fetches the cached allow/deny decision for the word: -1 = allowed, 0 = denied. |
| `ACL-HEAT@` | `( xt -- heat )` | Fetches the execution-heat counter for the word (used to calibrate TTL). |
| `ACL-WORD-ID` | `( xt -- n )` | Fetches the word's stable `word_id`, assigned at registration and usable as a persistent table index. |
| `ACL-MODE!` | `( mode xt -- )` | Sets the ACL enforcement mode of word `xt`. No-op if the word is pinned. |
| `ACL-TTL!` | `( n xt -- )` | Sets the TTL countdown on the word's ACL entry (clamped to `[0, UINT32_MAX]`). No-op if pinned. |
| `ACL-ALLOW!` | `( flag xt -- )` | Sets the cached allow/deny decision for word `xt`. No-op if pinned. |
| `ACL-PIN` | `( xt -- )` | Sets `acl_pinned` on word `xt`. One-way ratchet — can never be cleared once set. |
| `ACL-INHERIT` | `( src dst -- )` | Copies `acl_mode` from `src` to `dst`, then clears `dst`'s pin, resets its TTL to 0, and sets `acl_allow` to 1 (optimistic default). |
| `ACL-INIT-PRIMITIVES` | `( -- )` | Walks the entire dictionary and resets ACL fields (TTL=0, allow=1, mode=TTL) on every unpinned entry. |

## Compudynamics: Benchmark (`physics_benchmark_words.c`)

| Word | Stack Effect | Description |
|---|---|---|
| `BENCH-DICT-LOOKUP` | `( iterations -- )` | Benchmarks dictionary lookup performance over a set of common words for the given iteration count; warns if iterations < 10,000 for statistical validity. |
| `PHYSICS-CACHE-STATS` | `( -- )` | Displays detailed hot-words cache statistics and current cache contents. |
| `PHYSICS-TOGGLE-CACHE` | `( -- )` | Enables/disables the hot-words cache at runtime for A/B testing. |
| `PHYSICS-RESET-STATS` | `( -- )` | Resets cache and pipeline-metrics statistics for a clean before/after comparison. |
| `PHYSICS-BUILD-INFO` | `( -- )` | Prints the current hot-words cache build configuration and runtime state. |
| `PHYSICS-BAYESIAN-REPORT` | `( addr_baseline -- )` | Generates a Bayesian inference report comparing current cache stats against a baseline. |

## Compudynamics: Pipelining Diagnostics (`physics_pipelining_diagnostic_words.c`)

Registers via `vm_create_word()` directly rather than `register_word()` — the only file in
the tree that does this (verified by a `vm_create_word(vm, "` sweep of the whole
`word_source/` directory).

| Word | Stack Effect | Description |
|---|---|---|
| `PIPELINING-SHOW-STATS` | `( c-addr u -- )` | Displays word-to-word transition metrics (prefetch attempts/hits/misses, latency saved) for the named word. |
| `PIPELINING-SHOW-TOP-TRANSITIONS` | `( c-addr u n -- )` | Displays the top `n` words that typically follow the named word, ranked by transition count. |
| `PIPELINING-RESET-ALL` | `( -- )` | Clears transition metrics from every word in the dictionary. |
| `PIPELINING-ENABLE` | `( -- )` | Reports whether pipelining metrics collection is enabled (compile-time flag; this word does not toggle it). |
| `PIPELINING-STATS` | `( -- )` | Displays aggregate pipelining statistics (transitions, prefetch hit rate) across the whole dictionary. |
| `PIPELINING-ANALYZE-WORD` | `( c-addr u -- )` | Comprehensive analysis of one word's transition predictability (entropy/distribution spread) plus prefetch net benefit. |

## Compudynamics: Freeze/Decay Control (`physics_freeze_words.c`)

| Word | Stack Effect | Description |
|---|---|---|
| `FREEZE-WORD` | `( caddr u -- )` | Sets `WORD_FROZEN` on the named word so its execution heat stops decaying; silently succeeds if not found. |
| `UNFREEZE-WORD` | `( caddr u -- )` | Clears `WORD_FROZEN` on the named word, letting heat decay resume normally. |
| `FROZEN?` | `( caddr u -- flag )` | Pushes true (-1) if the named word is frozen, false (0) otherwise or if not found. |
| `HEAT!` | `( heat caddr u -- )` | Directly writes `execution_heat` for the named word (diagnostics; bypasses normal accumulation/decay). |
| `HEAT@` | `( caddr u -- heat )` | Pushes the current `execution_heat` of the named word (0 if not found). |
| `SHOW-HEAT` | `( caddr u -- )` | Prints the named word's heat plus frozen/pinned status to stdout. |
| `ALL-HEATS` | `( -- )` | Prints a table of every dictionary word sorted by descending execution heat. |
| `DECAY-RATE@` | `( -- rate )` | Pushes the compile-time base heat decay rate (Q48.16) per microsecond used by Loop #3. |
| `FREEZE-CRITICAL` | `( -- )` | Freezes a hard-coded list of 21 system-critical words (`DUP`, `DROP`, `SWAP`, `IF`, `EXECUTE`, etc.) so they never decay out of the hot-words cache. |

## Compudynamics: General Diagnostics (`physics_diagnostic_words.c`)

| Word | Stack Effect | Description |
|---|---|---|
| `PHYSICS-WORD-METRICS` | `( -- )` | Displays temperature, execution heat, latency, mass, and derived thermal pressure for the most recently executed word. |
| `PHYSICS-CALC-KNOBS` | `( -- )` | Calculates and displays recommended priority/sampling/stack-limit/affinity adjustments based on the most recent word's thermal pressure. |
| `PHYSICS-BURN` | `( n -- )` | Executes the most recently executed word `n` times, printing thermal feedback progress and a final summary. |
| `PHYSICS-SHOW-FEEDBACK` | `( -- )` | Displays the full feedback-loop demonstration (metrics → math → knobs → effect) for the most recent word. |

## Dictionary Heat Optimization (`dictionary_heat_diagnostic_words.c`)

| Word | Stack Effect | Description |
|---|---|---|
| `HEAT-PERCENTILES` | `( -- 25th 50th 75th )` | Pushes the three heat percentile thresholds used by heat-aware dictionary lookup. |
| `LOOKUP-STRATEGY@` | `( -- strategy )` | Pushes the current lookup strategy: 0 = naive (newest-first), 1 = heat-aware. |
| `LOOKUP-STRATEGY!` | `( strategy -- )` | Sets the lookup strategy; only 0 or 1 accepted, other values silently discarded. |
| `REORG-BUCKETS` | `( -- )` | Forces an immediate re-sort of dictionary lookup buckets by heat and refreshes percentile thresholds. |
| `SHOW-HEAT-OPTIMIZATION` | `( -- )` | Prints a summary of lookup strategy, percentile thresholds, and resulting hot/warm/cool zones. |
| `COMPARE-LOOKUPS` | `( iterations -- )` | Micro-benchmarks naive vs. heat-aware dictionary lookup over six common words and prints the speedup/slowdown. |

## Log Level Control (`log_words.c`)

| Word | Stack Effect | Description |
|---|---|---|
| `LOG-ERROR` | `( -- n )` | Pushes the `LOG_ERROR` level constant. |
| `LOG-WARN` | `( -- n )` | Pushes the `LOG_WARN` level constant. |
| `LOG-INFO` | `( -- n )` | Pushes the `LOG_INFO` level constant. |
| `LOG-TEST` | `( -- n )` | Pushes the `LOG_TEST` level constant. |
| `LOG-DEBUG` | `( -- n )` | Pushes the `LOG_DEBUG` level constant. |
| `LOG-LEVEL!` | `( n -- )` | Sets the active log filter level (clamped to `[LOG_ERROR, LOG_DEBUG]`). |
| `LOG-LEVEL@` | `( -- n )` | Pushes the current log filter level. |
| `(do-log-error)` | `( -- )` | Runtime for compiled `LOG-ERROR"` — emits the inline string at ERROR level. |
| `(do-log-warn)` | `( -- )` | Runtime for compiled `LOG-WARN"` — emits the inline string at WARN level. |
| `(do-log-info)` | `( -- )` | Runtime for compiled `LOG-INFO"` — emits the inline string at INFO level. |
| `(do-log-test)` | `( -- )` | Runtime for compiled `LOG-TEST"` — emits the inline string at TEST level. |
| `(do-log-debug)` | `( -- )` | Runtime for compiled `LOG-DEBUG"` — emits the inline string at DEBUG level. |
| `LOG-ERROR"` | `( "ccc<quote>" -- )` | Logs a quoted string literal at ERROR level (interpret: immediate; compile: compiles the runtime + inline data). Immediate. |
| `LOG-WARN"` | `( "ccc<quote>" -- )` | Logs a quoted string literal at WARN level. Immediate. |
| `LOG-INFO"` | `( "ccc<quote>" -- )` | Logs a quoted string literal at INFO level. Immediate. |
| `LOG-TEST"` | `( "ccc<quote>" -- )` | Logs a quoted string literal at TEST level. Immediate. |
| `LOG-DEBUG"` | `( "ccc<quote>" -- )` | Logs a quoted string literal at DEBUG level. Immediate. |
| `LOG-ERROR-STR` | `( c-addr u -- )` | Logs a stack-supplied string (e.g. from `S"`) at ERROR level. |
| `LOG-WARN-STR` | `( c-addr u -- )` | Logs a stack-supplied string at WARN level. |
| `LOG-INFO-STR` | `( c-addr u -- )` | Logs a stack-supplied string at INFO level. |
| `LOG-TEST-STR` | `( c-addr u -- )` | Logs a stack-supplied string at TEST level. |
| `LOG-DEBUG-STR` | `( c-addr u -- )` | Logs a stack-supplied string at DEBUG level. |

## Q48.16 Fixed-Point Math (`q48_words.c`)

`cell_t` reinterpreted as `uint64_t`; 1.0 = 65536, resolution ≈ 0.0000153.

| Word | Stack Effect | Description |
|---|---|---|
| `Q.+` | `( q1 q2 -- q_sum )` | Q48.16 addition. |
| `Q.-` | `( q1 q2 -- q_diff )` | Q48.16 subtraction. |
| `Q.*` | `( q1 q2 -- q_prod )` | Q48.16 multiplication. |
| `Q./` | `( q1 q2 -- q_quot )` | Q48.16 division; returns `q=0` on division by zero. |
| `Q.ABS` | `( q -- \|q\| )` | Absolute value. |
| `Q.NEG` | `( q -- -q )` | Negation. |
| `Q.LOG` | `( q -- ln_q )` | Natural log via Newton-Raphson approximation. |
| `Q.EXP` | `( q -- e^q )` | Exponential via Taylor series approximation. |
| `Q.SQRT` | `( q -- sqrt_q )` | Square root via Newton-Raphson approximation. |
| `Q.SIN` | `( q -- sin_q )` | Sine (radians, any magnitude) via Taylor series. |
| `Q.COS` | `( q -- cos_q )` | Cosine (radians, any magnitude) via Taylor series. |
| `Q.FROM-INT` | `( n -- q )` | Converts integer to Q48.16 (`n << 16`). |
| `Q.TO-INT` | `( q -- n )` | Converts Q48.16 to integer, truncating (`q >> 16`). |
| `Q.1` | `( -- 65536 )` | Pushes 1.0 in Q48.16. |
| `Q.0` | `( -- 0 )` | Pushes 0.0 in Q48.16. |
| `Q.SCALE` | `( -- 65536 )` | Pushes the scale factor (alias of `Q.1`). |
| `Q.=` | `( q1 q2 -- flag )` | -1 if equal, else 0. |
| `Q.<` | `( q1 q2 -- flag )` | -1 if `q1 < q2`, else 0. |
| `Q.>` | `( q1 q2 -- flag )` | -1 if `q1 > q2`, else 0. |
| `Q.0=` | `( q -- flag )` | -1 if `q = 0`, else 0. |
| `Q.MAX` | `( q1 q2 -- q_max )` | Maximum of two Q48.16 values. |
| `Q.MIN` | `( q1 q2 -- q_min )` | Minimum of two Q48.16 values. |
| `Q.PRINT` | `( q -- )` | Prints as `"integer.frac"` to the console. |

Note: `q48_16_words.c` (despite the similar filename) registers no FORTH words at all — it's
a pure C support library (multiply/divide with wide intermediates) consumed by other files
like `ttf_words.c`, not a word-registration file.

## SSM Inference + Jacquard (`inference_words.c`)

| Word | Stack Effect | Description |
|---|---|---|
| `Q.VARIANCE` | `( addr u -- q )` | Computes the variance of `u` uint64 cells starting at `addr`, result as Q48.16. |
| `INFER-DECAY-SLOPE` | `( addr u -- q )` | Computes the exponential decay slope of `u` cells at `addr` via linear regression, as Q48.16. |
| `INFER-WINDOW-WIDTH` | `( addr u -- n )` | Computes the optimal window width from the variance inflection point of `u` cells at `addr`. |
| `WINDOW-DIVERSITY` | `( -- u )` | Pushes the rolling window's diversity (entropy) metric. |
| `INFER-RUN` | `( -- )` | Runs the full inference engine against this VM's rolling window and dictionary heat stats, updating `vm->last_inference_outputs`. |
| `INFER-WINDOW@` | `( -- u )` | Fetches the last computed adaptive window width. |
| `INFER-DECAY@` | `( -- q )` | Fetches the last computed adaptive decay slope (Q48.16). |
| `INFER-VARIANCE@` | `( -- q )` | Fetches the last computed window variance (Q48.16). |
| `INFER-FIT@` | `( -- q )` | Fetches the last computed slope fit quality (Q48.16). |
| `INFER-EARLY-EXIT@` | `( -- flag )` | Pushes 1 if the last `INFER-RUN` used the ANOVA early-exit path. |
| `L8-MODE` | `( -- n )` | Pushes the current L8 Jacquard mode (0-15). |
| `L8-UPDATE` | `( entropy_q cv_q temporal_q stability_q -- )` | Feeds four Q48.16 metrics into the L8 Jacquard mode selector's update function. |
| `L8-APPLY` | `( -- )` | Applies the current L8 mode to `vm->ssm_config` (legacy 16-mode path). |
| `L8-TABLE-FORCE` | `( config_idx -- )` | Forces the adaptive 128-config table onto `config_idx`, as if the bandit's own selection had picked it, and applies it immediately. |
| `BAYES-CACHE-MEAN` | `( -- q )` | Pushes the Bayesian mean latency estimate for hot-word cache hits (Q48.16). |
| `BAYES-CACHE-LOWER` | `( -- q )` | Pushes the 95% credible lower bound for cache-hit latency. |
| `BAYES-CACHE-UPPER` | `( -- q )` | Pushes the 95% credible upper bound for cache-hit latency. |
| `BAYES-BUCKET-MEAN` | `( -- q )` | Pushes the Bayesian mean latency estimate for dictionary bucket searches. |
| `BAYES-BUCKET-LOWER` | `( -- q )` | Pushes the 95% credible lower bound for bucket-search latency. |
| `BAYES-BUCKET-UPPER` | `( -- q )` | Pushes the 95% credible upper bound for bucket-search latency. |

## DEFER / Late Binding (`defer_words.c`)

| Word | Stack Effect | Description |
|---|---|---|
| `DEFER` | `( -- )` | Parses a name and creates a deferred word with an unset (0) data field; calling it before `IS` sets `vm->error`. |
| `IS` | `( xt -- )` | Parses a name (which must have been created by `DEFER`) and stores `xt` as its target action, enabling late binding. |
| `DEFER@` | `( -- xt )` | Parses a name (must be `DEFER`-created) and pushes its current target execution token. |

## Console Fabric — Framebuffer (`framebuffer_words.c`)

Kernel-only (`__STARKERNEL__`); no-ops on hosted builds. Raw hardware-boundary access —
FABRIC.md item 4.3.3.

| Word | Stack Effect | Description |
|---|---|---|
| `PLOT` | `( x y color -- )` | Raw raster pixel write at (x,y), top-left origin, Y-down. No Cartesian awareness. |
| `FB-WIDTH` | `( -- n )` | Pushes the framebuffer width in pixels (0 on hosted builds). |
| `FB-HEIGHT` | `( -- n )` | Pushes the framebuffer height in pixels (0 on hosted builds). |

## Console Fabric — Keyboard (`keyboard_words.c`)

| Word | Stack Effect | Description |
|---|---|---|
| `KBD-SCAN` | `( -- c -1 \| 0 )` | Pops one raw scancode off the amd64 i8042 ring buffer if available; pushes 0 if empty or on other architectures. |
| `KBD-DEBUG` | `( -- isr_count spurious_count )` | Pushes the i8042 interrupt and spurious-interrupt counters (amd64 diagnostic). |
| `VKBD-EVENT` | `( -- code value -1 \| 0 )` | Pops one decoded EV_KEY event off the virtio-input ring buffer (riscv64/aarch64); pushes 0 if empty. |
| `VKBD-DEBUG` | `( -- isr_count )` | Pushes the virtio-input interrupt counter (riscv64/aarch64 diagnostic). |
| `KEY-EVENT` | `( -- keycode pressed -1 \| 0 )` | Cross-architecture converged key event: pops one keycode/pressed pair in the Linux input-keycode namespace, translated from whichever backend (i8042 or virtio-input) is live. |
| `ALT+TAB` | `( -- )` | Programmatic equivalent of the physical Alt+Tab interception — toggles the framebuffer graphics/text overlay state. |

## Console Fabric — TrueType Text (`ttf_words.c`)

Kernel-only (`__STARKERNEL__`); no-op on hosted builds. FABRIC.md item 4.3.7e.

| Word | Stack Effect | Description |
|---|---|---|
| `TTF-TEXT` | `( c-addr u x y size color -- )` | Renders a UTF-8 string via the TrueType rasterizer at Cartesian position (x,y) (origin bottom-left of the framebuffer) with the given point size and color. |

## Console Fabric — Scrollback (`scroll_words.c`)

Kernel-only (`__STARKERNEL__`); no-op on hosted builds. FABRIC.md item 4.4q (boot-mode
scrollback added by 4.4ac).

| Word | Stack Effect | Description |
|---|---|---|
| `SCROLL-BACK` | `( n -- )` | Moves the REPL framebuffer scrollback view back `n` lines. |
| `SCROLL-FWD` | `( n -- )` | Moves the REPL framebuffer scrollback view forward `n` lines, toward live. |

## Kernel: Capsule Birth & Tripod Fleet (`mama_forth_words.c`)

Kernel-only (`__STARKERNEL__`). Implements the MAMA vocabulary — capsule birth protocol and
Tripod fleet control (`src/starkernel/capsule/mama_forth_words.c`). Two registration
functions exist: `register_mama_forth_words()` gives Hera (Mama) her full word set,
registered identically into both the FORTH and MAMA vocabularies; `register_child_vm_words()`
gives child VMs (Hermes/Artemis/etc.) a smaller subset, since they aren't bootstrapped
through the same path.

**Hera's word set:**

| Word | Stack Effect | Description |
|---|---|---|
| `BYE` | `( -- )` | Hera-only override: reaps all child VMs, then cold-restarts the machine. (Children instead get the standard `system_word_bye` from `system_words.c`, which just halts back to the parent's REPL.) |
| `CONNECT-HERMES` | `( -- )` | Enters Hermes's REPL, birthing her first if not already live/stopped (idempotent). |
| `CONNECT-ARTEMIS` | `( -- )` | Enters Artemis's REPL, birthing her first if not already live/stopped (idempotent). |
| `BIRTH` | `( c-addr u -- )` | Births a named child VM from its capsule (name → `name:init.4th`). Idempotent if already live; refuses to re-birth Hera. |
| `KILL` | `( c-addr u -- )` | Destroys a named VM unconditionally, fanning its heat out to survivors first. Hera cannot be killed. Idempotent. |
| `START` | `( c-addr u -- )` | Enters a named VM's REPL loop synchronously; caller blocks until the target halts via STOP/BYE. Cannot start a LIVE/DEAD/STILLBORN VM. |
| `STOP` | `( -- )` | Self-stop: sets `vm->halted` so the current VM's REPL loop exits on its next iteration. Registered in every VM including children. |
| `USE` | `( c-addr u -- )` | Redirects system-wide REPL input to a named VM without touching the C call stack; `USE Hera` resets to default dispatch. |
| `EXEC` | `( c-addr u -- )` | Executes a named capsule in the current VM — same path as Mama's own init auto-run. |
| `CAPSULE-COUNT` | `( -- n )` | Pushes the number of capsules in the capsule directory. |
| `CAPSULE@` | `( idx -- desc )` | Pushes the capsule descriptor address at index `idx` (0 if out of bounds). |
| `CAPSULE-HASH@` | `( desc -- hash )` | Pushes the content hash field from a capsule descriptor. |
| `CAPSULE-FLAGS@` | `( desc -- flags )` | Pushes the flags field from a capsule descriptor. |
| `CAPSULE-LEN@` | `( desc -- len )` | Pushes the payload length field from a capsule descriptor. |
| `CAPSULE-BIRTH` | `( capsule-id -- vm-id-hi vm-id-lo )` | Births a baby VM from a production (p) capsule by index; returns the new VM's 128-bit ID as a double, or all-ones on failure. |
| `CAPSULE-RUN` | `( capsule-id -- )` | Runs an experiment (e) capsule on Mama by index. |
| `MAMA-VM-ID` | `( -- 0 0 )` | Pushes Mama's (Hera's) own VM ID as a double — always zero. |
| `VM-COUNT` | `( -- n )` | Pushes the number of registered VMs. |
| `VM-CONSERVED?` | `( -- flag )` | FORTH boolean: true if the fleet heat sum is within epsilon of `Q.1` (conservation check). |
| `VM-PHYSICS-STATUS` | `( -- )` | Prints the fleet compudynamics diagnostic report. |
| `VM-STEP` | `( c-addr u -- )` | Gives one REPL turn (prompt, read one line, execute, return) to a named VM — the Compudynamics context-switch primitive. |
| `VM-EXEC` | `( cmd-caddr cmd-u vm-name-caddr vm-name-u -- )` | Injects and immediately executes a command string in a named VM, no readline/blocking. |
| `VM-CALL` | `( cmd-caddr cmd-u vm-name-caddr vm-name-u -- n )` | Like `VM-EXEC` but pops one cell from the target's stack afterward and pushes it onto the caller's stack (cross-VM query primitive). |
| `CAPSULE-TEST` | `( -- )` | Prints a diagnostic message confirming the capsule system is active. |

**Additional words in `register_child_vm_words()` only (not in Hera's own dictionary — this
keeps Hera's `dict_hash` off item 4.1's baseline):**

| Word | Stack Effect | Description |
|---|---|---|
| `STADIUM-ADMIT` | `( identity heat behaviour -- cell \| -1 )` | Admits a mass-1 patron into the calling VM's own Stadium quota; -1 if behaviour tag is invalid or admission is refused. |
| `STADIUM-EVICT` | `( cell -- flag )` | Reaps the patron header at `cell`; true (-1) on success, false (0) if refused (out of range, not resident, pinned, or contains-gated). |
| `STADIUM-RES@` | `( -- heat )` | Read-only peek at the calling VM's own reservoir balance (Q48.16). |
| `STADIUM-RES-PULL` | `( qty -- heat )` | Pulls up to `qty` (Q48.16) from the calling VM's own reservoir; returns the amount actually pulled (never more, never negative). |
| `STADIUM-RES-PUSH` | `( heat -- )` | Credits heat (Q48.16) back into the calling VM's own reservoir. |
| `STADIUM-HEAT@` | `( cell -- heat )` | Reads a resident cell's own heat; 0 if not resident or not owned by the calling VM. |
| `STADIUM-HEAT!` | `( new-heat cell -- )` | Writes a resident cell's own heat, atomically reconciling the reservoir delta; silently refused if not owned by the calling VM or reservoir can't cover an increase. |
| `STADIUM-WORD-HEAT` | `( -- heat )` | Sum of heat held by the calling VM's own word-execution residents (item 4.1's cells) — closes the term application-level conservation checks (e.g. Hermes's `HERMES-K`) need. |

## Hosted-Build-Only Lifecycle Stubs (`lifecycle_words_hosted.c`)

Compiled only when `__STARKERNEL__` is **not** defined. In the hosted build there is no
capsule blob or kernel VM registry, so these five just consume their arguments and log
intent — real behavior lives in `mama_forth_words.c` (`BIRTH`/`USE`) plus separate
kernel-side `KILL`/`PAUSE`/`RESUME` words for the kernel build.

| Word | Stack Effect | Description |
|---|---|---|
| `BIRTH` | `( c-addr u -- )` | Hosted stub: logs "BIRTH name (hosted)"; no real VM lifecycle in the hosted build. |
| `KILL` | `( c-addr u -- )` | Hosted stub: logs "KILL name (hosted)". |
| `PAUSE` | `( c-addr u -- )` | Hosted stub: logs "PAUSE name (hosted)". |
| `RESUME` | `( c-addr u -- )` | Hosted stub: logs "RESUME name (hosted)". |
| `USE` | `( c-addr u -- )` | Hosted stub: logs "USE name (hosted)". |

---

## Keeping this current

This document was built by reading every `register_word()` (and the one `vm_create_word()`)
call site directly, plus the doc comment above each implementing function. When words are
added, removed, or re-registered:

1. Update the relevant category table above — keep registration order within a file, not
   alphabetical.
2. If a new file registers a name that collides with an existing one, add it to the collision
   note at the top of this document and mark both entries (`*(shadowed)*` / live) at point of
   use, the same way `[`/`]`/`STATE` and `MOD`/`/MOD`/`*/`/`*/MOD` are handled above —
   determine the winner from `register_forth79_words()`'s call order in `src/word_registry.c`
   (later registration wins; search is newest-first via `vm->latest`/`->link`).
2. If a new `word_source/*.c` file is added, give it its own `##` section, placed near
   related categories.
3. Word counts aren't tracked as a running total in this document on purpose — they drift
   too easily and the categories are the useful unit, not a single number. If a total is
   needed, `grep -rc 'register_word(' src/word_source/*.c src/starkernel/capsule/mama_forth_words.c`
   plus a check for `vm_create_word(vm, "` (the one alternate registration path found so
   far) gets close, but always verify against this document rather than trusting either
   grep alone — see the `physics_pipelining_diagnostic_words.c` case above for why.