LithosAnanake/docs/v4.0.0/ENGINE.md

StarForth v4.0.0 — The F18 engine in the VM's place

Design, 2026-10-05. Written from Captain Bob's rulings of that day (V3-PARITY.md sections 1a to 1h, where each is recorded with its words) and from v3's code. It replaces the lone-node assumptions of NUCLEUS.md sections 5.3 and 7 to 9.

1. The principle

JUSTIFICATION.md section 16: v4 is equivalent to v3 at any point in time; "the only difference is the machine underneath: the F18-derived engine instead of the original StarForth VM."

Ruled 2026-10-05: v4 is exactly like v3 in functional requirements up to the first FORTH prompt, and that is the stopping point for now. Nothing is stubbed, simulated or stood in for.

So v4 is not a new system beside LithosAnanke. It is LithosAnanke with a different machine executing its FORTH.

2. What stays, and what is replaced

Stays, untouched: everything the kernel does. The Stadium and each patron's own accounts; sessions; the switcher; kernel-Hermes; the capsule directory, birth protocol, hashing, signing and parity; the block subsystem and its devices; identity and Zuse; the HAL console, Hestia, the console proxies and the kernel's REPL; the heartbeat; the boot order in kernel_main.c.

Replaced: the part of a v3 VM that executes FORTH.

