diff --git a/docs/v4.0.0/MESH.md b/docs/v4.0.0/MESH.md index e72889fa..cc1270dd 100644 --- a/docs/v4.0.0/MESH.md +++ b/docs/v4.0.0/MESH.md @@ -1352,6 +1352,147 @@ first VM; a born node prints its parity. And the kernel is to hold POST's cases and feed them to Hera itself, with no POST words loaded into her dictionary — today they are a capsule she loads (`NUCLEUS.md` section 6). +## 9a. Step 7: a second unit, PAUSE, RESUME and KILL (designed 2026-10-16) + +Ruled by Captain Bob by question and answer on 2026-10-16, after the +ruling that births follow v3 (section 9). Built and proven in the fabric +under test (`v4/tests/test_host_unit.c`), as step 5 was. The products take +it at steps 8 and 9. + +### 9a.1 v3, as built + +Checked in the code on 2026-10-16 (`kernel/src/capsule/mama_forth_words.c`, +`capsule_birth.c`): + +| | v3 | +|---|---| +| Birth | Any VM: `S" name" BIRTH`, from the capsule `name:init.4th`. The child's parent is the VM that births it. | +| Kill | `S" name" KILL`, Hera's alone, by name through the kernel's registry of VMs. Hera cannot be killed. The VM's children are not killed with it. | +| Sleep and wake | None on bare metal. `STOP` is a VM stopping itself. The hosted build has `PAUSE` and `RESUME ( name )`, which only log. | + +### 9a.2 The rulings + +1. **A second unit: Hera births its centre, and the centre births its + own.** Hera births the second centre on her port 6. That centre runs + `UNIT` and births its four outer nodes on its own ports 2 to 5. Each + node's parent is the node that birthed it. +2. **`hera.4th` is split.** What every birthing node needs goes into a new + capsule, `centre.4th`. What is Hera's alone stays in `hera.4th`. Hera + loads both; a centre she births is given `centre.4th` only. +3. **`PAUSE` and `RESUME`, by number.** v3's names. They take a node's + number, as `KILL` does (7b.5), and are Hera's alone, as `KILL` is: + ruling 7 says she decides which nodes are awake. +4. **The kernel keeps the registry.** As v3's kernel does. Hera reaches a + node she did not birth through it. +5. **`KILL` removes one node.** As v3's does. A unit is removed by a word + composed from it in FORTH. +6. **A centre faces another centre on port 6, on both sides.** The ports + of a centre: 0 the kernel, 1 the console or devices, 2 to 5 its outer + nodes, 6 and 7 other centres (section 4.1's proposal). +7. **GONE goes down the birth graph.** Hera sends it to the nodes she + birthed. A node that believes a GONE sends it on to the nodes it + birthed, as from itself. A node still believes a GONE only from its own + centre (7b.4). + +### 9a.3 The capsules + +- **`centre.4th`** (`v4:centre.4th`, blocks 8100 up): what every birthing + node needs. + - `BIRTH-AS ( number port childport baddr u -- place )`. The newborn is + wired from its port `childport` to `port` of this node; it is told its + number, that its parent is on `childport`, and that `childport` is its + way for everything else; it is sent the system and FORTH-79, and then + the capsule named by `baddr u` if `u` is not 0 (its personality, as + v3's `name:init.4th`); it seals, so that `COLD` keeps all of it; and + its parity is reported, with this node as its parent. + - `BIRTH ( number port childport -- place )`: `BIRTH-AS` with no + capsule. It gains the child's port. + - `UNIT ( n -- )`, as now, giving `childport` 2. + - The words that join two outer nodes (`(JOIN)`, `(SAY)`), as now. + - Passing a believed GONE on to the nodes this node birthed. +- **`hera.4th`**: what is Hera's alone. + - `KILL ( n -- )`, `PAUSE ( n -- )`, `RESUME ( n -- )`. + - `UNIT-KILL ( n -- )`: asks the kernel for n's children, kills each, and + then n. + - `CENTRE ( n -- )`: births node n on her port 6 into its port 6 with + `S" v4:centre.4th" BIRTH-AS`, sets her way to n+1 to n+4 to port 6, + and sends it the text `n UNIT`, waiting for it to end. + - Her own table of the nodes she birthed goes: the kernel's registry + replaces it. + +### 9a.4 The kernel (`v4/include/v4/manage.h`, `v4/src/manage.c`) + +- **The registry.** For each live node: its number, its place, and its + parent's number. A node is entered when its birther reports its parity + (`NODE-PARITY`), which gains the parent: the node that asks. A number + that is already live is refused, as v3 refuses a name that is live. +- **Every node's port 0 serves the requests**, and the kernel checks who + may ask: + + | Request | Who may ask | + |---|---| + | `NODE-ME`, `NODE-BORN`, `CAPSULE-OPEN`, `CAPSULE-CELL`, `CAPSULE-LINE` | any node | + | `NODE-WIRE`, `NODE-UNWIRE` | any node, for ports of itself or of a node it birthed | + | `NODE-PARITY` | any node, for a node it birthed | + | `NODE-SLEEP`, `NODE-WAKE`, `NODE-KILL` | Hera alone | + + A request refused is error 12, as a request no one serves is today. +- **`NODE-SLEEP`, `NODE-WAKE` and `NODE-KILL` take a number**, which the + registry turns into a place. `NODE-KILL` refuses Hera. A number that is + not live does nothing, as v3's `KILL` of a dead VM. +- **Two queries:** `NODE-CHILD ( number i -- child | 0 )`, the i-th live + child of that node; `NODE-PLACE ( number -- place | -1 )`. + +### 9a.5 Not in this step + +- **A born node's word access records copied from its parent's**, as v3 + does at birth (`dictionary_snapshot_acl_from_parent`). v4 does not load + its access records at boot (`V3-PARITY.md` section 1, row 8), so there + is nothing to copy yet. Stated, not stood in for. +- **A mesh node's own memory size** (D-4, deferred). +- **The products**: steps 8 and 9. + +### 9a.6 Acceptance + +Each test is written to fail first. + +1. **It scales while running** (acceptance 4). While unit 1's outer nodes + are busy, Hera's `20 CENTRE` births the second centre, node 20, and it + births its four, 21 to 24. All + five report parity, with the same dictionary hash as unit 1's nodes. + Text from an outer node of unit 1 reaches an outer node of unit 2, by + way of Hera and the second centre, and its answer comes back. + `UNIT-KILL` removes the second unit; then the registry holds unit 1 + alone, no node of unit 1 has a way to a removed number, and every node + of unit 1 answers `1 2 + .`. +2. **Hera manages** (acceptance 5). An idle node executes nothing: its + anti-clock, read from C, does not move over thousands of steps. + `PAUSE` a node in a loop: its anti-clock stops, and text sent to it + waits on its wire; after `RESUME` the loop goes on and the text is done. + `KILL` a node stuck in an endless loop (`BEGIN 0 UNTIL`): every other + node goes on, and one that was waiting on it ends "Node gone". +3. **Who may ask.** Each of these is error 12 and changes nothing: `KILL`, + `PAUSE` or `RESUME` asked by a node that is not Hera; an outer node + wiring a port of a node it did not birth; a birth that reuses a live + number; `KILL` of Hera. +4. **GONE down the graph.** A node of unit 2 waiting on a node of unit 1 + ends "Node gone" when Hera kills that node. A GONE from any node but a + node's own centre is still not believed. +5. **The new message path** (a centre passing a GONE on to the nodes it + birthed): every depth of both stacks (`v4/tests/test_host_depth.c`); + and the passing on disturbed at every engine step -- the centre + removed, a child removed, the wire cut -- with every node left coming + to rest and answering (`v4/tests/test_host_mesh.c`'s way). +6. **The kernel's side.** The registry and who may ask, tested in C at + both cell widths. +7. **Nothing else changes.** `make -C v4 test test-32 sanitize + hosted-check`; `mkcapsule --lint capsules/`; the three QEMU boots and + `make -C v4 test-32`, as `.claude/CLAUDE.md` says. The products load + neither capsule, so their `dict_hash` must not move. + +**A limit kept, not widened:** `test_host_unit.c` is not run at 32 bits; +POST's expected results are 64-bit (step 5). + ## 10. Steps Each is tested, committed and pushed before the next. @@ -1884,7 +2025,7 @@ Each is tested, committed and pushed before the next. - **Not done:** a second review, of the mends. 7. **A second unit; scaling while running; sleep, wake and kill by - command.** + command.** Designed 2026-10-16: section 9a. 8. **The hosted product is the five nodes**, on three ISAs: acceptance 1 to 5. 9. **The same on bare metal:** acceptance 6.