From 38c4d5ac69a82a0e6058bebd778f22a8664bf3c4 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 18 Nov 2026 17:20:37 +0000 Subject: [PATCH] plan: capsules and their blocks -- the talk so far (rulings 1, 1b, 1c; the fixed 2048 is the bug) Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm --- .../v4.0.0/plans/2026-11-18-capsule-blocks.md | 51 +++++++++++++++++++ 1 file changed, 51 insertions(+) create mode 100644 docs/v4.0.0/plans/2026-11-18-capsule-blocks.md diff --git a/docs/v4.0.0/plans/2026-11-18-capsule-blocks.md b/docs/v4.0.0/plans/2026-11-18-capsule-blocks.md new file mode 100644 index 00000000..f8c10e86 --- /dev/null +++ b/docs/v4.0.0/plans/2026-11-18-capsule-blocks.md @@ -0,0 +1,51 @@ +# Capsules and their blocks -- the talk, and the bug it found + +Written 2026-11-18, from the capsules talk with Captain Bob. It records the rulings as they are given. +**Nothing here is built.** + +## 1. The design (Captain Bob) + +- **A capsule is ephemeral.** "Capsules load into their respective block by the header for that + block, `Block `. Then relocated into fast ram for execution. Other than the blocks used as + actual held data, everything else should be free for reuse." +- **`Block `** "loads 1024 bytes from the defined block number and relocated". A page shorter + than 1024 bytes is padded; zeroes or spaces, "doesn't matter". +- **The order in the file is irrelevant.** His example, as the pages appear in the file: + + ``` + Block 4098 \ stuff + Block 4255 \ stuff + Block 4096 \ program for stuff + Block 5077 \ crappy stuff + ``` + + Each page lands by its own number, then is relocated into the VM's RAM and interpreted there. +- **The offset is not a constant** (ruled: "That's THE BUG! #1 needs to determine that from the + runtime and build knobs"). Where the VM's RAM ends, and so how far a page moves, comes from the + runtime and the build's knobs, never from a fixed 2048. +- **The order of interpretation** (ruled): "Start with lowest block loaded. The current block will + determine the next block interpreted." The lowest page runs first. What runs next is decided by + the page that is running, through `-->`, `LOAD` or `THRU` by number. + +## 2. What the tree does today (read 2026-11-18) + +| Where | What it does | Against the design | +|---|---|---| +| `tools/mkcapsule.c:414`, `:1094` | Refuses a page below the literal `2048`, "the VM's fast RAM (0..2047)" | The fixed number is the bug (ruled) | +| `v3/include/block_subsystem.h:78-88` | `BLK_RAM_BLOCKS` 2080 and `BLK_FORTH_SYS_RESERVED` 32 give 2048 user blocks | The knobs exist, but nothing derives the capsule offset from them | +| v3's `INIT` (`v3/src/word_source/starforth_words.c:300-490`) | Renumbers the pages 1, 2, 3 ... in **file order** and runs them | Places by file order, not by number; no offset from the knobs | +| v4's loader (`v4/system/mesh.c:102-117`, `load()`) | Drops the number and sends each page's lines to Hera **in file order**; writes no block | The pages are never in blocks, so a capsule cannot `LOAD`, `THRU` or `-->` its own pages; file order is execution order | +| `experiments/bare_metal/README.md` rule 3 | "Blocks are loaded in file order and executed top-to-bottom" | Contradicts "order is irrelevant" | +| `mkcapsule`'s collision check (`:846-879`), `BLOCK_MAP.md`, the range tables (`experiments/bare_metal/README.md`, `.claude/CLAUDE.md`, `capsules/README.md`) | Treat each page number as a permanent claim across all capsules | Open: see section 3 | + +## 3. Open, one at a time + +1. ~~The `Block ` header~~: ruled above. +2. **The collision check across capsules.** If each capsule is loaded, relocated, interpreted and + then freed before the next, two capsules may use the same numbers. Does the check go, or is it + kept for capsules that are resident together? +3. **The knobs:** which ones set the offset (where the VM's RAM ends), for v3 and for v4. v4's node + has its own block window (`V4_BLOCK_SLOTS`). +4. **Where the pages land before relocation:** in the kernel's block store at `n`, or straight into + the relocated slot. +5. **The range tables and `BLOCK_MAP.md`:** go, or become a record of what each capsule uses.