Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
74 lines
5.0 KiB
Markdown
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.
|