feat(v4.0.0): the defining and compiling words

The fourth layer of the compiler capsule.  compile.v4: INTERPRET's
loop, STATE [ ] : ; EXIT IMMEDIATE LITERAL COMPILE [COMPILE] ' EXECUTE,
CREATE VARIABLE CONSTANT DOES>, and IF ELSE THEN BEGIN UNTIL AGAIN
WHILE REPEAT DO ?DO LOOP +LOOP on a control-flow stack in memory.
forth.v4: the first words of the vocabulary, the in-line ones.

FORTH source now goes in and running code comes out.  49 programmes
were run through the v3 binary and through this; every result agrees,
bar COMPILE, which v3 cannot run.  The code laid down for each control
structure is word for word the expansion DECOMPOSITION.md gives.

A line may have six values on the stack while it is interpreted, and
words called from the interpreter may nest eight deep.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/v4.0.0/DECOMPOSITION.md

@@ -682,10 +682,10 @@ The storage service belongs to the Artemis role, now a device node.
 | Word | Fate |
 | --- | --- |
 | `FIND` | CC | `( -- xt \| 0 )`, FORTH-79 and v3 alike: the compilation address of the next word in the input stream, or 0 if it is not in the dictionary. `32 WORD` then a search from the newest entry back, skipping hidden ones; names are case sensitive, as v3, and 31 characters are significant (FORTH-79). Executed on the golden model's host node (2026-10-04) against a list kept in C, 300 entries. Leaves its caller 7 data cells and 5 return entries. |
-| `'` | CC | `( -- addr )`, FORTH-79: the parameter field address of the next word in the input stream; not found is an error (0, and `NODE-ERROR` set). v3's `'` returned what `FIND` returns. For a word that is code the two are the same address; for a data word the parameter field is the cell after its code, which is what FORTH-79's `n ' NAME !` needs. Its compiling behaviour comes with the compiler words. Executed on the golden model's host node (2026-10-04). |
+| `'` | CC | `( -- addr )`, FORTH-79: the parameter field address of the next word in the input stream; not found is an error (0, and `NODE-ERROR` set). v3's `'` returned what `FIND` returns. For a word that is code the two are the same address; for a data word the parameter field is the cell after its code, which is what FORTH-79's `n ' NAME !` needs. It is immediate: inside a definition the address is compiled as a literal (FORTH-79), where v3's `'` parsed when the definition ran. Executed on the golden model's host node (2026-10-04). |
 | `>LINK` `LFA` `LINK>` `>NAME` `NFA` `NAME>` `CFA` `PFA` `>BODY` `TRAVERSE` | CC | The fields of an entry, all reached from its xt, as in v3 where the xt was the entry: `>LINK`/`LFA` the link's address, `LINK>` the older entry's xt, `>NAME`/`NFA` the byte address of the counted name, `NAME>` back to the xt, `CFA` the xt itself, `PFA`/`>BODY` the parameter field, `TRAVERSE` from a name's count byte to past its last character (for `n > 0`; otherwise unchanged, as v3). Executed on the golden model's host node (2026-10-04). |
 | `SMUDGE` `HIDDEN` | CC | `SMUDGE` toggles the hidden flag of the newest entry; `HIDDEN` sets it. v3 refuses both outside compilation; that check comes with the compiler words. Executed on the golden model's host node (2026-10-04). |
-| `INTERPRET` | CC |  |
+| `INTERPRET` | CC | FORTH-79; source in `v4/capsule/compile.v4`. Takes words from the input stream until it is exhausted: a word in the dictionary is executed, or, when compiling and not immediate, compiled; anything else must be a number in the current `BASE` (a single cell, with an optional leading minus), left on the stack or compiled as a literal. What is neither, or a compile-only word met while interpreting, abandons the line: compiling stops, the definition under way stays hidden, the rest of the input is skipped and `NODE-ERROR` is set (the message and the stack reset come with `QUIT`). Executed on the golden model's host node (2026-10-04). |
 
 An entry, as `v4/capsule/dict.v4` builds it. A word's execution address (xt) is the address of its
 code, and everything else is found from it:
