Ruled 2026-10-08. The engine, the nucleus and their tests are as they
were at dfabfa46, before step 6d; the code of the wait and its tests are
in history at 075385ab..2cf37aab. The limit of MESH.md 7b.7 stands: a
node that is stuck can hold up its neighbours until Hera kills it.
MESH.md 7c is kept as the record of the design as approved, and 7c.6 says
what was built, what the two reviews found, the cause the findings share
-- a node's message machinery runs on the stacks its text is using, and a
fault abandons whatever was in progress -- and what a second attempt
must settle before anything is built.
Kept from it, in hosted-check: a line that leaves 29 values on the stack,
and WORDS with 26 values on it. Both hung the products at some commit of
the wait.
make -C v4 test and sanitize at both widths, hosted-check, lint; three
bare-metal boots typing both. POST 538 of 538, word_count=317,
dict_hash=0xc0769523a47b7dc3 on all six: the hash of step 6c's code.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Ruled 2026-10-08: A, B, C, D and the guard for a half message. Each with
a scene in test_host_mesh.c that failed first.
A. The words of a message after its first are written from the passes
over the messages waiting by (!W): an offer and a wait for that offer
only (a new engine address). A reader removed in mid-message makes no
error; the rest is let go and counted. Before, the error left the
messages waiting in pieces and the node going round for ever.
B. A store to the wait withdraws every offer; (GATE1) and (PAY-SET) do it
first. Before, text begun after a node went round without sleeping
could go to the port of an older offer: text for one node was done by
another.
C. What a finished text printed is put with the messages waiting, as how
it ended is. With no room either is let go and counted; neither is
begun as a message from (FINISH) any more, where a stuck node on the
way held the whole node.
D. Only what a sender is owed from an earlier text -- its output, how it
ended -- holds that sender's next text back; a GONE does not; and what
cannot be noted holds nothing. A node's own messages keep the order
they were made in.
- A message half taken in when its writer is removed is let go
((MQ-MEND)), not kept as if whole.
- Smaller: a refused line no longer ends a waiting text 'Interrupted';
a node's own queued messages may be passed on by 16 nodes, not 15; no
value is left on the stack when a port goes in mid-refusal.
make -C v4 test and sanitize at both widths, hosted-check.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The engine's console release (v4_fabric_interrupt_error), a device's
pending, and the count of words since a look are removed: nothing uses
them. MESH.md 4.1, 7b and 7c say what was built, where it differs from
what was approved and why, and what is still a limit; step 6d is marked
built, with the defects found on the way.
make -C v4 test and sanitize at both widths, hosted-check, lint; three
bare-metal boots. POST 538 of 538, word_count=317,
dict_hash=0x6a39c0bb9d183418 on all six.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Found in the five-node test, each with a check that failed first:
- A node with answers it could not give to two stuck senders began no
text at all. It now holds back only text from a sender whose own
answer is still with it.
- KILL waited to tell a stuck node, and a typed line that broke it left
the nodes after it untold. GONE is put with the messages waiting, as
how text ended is, and goes when it can.
- So that 'tell, then wait' still works, AWAIT does what (IDLE) does but
for beginning text: it looks through the messages waiting, offers what
is to be passed on and what is owed, and sleeps in the wait. A waiting
node no longer keeps back what passes through it.
- A node in the wait with an offer on a port that turns out to have
nothing on it is woken and told so (which port: 2 * V4_PORTS + k); no
error is raised on it. (GATE) makes it error 18; (IDLE) and AWAIT let
the message go. Before, removing a node raised 'No one on that port'
on the unrelated text of a neighbour that had something queued for it.
make -C v4 test and sanitize at both widths, hosted-check.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A node stores a word to offer on any of its ports and fetches the wait: it
is blocked until a word comes for it or one of its offers is taken, and
the fabric does the handing over in one step. The port block moves in
the nucleus's map to make room for the new addresses. Nothing uses it
yet. MESH.md 7c; plan step 6d task 1.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The review of step 6c found it did not keep its rule. Ruled: fix them
all; 16 hops.
- Paying a NACK no longer waits on a lower-numbered neighbour; a node
that owes one does not sleep, and goes on taking in what it is sent.
- AWAIT looks first through the messages already waiting.
- A node waiting to write to a removed neighbour gets error 18: the
word that says who is reading also says which ports have anything on
them.
- A console line lets Hera go when she is blocked on the first word of
a message (v4_fabric_interrupt_error, a device's `pending`).
- A refused answer is told to the node that waits, not the one that
answered; one owed to the node itself goes to its own queue.
- A message is passed on by at most 16 nodes, then refused.
- A GONE is believed only when it says it is from the node's centre.
- Tests: the check that tested nothing is replaced; no room for a
waiting sender; the limit that remains is tested as a limit.
- MESH.md 7b's rule reworded to what holds, 7b.7 says where it falls
short; README likewise.
make -C v4 test, sanitize, hosted-check; three bare-metal boots. POST
538 of 538, word_count=317, dict_hash=0xc0769523a47b7dc3 on all six.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A node writing to a node that was stuck, and was then killed, stayed
blocked for ever: killing a stuck node could cost its neighbours. And on
the hosted and bare-metal products a write to an empty port, 5 7 PORT!,
ended the program with "the node stopped".
Now a node that can take an error, blocked writing to or reading from one
port that nothing is wired to -- nothing ever was, or what was there has
been killed or the wire cut -- has error 18, No one on that port, raised
on it and goes on. A bare node waits as on the fabric; so does a node
whose neighbour is asleep, and one reading "any port".
test_host_unit.c: Hera kills node 14 while node 12 is blocked writing to
it. It failed first: 12 stayed blocked. test_fabric.c: a bare node still
waits. hosted-check types 5 7 PORT! and goes on; it failed first too.
make -C v4 test, sanitize and hosted-check pass; amd64, aarch64 and
riscv64 boot, POST 538 of 538, dict_hash 0x5f0a949a6fc8ef2b on all six:
logs/20261007-121743, -122008, -122337.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A block is a kernel request, as ENGINE.md 3.3 has it: the node puts the
block's number and the address of 256 cells on its stack and writes the
request to port 0, and the kernel leaves the status there. The requests
are -1, read, and -2, write, the same for every node. v4/system/blocks.c
serves them from the kernel's block subsystem, which is v3's. The four
storage registers are gone from the engine.
The device that spoke block messages (4a505a15) is withdrawn with its
test and its message types: Captain Bob ruled on 2026-10-07 that it, a
node's own drive, and nodes with no storage had left the OS as designed
(docs/v4.0.0/MESH.md 8.5).
Hera no longer sends POST to the nodes she births: POST is the kernel's,
once. Every node has its kernel on port 0; it serves a node's blocks and,
for Hera alone, her requests for nodes and capsules.
Bare metal: the node boots and is POSTed against POST's own block RAM,
and the kernel's chain -- fast RAM, the ramdrive, the virtio disk -- is
set up after POST and before the prompt, as on the v3 path. The disk is
read and not written: nothing in v4 yet gives the owner's word that it
may be formatted. A hosted program has the chain's fast RAM, as hosted
v3 has with no disk. Error 17 is Storage refused.
make -C v4 test and sanitize pass at both widths; hosted-check passes on
three ISAs; amd64, aarch64 and riscv64 boot, POST 538 of 538, with the
typed session: logs/20261007-081603, -081839, -082226. The hashes are
the same on all six.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
MESH.md step 4, the fault found there, as ruled (section 7a): a node
writes only to a neighbour that is reading, keeps what it takes in
meanwhile, and loses and counts what it has no room for.
Engine: two more addresses after a node's ports -- which ports have a
neighbour waiting to write to it, which to read from it. Nucleus: (GATE)
before every message; the messages waiting, a ring of 400 cells, dealt
with when the node is idle. Of two neighbours the lower number may wait
to write (ruled after it was built); NEIGHBOUR tells a node who is on
each port.
test_host_mesh.c, 44 checks: the case that stopped the nodes passes; six
messages from each node to each at once all arrive; 800 at once, the
nodes come to rest and every message arrived or was counted (287 arrived,
714 of all kinds let go). test_fabric.c: the two looks. Both widths,
ASan+UBSan.
POST: twelve cases handed HERE, a cell address on v4, to words that take
a byte address, and so wrote into or read from the nucleus's code at cell
HERE/4. Ruled: left out, marked OPEN, until HERE and the byte words are
made to agree as its own step. POST is 538 cases.
hosted-check on three ISAs, 538/538. Bare metal: logs/20261006-134817
(amd64), -135044 (aarch64), -135440 (riscv64).
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>
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>
- 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>
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>
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.
- 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>
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>
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>
First code for StarForth v4 (JUSTIFICATION.md section 10, step 1): one node
of the 32-instruction core as a C99 model, with cell width as a build
parameter.
- Node: P, A, B, F18 circular stacks (10 and 9 deep, D-2), word-addressed
memory (D-1), 5% guard bands on every bounded list.
- Instruction word: six 5-bit slots in 32 bits at every cell width.
- Executor: all 32 opcodes of DECOMPOSITION.md 1.3. Cell arithmetic wraps
explicitly; no signed overflow or implementation-defined shift.
- Heat: per-opcode and per-call-target counters and the anti-clock, driven
by instruction retirement (1.4, D-6 interim).
- Slot packer and runner for tests, and a reference unsigned multiply in
plain C99 with no 128-bit type.
Tests run at 32- and 64-bit cells, and under ASan and UBSan. They cover
every opcode and execute the first section 4 definitions (NIP SWAP OR
NEGATE ROT 0< 0= 2DUP - U<) against the C operation each stands for.
UM* as written in section 4 is exact only while u1 <= 2^(n-2). Two known
failing cases are pinned in test_foundation.c until it is rewritten.
DECOMPOSITION.md: record D-9, the instruction word is 32 bits at every
cell width (ruled 2026-10-02).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
