diff --git a/FABRIC-2.md b/FABRIC-2.md index 5bb5c72..856d7e4 100644 --- a/FABRIC-2.md +++ b/FABRIC-2.md @@ -346,11 +346,26 @@ and recorded. ## E. Documentation debt -- [ ] **Taxonomy / glossary.** Captain Bob's own flag, 2026-08-04: the physics vocabulary +- [x] **Taxonomy / glossary.** Captain Bob's own flag, 2026-08-04: the physics vocabulary (heat, mass, density, patron, Stadium, and Kconfig knob names built on it) needs an explicit glossary stating these are named analogies, so code, Kconfig, and documentation terminology don't drift apart over time. Never scoped into any phase. Real, acknowledged debt: "I guess that we didn't finish out FABRIC.md quite as much as we thought." + + > **DONE 2026-08-13.** `ONTOLOGY.md` already existed and already did exactly this job for + > the original heat/decay/inference vocabulary (Section III's lexicon, Section 3.2's + > "avoid/deprecated terms" table) — it just predated the Stadium work entirely (confirmed: + > zero mentions of "Stadium," "patron," "mass," or "density" before this edit) and was + > never extended to cover it. Added new §IX "Stadium/Fabric Vocabulary" in the same + > format as the existing lexicon: a metaphor-mapping table, alphabetical definitions for + > Cell, Code field, Density, K, Mass, Mass-vs-heat-conservation, Patron, Reap, Stadium, + > Warehouse, and Utility (all cited back to their `FABRIC.md` DECIDED sections, not + > invented), plus a Kconfig-knob-to-concept table with **verified, not assumed** wiring + > status for every `STADIUM_*` symbol — including flagging `STADIUM_CAPACITY_TICK` as + > dead, the same finding this document's own §12 Q5 closure made independently, now + > cross-referenced from the glossary too. Bumped `ONTOLOGY.md` to v1.1 with a version- + > history entry. No FABRIC.md/FABRIC-2.md content moved — this is a new, additive section + > in the document that already owned this job. - [ ] **ACL-RWT DoE overhead re-measurement.** The measured overhead numbers in `.claude/CLAUDE.md` ("+0.0054%–+0.0088%") were all captured at `-O0`, before item 4.5 enabled real compiler optimization. Nobody has re-measured, or even confirmed the old and diff --git a/ONTOLOGY.md b/ONTOLOGY.md index ef75342..7636fd4 100644 --- a/ONTOLOGY.md +++ b/ONTOLOGY.md @@ -1,7 +1,7 @@ # StarForth Ontology, Taxonomy, and Lexicon -**Version**: 1.0 -**Date**: 2025-12-13 +**Version**: 1.1 +**Date**: 2026-08-13 **Purpose**: Formal conceptual framework for precise academic discourse --- @@ -508,7 +508,180 @@ Slide 2: "Formally: f(t) = f₀ * e^(-λt)" --- -## IX. VERSION HISTORY +## IX. STADIUM / FABRIC VOCABULARY (v1.1 extension) + +**Added 2026-08-13**, closing a real, acknowledged documentation-debt item: the physics +vocabulary built on top of the original heat/decay/inference model above (patron, mass, +density, Stadium, and the Kconfig knob names built on them) accumulated across +`FABRIC.md`/`FABRIC-2.md` without an explicit statement, in one place, that these are named +analogies — the same discipline Section III already applies to "heat," extended to the +newer terms. Definitions below are drawn directly from `FABRIC.md`'s own DECIDED sections +(cited inline), not invented here. + +### 9.1 The metaphor, restated for this layer + +``` +METAPHORICAL MAPPING (Stadium → Runtime state): + Stadium ≈ Bounded live-state region (a venue, not a building) + Patron ≈ A live thing occupying floor space in that region + Mass ≈ How much floor space a patron occupies + Density ≈ How much heat a patron holds per unit of floor space + Warehouse ≈ What is not currently live (Artemis, the dictionary at rest) + Utility ≈ Infrastructure beside the Stadium, never inside it (framebuffer) + +LITERAL IMPLEMENTATIONS (No Metaphor): + Stadium → A fixed-size array of cells, index-linked, allocated at boot + Patron → A cell (or linked run of cells) with a nine-field header + Mass → Integer count of cells a patron occupies (≥ 1) + Density → heat ÷ mass, a derived ratio, not stored + K → Σ execution_heat_q48 across live entries, conserved at 1.0 +``` + +The Stadium metaphor is a **venue**, not a building: §2 (`FABRIC.md`) is explicit that a +patron *arrives and departs* — the Stadium holds what is live, not everything that exists. +That is the load-bearing distinction between "Stadium" and "warehouse" below, and it is why +the dictionary-at-rest is warehouse, not Stadium, even though every dictionary entry is +*eligible* to become a patron. + +### 9.2 Lexicon additions (alphabetical, same format as Section III) + +**Cell** +*Definition*: The Stadium's fixed-size unit of storage — a patron header, or a continuation +cell owned by exactly one patron. +*Formal*: A closed, two-constructor sum type: `Cell = Header | Continuation(owner)`, fixed +at build time (`FABRIC.md` §3). +*Measurement*: Proposed size 64 bytes (`FABRIC.md` §23.3, **not yet built** — see +`FABRIC-2.md`'s §23.4 #2 closure: the one real patron kind actually shipped, Hermes +messages, did not adopt this cell shape). +*Category*: Storage unit. +*Warning*: Not a pointer target — links between cells are Stadium-array indices, never +addresses (`FABRIC.md` §3, §13). + +**Code field** +*Definition*: A closed-enumeration behaviour tag stored in a patron header, dispatched by +the engine rather than branched on by kind. +*Formal*: `behaviour ∈ {MIGRATE, DELIVER, EXPIRE, COOL, ...}` — a fixed datatype, not an +open extension point (`FABRIC.md` §3, §13, §18.3). +*Category*: Dispatch mechanism. +*Note*: This is deliberately **the entire type system** — the engine never asks what kind +of patron it holds, only what its code field says to do (`FABRIC.md` §3). + +**Density** +*Definition*: A patron's heat share divided by its mass — heat per unit of occupied +Stadium floor space. +*Formal*: `density(p) = heat(p) / mass(p)`, derived, never stored (`FABRIC.md` §19.2). +*Measurement*: Used for ranking and admission (denser evicts sparser), not computed by a +separate scheduler — it is read, not decided (`FABRIC.md` §19.3). +*Category*: Derived quantity. +*Warning*: This is the one place the thermodynamic metaphor is literal in form (quantity +per unit volume) even though heat itself remains metaphorical. + +**K (conservation constant)** +*Definition*: The sum of every live entry's normalised heat share. +*Formal*: `K = Σ execution_heat_q48`, held at `Q48_ONE` (1.0) by construction — verified by +`vm_physics_conserved()` (`capsule_vm_physics.c`). +*Measurement*: A correctness check, not a diagnostic — it is 1.0 by construction and can +never itself signal system state (`FABRIC.md` §14, §19.1). Entropy over the heat +*distribution* is the actual instrument; K is not. +*Category*: Invariant. +*Warning*: Not an occupancy ratio (`Σmass / capacity`) — that definition was considered and +explicitly rejected because it contradicts the already-implemented, tested mechanism +(`FABRIC.md` §19.1). + +**Mass** +*Definition*: The number of Stadium cells a patron occupies — its footprint. +*Formal*: Integer ≥ 1, an entry field independent of heat; never enters K +(`FABRIC.md` §3, §19.2). +*Category*: Structural quantity, not conserved. +*Note*: A large patron is not "referenced" from the Stadium — it simply occupies more +cells. By-reference storage is reserved for things outside the Stadium entirely +(`FABRIC.md` §19.3, §23.1). + +**Mass conservation vs. heat conservation** +*Definition*: Two independent invariants that must not be confused. Heat (K) is conserved +globally and moved by traffic. Mass is conserved *per patron* during a residency — +identity and mass never change as a side effect of use — but is not a fleet-wide summed +invariant the way heat is (`FABRIC.md` §24.2). + +**Patron** +*Definition*: A live thing occupying a Stadium cell or linked run of cells — the unit the +Stadium actually holds. +*Formal*: One structure, no variants, no type field — identified by its code field's +behaviour, not by a kind tag (`FABRIC.md` §3, §13). +*Measurement*: Nine header wires: identity, heat, TTL, pin, link, code field, mass, +payload, contains (`FABRIC.md` §3, with amendments cited in place). +*Category*: The Stadium's sole occupant type. +*Known kinds (as of this writing)*: words (dictionary, warehouse-resident today, not yet +migrated — `FABRIC.md` §16.3), blocks (Artemis), messages (Hermes — shipped with a +**different** shape than this header, see `FABRIC-2.md`'s §23.4 #2 closure), VMs (Tripod, +`FABRIC.md` §20), dirty events (console, `FABRIC.md` §17.5). Five kinds, not four — an +earlier draft undercounted (`FABRIC.md` §1). + +**Reap** +*Definition*: The event that ends a patron's residency — not destruction, a return of its +cells and remaining heat to the pool. +*Formal*: Consumed on delivery (messages), on redraw (dirty events), on cooling below floor +(VMs), or on eviction by a denser newcomer (`FABRIC.md` §17.2, §17.5, §19.3). +*Category*: Lifecycle event. + +**Stadium** +*Definition*: A single, bounded region of memory outside any VM, holding everything +currently live. +*Formal*: A fixed-size array of cells, index-linked (not pointer-linked), allocated at +boot before any VM exists, not part of the heap (`FABRIC.md` §2, §17.6). +*Measurement*: Per-VM quota over a single global cell pool, elastic under pressure, +arbitrated by Hera (`FABRIC.md` §22) — not per-VM physical regions. +*Category*: The bounded live-state substrate this whole vocabulary describes. +*Warning*: "Live" is the operative word — the Stadium holds what is live, not everything +that exists. A dictionary word sitting cold and unexecuted is warehouse, not Stadium, even +once the dictionary itself migrates into this representation (`FABRIC.md` §2, §16.3). + +**Warehouse** +*Definition*: What lies beneath the Stadium — storage for things not currently live. +*Formal*: Artemis (block storage) and the resting dictionary are warehouse; the Stadium is +the floor above it (`FABRIC.md` §17.5's three-category taxonomy: warehouse / Stadium / +utility). +*Category*: Storage layer, outside the engine's live-state model. + +**Utility** +*Definition*: External infrastructure the Stadium consumes but never contains — beside the +building, not inside or beneath it. +*Formal*: The framebuffer and devices generally; the engine never learns about a utility's +existence, which is what makes it a boundary rather than an exception (`FABRIC.md` §17.5). +*Category*: Third taxonomy category, coordinate with warehouse and Stadium, not a +sub-case of either. + +### 9.3 Kconfig knob names built on this vocabulary + +Per Bob's own flag: code, Kconfig, and documentation terminology must not drift apart. +The table below is the current, verified wiring status of every `STADIUM_*` Kconfig +symbol — confirmed by direct source grep during the `FABRIC-2.md` closure work this +vocabulary accompanies, not assumed from the symbol's name or Kconfig help text alone. + +| Kconfig symbol | Vocabulary term | Wiring status (2026-08-13) | +|---|---|---| +| `STADIUM_MAX_VM_COUNT` | Patron (VM kind) population bound | **Live** — read in `stadium.c`, `stadium_words.c`, `capsule_birth.c` | +| `STADIUM_MEMORY_PERCENT` | Stadium capacity sizing | **Live** — read in `stadium.c` | +| `STADIUM_WORD_HEAT_QUANTUM` | Heat (word-patron admission) | **Live** — read in `stadium_words.c` | +| `STADIUM_WORD_COOL_RATE_Q48` | Heat decay rate (word patrons) | **Live** — read in `stadium_words.c` | +| `STADIUM_CONTAINS_DEPTH_MAX` | `contains` wire depth cap (§3, §8) | **Declared, not yet enforced** — reap-gating enforcement is item 3.5's scope, not implemented (`FABRIC-2.md` §A item 5.3 area; not a bug, a known sequencing gap) | +| `STADIUM_CAPACITY_TICK` | Capacity-loop cadence, distinct from heat's (§22.4) | **Dead** — declared with the correct intended default (1000, matching §22.4's precedent) but never read by any code path; only appearance beyond its own default is a compile-time `> 0` static assertion in `stadium.h`. Found and reported during this session's §12 Q5 closure (`FABRIC-2.md`) — `vm_physics_heartbeat_tick()` still literally shares `HEARTBEAT_INFERENCE_FREQUENCY` instead | + +This table is a snapshot, not a promise — it will drift the moment any of these symbols is +wired or unwired. Re-verify against source before relying on it for anything past a casual +read; do not assume "Live" here still means live without checking. + +--- + +## X. VERSION HISTORY + +**v1.1** (2026-08-13): +- Added Section IX: Stadium/Fabric vocabulary (patron, mass, density, Stadium, warehouse, + utility, K, cell, code field, reap) as named analogies, matching Section III's existing + discipline for the original heat/decay vocabulary +- Added a Kconfig knob-name-to-concept mapping table with verified (not assumed) wiring + status, per Captain Bob's 2026-08-04 flag that code/Kconfig/documentation terminology + must not drift apart **v1.0** (2025-12-13): - Initial ontology, taxonomy, and lexicon @@ -518,7 +691,7 @@ Slide 2: "Formally: f(t) = f₀ * e^(-λt)" --- -## X. ACKNOWLEDGMENTS +## XI. ACKNOWLEDGMENTS This ontology provides the formal conceptual framework for the StarForth project. It aims to eliminate ambiguity and enable precise academic discourse while