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).
3. If a new word_source/*.c file is added, give it its own ## section, placed near related categories.
4. 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.