MESH.md step 3. The ports are the transport; the message is what is
transported: to, from, type, heat and TTL, ACL tag, sequence, length, then
text four characters to a word.
- quit.v4: a node with nothing to do is blocked reading "any port"; text
for it is interpreted; (FINISH) sends what it printed and then how the
text ended, and it waits again
- core.v4: EMIT keeps what is printed, (FLUSH-OUT) and (HDR) send it to the
sender on the port the message came on. EMIT still needs one free data
cell and no more; it works on the return stack and in A and B
- message.h/.c: the same format for whatever is on a port and is not a node
- boot.c: the boot is the node's console on port 1 and its kernel on port 0
- the prompt tests are a console that speaks messages
- gone: v4_line_begin, v4_line_done, v4_line_status; writing a node's input
buffer and setting its P from outside; any use of CONSOLE-TX
Verified: make -C v4 test (test_host_quit.c 1283 checks, the full-stack
figures unchanged) and make -C v4 sanitize pass; hosted-check passes on
three ISAs with POST 550 of 550; clean qemu with STARFORTH_V4=1 passes POST
and answers lines typed at each prompt on amd64, aarch64 and riscv64
(logs/20261006-110551, -111621, -111341). -110837 is an aarch64 run ended
by the test wrapper's limit while still in UEFI firmware; it shows nothing
about v4.
Not done: KEY, EXPECT and QUERY still read the console's input registers;
a message not for this node is let go (step 4).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
MESH.md step 2. A capsule of F18 code is the words a neighbour writes to a
node's port: for each stretch of memory, "@p a! @p push", the address and
count, "@p !+ unext" and the words; then a jump to the start. A node born
empty executes that from its port, so it needs nothing in it beforehand.
- capsule.h/.c: v4_capsule_write, any node's memory as such a capsule
- mkimage writes the nucleus so, to capsules/v4/nucleus-64.f18, and the
addresses a host needs as a C file; the memory image is no longer linked
into either product
- mkcapsule is unchanged: the nucleus capsule is a built file kept under
capsules/, as BLOCK_MAP.md is, and is baked, hashed and signed with the
rest
- boot: the node is born empty (v4_image_born); the nucleus capsule is
found, its hash and signature checked, and given to the node a word at a
time as it reads its port; PARITY:V4_NUCLEUS carries its name and hash
Verified: test_fabric.c (59 checks, both widths, and under ASan and UBSan):
a memory with a programme and scattered words arrives word for word in an
empty node and runs. The nucleus capsule rebuilds byte for byte.
hosted-check passes on three ISAs; clean qemu with STARFORTH_V4=1 on amd64,
aarch64 and riscv64 takes the nucleus in, passes POST (550 of 550) and
answers lines typed at each prompt (logs/20261006-102421, -102706,
-103048).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
MESH.md step 1, in the engine, which knows nothing of StarForth or of any
kernel.
- node: V4_PORTS ports (8), a build parameter; "any port" and the port the
last such read came from; a read blocks until the neighbour writes, as a
write blocks until the neighbour reads; v4_node_born: empty, P at "any
port"
- exec: a fetch from a port -- @ @b @+ @p, or of an instruction word when P
is a port -- waits for a word; a node executes what arrives at a port
without advancing P; a blocked node goes on from the slot it stopped at
- fabric: the nodes there are and the table of how their ports are wired,
both changed while the nodes run; devices on a port; asleep and awake; a
step is every unblocked node executing one instruction word, then every
write with a reader waiting being handed over
- DECOMPOSITION.md section 6: four named ports withdrawn for V4_PORTS
numbered ones and wiring as data, as ruled
Verified: tests/test_fabric.c, 53 checks at both widths: two nodes exchange
words; an empty node is filled through its port by a device, and by another
node, and runs what it was sent; a word is passed on by a node in between;
a waiting node executes nothing; the wiring is changed while they run; a
node is put to sleep, woken and removed while looping; a node is born while
others run; the fabric is given more room. make -C v4 test and make -C v4
sanitize pass. The single-node products are unchanged: hosted-check on
three ISAs, and clean qemu with STARFORTH_V4=1 on amd64, aarch64 and
riscv64 with lines typed at each prompt (logs/20261006-074907, -075150,
-075532).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
From Captain Bob's rulings of 2026-10-05 and -06 (ENGINE.md 3d) and the
acceptance he approved. Ports with blocking reads and writes, a node born
empty that executes what arrives at its port, a fabric of nodes and wiring
that change at run time, capsules of F18 code, messages, finding the way,
storage, birth and Hera; nine steps. Marks which parts are rulings and
which are proposals.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Captain Bob, 2026-10-05: F18 engines digesting capsules, 12x12 then 12^3;
the next step is nodes talking and sharing the common SSD, ahead of v4 = v3
on bare metal. Rulings so far: ports are the transport and v3's message is
what is transported; some nodes have storage of their own.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
ENGINE.md 3b, the node's side of ruling A (a word's code is the node's, its
accounts the kernel's).
- dict.v4, system.v4: (WORD-DEFINED) ( xt -- ) is run when an entry is
made, (WORD-FORGOTTEN) ( w -- ) when FORGET or COLD removes entries; with
0 there no one is told, as on the hosted product
- test_host_quit.c: a kernel that keeps the list of words and is checked to
hold exactly the node's dictionary after definitions, a vocabulary, an
abandoned definition, FORGET, a refused FORGET and COLD; KERNEL-WORD
called from the prompt and from a definition
Fixed, found while writing that test: since the capsules moved from build
time to boot time (294e6946), what COLD returns to and FORGET protects was
still the nucleus alone, so COLD lost U*, U/MOD and BYE and FORGET U* was
allowed. The boot now seals the system when it has loaded it
(v4_image_seal), and hosted-check checks COLD, the capsule word after it,
the refused FORGET and BYE.
Verified: make -C v4 test passes at both widths (1283 checks in
test_host_quit.c); hosted-check passes on three ISAs; clean qemu with
STARFORTH_V4=1 on amd64, aarch64 and riscv64 passes POST, and COLD, U*
after it, FORGET U* (refused), an unserved kernel word and BYE typed at
each prompt are answered correctly (logs/20261005-193045, -193307, -193636).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Captain Bob, 2026-10-05. Withdraws the claim that the hosted v4 product
should become v3's hosted program with the node as its interpreter. The
bare-metal product is LithosAnanke with the node in the VM's place; the
hosted product is its own and need not follow it; the six builds no longer
have to print the same lines.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Ruling A recorded as design. Measured: each build has one interpreter file
(v3/src/vm.c hosted, kernel/src/vm/vm_core.c in the kernel) and the swap is
a third, answering the same functions with a node. So the hosted v4
product is v3's hosted program with the node as its interpreter, not a
separate program. Steps re-cut; two things in v3's C words that do not
carry over as they are (vm_ptr into packed bytes, direct stack fields).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Captain Bob, 2026-10-05. For each word on a node the kernel keeps v3's own
DictEntry record, joined by word ID; v3's physics, heartbeat, ACL words,
Stadium word layer and parity run on the records unchanged.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
ENGINE.md step 2, the carrier. Ruled 2026-10-05 (V3-PARITY.md 1i), on
DECOMPOSITION.md section 6: a write to a port blocks until the neighbour
reads.
- node: v4_node_port_attach, v4_node_port_served; a store to the port keeps
the value as the request and blocks the node
- exec: a blocked node executes nothing; served, it goes on from the opcode
after the store, in the same instruction word; a fault meanwhile abandons
the rest of the word
- compile.v4: n KERNEL-WORD name makes a word whose body writes n to the
port; its arguments and results are on the data stack
- boot: the kernel's words are made by handing the node text, and requests
are served between the node's opcodes; one no one serves is error 12
- BYE, the first kernel word: hosted it leaves the program, as hosted v3;
on the lone node it is v3's cold restart
- ENGINE.md 3a: multiuser, multitasking, preemptive and cooperative, and
what that asks of the engine
Verified: make -C v4 test passes at both widths, with tests/test_port.c;
hosted-check passes on three ISAs; clean qemu with STARFORTH_V4=1 on amd64,
aarch64 and riscv64 passes POST with the same hashes as hosted, and a
kernel word no one serves and BYE typed at each prompt are answered
(logs/20261005-185506, -185734, -190101; -185234 is an amd64 run in which
those two lines were not typed).
Not done: v3's own C functions serving a node.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Ruled 2026-10-05. Hera as process manager via compudynamics per node is
recorded as said and is not yet designed.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A v4 node no longer reads its own command line or prints a prompt. Its
host puts a line of text in the node's input buffer and starts it at
(LINE); the node interprets it and stops at (IDLE), leaving in
(LINE-STATUS) how it ended: completed, an error, or QUIT. The host says
" ok" or " ERROR" and prompts, as the kernel's REPL does for a v3 VM. A
line may be 1024 characters, a block, as v3's. Ruled 2026-10-05
(V3-PARITY.md 1b); design ENGINE.md 3.1.
- quit.v4: (REPL), the node's prompt loop, is gone; (LINE) (IDLE) (DONE)
- image.h/.c: v4_line_begin, v4_line_done, v4_line_status; the node is
idle at switch-on
- boot.c: v4_boot_line, the one loop the hosted binary, the kernel and the
capsule loader hand a line with; the code that took " ok" and the prompt
back out of the node's output is gone
- hosted.c, sk_v4.c: the prompt and the line editing are the host's
- test_host_quit.c: the tests are the node's host; two tests of the old
80-character prompt line now test a whole line, 1024 and 1025 characters
Verified: make -C v4 test passes at both widths; hosted-check passes on
three ISAs; clean qemu with STARFORTH_V4=1 on amd64, aarch64 and riscv64
passes POST (550 of 550) with the same hashes as hosted, and three lines
typed at each bare-metal prompt through the serial port are answered
correctly (logs/20261005-180922, -181152, -181541).
Still the lone node: kernel_main.c starts it before the fleet tables.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
From the rulings of 2026-10-05 and v3's code. The kernel stays untouched;
what is replaced is the part of a v3 VM that executes FORTH. Sets out the
interface the kernel reaches a VM through (interpret this text, a
character out, asking the kernel, the stacks and dictionary, a word being
executed, an error, a tick, the dictionary hash), what a node needs for
each, what becomes of the lone-node work, seven steps, and what is open.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Captain Bob, 2026-10-05: observe the opcode counts, build no opcode patron
layer yet; likely needed at the FPGA; keep it available. Amends section
2.7: word patrons do not become opcode patrons now.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Captain Bob, 2026-10-05. Records, from stadium.c and its layers, the
accounting rules of the VM, word, block and message patrons, that a v3
word already has more than one account, and withdraws two statements that
treated heat as one number per thing.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Captain Bob, 2026-10-05: a fixed TTL makes no sense; the hotter the word,
the more often it is checked. The node counts executions per word at the
call hook for ACL-TTL-COMPUTE, as v3, beside the per-opcode heat.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Captain Bob, 2026-10-05. The countdown runs on every execution; the
permission check only when it reaches zero. A compile-time check does not
meet the intent, so a word that is to be checked must be called.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Captain Bob reversed the change the same day: leave the word card exactly
as v3, if a place to hook can be found. Records that there is one -- the
call opcode, one place in the engine -- and what does not pass through it:
62 in-line words, EXECUTE, hand-written jumps, and call targets that are
not dictionary entries. Notes that v3's TTL is computed from per-word
heat.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Records the stack-of-cards model, that the block, message and VM cards
carry over, and Captain Bob's statement of 2026-10-05 that the word card
changes too, with the reason: the opcode level is the division point for
the machines to be built on the fabric. What it becomes is not settled.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Records kernel-Hermes as built and the ruling of 2026-10-05; the open
question of a node's safe moment; and the stated intent to pull Artemis up
into the kernel later, as Hermes was.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Records that compudynamics is the kernel's Stadium (words, VMs, blocks,
messages and ACLs all patrons of one engine), v3's block subsystem as
built, and the ruling of 2026-10-05: a v4 node only asks for a block by
number; ownership, ACL, physics and devices stay on the kernel's side under
the VM's identity.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Records v3's console as built (fabric, Hestia, proxies, the kernel's REPL
owning input and the prompt) and the ruling of 2026-10-05: for now a v4
node is handed a whole line and gives characters back; its own prompt loop
plays no part at that level.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The table called rows 1 and 6-12 missing in v4. They are all in this
kernel and run today. kernel_main.c calls sk_v4_run() before the fleet
tables, VM bootstrap, devices, Mama birth, heartbeat and fleet birth, and it
never returns, so the v4 node comes up beside the system and skips it.
Records how v3's boot fits together around the VM interface, and that the
open question is how the F18 engine takes the VM's place behind it.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Captain Bob, 2026-10-05: v4 = v3 functionally; heat accumulates on the 32
opcodes; the opcode replaces the word as the smallest unit. Answers D-6 and
the three conflicts of V3-PARITY.md 2.4. Records what follows (the
per-call-target array goes; pipelining and the hot-words cache are not
retired; decomposition no longer waits) and what is still open.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Measures v4 against the ruling of 2026-10-05: v4 is exactly like v3 in
functional requirements up to the first FORTH prompt. Twelve things v3 does
before its prompt, and what v4 does of each. Row 3 in full: what v3 does
for every executed word and on every heartbeat tick, what a v4 node has,
what the v4 design documents say instead, the three places they conflict
with the ruling, and what each answer would take. Lists the stand-ins
found in v4. Proposes; decides nothing; nothing in it has been built.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The boot is now nucleus, forth79.4th, POST, prompt, on both products.
- forth79.4th: U* and U/MOD, the capsule's first colon definitions. They
are in the FORTH-79 Required Word Set and neither v3 nor v4 had them.
- post79.4th: 550 cases, 126 of the 130 required words. 443 are v3's with
v3's result. The rest follow three rulings (2026-10-05): address-
dependent cases are checked for count, not value; where v3 departs from
FORTH-79 the standard's result is expected; words v3 has no case for get
cases written by hand. v4/tools/post79_rules.py holds each exception
with its reason and docs/v4.0.0/POST79.md lists them all.
- every case starts from an empty stack, DECIMAL and FORTH DEFINITIONS
- the boot requires POST's tally line with fail=0
Verified: tests=550 pass=550 fail=0 and identical PARITY lines on hosted
amd64, aarch64 and riscv64 (make -C v4 hosted-check) and on bare metal,
clean qemu with STARFORTH_V4=1, on the same three (logs/20261005-1619xx,
-1621xx, -1625xx). A U/MOD broken on purpose fails five cases and stops
the boot. make -C v4 test passes.
Not shown: all words but those two are still assembled, so POST has so far
tested the assembled words. Nothing was typed at a bare-metal prompt.
Open: PAD 42 OVER ! faults on v4 (D-1).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
capsules/v4/post79.4th: 537 of v3's POST cases for the FORTH-79 Required
Word Set, each carrying what the hosted v3 binary did with the same line
(error or not, the stack, the length and checksum of what it printed).
Written by v4/tools/mkpost.py. The harness is FORTH-79 plus the two
nucleus hooks. docs/v4.0.0/NUCLEUS.md section 6.
- NODE-ERROR has a FORTH name: how a definition in FORTH raises an error
- the boot passes POST only on seeing its tally line with fail=0
- POST is not in the boot yet (V4_POST_AT_BOOT=0); make -C v4 post runs it
Result: tests=537 pass=439 fail=98. The 98 are not yet sorted into v4
defects and differences needing a ruling; v4/README.md has a first reading.
Verified: make -C v4 test passes; hosted-check passes on three ISAs; clean
qemu with STARFORTH_V4=1 on amd64, aarch64 and riscv64 reaches ok> with the
same hashes as hosted (logs/20261005-1601xx..1604xx). Nothing was typed at
a bare-metal prompt.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
(CATCH): while it is not zero, a line that ends in an error sets it to -1
and ends " ok" instead of " ERROR". (EMIT-HOOK): the xt of a word that is
given each character EMIT would send to the console. The prompt loop sets
(EMIT-HOOK) to 0 at the end of every line. docs/v4.0.0/NUCLEUS.md 6.3,
amended: it said one nucleus word would do.
Verified: make -C v4 test passes at both widths; by hand at the hosted
prompt, an unknown word and a division by zero are caught, the output hook
receives every character, and an uncaught error still says ERROR.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
clean qemu with STARFORTH_V4=1 on amd64, aarch64 and riscv64, one at a
time. Each prints the same PARITY:V4_NUCLEUS and PARITY:V4_CAPSULE lines as
the three hosted binaries (image_hash 0x60b74e4f87adb0ac, dict_hash
0x0baed67626b4fac4), then PARITY:OK and ok>.
Each run was ended once the prompt was in the log. Nothing was typed at a
bare-metal prompt. The capsules were unsigned: no signing key on this
machine. The v3 boot (STARFORTH_V4=0) was not re-run.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
One boot, v4/system/boot.c, for both products: it starts the nucleus image,
finds each capsule in the baked capsule directory, recomputes its hash,
checks its signature, gives its blocks to the node a line at a time, and
prints PARITY:V4_NUCLEUS, PARITY:V4_CAPSULE and PARITY:OK before the prompt.
A line the node does not accept ends the boot with the capsule, block and
line named. docs/v4.0.0/NUCLEUS.md.
- hosted Linux product for amd64, aarch64 and riscv64 (make -C v4 hosted);
make -C v4 hosted-check boots all three and requires identical output
- the kernel's v4 entry (STARFORTH_V4=1) calls the same boot
- capsules/v4/forth79.4th, block 6000: no definitions yet
- mkimage builds the nucleus only; no FORTH source is compiled at build time
- capsule_blocks.c: the Block-header parse, free of any VM, for every loader
Verified: make -C v4 test passes; hosted-check passes on the three ISAs with
the same hashes; the kernel compiles with STARFORTH_V4=1 on the three.
Not verified: no bare-metal boot of v4 has been run.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Blocks 0..2047, the VM's fast RAM, are the only ones a capsule may not
claim (docs/v4.0.0/NUCLEUS.md 5.2). The ceiling of 5120 matched no device.
All 36 capsule files still lint clean.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The assembled vocabulary shrinks to a nucleus; the FORTH-79 Required Word
Set is loaded at boot from a capsule as colon definitions, POST (v3's cases,
ported, comparing results) runs on it, and the node reaches ok> -- hosted
and bare metal, on amd64, aarch64 and riscv64.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Each entry's flags cell also holds v3's four fields: denied, pinned,
mode and a 16-bit TTL.
- compile.v4: INTERPRET checks every word it is about to execute or
compile -- recheck at TTL 0, else count down; a denied word is refused
with v3's line, the stack emptied and the line ended.
- capsule/acl.v4: ACL-MODE@ ACL-MODE! ACL-TTL@ ACL-TTL! ACL-ALLOW@
ACL-ALLOW! ACL-PINNED? ACL-PIN ACL-INHERIT ACL-INIT-PRIMITIVES ACL-HEAT@
ACL-WORD-ID, and ACL-HOOK.
- capsule/ACL.fth: v3's ACL.4th as FORTH source the node compiles; loading
it switches access control on.
- v3 checks every execution, inside definitions too. v4's code is native,
so it checks a word when it is compiled as well as when interpreted; a
call compiled while the word was allowed is not checked again.
DECOMPOSITION.md 5.20 says so.
- ACL-HEAT@ is 0 until heat is readable (D-6).
- tests/test_host_quit.c: seven transcripts of the v3 binary; the policy
file loaded and exercised; COLD.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- capsule/log.v4: the level constants LOG-ERROR .. LOG-DEBUG, LOG-LEVEL!
and LOG-LEVEL@, LOG-ERROR" .. LOG-DEBUG" and LOG-ERROR-STR ..
LOG-DEBUG-STR. A message is printed if its level is at or below
LOG-LEVEL, as v3's line -- colour, level, text -- without the time of
day, which a node has not got.
- LOG-xxx" compiles like ." : the level, a call to (LOG"), the text. SEE
shows it as text. COLD puts LOG-LEVEL back to LOG-INFO.
- tests/test_host_quit.c: ten transcripts of the v3 binary, every level
at every setting.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- capsule/tools.fth: SEE as FORTH source the node compiles itself. v4
code is native, so it shows each instruction word of a definition: the
opcodes by name, literals' values, the names of the words called or
jumped to, and text compiled by ." S" and ABORT" as text. A data word
shows what it holds; an immediate word says so.
- quit.v4: the three string run-time words get names, compile-only, so
that SEE can tell text from code.
- tests/test_host_quit.c: definitions with literals, text, IF and loops;
the capsule's own words; SEE shown by SEE.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- capsule/editor.fth: the block editor as FORTH source, which the node
compiles itself. It is a vocabulary, EDITOR, used at the ordinary
prompt: n EDIT, then L N B T P E D S H R I WIPE DONE. v3's EDIT, a
shell of its own, is not carried over (ruled 2026-10-05); v3's L S and
SHOW are kept in FORTH as they were, with COPY.
- system.v4: COLD (the system as the loader left it), WARM, PAGE,
VERSION, 79-STANDARD (FORTH-79: silent), and DEFER IS DEFER@ as v3.
- input.v4: where words are split at blanks a zero byte reads as a blank,
so a block never written, or filled a line at a time, loads cleanly.
- tests/test_host_quit.c: the editor's source fed to the prompt line by
line, every command on empty and full screens, what reaches storage;
the system words; deferred words.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- The golden model's host node gets a block storage device: four
memory-mapped registers (number, address, command, status), 1024-byte
blocks as 256 cells. tests/test_node.c.
- capsule/blocks.v4: BLOCK BUFFER UPDATE SAVE-BUFFERS EMPTY-BUFFERS LIST
LOAD SCR BLK (FORTH-79) and v3's FLUSH THRU and -->, over two buffers.
- The text being interpreted is at the address in (SRC), which QUERY makes
the terminal's buffer and LOAD a block's; LOAD saves and restores it, so
blocks nest and the rest of LOAD's line runs afterwards. WORD makes
sure a loading block is still in a buffer before it reads.
- In a block, \ skips to the next 64-character line.
- A block number that does not exist, and --> at the terminal, are errors
with messages (D-18).
- tests/test_host_quit.c: ten transcripts of the v3 binary; nesting three
deep on two buffers; what reaches the device and when.
v3's LOAD drops the rest of its line, and v3 has no BLK.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- VOCABULARY DEFINITIONS CONTEXT CURRENT FORTH, and v3's ORDER. A name is
looked up in the CONTEXT vocabulary and then in FORTH; a new entry goes
into the CURRENT vocabulary; : makes the CURRENT vocabulary CONTEXT;
FORTH is immediate.
- WORDS lists the CONTEXT vocabulary. FORGET takes what was defined later
out of every vocabulary, and a vocabulary that goes gives way to FORTH.
- v3's vocabularies separate nothing: a word defined in one is found from
every other, and one redefined in a vocabulary replaces FORTH's for good.
- tests/test_host_quit.c: isolation, chaining to FORTH, two vocabularies
with the same names, FORGET across them; and DUMP is now checked to put
BASE back.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- capsule/qmath.v4: Q.FROM-INT Q.TO-INT Q.1 Q.0 Q.SCALE Q.+ Q.- Q.* Q./
Q.ABS Q.NEG Q.= Q.< Q.> Q.0= Q.MAX Q.MIN Q.EXP Q.SQRT Q.LOG Q.SIN Q.COS
Q.PRINT -- the definitions test_foundation.c executes on the mesh node,
now in the host node's vocabulary.
- numout.v4: DUMP.
- Q./ by zero, and Q.SQRT and Q.LOG outside their domain, leave the
result D-11 and D-12 give and then raise an error (D-18): "Division by
zero", "Argument out of range". v3 returns 0 silently.
- tests/test_host_quit.c: 122 results printed by Q.PRINT are transcripts
of the v3 binary, the same at both cell widths; signed values, the
errors and DUMP's layout besides.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- compile.v4: CASE OF ENDOF ENDCASE, as v3 (they nest; a word out of
place is a control structure mismatch); ['] and [LITERAL].
- quit.v4: S" and its run-time word; at the prompt the text is copied to
PAD.
- capsule/system.v4: WORDS and VLIST; FORGET (FORTH-79), which gives the
space back and will not remove a word below FENCE -- the capsule's own
words -- where v3's FORGET DUP succeeds.
- tests/test_host_quit.c: ten more transcripts of the v3 binary, and
nesting, the fence and the listing.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
capsule/words.v4: the stack, comparison, shift, double, mixed and string
words whose definitions DECOMPOSITION.md already gives and the mesh-node
tests execute, now in the host node's vocabulary:
2SWAP 2OVER 2ROT 2>R 2R> 2R@ 2@ 2! -! 0<> 0> <> <= >= U< U> ABS MAX MIN
WITHIN LSHIFT RSHIFT D- DABS D0= D0< D= D2* D2/ D< DMAX DMIN M+ M-
CMOVE> MOVE FILL ERASE BLANK -TRAILING COMPARE SEARCH SCAN SKIP
?TERMINAL TRUE FALSE INVERT NOP
- A shift count that is negative or as large as the cell is an error, as
in v3 (code 9, "Shift count out of range").
- tests/test_host_quit.c: 36 sessions from the prompt that are
transcripts of the v3 binary, and the cases where v4 keeps the standard
(MOVE in cells; M+ and M- with the double low cell first).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Ruled 2026-10-04: guard all errors. The errors that set NODE-ERROR and
let the line run on now stop it at once, with a message.
- A store of a non-zero code to NODE-ERROR is a trap, a sixth kind of
fault: nothing after it executes, the return stack is emptied, and the
data stack is left as the word left it. Not attached, NODE-ERROR is
plain memory, as the tests below the prompt use it.
- The capsule's words store a code where they stored -1, and the prompt's
(RAISED) prints its message: Negative count, Not a number, Number too
long, Not a character, Dictionary full, Name missing, Control structure
mismatch, Control structures too deep.
- ' and COMPILE and [COMPILE] of a word that is not there say
UNKNOWN WORD: 'xxx', as the interpreter does.
- tests: the trap in test_exec.c; every message from the prompt, with the
rest of the line not run and the stack kept, in test_host_quit.c.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- capsule/numout.v4: <# # #S HOLD SIGN #>, . .R U. U.R D. D.R, ?, SPACES,
DECIMAL HEX OCTAL -- the definitions DECOMPOSITION.md 5.8 gives and the
mesh-node tests execute, now words of the host node's vocabulary.
- .S, which D-16 makes possible again: as v3, the depth, then every value
from the deepest, then a new line. It needs six cells of the stack
free.
- tests/test_host_quit.c: printed from the prompt, with 14 more sessions
that are transcripts of the v3 binary, and the ends of the number range
at each cell width.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
With the stacks counted and guarded (D-16) their size is a parameter of
the node. The host node, which runs the interpreter and the compiler
under the user's programme, gets 32 values and 32 return entries; a mesh
node keeps the F18's 10 and 9. Nothing else about the mechanism or any
word's definition changes.
- stack.h: V4_DATA_RING and V4_RET_RING are build parameters; the
Makefile sets them for the host-node tests.
- tests/test_host_quit.c no longer assumes a size: it fills the stacks to
whatever they are, and takes every exit with the return stack full.
- Measured on the host node now: 28 values on a line, 29 waiting between
lines, words 31 deep from the prompt.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Ruled 2026-10-04, revising D-2: stack overflow and underflow are errors
that are shown and return to the prompt, not silent wrap-around.
- Each stack counts what it holds. Before every opcode the executor
checks that the stacks hold what it takes and have room for what it
leaves; otherwise the opcode does nothing and the node faults, as for a
bad address, to that kind's handler. Every fault empties both stacks.
- The fault handler is now a table of five jumps: address, data overflow,
data underflow, return overflow, return underflow. The host node says
"Stack overflow", "Stack underflow", "Return stack overflow",
"Return stack underflow", then ERROR and the prompt.
- Two registers, DSTACK-DEPTH and RSTACK-DEPTH: a fetch reads the depth,
a store empties the stack. QUIT, ABORT and the error exits empty the
return stack before they call anything; ABORT empties the data stack.
- capsule/forth.v4: DEPTH, PICK and ROLL, to FORTH-79 (counting from
one). PICK and ROLL set the values above the one wanted aside in
memory, and work with the stack full.
- Division by zero now takes its operands off the stack, as v3 does.
- A colon with no room for its entry abandons the line.
- tests: every opcode at every depth of both stacks; the faults, the
registers and the three words from the prompt.
The sizes are unchanged: ten values, nine return entries.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Ruled 2026-10-04: guarded, an error shown, back to the prompt.
- capsule/forth.v4: / MOD /MOD */ */MOD M/MOD, M* and S>D join the
vocabulary. Each dividing word tests its divisor first; zero prints
v3's message ("/: Division by zero"), ends an open definition, prints
ERROR and returns to the prompt from however deep.
- SM/REM here has UM/MOD written into it and keeps its signs in memory,
and */MOD has M* written in, so that division can be used inside words
that other words call: / from four words deep, */MOD from three.
- forth.v4 now loads after quit.v4, which the guard leaves through.
- tests: v3 transcripts for each message; /MOD, /, MOD and */MOD against
C on every pair of edge values.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Ruled 2026-10-04: guarded, an error shown, back to the prompt.
- The executor checks every address a programme uses (P, A, B) before
using it. Outside memory the opcode does nothing, the rest of its word
is not executed, and P becomes the node's fault handler; a node with no
handler stops. v4_node_load/store never index outside memory.
- capsule/quit.v4: (FAULT), the host node's handler, prints
"Address out of range", ends an open definition, prints ERROR and
returns to the prompt.
- tests: every memory opcode and P in test_exec.c; from the prompt, from
inside nested words and loops, in test_host_quit.c.
This closes the hole node.h described: a wild address used to index the
model's own memory gigabytes out of bounds.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Layer 5 of the compiler capsule. The host node is now started at QUIT and
left running: it prompts, reads a line from its console with QUERY,
interprets it, says " ok" or " ERROR", and goes round again.
- capsule/quit.v4: QUIT and ABORT (FORTH-79), ABORT" and (ABORT") as v3 has
them, ." and (.") (FORTH-79). Text is compiled as a counted string after
the call; the run-time word returns to the cell after it.
- INTERPRET prints v3's messages before abandoning a line:
UNKNOWN WORD: 'xxx' and xxx: compile-only.
- core.v4: CR SPACE COUNT TYPE, as DECOMPOSITION.md gives them.
- input.v4: WORD split so that (PARSE) can take text without skipping
leading delimiters (." " is an empty string); EXPECT keeps its place in
memory, so six values may wait on the stack while a line is typed.
- tests/test_host_quit.c: the node is fed characters and its output read;
16 sessions are transcripts of the v3 binary.
QUIT stops the line from inside any word and says nothing; v3's goes on
with the line and cannot be compiled. v3's compiled ABORT" crashes.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Measured, compiling a DO loop left one return entry spare under
INTERPRET and a defining word called from inside another word
overflowed the nine-entry return stack (D-2); the prompt loop will take
one more.
C@ and C! shift without a loop. The code generator shifts each opcode
into the word being built, so nothing is placed by a counted shift, and
the address masks come from a table. The dictionary search, the
in-liner, the end of a loop and the making of a data word are each one
word reached by a jump.
Every kind of line now leaves at least three return entries spare while
it compiles; a word run from the interpreter has six; and CREATE ...
DOES> works from the prompt, from a word, and from a word that calls
that.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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>
WORD, the dictionary words and the code generator run underneath
whatever the user has on the stacks, which are ten and nine deep (D-2).
Measured, they used five to seven data cells of their own, leaving a
line about three. Each now keeps what it works on in its file's
scratch cells and has at most three cells on the data stack; , calls
nothing; and the longest chains of calls are shorter.
The public words of core.v4, input.v4 and dict.v4 get dictionary
headers. NUMBER is split so the interpreter can have a flag instead of
NODE-ERROR. The host-node tests share one memory map, host_map.h.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
&NAME is the address of a word as a literal; CONST+N is a loader
constant plus an offset as one literal, so that a capsule file can
address the cells of its scratch area without adding at run time.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
'header NAME [flags]' in front of a word gives it a dictionary entry in
the layout capsule/dict.v4 uses, linked to the header before it, so the
words of a capsule are in the dictionary as soon as it is assembled.
The name is taken as it stands (it may be ( or + or ;) and the
assembler's own name for the code may differ.
Tested in the assembler's own test, and by FIND and the field words
running over assembler-made entries beside ones (HEADER) made.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The third layer of the compiler capsule, v4/capsule/codegen.v4: opcodes,
literals and branches packed into instruction words at HERE, by the
rules of sections 1.2 and 2. (OP,) (LIT,) (LABEL) (BRANCH,) (JUMP,)
(CALL,) (BRANCH>) (RESOLVE) (FLUSH) (CG-RESET).
Tested by laying the same programmes down with the text assembler on
one node and with the code generator, running, on another, and
comparing memory word for word: every opcode, literals and branches in
every slot position, and 600 random programmes. What it lays down is
then run.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The second layer of the compiler capsule, v4/capsule/dict.v4: HERE ALIGN
ALLOT , C, 2, PAD LATEST; an entry layout reached entirely from the xt,
with >LINK LFA LINK> >NAME NFA NAME> CFA PFA >BODY TRAVERSE SMUDGE
HIDDEN on it; and FIND and ' .
FIND is FORTH-79's and v3's. ' is FORTH-79's: the parameter field
address, which for a code word is what FIND gives. ALLOT counts cells
(D-1). 31 characters of a name are significant.
Executed at both cell widths against a list of 300 entries kept in C.
WORD no longer holds its length on the return stack.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
FORTH-79's reference .R right-justifies the number in its field and
prints nothing after it; v3 printed a space. . U. and D. still print
their one space.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
MOVE moves n cells, the cell at addr1 first, and nothing for n <= 0.
v3's moved bytes like memmove; CMOVE and CMOVE> do that.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
LEAVE sets the limit equal to the index: the rest of the body runs with
the index unchanged and the loop ends at the next LOOP or +LOOP. v3's
left the loop at once, which is FORTH-83's.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Ruled 2026-10-04: standard words follow the standard where v3 did not.
EXPECT takes up to n characters (v3 took n-1) and does nothing for
n <= 0. QUERY takes up to 80 (v3: 1024). WORD stores the delimiter it
met, or a zero at the end of the text, after the word, and leaves >IN
just past that one delimiter (v3 skipped them all and stored a zero);
the word may be up to 255 characters (v3: 62).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The first layer of the compiler capsule, on the host node: TIB >IN SPAN
SOURCE BL EXPECT QUERY WORD ENCLOSE CONVERT NUMBER and the comment
words. The definitions are text, v4/capsule/core.v4 (the core words
they rest on) and v4/capsule/input.v4, assembled by the text assembler,
which can now read a file.
EXPECT, QUERY, WORD and ENCLOSE behave as v3's. CONVERT and NUMBER are
FORTH-79 (ruled 2026-10-04): any BASE, a double in the standard order,
and NUMBER returns a signed double or sets NODE-ERROR.
Executed at both cell widths against C and against values recorded from
the v3 binary.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Node memory is a build parameter. Tests named test_host_*.c are now
built with V4_NODE_WORDS=16384, the host node that will hold the
compiler, the dictionary and the text being compiled; every other test
keeps the 1024-word mesh node.
The first such test checks the node at that size and the text
assembler's branch placement, which only matters there: a branch slot
that cannot reach the whole node is not used.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Test support, beside the slot packer: reads definitions in the notation
DECOMPOSITION.md uses -- words, opcodes, literals, constants, labels,
branches, FOR NEXT and FOR UNEXT, in-line macros, comments -- and lays
them down through the slot packer, so they no longer have to be retyped
opcode by opcode in C.
Tested by assembling SWAP, UM/MOD, C@ and C! both ways on two nodes and
comparing memory word for word, by running what is assembled, and on
every error it reports, each with its line number.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
?TERMINAL reads CONSOLE-STATUS; KEY polls it until a character is
pending and then takes it from CONSOLE-RX. Executed on the golden
model at both cell widths, including a transcript of the v3 binary, and
KEY shown still waiting after 5000 instruction words with no input.
v3's KEY returned -1 at the end of its input; here KEY waits.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The console's receive side, standing in for the console node until the
mesh exists, as CONSOLE-TX does for output. A data fetch (@, @+, @b)
from CONSOLE-STATUS gives -1 when a character is pending and 0 when
not; from CONSOLE-RX it gives the next character and takes it, or -1
with none pending. The characters come from a queue the test feeds.
Instruction words and literals are still fetched with v4_node_load, so
code at a register's address is never taken for the register.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
(DO) (?DO) (LOOP) (+LOOP) (LEAVE) I J UNLOOP and (0BRANCH), laid down
in line by hand as the compiler will, executed on the golden model at
both cell widths against C on every pair of 14 loop ends and 11 steps,
and against sequences recorded from the v3 binary.
(LOOP) goes round again while index < limit, signed, as v3 does; the
document's equality test differed whenever start >= limit. (+LOOP) is
now specified. J keeps the outer index in A and needs no extra return
entry.
LEAVE discards the limit and index. v3 left them on its return stack,
which made a LEAVE in an inner loop stop the outer one.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
M- M* M/MOD MOD */ */MOD, D0< D2* D2/ 2ROT, 2DROP and 2>R 2R@ 2R>,
beside UM* and SM/REM in test_foundation.c. Executed on the golden
model at both cell widths against C and results recorded from the v3
binary.
M- widens n before negating it, so the most negative n is right.
*/MOD goes through a full double product. D2/ is one +* step.
M- and M/MOD take the double in the standard order ( lo hi ), as M+
does; v3 took its low cell on top.
The foundation test's node is now full: 958 of the 960 words below its
variables.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
NIP SWAP ROT -ROT ?DUP 2DUP, >R R@ R>, @ ! +! -! 2@ 2! CELLS,
- NEGATE 1+ 1- 2+ 2- MIN MAX, OR NOT 0= 0< 0<> 0> = <> < > <= >= U<
WITHIN TRUE FALSE in a new test, and * and / beside UM* and /MOD in
test_foundation.c. Executed on the golden model at both cell widths
against C on every combination of the edge values and against recorded
transcripts of the v3 binary.
WITHIN is low <= n < high with signed comparisons, which is what v3
computes; the document's circular form differed for low > high.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
FILL ERASE MOVE, COUNT CMOVE CMOVE> BLANK -TRAILING COMPARE SEARCH SCAN
SKIP, as loops over the call-free C@ and C!, executed on the golden
model at both cell widths against C and five recorded transcripts of
the v3 binary.
A negative count reads as 0 where v3 read it so, and elsewhere writes
nothing and sets NODE-ERROR. v3's counted-string auto-detection is not
kept in any of them.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
One case per byte position, like C!: the cell is shifted down with a
2/ loop and masked. It replaces the version built on LSHIFT, RSHIFT
and SWAP calls. C@ now leaves its caller 7 return entries (was 4), and
the words above it gain with it: TYPE 6 (was 3), DUMP 4, Q.PRINT, U.
and U.R 3 (were 2). The signed number words stay at 2: their sign
waits on the return stack.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
BASE and HLD leave their variable's word address; DECIMAL, HEX and
OCTAL store 10, 16 and 8. Executed on the golden model at both cell
widths, including a recorded transcript of the v3 binary.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Built on the number-output words and executed on the golden model at
both cell widths against a C reference and recorded transcripts of the
v3 binary (DUMP byte for byte at 64-bit cells).
Q.PRINT is signed (D-8) and always decimal; DUMP is always hex; both
put BASE back. Each keeps its working state in a variable, (QP) and
(DP), so each leaves its caller 4 data cells and 2 return entries.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The number-printing words, on pictured output and TYPE, executed on the
golden model at both cell widths against a C reference (ten bases,
eleven field widths) and six recorded transcripts of the v3 binary.
Each plain word is its .R word with a width of 0; all six share one
tail. The field width waits in a variable, (W), so the picture runs no
deeper than it does on its own: each word leaves its caller 4 data
cells and 2 return entries.
As v3, the .R words print a trailing space. Unlike v3, D. takes
( lo hi ), prints the whole double, and printing honours BASE.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
: EMIT ( c -- ) CONSOLE-TX b! !b ;
: CR ( -- ) 10 jump EMIT
: SPACE ( -- ) 32 jump EMIT
: TYPE ( baddr u -- )
-if OK drop drop NODE-ERROR b! -1 !b ;
OK: if DONE over C@ EMIT push 1 + pop -1 + jump OK
DONE: drop drop ;
They follow v3 (v3/src/word_source/io_words.c): EMIT prints the low byte
of the cell, CR character 10, SPACE a blank; TYPE prints u bytes,
nothing for u = 0, and for u < 0 nothing, with NODE-ERROR set where v3
raised its error flag. TYPE does not check the address range, which v3
does; out-of-range addressing is still an open question in node.h.
New test v4/tests/test_terminal.c, on a node of its own with the console
attached, 939 checks per width. Two transcripts of the real v3 binary
are recorded as expected output:
65 EMIT 66 EMIT SPACE 67 EMIT CR 68 EMIT 321 EMIT -> "AB C\nDA"
S" Hello, v3" TYPE 91 EMIT <text> 0 TYPE 93 EMIT -> "Hello, v3[]"
Also: EMIT of every byte and of wider values, CR, SPACE, TYPE from every
start within a cell at lengths 0..40, bytes with the top bit set and
zero bytes, negative counts, and that TYPE writes no memory. At 32- and
64-bit cells, optimised and ASan+UBSan (`make test`, `make sanitize`).
Five mutations each fail.
Headroom (data cells under args / return entries): EMIT 8/8, TYPE 4/3.
TYPE's depth is C@'s, which is still as written (C@ -> RSHIFT -> SWAP).
Test results on the amd64 host only. This is a development check, not
acceptance (JUSTIFICATION.md section 16).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
EMIT is a device service: a character sent to the console node. The
mesh and its ports are development step 2 and the memory map is open
(D-4), so the single-node model now stands in for the console with one
memory-mapped register, so that printing words can be run and their
output compared with v3's.
v4_node_console_attach(n, addr): after it, a store to word address
`addr` appends the low 8 bits of the value to a buffer on the node
(V4_CONSOLE_CAP characters, 4096 by default) and does not write memory;
a load from `addr` reads the memory word as before. Characters past the
capacity are counted in console_dropped and discarded. The hook is in
v4_node_store, which all four store opcodes use.
It is off by default: v4_node_reset detaches the console (address -1)
and empties the capture, so the ISA's behaviour and every existing test
are unchanged unless a console is attached. The address is the
caller's choice.
New test v4/tests/test_console.c, 22 checks per width: direct stores,
!b, ! and !+ through the executor printing "Hi!", memory at and around
the register untouched, the low byte only, overflow, detach, a console
at word 0, and reset. At 32- and 64-bit cells, optimised and ASan+UBSan
(`make test`, `make sanitize`); all other v4 tests still pass. Four
mutations of the hook each fail.
DECOMPOSITION.md section 7 gains the CONSOLE-TX row. No printing word is
defined here; EMIT and the words on it are still to do.
Test results on the amd64 host only. This is a development check, not
acceptance (JUSTIFICATION.md section 16).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
`#` held the high quotient on the return stack across its second
UM/MOD, which was the deepest point of pictured output once C! was made
call-free. It now rotates it under the division on the data stack
(-ROT in line: SWAP push SWAP pop).
Headroom, return entries: <# #S #> 2 -> 3, the signed picture 1 -> 2.
Data room is unchanged.
Same 4716 checks per width at 32- and 64-bit cells, optimised and
ASan+UBSan (`make test`, `make sanitize`); the headroom checks now
require the new figures.
Test results on the amd64 host only. This is a development check, not
acceptance (JUSTIFICATION.md section 16).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
C! as written in 5.3 called RSHIFT and LSHIFT (which call SWAP) and OR.
It is now one straight-line case per byte position: the byte is shifted
up with a `2* unext` loop, that byte of the cell cleared with a constant
mask, and the two added. The word address is `2/ 2/` of the byte
address. The upper half of a 64-bit cell is still preserved.
Headroom (data cells under args / return entries): 5/4 -> 7/7.
Same checks as before (every byte of two adjacent words, eight values,
neighbours and the upper half untouched) at 32- and 64-bit cells,
optimised and ASan+UBSan (`make test`, `make sanitize`). Four mutations
fail, one of them only at 64-bit cells, where it differs.
test_pictured.c carries the same C!. The pictured words did not gain
return-stack room from this: <# #S #> still leaves 2 entries and the
signed picture 1. With C! shallow, the deepest point is now inside `#`,
which holds the high quotient on the return stack across its second
UM/MOD. Recorded in 5.8; `#` is unchanged.
Test results on the amd64 host only. This is a development check, not
acceptance (JUSTIFICATION.md section 16).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
DECOMPOSITION.md 5.8 only named these as "standard pictured-output
definitions over UM/MOD and a hold buffer". They are now written out
(5.8) and run on the golden model.
D-13 (ruled 2026-10-03): the hold buffer takes 63 characters, as v3's;
HOLD of a value outside 0-255, or into a full buffer, stores nothing and
sets NODE-ERROR, which is what v3 did with its error flag.
Behaviour follows v3 otherwise: digits 0-9 then A-Z, BASE outside 2..36
reads as 10, SIGN ( n -- ). Stack effects are the standard ones, as 5.8
already ruled (v3 took its double low cell on top). The buffer is 64
bytes, filled backwards from its end through HLD; `#` divides by the
base in two UM/MOD steps. HOLD, SIGN and # end in a jump to the next
word instead of a call, which saves two return-stack entries: with
calls, the signed picture `.` needs overflowed the 9-deep return stack.
New test file v4/tests/test_pictured.c, on a node of its own:
test_foundation.c's hand-assembled words already fill 901 of a node's
1024 words. It re-assembles SWAP, OR, UM/MOD, LSHIFT, RSHIFT and C! as
they are in test_foundation.c.
Checked against a C reference (short division on 16-bit limbs) at 32-
and 64-bit cells, optimised and ASan+UBSan (`make test`, `make
sanitize`), 4716 checks per width: <# #S #>, <# # # 46 HOLD #S #> and
the signed picture, in bases 10, 16, 2, 8, 36, 3 and the invalid 0, 1,
37, -5, on every pair of 15 edge cells; HOLD of 12 values; and a base-2
number that overflows the buffer (63 characters kept, NODE-ERROR set,
nothing outside the buffer written). Six mutations all fail.
Headroom: <# #S #> leaves 3 data cells and 2 return entries; the signed
picture leaves 1 return entry. The depth is C!'s as written (C! ->
LSHIFT -> SWAP), which is unchanged.
Test results on the amd64 host only. This is a development check, not
acceptance (JUSTIFICATION.md section 16).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Both run exactly as written in DECOMPOSITION.md 5.3 and need no change:
four bytes to a cell, little-endian, byte address = 4 * word address +
byte index, at either cell width.
Checked at 32- and 64-bit cells, optimised and ASan+UBSan (`make test`,
`make sanitize`): every byte of two adjacent words, eight values
including ones wider than a byte, with the other bytes of the word, the
upper half of a 64-bit cell and the neighbouring words left untouched.
Breaking C!'s mask or C@'s mask fails.
Headroom (data under args / return): C@ 6/4, C! 5/4.
Test results on the amd64 host only. This is a development check, not
acceptance (JUSTIFICATION.md section 16).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Both run exactly as written in DECOMPOSITION.md 5.5 and need no change.
Checked against C on the edge vectors for every count 0 .. N (a count
of N gives 0), at 32- and 64-bit cells, optimised and ASan+UBSan
(`make test`, `make sanitize`). Removing RSHIFT's sign-bit mask fails.
Headroom (data under args / return): 7/5 each.
They are dependencies of C@ and C!, which the pictured-output hold
buffer needs.
Test results on the amd64 host only. This is a development check, not
acceptance (JUSTIFICATION.md section 16).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
DECOMPOSITION.md 5.26 gives them fate IN: the compiler places two
literals, low cell first. Q.1 and Q.SCALE are `65536 0`, Q.0 is `0 0`;
v3's are 65536, 0 and 65536.
Each expansion is assembled and run, and checked against v3's value;
then in use: Q.1 Q.TO-INT is 1, 1 Q.FROM-INT is Q.1, and q Q.1 Q.* and
q Q.0 Q.+ return q for 2000 pseudo-random q plus 0, Q max and Q min.
At 32- and 64-bit cells, optimised and ASan+UBSan (`make test`,
`make sanitize`). A wrong value in any of the three fails.
Test results on the amd64 host only. This is a development check, not
acceptance (JUSTIFICATION.md section 16).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Q.COS is v3's q48_cos_approx: on |(Q.REDUCE) x|, the even Taylor series
to n = 10. It sets term and sum to 1.0, n to 2 and the sign cell to 0,
then jumps into Q.SIN's loop, so it adds no call level.
Checked bit for bit against v3's q48_cos_approx (ported into the test)
on the same 33 edge angles and 3000 pseudo-random angles as Q.SIN, at
32- and 64-bit cells, optimised and ASan+UBSan (`make test`,
`make sanitize`). Mutating the start index, the start sum, the
alternation or the sign cell each fails 2500+ cosine checks and no sine
checks.
Headroom (data under arg / return): Q.COS 3/2.
Test results on the amd64 host only. This is a development check, not
acceptance (JUSTIFICATION.md section 16).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
(Q.REDUCE) is v3's q48_reduce_angle: the angle as one cell in [-pi, pi].
x / 2pi does not fit a cell, but only the remainder is needed, and
|x| mod 2pi is two UM/MOD steps (high cell first, its remainder leading
the low cell); then the sign of x and one step of 2pi back into range.
Q.SIN is v3's q48_sin_approx on the reduced angle: the odd Taylor series
to n = 11, each term the last times x^2 over n(n-1), stopping below 10
ulp. After the reduction every value fits one cell, so the 6-cell
variable (QT) holds single cells. The loop is laid out for Q.COS to jump
into, so the pair share it without an extra call level.
Checked bit for bit against v3 (both functions ported into the test) on
33 edge angles -- around +-pi/2, +-pi, +-2pi, the 32-bit seam and both
64-bit extremes -- and 3000 pseudo-random angles of every size and sign,
at 32- and 64-bit cells, optimised and ASan+UBSan (`make test`,
`make sanitize`). Mutating either range boundary, the series length or
the sign alternation fails. Moving the 10-ulp stop to 11 fails nothing,
and a scan of all 205888 reduced angles in C shows why: no input's
result depends on it, for sine or cosine.
Headroom (data under arg / return): (Q.REDUCE) 5/5, Q.SIN 3/2.
Test results on the amd64 host only. This is a development check, not
acceptance (JUSTIFICATION.md section 16).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Q.LOG is v3's q48_log_approx: x = 2^k * m with 1.0 <= m < 2.0, ln m by
up to 6 Newton rounds on e^y = m, result y + k * ln 2. As ruled, e^y is
Q.EXP's Taylor loop written in line rather than a call to Q.EXP, so
Q.LOG calls only Q.*, Q./ and UM*. After the reduction m, y, the Taylor
term and its sum each fit one cell, so the 7-cell variable (QL) holds
single cells. x <= 0 returns 0 and sets NODE-ERROR (D-12).
Checked bit for bit against v3's q48_log_approx (ported into the test)
on 22 positive edge values, 2000 pseudo-random x of every magnitude and
a sweep of every 17th reduced m, at 32- and 64-bit cells, optimised and
ASan+UBSan (`make test`, `make sanitize`). Mutating the round count, the
100-ulp stop, ln 2 or the Taylor length all fail.
v3's clamp y = max(y - corr, 0) is kept but cannot fire: a scan of all
65536 values of m in C never reaches it, and never needs more than 4
rounds. So no test covers it.
The test harness's per-call step limit is raised from 100000 to 4000000
instruction words: a 64-bit Q./ takes about 6500, and a mutant forcing
extra Newton rounds ran past the old limit and looked like a width
difference.
Headroom (data under arg / return): Q.LOG 3/2.
Test results on the amd64 host only. This is a development check, not
acceptance (JUSTIFICATION.md section 16).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Both ruled by Captain Bob, 2026-10-03.
Products (README.md, JUSTIFICATION.md section 15): Hosted StarForth F18
(native Linux, amd64/arm64/riscv64, on hardware); FPGA StarForth F18 (a
32-bit build loaded into the FPGA, the gateway and foundation); and
StarshipOS (bare metal, LithosAnanke on the v4 F18 engine). FORTH-79
recomposed on the F18 engine is stored as a capsule, as are the
StarshipOS portions; the tree will be reorganised around this.
Acceptance (JUSTIFICATION.md section 16, v4/README.md): v4 is equivalent
to v3 at any point in time -- same vocabularies, same behaviour, on the
F18-derived engine -- and every ISA, hosted and bare metal, must still
reach its ok prompt. `make -C v4 test` is a development check, not
acceptance. v4 had no acceptance criteria before this.
Documentation only; no code changed.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Baseline run for StarForth-v4.0.0 as it stands, before any further work.
`make -f kernel/Makefile ARCH=<arch> clean qemu` for amd64, aarch64 and
riscv64, one at a time, disk/artemis.img and
disk/thumbdrives/zuse-thumb-ident.img restored to their committed state
before each.
All three reach `[zuse@Hera] ok>`, with zero UNKNOWN WORD, PARITY:OK,
1050 POST tests run and ALL IMPLEMENTED TESTS PASSED,
stadium_conserved(Artemis)=true.
dict_hash is identical across the three:
Hera (PARITY:M7.1a, word_count=530) 0x08873e0f44b7cb2a
dict_hash 0xe11082140cf86b05
dict_hash 0xb1256603f848e2b9
dict_hash 0xc791409ac1715690
QEMU was asked to quit over QMP once the prompt had appeared and the
serial log had been quiet for 10 seconds.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
D-12 (ruled 2026-10-02): Q.SQRT of a negative value and Q.LOG of zero or
a negative value return 0 and set NODE-ERROR, as Q./ does on division by
zero.
Q.SQRT is v3's q48_sqrt_approx: Newton from x0 = q/2 + 0.25, up to 8
rounds of x' = (x + q/x) / 2, returning x once |x' - x| < 10 ulp;
sqrt(0) = 0 and sqrt(1.0) = 1.0. q, x and the rounds left live in a
5-cell variable (QR). Checked bit for bit against v3's q48_sqrt_approx
(ported into the test) on 19 edge values and 3000 pseudo-random q below
2^48, at both cell widths, optimised and ASan+UBSan. Above 2^48 v3's
q48_div saturates and v4 divides correctly, so there is no parity there.
Bug found and fixed on the way: the "< 10 ulp" test subtracted 10 from
the step's low cell as a signed number, so at 32-bit cells a step of
2^31 or more read as small and the iteration stopped early. It now
tests the low cell's top bit first, as Q.EXP does. The first test run
missed it because `make build/32-test_foundation.c` rebuilds nothing
(the Makefile's rules use absolute paths); the mutation runs, compiled
from source, exposed it. Only `make test` is used from here.
Headroom (data under arg / return): Q.SQRT 3/2.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Q.EXP is v3's q48_exp_approx: the Taylor series to 10 terms on |q|,
stopping below 50 ulp, 1.0 Q./ e^|q| for q < 0, e^0 = 1.0, and for
|q| >= 16.0 either 0 or Q max (v3 returned all ones, which is -ulp read
signed under D-8). x, term, sum, sign and term index live in a new
8-cell variable (QE). Checked bit for bit against v3's q48_exp_approx
(ported into the test) on 23 edge values and 3000 pseudo-random q in
(-16.0, 16.0), at both cell widths, optimised and ASan+UBSan; dropping a
term, moving the 50-ulp stop or skipping the reciprocal all fail.
Q.EXP calls Q./, which calls (UQ/), which calls D2*C, and at first it
left its caller no return entries. Lightened along the chain:
- D2*C takes cin in A and builds 2hi+m with `over + +`: no ROT, no SWAP.
- (UQ/) parks the quotient bit instead of using ROT, stores q without
SWAP, and does its full trial subtraction (with borrow) in line
instead of calling DNEGATE D+.
- Q.EXP keeps its term index in (QE) instead of a FOR count.
Headroom (data under args / return): (UQ/) 4/3 -> 4/4, Q./ 3/2 -> 3/3,
Q.EXP 3/2.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
D-11 (ruled 2026-10-02): Q./ rounds toward zero, saturates to Q max /
Q min on overflow, and on division by zero returns Q max / Q min by the
dividend's sign (0 for 0/0) and sets the new NODE-ERROR register (7),
which VM-ERROR? reads.
- (UQ/): unsigned floor(a * 2^16 / b) for b != 0 and no overflow.
Restoring division, 2N+16 steps, on one shifting register (quotient
above remainder). Quotient register and divisor live in a 5-cell
variable (Q/), like BASE and the hold buffer, so the stacks carry only
the remainder, the quotient bit and the loop count. A first version
kept the divisor on the return stack and overflowed it when called
from Q./ (it never returned).
- D2*C: double shift left with carry in and out.
- Q./: zero-divisor handling, signs (kept in (Q/)), an overflow test
that needs no division (|a| * 2^16 >= |b| * 2^(2N-1), possible only
for |b| < 2^17), then (UQ/) and the sign.
Checked at 32- and 64-bit cells, optimised and ASan+UBSan, against an
independent limb-by-limb long division (including NODE-ERROR): every
pair of 18 edge Q values, 13 width-native edge values (true Q max/min at
either width), the overflow boundary, divisors in [2^(2N-2), 2^(2N-1)),
and pseudo-random cases; and against v3's q48_div for non-negative
a < 2^48. Q.* now also runs on the width-native edge values.
Mutations of the compare paths, the take path, the error flag and the
overflow mask are all caught (the mask matters only for Q min / -1.0).
Headroom (data under args / return): Q./ 3/2.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Q.* now forms its products in the order a1*b1 (low cell), a0*b1, a1*b0,
a0*b0, dropping each input after its last use, with b0 waiting on the
return stack. Each sign correction, (b1<0 ? a0 : 0) and (a1<0 ? b0 : 0),
is folded into cell 2 as soon as its operands are adjacent, using -if
rather than 0< calls. At most four live values sit under any UM* call.
Headroom (data cells under args / return entries): 2/2 -> 3/3.
Same checks as before at 32- and 64-bit cells, optimised and ASan+UBSan;
dropping either sign correction fails about 9900 checks.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
UM* parked its three corrections (c_hi, c_lo, t0) on the return stack
before the +* loop, leaving its caller 4 return entries. Now u1 and u2
wait on the data stack under the loop -- +* touches only T, S and A --
and the corrections are made after it, with -if in place of 0< calls.
The return stack holds the loop count, then at most two temporaries.
The loop count is pushed before s is made, so the data stack never holds
more than four cells: data headroom is unchanged at 6.
Headroom (data cells under args / return entries): 6/4 -> 6/6.
Q.*, which calls UM* four times, goes from 2/1 to 2/2.
Same checks as before at 32- and 64-bit cells, optimised and
ASan+UBSan; breaking any of the four corrections fails 4900+ checks.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Q.* is floor(a*b / 2^16), signed (D-8), cut to two cells. Cells 0..2 of
the product come from the unsigned cell products a0*b0, a0*b1, a1*b0 and
the low cell of a1*b1; reading a1 and b1 as signed takes
(a1<0 ? b0 : 0) + (b1<0 ? a0 : 0) off cell 2. The result is cells 0..2
shifted right 16 with Q.TO-INT twice. Clobbers A.
Checked at 32- and 64-bit cells, optimised and ASan+UBSan, on every pair
of 17 edge Q values plus 20000 pseudo-random pairs:
- against an independent reference (16-bit limbs, magnitudes multiplied
schoolbook, negated, shifted), and
- against v3's q48_mul for non-negative operands.
The first draft applied only a1's sign correction; the reference caught
the missing b1 term (9860 failures at 32-bit cells).
v3 bug found, not fixed: q48_mul's portable branch (used where there is
no __int128) returns (result_hi << 16) | (result_lo >> 16); the high
part must move up 48, so it is wrong whenever the product passes bit
64, e.g. 0.5 * Q max gives 0000ffffffffffff instead of 3fffffffffffffff.
The parity reference here is that branch with the shift corrected,
which matches v3's __int128 branch.
Stack use is tight: Q.* leaves its caller 2 data cells and 1 return
entry, because UM* parks three values on the return stack. Recorded in
5.26; to be improved next.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Executed on the golden model as written, and correct: <, =, D<, 2OVER,
and Q.=, Q.<, Q.0= (the D=, D<, D0= words).
Fixed, because they could not work under D-2 or were wrong:
- DMAX, DMIN: 2OVER 2OVER D< needs 8 data cells plus D<'s 2, the whole
10-deep data stack, so both failed on every case once the caller held
anything. Rewritten on a new call-free helper
(D<) ( d1 d2 -- d1 d2 flag )
which compares copies of the high cells, then the low cells unsigned
on a tie, with in-line sign tests; DMAX and DMIN then drop the loser.
- 2SWAP: ROT and SWAP written in line. Return headroom 2 -> 4, which
also lifts 2OVER 1 -> 3 and Q.> 1 -> 2.
- Q.>: section 5.26 gave SWAP D<, which swaps single cells; it was wrong
in 11702 of 20169 cases. Now 2SWAP D<.
Checked at 32- and 64-bit cells, optimised and ASan+UBSan: every
edge-vector quadruple (50625) for D<, (D<), 2SWAP, 2OVER, DMAX and DMIN;
Q comparisons on every pair of 13 edge Q values plus 20000 pseudo-random
pairs weighted to ties and one-bit differences, signed (D-8) and against
v3's unsigned comparisons where both values have the same sign.
Mutating any (D<) branch or subtraction fails 700+ checks.
The new fatal-UBSan setting caught a test-side array overflow in the
headroom probe (results buffer sized 4, six needed); fixed.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
