Robert Allan JamesandClaude Sonnet 5
413b5a9bbf
Disabled capsules/artemis/init.4th block 4170's ART-STRESS-CAMPAIGN -- its own comment already said to revert to disabled once the K-invariant/ heartbeat verification run (item 4.6, closed earlier this session) was done. This was the actual ~25-30 minute wall blocking interactive REPL access, unrelated to any DoE mechanism. Verified capsules/turtle.4th and capsules/sdk.4th live in a gtk-display QEMU session: a red hexagon (6 100 POLYGON) and a green self-intersecting star (100 STAR) both render with correct geometry and color. Screenshot in evidence/amd64/. Two real obstacles found and worked around along the way: CS's full- framebuffer PLOT loop is far slower under TCG than previously documented (closer to 20+ minutes than "slow"), and the kernel's heartbeat CSV logging draws to the same console surface PLOT writes pixels to, overwriting drawings within a fraction of a second unless silenced first with the existing HB-OFF word. Both HOWTOs updated to record this. Re-verified full three-arch acceptance boot (POST, DoE, parity) with the ART-STRESS-CAMPAIGN change: 1012/0/0 and matching dict_hash on all three, identical to the pre-change baseline. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
99 lines
5.2 KiB
Markdown
99 lines
5.2 KiB
Markdown
<!-- Living draft (docs/working/ tier). Source for a future docs/formal/cookbook
|
||
scrap once reviewed -- see docs/formal/CLAUDE.md's Scraps System. Not yet
|
||
promoted; do not cite. -->
|
||
|
||
# SDK HOWTO — `capsules/sdk.4th`
|
||
|
||
**Status:** WORKING. Part of the v1.9.0 scoping work (FABRIC-2.md section K).
|
||
Loads the two cookbook capsules (turtle graphics, DoE library) and adds an
|
||
`SDK` vocabulary entry point plus `FENCE` protection on top of them.
|
||
|
||
## Loading it
|
||
|
||
Kernel-only (it loads other capsules via `EXEC`, which does not exist in
|
||
the hosted build), REPL-invoked — not part of `init.4th`'s boot sequence,
|
||
matching `turtle.4th`'s own choice:
|
||
|
||
```forth
|
||
S" sdk.4th" EXEC
|
||
```
|
||
|
||
This loads `turtle.4th` and `doe.4th`, defines an `SDK` vocabulary with two
|
||
introspection words (`SDK-VERSION`, `SDK-HELP`), then calls `FENCE` to
|
||
protect everything loaded so far — the base wordset, both cookbook
|
||
capsules, and `sdk.4th`'s own words — from `FORGET`. Prints a one-line
|
||
confirmation and hint on load; run `SDK-HELP` for the full word list.
|
||
|
||
## What `VOCABULARY` actually does here — read before assuming isolation
|
||
|
||
`sdk.4th` defines its own words (`SDK-VERSION`, `SDK-HELP`) into a named
|
||
`SDK` vocabulary via `SDK DEFINITIONS`. This is **organizational, not
|
||
isolating**: this VM's primary word lookup (`vm_find_word`, used by the
|
||
ordinary interpreter loop) is a flat, first-character-bucketed scan of the
|
||
whole dictionary — it does not consult `CONTEXT`/`CURRENT` at all. Verified
|
||
directly before writing this file: a word defined while `CURRENT` targeted
|
||
a custom vocabulary remained globally callable immediately after switching
|
||
back to `FORTH DEFINITIONS`, exactly as if no vocabulary had been involved.
|
||
The `VOCABULARY`/`DEFINITIONS`/`CONTEXT`/`ORDER`/`(FIND)` machinery is real,
|
||
standard FORTH-79, and useful for anything that explicitly walks vocabulary
|
||
chains (`(FIND)`, `ORDER`) — it just isn't what makes SDK words reachable
|
||
day to day. Don't build anything on the assumption that loading a second
|
||
vocabulary hides or scopes its words from the rest of the system.
|
||
|
||
## FENCE — and the bug it surfaced
|
||
|
||
`FENCE ( -- )` is new (this scoping pass) — it raises the dictionary's
|
||
`FORGET` boundary to whatever is currently the newest word, so anything
|
||
defined afterward can be safely `FORGET`ten without reaching back into
|
||
protected territory. `sdk.4th` calls it once, at the very end of loading.
|
||
|
||
Building a direct test for `FENCE` surfaced a real, severe, pre-existing
|
||
bug in `FORGET` itself — completely independent of `FENCE`, reproducible
|
||
with the *original* boot-time fence alone. Forgetting the single newest
|
||
word wrongly destroyed every other word back to the fence too; forgetting
|
||
an older word (which correctly cascades to remove newer words, per
|
||
FORTH-79 semantics) crashed with a SIGSEGV — a use-after-free in the
|
||
dictionary relink logic. Found and fixed as part of this work; full
|
||
root-cause writeup in FABRIC-2.md section K. Three POST cases were added to
|
||
`dictionary_manipulation_words_test.c` (Module 14) alongside `FORGET`'s
|
||
own, including the exact regression scenario, so it can't silently return.
|
||
|
||
## Vocabulary
|
||
|
||
| Word | Effect |
|
||
|------|--------|
|
||
| `SDK-VERSION` | Prints the release tag (`SDK v1.9.0 (scoping)`). |
|
||
| `SDK-HELP` | Prints the full word list for both cookbook capsules, with HOWTO pointers. |
|
||
| `FENCE` | (Not SDK-specific — a base word, used by this capsule.) Raises the `FORGET` boundary to the current dictionary top. |
|
||
|
||
Everything from `turtle.4th` and `doe.4th` is also available after loading
|
||
— see their own HOWTOs (`TURTLE-GRAPHICS-HOWTO-20260819.md`,
|
||
`DOE-LIBRARY-HOWTO-20260819.md`) for their vocabularies.
|
||
|
||
## Verification performed
|
||
|
||
- `mkcapsule --lint capsules/` clean (block range `5109`–`5115`, clear of
|
||
`turtle.4th`'s `5100`–`5108`).
|
||
- Hosted-build logic trace: `fabric.4th`'s core blocks + `turtle.4th` +
|
||
`doe.4th` + `sdk.4th`'s own blocks (with its two `EXEC` lines stripped,
|
||
since `EXEC` doesn't exist hosted — the capsules they'd load were
|
||
concatenated directly instead) piped into the hosted binary. `SDK-HELP`
|
||
runs and prints correctly; zero VM errors from any of this content
|
||
(all errors present in the log are the built-in POST suite's own
|
||
deliberate error-injection cases, confirmed by cross-checking against
|
||
the same baseline used for the cookbook capsules' own verification).
|
||
- Built cleanly (zero warnings) and baked into the capsule set on all
|
||
three kernel architectures (amd64/aarch64/riscv64); boot verified clean
|
||
through POST on all three, `1012 passed / 0 failed / 0 errors`
|
||
identically, `dict_hash` unchanged from the pre-`sdk.4th` baseline on
|
||
all three (expected — `sdk.4th` isn't autoloaded, so it cannot affect
|
||
boot-time dictionary content).
|
||
- **Driven interactively 2026-08-19**, live over the QEMU serial socket:
|
||
`S" sdk.4th" EXEC` loads cleanly (`SDK v1.9.0 (scoping)` banner prints),
|
||
and the re-exported `turtle.4th` renders correctly (see that HOWTO's own
|
||
updated verification section for the screenshot and the two practical
|
||
gotchas found along the way — `ART-STRESS-CAMPAIGN` was the actual
|
||
~25–30 minute wall, not any DoE mechanism, and `HB-OFF` is needed before
|
||
drawing anything since heartbeat logging shares the same console surface
|
||
`PLOT` draws to).
|