# 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).