Files
LithosAnanke/docs/v4.0.0/plans/2026-11-18-capsule-blocks.md
T

3.4 KiB

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 <n>. Then relocated into fast ram for execution. Other than the blocks used as actual held data, everything else should be free for reuse."

  • Block <n> "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 <n> 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.