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

74 lines
5.0 KiB
Markdown

# 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~~ **Ruled: "Overwrite. That's it. Deterministic and
final."** A page written to a block number already in use overwrites it; what was there is gone.
Which write wins follows from the load order, which is fixed, so it is deterministic. A shared
number is not an error, so `mkcapsule`'s cross-capsule collision check (`:846-879`) goes.
3. ~~The knobs~~ **Ruled: the RAM block count.** The offset is the VM's user RAM block count,
`BLK_RAM_BLOCKS - BLK_FORTH_SYS_RESERVED` (2048 today, `v3/include/block_subsystem.h:78-88`).
- It becomes a Kconfig symbol.
- The kernel reads it.
- `mkcapsule` is given it at build time in place of its literal 2048 (`:414`, `:1094`).
v4's node window (`V4_BLOCK_SLOTS`) is not the source of the offset.
4. ~~Where the pages land~~ **Ruled: at `n`, then copied down.**
- Each page is written to the block store at `n`, then copied to `n - R` for interpreting, where
R is the RAM block count (ruling 3).
- Block `n` is then free again.
- Asked about pages whose `n - R` falls outside the RAM (`Block 4096` lands at 2048 when R is
2048), Captain Bob ruled: **"Just copy down the specified blocks. Where they land will be
developers responsibility."** The loader does not check where a page lands. The one rule left
is that `n` is at least R (`mkcapsule`'s floor, from the knob).
5. ~~The range tables and `BLOCK_MAP.md`~~ **Ruled: "Map stays, tables go".**
- `BLOCK_MAP.md` stays, generated by `mkcapsule`, as a record of the numbers each capsule uses
("Blocks used", not "claimed"). Captain Bob: **"Block map is a convenience"**: an aid for
developers, with no authority and nothing checked against it.
- The range tables go from `experiments/bare_metal/README.md`, `.claude/CLAUDE.md` and
`capsules/README.md`. In their place: `n` is at least R, a later write overwrites, and where a
page lands is the developer's responsibility.
6. **Chaining.** Under "the lowest block first; the current block determines the next", only a
capsule's lowest page runs unless it chains. No capsule in the tree chains its pages today
(`forth79.4th` has 3 pages, `centre.4th` 7, v3's `init.4th` 3, none with `-->`, `LOAD` or
`THRU`). Open: awaiting Captain Bob's answer.