@@ -713,7 +713,7 @@ it, `xt + 1`; for any other word the parameter field is the code itself.
 | Word | Fate | Notes |
 | --- | --- | --- |
 | `(` `\` | CC | `(` is `41 WORD drop`; `\` is `SPAN @ >IN !`. In `v4/capsule/input.v4` under the names `PAREN` and `BACKSLASH`. Executed on the golden model's host node (2026-10-04). |
-| `EXECUTE` | CAP | `push ;` (tail-jumps to the xt; the xt returns to `EXECUTE`'s caller) |
+| `EXECUTE` | CAP | `push ;` (tail-jumps to the xt; the xt returns to `EXECUTE`'s caller). Executed on the golden model's host node (2026-10-04). |
 | `NOP` | OP | `nop` |
 | `QUIT` `ABORT` `ABORT"` `(ABORT")` `COLD` `WARM` | CC |  |
 | `BYE` `REBOOT` | HERA |  |
@@ -732,10 +732,35 @@ it, `xt + 1`; for any other word the parameter field is the code itself.
 
 | Word | Fate | Notes |
 | --- | --- | --- |
-| `:` `;` `CREATE` `VARIABLE` `CONSTANT` `DOES>` `IMMEDIATE` `STATE` `[` `]` `LITERAL` `COMPILE` `[COMPILE]` `FORGET` `FENCE` | CC |  |
+| `:` `;` `EXIT` `IMMEDIATE` `STATE` `[` `]` `LITERAL` `COMPILE` `[COMPILE]` | CC | Source in `v4/capsule/compile.v4`, all to FORTH-79. `:` makes an entry and starts compiling; the word cannot be found until `;`, so a redefinition can use the old word. `;` lays the return, reveals the word and stops compiling. `LITERAL` compiles the number on the stack when compiling. `COMPILE xxx` lays code that compiles `xxx` when the word it is in runs; `[COMPILE] xxx` compiles `xxx` though it is immediate. Executed on the golden model's host node (2026-10-04) against results recorded from the v3 binary; v3's `COMPILE` does not work (`: C1 COMPILE DUP ; IMMEDIATE  : U3 C1 + ;` gives `DUP: Stack underflow`), reported, not fixed. |
+| `CREATE` `VARIABLE` `CONSTANT` `DOES>` | CC | FORTH-79. A data word's code is one instruction word, a call to its run-time routine, and its parameter field is the cell after it: `(DOVAR)` is `pop ;` (the call's return address is the parameter field's address) and `(DOCON)` is `pop a! @ ;`. `VARIABLE` allots one cell, set to 0. `DOES>` lays a call to `(DOES)` and then `pop`: `(DOES)`, run by the defining word, rewrites the newest entry's code into a call to the code after it and returns from the defining word; that code's `pop` fetches the parameter field address. Executed on the golden model's host node (2026-10-04) against results recorded from the v3 binary. |
+| `FORGET` `FENCE` | CC |  |
 | `LIT` | OP | `@p` |
 | `does_rt` | RET | Internal helper; `DOES>` is implemented by the compiler capsule. |
 
+**How a word is compiled.** v4 code is native: a colon definition is instruction words, and
+compiling a word into one lays down a call to it. Two flags on an entry change that. An **in-line**
+word's code is a straight run of opcodes and literals ending in `;`, and that run is copied in place
+of a call; this is fate IN (§0), and everything that touches the return stack must be in line, since a
+call would bury what it works on. A **compile-only** word may not be executed by the interpreter.
+`v4/capsule/forth.v4` holds the first words of the vocabulary flagged this way (`DUP`, `+`, `>R`, `I`,
+`LEAVE`, `@`, the in-line variables and so on).
+
+**The short stacks (D-2) and the compiler.** The interpreter and compiler run on the same ten-cell and
+nine-entry stacks as the user's words, with the user's values beneath them. Two consequences are
+built into the capsule:
+
+- Every word of the capsule keeps what it works on in memory and has at most three cells of its own on
+  the data stack. Measured on the golden model: a line may have **6 values on the stack** while the
+  interpreter reads its next word, and defining and running a word leaves 4 cells under it untouched.
+- Words called from the interpreter may nest **8 deep**; a `DO` loop takes two return entries, so two
+  nested loops leave four. `*` is therefore not `UM* drop` on the host node but N steps of `+*` with
+  only the count on the return stack; it gives the same low cell (what `+*` loses at the top of `T`
+  takes N shifts to reach the bit that moves into `A`, and the loop ends first).
+
+A programme that v3 runs with more than that on its stacks does not run here; that is D-2, not the
+compiler.
+
 **The code generator** (`v4/capsule/codegen.v4`) is what these words are built on. It packs opcodes,
 literals and branches into instruction words at `HERE`, by the rules of §1.2 and §2: slots filled left
 to right, unused slots `nop`, a literal's value in the cell after its word, `;` `ex` and any branch
@@ -761,7 +786,9 @@ lays down was then run.
 
 | Word | Fate | v4 definition / notes |
 | --- | --- | --- |
-| `IF` `ELSE` `THEN` `BEGIN` `UNTIL` `AGAIN` `WHILE` `REPEAT` `DO` `?DO` `LOOP` `+LOOP` `LEAVE` `CASE` `OF` `ENDOF` `ENDCASE` | CC | Compile-time structure words. Expansions per §2 and below. |
+| `IF` `ELSE` `THEN` `BEGIN` `UNTIL` `AGAIN` `WHILE` `REPEAT` `DO` `?DO` `LOOP` `+LOOP` | CC | Compile-time structure words, immediate and compile-only; source in `v4/capsule/compile.v4`. Expansions per §2 and below. What an opening word leaves for the word that closes it goes on a **control-flow stack in memory** (32 cells), not on the data stack, with a number saying which word left it; a closing word that finds the wrong number, or nothing, abandons the line. A loop that tests at its end (`UNTIL`) must drop the flag on both ways out, so `BEGIN` lays `jump L0  Ld: drop  L0:` and `UNTIL` lays `if Ld  drop`. Executed on the golden model's host node (2026-10-04): the code laid down for each is word for word what the text assembler makes of the expansion given here, and the programmes run give what the v3 binary gave. |
+| `LEAVE` `I` `J` `UNLOOP` | CC | In-line words (below), compile-only. |
+| `CASE` `OF` `ENDOF` `ENDCASE` | CC |  |
 | `EXIT` | OP | `;` |
 | `(BRANCH)` | OP | `jump` |
 | `(0BRANCH)` | IN | `if L … drop` (§2) — executed on the golden model (2026-10-03) as `IF 1 ELSE 2 THEN`, including results recorded from the v3 binary. |