FABRIC-2.md: SDK v1.9.0 scoping ruling -- FENCE already exists, VOCABULARY already exists

No code in this commit. Two findings that reframe the scope: dict_fence_latest/
dict_fence_here already exist on VM and FORGET already honors them correctly --
set once at bootstrap, right after the base wordset registers, never exposed to
FORTH. "A proper FENCE" is exposing existing state via one new word (FENCE ( -- )),
not designing a new mechanism. VOCABULARY/DEFINITIONS/CONTEXT/ORDER are already
registered and POST-tested but have never been used in any real capsule content --
an SDK capsule would be the first production use.

Five open questions named but not decided: SDK word inventory, load model
(autoload/opt-in/REPL-only), kernel-only-vs-portable (EXEC is kernel-only, so a
capsule that EXECs the cookbook capsules can't claim hosted portability), the
1.5.4 -> 1.9.0 version jump, and turtle.4th's still-unconfirmed rendering if it
ships as an SDK demo.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
Robert Allan James
2026-08-19 05:26:48 -04:00
co-authored by Claude Sonnet 5
parent d0a76420a5
commit 6d8b48f100
+67
View File
@@ -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.