diff --git a/FABRIC-2.md b/FABRIC-2.md index 30c3151..7d5ce02 100644 --- a/FABRIC-2.md +++ b/FABRIC-2.md @@ -1685,3 +1685,70 @@ trustworthy per-row index. This closes the cookbook track's two planned entries (turtle demo, DoE library). Next per the user's own sequencing is SDK v1.9.0 scoping (VOCABULARY + FENCE) — not started, pending explicit go-ahead, since it's a new, larger workstream. + +## K. SDK v1.9.0 scoping — FENCE, VOCABULARY, open questions — 2026-08-19 + +**Scoping only, per this repo's own precedent (item 4.6 was ruled in FABRIC-2.md before any +implementation) — no code in this entry, no capsule written yet.** The user's own framing: +"once the cookbook is optimized... we're going to have all this stuff accessible inside the +SDK capsule, with a VOCABULARY and proper FENCE to aid developers. THAT's the definition of +v1.9.0 right there — the last v1.x release before v2.0.0 (SDK + Tripod + Console + ACL)." + +**Finding 1 — FENCE already exists, just not exposed to FORTH.** `VM` already carries +`dict_fence_latest`/`dict_fence_here` (`include/vm.h:410-411`), and `FORGET` +(`defining_words.c:568-`) already honors them correctly — it refuses to forget anything at or +below the fence (`defining_words.c:601-612`) and clamps the rewound `HERE` to the fence's `HERE` +(`:617-628`). The fence is set exactly once, in `vm_bootstrap.c`/`main.c`, immediately after +`register_forth79_words()` — protecting the entire C-registered base wordset, before any +capsule (init.4th, ACL.4th, fabric.4th, the cookbook capsules, everything) ever loads. **No +FORTH word reads or advances it** — confirmed via grep, zero hits for a `"FENCE"` registration +anywhere. So "a proper FENCE" isn't a new mechanism to design from scratch; it's exposing an +existing, already-correct one. Proposed minimal addition: a single new word, `FENCE ( -- )` — +raises `dict_fence_latest`/`dict_fence_here` to the current dictionary top, i.e. "protect +everything defined so far." An SDK capsule would call this once, at the end of its own loading, +so a developer experimenting at the REPL afterward can `FORGET` their own scratch definitions +without being able to accidentally tear down either the base wordset *or* the SDK vocabulary +underneath them. This is a genuinely different protection axis from `ACL-PIN`/`WORD_PINNED` +(already exists, per-word, one-way) — FENCE is an *address boundary* protecting a whole epoch +of definitions at once, not a per-word flag. One new C word, no new `VM` fields, no policy +logic in C beyond exposing state that already exists — consistent with "compose in FORTH +first." + +**Finding 2 — VOCABULARY already exists, is POST-tested (27 test-suite entries, +`vocabulary_words_test.c`), and has never been used in any real capsule content yet.** +`VOCABULARY`/`DEFINITIONS`/`CONTEXT`/`CURRENT`/`FORTH`/`ORDER`/`(FIND)` are all registered +(`vocabulary_words.c:581-587`), standard FORTH-79, nothing new needed here — but an SDK +capsule using them for real would be the first production use of the vocabulary system in this +codebase. Worth naming as a small first-use risk, not a blocker (the POST suite gives +reasonable confidence). + +**Open questions — genuinely the user's call, not decided here:** + +1. **Word inventory.** What does the SDK vocabulary actually *contain* — does it re-export the + cookbook capsules (turtle, doe) under an `SDK` vocabulary, wrap them, or just document how + to load them directly? Not scoped here because it depends on what "aid developers" is meant + to cover beyond the two cookbook entries. +2. **Load model.** Autoload from `init.4th` (like the base wordset), an opt-in commented toggle + (`ACL.4th`'s `\ S" ACL.4th" EXEC` precedent), or REPL-only (`turtle.4th`'s current choice, + per the original memory note's own scope)? +3. **Kernel-only vs. portable.** If `sdk.4th` loads other capsules via `EXEC`, it is + kernel-only by construction — `EXEC` is registered only in `mama_forth_words.c` + (`__STARKERNEL__`-gated), confirmed absent from the hosted build. `ACL.4th` deliberately + stays portable by omitting kernel-only words; an SDK capsule that bundles the cookbook + capsules cannot make the same claim unless it's explicitly scoped kernel-only. Needs a + decision, not an assumption. +4. **Version string.** `LITHOS_VERSION` (`Makefile.starkernel`) is currently `1.5.4`; `1.5.4` → + `1.9.0` is a real jump, not a patch bump. Naming this here, not touching it. +5. **`turtle.4th`'s unverified rendering.** Its HOWTO already flags that pixel-level rendering + has never been visually confirmed (arithmetic/control-flow verified, the DoE-before-REPL + wall made an interactive check impractical). If the SDK ships it as a headline demo, that + unverified state gets promoted into a release artifact — either verify it first (the + README's documented DoE-disable toggle in `init.4th` would make an interactive session + practical), or scope it explicitly as "demo, rendering unconfirmed" in the SDK's own + documentation. + +Block range for `capsules/sdk.4th`, whenever it's written: `5200+` (clear of `turtle.4th`'s +`5100`–`5108` and `fabric.4th`'s high-water mark at `5002`). Release criteria for v1.9.0 itself, +once scoped: three-arch boot to `zuse)ok>`, POST green, `mkcapsule --lint` clean, HOWTOs +present for everything shipped — matching every other acceptance bar in this document, nothing +new invented for this specific release.