v3	v4
The inner interpreter (v3/src/vm.c, kernel/src/vm/vm_core.c)	The node: v4/src, 32 opcodes
The dictionary as a list of C DictEntry records	The dictionary in the node's memory (v4/capsule/dict.v4)
The FORTH-79 words as C functions (v3/src/word_source)	The assembled nucleus (v4/capsule/*.v4) and colon definitions in capsules/v4/forth79.4th
The outer interpreter and compiler in C	The same, in the nucleus

A v3 VM is also a record the kernel keeps: its identity, its Stadium ID, its heartbeat state, its place in the registry, its Zuse flags. That record stays. What changes is what stands behind it.

3. The interface

The kernel reaches a VM through a small number of things. Each is listed with what v3 has, what was ruled, and what a node needs. This is the whole of the work: when a node answers all of these, the kernel's boot runs on it as it runs on a v3 VM.

3.1 Interpret this text

v3: vm_interpret(vm, text). The kernel's REPL hands over each line it has read; capsule_exec_payload hands over each line of a capsule; kernel-Hermes hands over a message's payload when the target drains its queue. The VM runs the text and returns, with its error flag set or not.

Ruled: the kernel hands a node a whole line and takes characters back; the node's own prompt loop plays no part at that level. A node receives a message by being handed its text.

v4: the node has an entry that interprets the text in its input buffer and then stops, saying how the line ended: completed, ended in an error, or QUIT. It prints no prompt and no ok. The buffer takes 1024 characters, a block, as v3's does. QUIT and ABORT end the line and return to whoever handed it over. KEY, EXPECT and QUERY stay FORTH-79 words that read characters.

With this one entry v3's capsule loader, REPL and message drain can all drive a node, and v4/system/boot.c's own loader is not needed.

3.2 A character out

v3: the host service putc, then console_putc; the fabric adds [user@VM].

v4: the node's EMIT gives the character to its host, which calls the same service. Present today.

3.3 Asking the kernel

v3: a kernel word is a C function registered in the VM's dictionary: BIRTH, KILL, USE, the block words, the Stadium and Hermes words, the framebuffer words. It takes its arguments from the VM's data stack.

Ruled: a node asks for a block by number and the kernel decides the rest; a node sends a message by asking.

v4, ruled 2026-10-05: a kernel word is an ordinary dictionary entry on the node whose body writes its request number to the node's port. The write blocks the node until the kernel, its neighbour on that port, has served it (DECOMPOSITION.md section 6: "a write blocks until the neighbour reads"). The kernel serves between the node's opcodes, so the node is always stopped when C touches it; the function takes its arguments from the node's data stack and leaves its results there. Kernel words are made by handing the node text at boot. The C functions are v3's.

3.4 The stacks and the dictionary, from the kernel's side

v3: vm_push, vm_pop, vm_find_word, and the fields of a DictEntry (the kernel pins BIRTH and CAPSULE-BIRTH by setting two of them).

v4: the same operations on the node's stacks and on entries in the node's memory.

3.5 A word is being executed

v3: the inner loop, for every word: the ACL's countdown and recheck, execution_heat, stadium_word_dispatch, the rolling window, pipelining.

Ruled: the word card stays exactly as v3 — a run-time check, the TTL adaptive from the word's own count. Every kind of patron keeps its own accounts; the word's are as v3. Opcodes are counted and left unwired.

v4: the node dispatches a word at the call opcode, one place in the engine. The node does there what v3's loop does. A word that is to be checked must be called, so the in-line words that can be called become calls.

3.6 An error

v3: vm->error. v4: how a line ended (3.1), and the node's error register for a C function to raise one.

3.7 A tick

v3: the kernel's timer drives vm_tick and the heartbeat state in the VM's record. v4: unchanged; that state is the record's, not the engine's.

3.8 The dictionary hash

v3: vm_dict_hash_fn, a hook the birth protocol calls. v4: the same hook, answered from the node's dictionary.

3b. A word's two halves (ruled 2026-10-05: "A is good")

V3-PARITY.md section 1j. A word on a node is its name and its code, in the node's memory, with its word ID in its header. Its accounts are v3's own DictEntry record, kept by the kernel: execution_heat, physics, the four ACL fields, the transition metrics, the word ID. The two are joined by the word ID.

• The node tells the kernel when a word is defined and when words are forgotten, by a request through its port. The kernel makes or drops the record.
• At each call the kernel does on the record what v3's inner loop does (3.5).
• v3's physics, heartbeat, ACL words, Stadium word layer and parity run on the records, unchanged. The ACL fields v4 keeps in an entry's flags cell (v4/capsule/acl.v4) go: v3's C ACL words serve a node as they are.

3c. What exactly is swapped, in v3's own files

Measured 2026-10-05. Each build already has one file that is the interpreter, and the rest of v3 calls into it:

Build	The interpreter file	The stacks
Hosted	v3/src/vm.c	v3/src/stack_management.c
Kernel	kernel/src/vm/vm_core.c (the kernel build leaves v3/src/vm.c out)	the same

The functions in it that execute FORTH, and so are the node's to answer: vm_interpret, vm_interpret_word, execute_colon_word, acl_recheck, vm_parse_word, vm_parse_number, vm_enter_compile_mode, vm_exit_compile_mode, vm_compile_word, vm_compile_literal, vm_compile_call, vm_compile_exit, vm_make_immediate; the memory accessors vm_addr_ok, vm_ptr, vm_load_u8, vm_store_u8, vm_load_cell, vm_store_cell; and the stacks, vm_push, vm_pop, vm_rpush, vm_rpop. The rest of those files — host services, the time base, vm_cleanup — is not the engine and stays.

So the swap is a third interpreter file, for both builds: the same functions, answered by a node. Everything else of v3 is compiled as it is.

The two products part here (Captain Bob, 2026-10-05): "I would say we are at a fair point where the hosted product and the bare metal product diverge completely."

This section first said the hosted v4 product should become v3's hosted program with the node as its interpreter. That is withdrawn. From here:

• The bare-metal product is LithosAnanke with the node in the VM's place. Everything in this document about the kernel's interface, word records, the hook at call, the fleet and identity is the bare-metal product's. The third interpreter file is for the kernel build.
• The hosted product is its own thing and is not required to follow the bare-metal one. Today it is the node, the nucleus, the FORTH-79 capsule, POST and its own prompt (v4/tools/hosted.c, v4/system/boot.c), and it works on three ISAs.
• The six builds no longer have to print the same lines. The three hosted builds agree with each other; the three bare-metal builds agree with each other.

What the two share (confirmed by Captain Bob the same day, "yes, exactly"): the engine in v4/src; the FORTH-79 capsule, capsules/v4/forth79.4th; and its POST, capsules/v4/post79.4th. The nuclei are separate. The bare-metal nucleus needs word IDs in its headers and words that are called where the hosted one compiles them in line; the hosted nucleus need not have either. The hosted product may become a hosted version of an SDK.

Two things in v3's C words do not carry over as they are, and must be dealt with word by word:

• A C word that takes an address from the stack and reads memory through vm_ptr gets a pointer into v3's flat bytes. A node's bytes are four to a cell (D-1), so they are not a flat run of C bytes. Such a word needs the text copied out of the node. mama_forth_words.c has 40 such uses.
• A C word that reaches into vm->data_stack or vm->dsp directly must go through vm_push, vm_pop or a depth accessor. mama_forth_words.c has 45.

Both are changes to files v3 also builds, so each must leave v3 as it is and be accepted by v3's own three-ISA boot.

3a. Many VMs at once (Captain Bob, 2026-10-05)

Do not forget that this is multiuser, multitasking, and a hybrid of preemptive and cooperative.

And, the same day: "Hera will be the process manager via compudynamics per node."

What that asks of the engine, and what it has:

• A node can be stopped between any two instruction words and gone on with later. Everything a node is doing is in the node and its execution state; v4_exec_step_word runs one instruction word and returns. So whoever runs the nodes can take the processor from one at any word and give it to another: that is the preemptive half, and the engine already allows it. Nothing may be built that needs a node to run a line, or a request, to its end without interruption.
• A node gives way by itself when it writes to its port. It is blocked until served (3.3), and while it is blocked another can run: that is the cooperative half.
• Each node has its own execution state. The place a blocked node goes on from is kept per node (v4_exec_state), never in one shared place.
• Each user is a VM (FABRIC-2.md D.2: "a session IS a VM"), so each is a node, with its own dictionary, stacks and ACL cards.

What is not designed: who decides which node runs next, and when. In v3 that is the switcher, reading what kernel-Hermes publishes, at the checkpoint in the inner loop; the ruling makes it Hera's, by compudynamics. It is step 6's, and section 6 lists it as open.

The loop that runs one node until its line ends (v4_boot_line, v4/system/boot.c) is the lone node's and the hosted program's, where there is one node and nothing to share the processor with. It is not how the kernel will run a fleet, and goes with the lone node at step 5.

4. What was built on the detour

Built 2026-10-05	What becomes of it
kernel_main.c calling sk_v4_run() before the fleet tables	Goes at step 4. Until then it is how the bare-metal build is kept booting while the interface is built.
v4/system/boot.c: its own capsule loader and PARITY:V4_* lines	Stays for the hosted product. On bare metal v3's birth protocol loads the capsules and prints v3's parity lines (step 4).
The node's prompt loop, and the code that strips ok from its output	Goes at step 1.
capsules/v4/forth79.4th, post79.4th, mkpost.py, the rules	Stay. POST is the gate for every word moved out of the nucleus.
(CATCH), (EMIT-HOOK), NODE-ERROR by name	Stay; POST uses them.
The per-call-target count (v4/src/heat.c, call[])	Goes at step 3, when the node does at call what v3 does.
The hosted Linux product (v4/tools/hosted.c, v4/system/boot.c)	Stays, as its own product (3c).

5. Steps

Each ends with all six builds booting and agreeing, and is committed with its logs.

1. Interpret this text (3.1). The node's line entry; no prompt loop. The hosts print the prompt and ok, as v3's REPL does. Done 2026-10-05. (LINE), (IDLE), (DONE) and (LINE-STATUS) in v4/capsule/quit.v4; v4_line_* in v4/src/image.c; v4_boot_line in v4/system/boot.c. All v4 tests pass at both widths; the six builds agree; lines typed at the three bare-metal prompts are answered. logs/20261005-180922, -181152, -181541.
2. Asking the kernel, and the stacks from the kernel's side (3.3, 3.4). Settle how a request is carried. Kernel words callable from a node. The carrier is done, 2026-10-05; the rest is not. Ruled: a node asks by a blocking write to a port. Built: the port (v4/src/node.c, v4_node_port_attach, v4_node_port_served); a blocked node goes on from the opcode after the store, in the same instruction word (v4/src/exec.c); KERNEL-WORD (v4/capsule/compile.v4), which makes a word whose body writes its request number to the port; the boot makes the kernel's words by handing the node text, and serves requests (v4/system/boot.c). A request no one serves is error 12 on the node. The one kernel word so far is BYE, on both products: hosted it leaves the program, as hosted v3; on the lone node it is v3's cold restart. v4/tests/test_port.c; six builds agree; BYE and an unserved request typed at each bare-metal prompt. logs/20261005-185506, -185734, -190101. Not done: v3's own C functions serving a node. They take a VM * and use vm_push, vm_pop and, in places, the stack's fields directly; a node has to stand behind that VM record first.
3. A word is being executed (3.5). The hook at call; the ACL's countdown and recheck; the word's count; stadium_word_dispatch. In-line words become calls. The per-call-target count goes.
4. The node as the kernel's interpreter. The third interpreter file (3c), for the kernel build. Under STARFORTH_V4 the kernel's boot brings the node up where it brings a v3 VM up: vm_interpret hands the node the line; register_word makes a kernel word and its record; the node's own words get records. sk_v4_run() goes. v3's POST runs through it and its failures are the list of what is not yet there.
5. (Folded into 4: the hosted product is no longer part of this path.)
6. Hera as v3 has her. init.4th runs on the node; v3's whole POST passes; v3's parity lines.
7. The fleet. Hestia and Artemis; message delivery; who runs next.
8. Identity and the prompt. Zuse; [zuse@Hera] ok>.

Moving words from the assembled nucleus to forth79.4th goes on beside these, a group at a time, with POST after each.

6. Open, and where each must be settled

Open	Before
How the node tells a dictionary entry from a bare address at call	Step 3
EXECUTE, which enters a word by a return	Step 3
>R R> R@ I J LEAVE, which cannot be called	Step 3
Who decides which node runs next, and when: Hera, by compudynamics; preemptive and cooperative	Step 7
The node's safe moment for message delivery and switching	Step 7
PAD 42 OVER !, a byte address given to ! (D-1)	Step 6
Which word patrons' accounts the hosted product keeps, having no Stadium	Step 3