From 903321e548ba9a43a498ce5d13ff115dfcd74700 Mon Sep 17 00:00:00 2001 From: rajames Date: Mon, 5 Oct 2026 15:18:30 -0400 Subject: [PATCH] feat(mkcapsule): no upper bound on capsule block numbers Blocks 0..2047, the VM's fast RAM, are the only ones a capsule may not claim (docs/v4.0.0/NUCLEUS.md 5.2). The ceiling of 5120 matched no device. All 36 capsule files still lint clean. Co-Authored-By: Claude Opus 5.5 --- .claude/CLAUDE.md | 4 +++- experiments/bare_metal/README.md | 6 ++++-- tools/mkcapsule.c | 10 ++++++---- 3 files changed, 13 insertions(+), 7 deletions(-) diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 8981e7d3..5e76a959 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -176,7 +176,9 @@ capsule files — accurate): previously described a 1024-byte-per-block budget — right by arithmetic, wrong as a rule): `validate_forth_blocks` enforces a **64-char × 16-line** format — **line length ≤ 64 chars, ≤ 16 content lines per block** (`mkcapsule.c:344-345`, `:430`) — and -a block number in **`[2048, 5120)`** (`:408-409`). 64 × 16 = 1024, which is where the old +a block number of **2048 or more, with no upper bound** (`:408-411`; ruled 2026-10-05, +`docs/v4.0.0/NUCLEUS.md` §5.2 — blocks 0–2047, the VM's fast RAM, are the only ones a capsule +may not claim; the check was `[2048, 5120)` before). 64 × 16 = 1024, which is where the old figure came from, but the enforcement is per-line and per-line-count: **8 lines of 128 chars is 1024 bytes and still fails.** Verify with `mkcapsule --lint capsules/`, not `wc -c`. diff --git a/experiments/bare_metal/README.md b/experiments/bare_metal/README.md index 81da9ff1..54c1001d 100644 --- a/experiments/bare_metal/README.md +++ b/experiments/bare_metal/README.md @@ -144,8 +144,10 @@ which block slot to fill. 1. The first line of each logical block must be `Block NNNN` (capital B, single space, decimal integer). -2. Block numbers must be unique within a single capsule file, and must fall - in `[2048, 5120)`. +2. Block numbers must be unique within a single capsule file, and must be + 2048 or more. Blocks 0–2047 are the VM's fast RAM and the only ones a + capsule may not claim; there is no upper bound (ruled 2026-10-05, + `docs/v4.0.0/NUCLEUS.md` §5.2 — previously `[2048, 5120)`). 3. Blocks are loaded in file order and executed top-to-bottom. 4. Each block can hold at most 16 content lines, each at most 64 characters long (`validate_forth_blocks` in `tools/mkcapsule.c`, corrected 2026-09-19 diff --git a/tools/mkcapsule.c b/tools/mkcapsule.c index 1c737904..d8b419b5 100644 --- a/tools/mkcapsule.c +++ b/tools/mkcapsule.c @@ -405,11 +405,13 @@ static int validate_forth_blocks(const char *fpath, block_num = (int)strtol((const char *)(data + start + 6), NULL, 10); line_in_block = 0; - /* Block number must be in user space: [2048, 5120) */ - if (block_num < 2048 || block_num >= 5120) { + /* Blocks 0..2047 are the VM's fast RAM and the only ones a + * capsule may not claim; there is no upper bound + * (docs/v4.0.0/NUCLEUS.md 5.2). */ + if (block_num < 2048) { fprintf(stderr, - "mkcapsule: ERROR: %s:%d: block %d out of user range " - "[2048, 5120)\n", + "mkcapsule: ERROR: %s:%d: block %d is in the VM's fast " + "RAM (0..2047)\n", fpath, file_line, block_num); errors++; }