admin/LithosAnanake
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

ONTOLOGY.md: add Stadium/Fabric vocabulary section, close taxonomy/glossary debt

Browse Source 
Extends the existing lexicon (which already covered heat/decay/inference vocabulary but predated Stadium work entirely) with patron, mass, density, K, cell, code field, Stadium, warehouse, utility -- all cited to their FABRIC.md DECIDED sections. Adds a Kconfig-knob-to-concept table with verified wiring status, flagging STADIUM_CAPACITY_TICK as dead (matches this session's §12 Q5 finding). Bumped to v1.1.
This commit is contained in:
Robert Allan James
2026-08-13 10:26:22 -04:00
parent c9710093ae
commit be598af65c
2 changed files with 193 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files
FABRIC-2.md
+16 -1
View File
@@ -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
ONTOLOGY.md
+177 -4
View File
@@ -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