docs: reorganise -- current reference gathered, finished work archived, superseded and dead ideas marked as such
docs/CLAUDE.md Phase 2, 2026-10-14. All moves by git mv; every archived file carries a header saying what it is, why, and where to look instead. - docs/reference/ (new): roadmap and versioning policy, M7.1, word-ACL design, kernel args, hosted acceptance test, dictionary, primitives, ontology, L8 table -- previously spread over docs/, docs/lithosananke/ and docs/03-architecture/. - docs/working/archive/historical/: finished work (session plan, test-gap audit, birthing plan, fix write-ups, the January architecture draft). - docs/working/archive/superseded/: the Hermes-VM Tripod docs and July Hermes designs (-> FABRIC-3.5/3.6), the StarForth roadmap, every working doc already flagged superseded or obsolete. - docs/working/archive/dead/: the hal_* target contract (never adopted), L4Re, metrics-and-knobs. - Papers and proposals into docs/working/papers/. - References rewritten across the repo (not logs/, not docs/patent/); CLAUDE.md's documentation section rewritten. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
rajames
co-authored by
Claude Opus 5.5
Claude Opus 5.5
parent
1a4b163861
commit
7aed588f78
@@ -0,0 +1,700 @@
|
||||
# StarForth Ontology, Taxonomy, and Lexicon
|
||||
|
||||
**Version**: 1.1
|
||||
**Date**: 2026-08-13
|
||||
**Purpose**: Formal conceptual framework for precise academic discourse
|
||||
|
||||
---
|
||||
|
||||
## I. ONTOLOGY (Conceptual Framework)
|
||||
|
||||
### 1.1 Core Concepts
|
||||
|
||||
```
|
||||
StarForth Adaptive Runtime System
|
||||
├── Execution Metrics
|
||||
│ ├── Execution Frequency (primary measurable)
|
||||
│ ├── Temporal Decay (derived quantity)
|
||||
│ └── Transition Probability (derived quantity)
|
||||
├── Adaptive Mechanisms
|
||||
│ ├── Frequency-Based Caching
|
||||
│ ├── Window-Based Inference
|
||||
│ └── Decay-Based Pruning
|
||||
├── Convergence Properties
|
||||
│ ├── Deterministic Behavior
|
||||
│ ├── Steady-State Equilibrium
|
||||
│ └── Variance Reduction
|
||||
└── Analysis Frameworks
|
||||
├── Dynamical Systems View
|
||||
├── Statistical Inference View
|
||||
└── Control Theory View
|
||||
```
|
||||
|
||||
### 1.2 Conceptual Relationships
|
||||
|
||||
```
|
||||
METAPHORICAL MAPPING (Thermodynamics → Execution):
|
||||
Thermal Energy ≈ Execution Frequency (measurable count)
|
||||
Heat Dissipation ≈ Exponential Decay (time-based reduction)
|
||||
Thermal Equilibrium ≈ Steady-State Convergence (stable metrics)
|
||||
Temperature ≈ Normalized Frequency Rank
|
||||
Cooling Rate ≈ Decay Coefficient (λ)
|
||||
|
||||
LITERAL IMPLEMENTATIONS (No Metaphor):
|
||||
Frequency Counter → Integer increment on execution
|
||||
Decay Function → f(t) = f₀ * e^(-λt)
|
||||
Hot-Words Cache → Top-K frequency-sorted entries
|
||||
Rolling Window → Circular buffer of execution records
|
||||
ANOVA Test → Statistical variance analysis (Levene's test)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## II. TAXONOMY (Hierarchical Classification)
|
||||
|
||||
### 2.1 Adaptive Runtime Components
|
||||
|
||||
```
|
||||
1. Measurement Layer
|
||||
1.1 Execution Frequency Tracking
|
||||
└── Dictionary Entry Counter (per-word increment)
|
||||
1.2 Temporal Recording
|
||||
└── Rolling Window of Truth (circular buffer)
|
||||
1.3 Transition Tracking
|
||||
└── Word-to-Word Transition Matrix
|
||||
|
||||
2. Transformation Layer
|
||||
2.1 Decay Models
|
||||
2.1.1 Linear Decay (Loop #3)
|
||||
└── Δf = -k * Δt
|
||||
2.1.2 Exponential Decay (Loop #6 Inference)
|
||||
└── f(t) = f₀ * e^(-λt)
|
||||
2.2 Normalization
|
||||
2.2.1 Frequency Ranking
|
||||
2.2.2 Probability Calculation
|
||||
|
||||
3. Inference Layer
|
||||
3.1 Window Width Inference (Loop #5)
|
||||
3.1.1 Variance Analysis (Levene's Test)
|
||||
3.1.2 Binary Search (Variance Inflection Point)
|
||||
3.2 Decay Slope Inference (Loop #6)
|
||||
3.2.1 Exponential Regression
|
||||
3.2.2 Least Squares Fitting
|
||||
|
||||
4. Actuation Layer
|
||||
4.1 Hot-Words Cache (Loop #1)
|
||||
4.1.1 Frequency-Based Sorting
|
||||
4.1.2 Top-K Selection
|
||||
4.1.3 Fast-Path Dictionary Lookup
|
||||
4.2 Speculative Execution (Loop #4)
|
||||
4.2.1 Transition Probability Calculation
|
||||
4.2.2 Prefetch Decision
|
||||
|
||||
5. Coordination Layer
|
||||
5.1 Heartbeat System (Loop #7)
|
||||
5.1.1 Time-Driven Tick Generation
|
||||
5.1.2 Loop Orchestration
|
||||
5.1.3 Adaptive Tick Rate
|
||||
```
|
||||
|
||||
### 2.2 Feedback Loop Taxonomy
|
||||
|
||||
```
|
||||
Feedback Loops (7 Total)
|
||||
├── Positive Loops (Amplifying)
|
||||
│ ├── Loop #1: Execution Heat Tracking
|
||||
│ │ └── More executions → Higher rank → More cache hits → More executions
|
||||
│ └── Loop #4: Pipelining Metrics
|
||||
│ └── More transitions → Better prediction → More prefetch hits
|
||||
├── Negative Loops (Stabilizing)
|
||||
│ ├── Loop #3: Linear Decay
|
||||
│ │ └── High frequency → Faster decay → Lower frequency → Slower decay
|
||||
│ ├── Loop #5: Window Width Inference
|
||||
│ │ └── High variance → Smaller window → Lower variance
|
||||
│ └── Loop #6: Decay Slope Inference
|
||||
│ └── Unstable metrics → Steeper decay → Faster stabilization
|
||||
├── Neutral Loops (Monitoring)
|
||||
│ └── Loop #2: Rolling Window History
|
||||
│ └── Execution occurs → Record in window → Historical data available
|
||||
└── Meta-Loop (Adaptive Coordination)
|
||||
└── Loop #7: Adaptive Heartbeat
|
||||
└── Stable system → Slower ticks → Less overhead
|
||||
```
|
||||
|
||||
### 2.3 Convergence Taxonomy
|
||||
|
||||
```
|
||||
Convergence Properties
|
||||
├── Determinism
|
||||
│ ├── Algorithmic Determinism (same inputs → same outputs)
|
||||
│ ├── Temporal Determinism (time-invariant steady state)
|
||||
│ └── Statistical Determinism (0% variance)
|
||||
├── Steady-State Characteristics
|
||||
│ ├── Fixed Point (attractors in phase space)
|
||||
│ ├── Periodic Behavior (limit cycles)
|
||||
│ └── Chaotic Behavior (sensitive dependence - avoided)
|
||||
└── Variance Metrics
|
||||
├── Inter-Run Variance (across multiple executions)
|
||||
├── Intra-Run Variance (within single execution)
|
||||
└── Temporal Variance (across time windows)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## III. LEXICON (Precise Definitions)
|
||||
|
||||
### 3.1 Core Terms (Alphabetical)
|
||||
|
||||
**Adaptive Heartbeat**
|
||||
*Definition*: Time-driven coordination mechanism that orchestrates feedback loop execution at dynamically-adjusted intervals.
|
||||
*Formal*: Thread T executing `vm_tick()` at frequency f_tick, where f_tick ∈ [f_min, f_max] adapts based on system stability.
|
||||
*Measurement*: Tick period in nanoseconds (configurable: HEARTBEAT_TICK_NS).
|
||||
*Category*: Coordination mechanism.
|
||||
|
||||
**Attractor**
|
||||
*Definition*: Stable equilibrium point or region in phase space toward which execution trajectories converge.
|
||||
*Formal*: Fixed point x* where F(x*) = x* for dynamical system x_{t+1} = F(x_t).
|
||||
*Measurement*: Coordinates in (window_size, decay_slope, variance) space.
|
||||
*Category*: Dynamical systems concept.
|
||||
|
||||
**Decay Coefficient (λ)**
|
||||
*Definition*: Rate parameter controlling exponential reduction in execution frequency over time.
|
||||
*Formal*: λ in f(t) = f₀ * e^(-λt), units of [1/time].
|
||||
*Measurement*: Derived via exponential regression; stored as Q48.16 fixed-point.
|
||||
*Category*: Transformation parameter.
|
||||
|
||||
**Deterministic Convergence**
|
||||
*Definition*: Property whereby repeated executions of identical workloads produce statistically indistinguishable steady-state metrics.
|
||||
*Formal*: ∀ executions i,j: |metric_i - metric_j| / σ < ε, where ε → 0 as t → ∞.
|
||||
*Measurement*: Coefficient of variation CV = σ/μ → 0%.
|
||||
*Category*: Convergence property.
|
||||
|
||||
**Execution Frequency**
|
||||
*Definition*: Count of times a dictionary entry has been executed since VM initialization, optionally adjusted by decay.
|
||||
*Formal*: f = Σ executions - ∫ decay(t) dt.
|
||||
*Measurement*: Unsigned 64-bit integer (`uint64_t execution_heat`).
|
||||
*Category*: Primary measurable quantity.
|
||||
*Note*: "Heat" is metaphorical naming; actual quantity is frequency.
|
||||
|
||||
**Exponential Decay**
|
||||
*Definition*: Mathematical function modeling reduction in execution frequency proportional to current value.
|
||||
*Formal*: f(t) = f₀ * e^(-λt), where f₀ is initial frequency.
|
||||
*Measurement*: Applied periodically by heartbeat system.
|
||||
*Category*: Transformation function.
|
||||
*Metaphor*: Analogous to radioactive decay or thermal dissipation.
|
||||
|
||||
**Hot-Words Cache**
|
||||
*Definition*: Fixed-size array storing pointers to the K most frequently executed dictionary entries for O(1) lookup acceleration.
|
||||
*Formal*: Cache C = {e_1, e_2, ..., e_K} where f(e_i) ≥ f(e_{i+1}) ∀ i.
|
||||
*Measurement*: Cache size K (configurable: HOTWORDS_CACHE_SIZE).
|
||||
*Category*: Frequency-based optimization.
|
||||
|
||||
**Levene's Test**
|
||||
*Definition*: Non-parametric statistical test for homogeneity of variance across groups.
|
||||
*Formal*: H₀: σ₁² = σ₂² = ... = σ_k² (variances equal).
|
||||
*Measurement*: F-statistic with p-value threshold (typically 0.05).
|
||||
*Category*: Statistical inference method.
|
||||
*Application*: Used to detect variance changes when adjusting window size.
|
||||
|
||||
**Phase Space**
|
||||
*Definition*: Multi-dimensional coordinate system where each axis represents a system state variable.
|
||||
*Formal*: Space S = {(w, λ, σ²) | w ∈ ℕ, λ ∈ ℝ⁺, σ² ∈ ℝ⁺}.
|
||||
*Measurement*: Coordinates: (window_size, decay_slope_Q48, variance_Q48).
|
||||
*Category*: Dynamical systems representation.
|
||||
|
||||
**Rolling Window of Truth**
|
||||
*Definition*: Circular buffer recording recent execution history for deterministic metric seeding.
|
||||
*Formal*: Buffer B[i] = word_id at execution event i mod |B|.
|
||||
*Measurement*: Buffer size (configurable: ROLLING_WINDOW_SIZE = 4096).
|
||||
*Category*: Temporal recording mechanism.
|
||||
*Purpose*: Ensures identical initial conditions for reproducibility.
|
||||
|
||||
**Steady-State Equilibrium**
|
||||
*Definition*: Condition where adaptive system metrics stabilize within bounded oscillation.
|
||||
*Formal*: ∃ t_0: ∀ t > t_0, |x(t) - x*| < δ for small δ.
|
||||
*Measurement*: Variance CV < 0.1% over 1000-tick window.
|
||||
*Category*: Convergence property.
|
||||
*Metaphor*: Analogous to thermodynamic equilibrium.
|
||||
|
||||
**Thermodynamic Metaphor**
|
||||
*Definition*: Conceptual mapping between thermodynamic quantities and execution metrics.
|
||||
*Mapping*:
|
||||
- Heat ↔ Execution Frequency
|
||||
- Temperature ↔ Normalized Rank
|
||||
- Cooling ↔ Exponential Decay
|
||||
- Equilibrium ↔ Steady State
|
||||
*Category*: Conceptual framework (not literal physics).
|
||||
*Warning*: Must qualify as metaphor in academic writing.
|
||||
|
||||
**Transition Probability**
|
||||
*Definition*: Conditional probability that word B is executed immediately after word A.
|
||||
*Formal*: P(B|A) = count(A→B) / count(A).
|
||||
*Measurement*: Stored as Q48.16 fixed-point in transition matrix.
|
||||
*Category*: Derived metric for speculative execution.
|
||||
|
||||
**Variance Inflection Point**
|
||||
*Definition*: Window size w* where variance begins to increase when window shrinks below w*.
|
||||
*Formal*: w* = arg min_w { Var(w) | w < w_current }.
|
||||
*Measurement*: Found via binary search with Levene's test.
|
||||
*Category*: Inference target.
|
||||
*Purpose*: Optimal window size for stable metrics.
|
||||
|
||||
**Word Transition**
|
||||
*Definition*: Sequential execution of word B immediately following word A in threaded code.
|
||||
*Formal*: Event (A, B, t) where A executes at time t and B at time t+ε.
|
||||
*Measurement*: Recorded in transition_metrics.history[] circular buffer.
|
||||
*Category*: Execution event.
|
||||
|
||||
---
|
||||
|
||||
### 3.2 Avoid/Deprecated Terms
|
||||
|
||||
| ❌ Avoid | ✅ Use Instead | Reason |
|
||||
|---------|---------------|--------|
|
||||
| "Physics-based" | "Thermodynamically-inspired metaphor" | Not literal physics |
|
||||
| "Execution heat" (in formal writing) | "Execution frequency with decay" | "Heat" is metaphorical |
|
||||
| "Temperature" | "Normalized frequency rank" | No actual thermal quantity |
|
||||
| "Quantum-inspired" | N/A | No quantum mechanics involved |
|
||||
| "AI-driven" | "Statistically-inferred" | No neural networks or ML |
|
||||
| "Learning" | "Adaptive inference" | Not machine learning |
|
||||
| "Training" | "Convergence to steady state" | Not supervised learning |
|
||||
|
||||
---
|
||||
|
||||
## IV. MATHEMATICAL FORMALISM
|
||||
|
||||
### 4.1 Execution Frequency Evolution
|
||||
|
||||
**Discrete-time update**:
|
||||
```
|
||||
f[t+1] = f[t] + Δexec[t] - Δdecay[t]
|
||||
|
||||
where:
|
||||
Δexec[t] = 1 if word executed at tick t, else 0
|
||||
Δdecay[t] = λ * f[t] * Δt (exponential decay approximation)
|
||||
```
|
||||
|
||||
**Continuous-time model**:
|
||||
```
|
||||
df/dt = r(t) - λf(t)
|
||||
|
||||
where:
|
||||
r(t) = execution rate [executions/second]
|
||||
λ = decay coefficient [1/second]
|
||||
|
||||
Solution:
|
||||
f(t) = e^(-λt) * [f₀ + ∫₀ᵗ r(τ)e^(λτ) dτ]
|
||||
```
|
||||
|
||||
### 4.2 Hot-Words Cache Selection
|
||||
|
||||
**Cache membership criterion**:
|
||||
```
|
||||
e ∈ Cache ⟺ rank(e) ≤ K
|
||||
|
||||
where:
|
||||
rank(e) = |{e' ∈ Dictionary : f(e') > f(e)}| + 1
|
||||
K = cache size (constant)
|
||||
```
|
||||
|
||||
### 4.3 Window Width Inference
|
||||
|
||||
**Objective function**:
|
||||
```
|
||||
w* = arg min { Var(w) : w ∈ [w_min, w_current] }
|
||||
|
||||
Subject to:
|
||||
Levene(w, w_current) → F-statistic
|
||||
p-value(F) < α (typically α = 0.05)
|
||||
```
|
||||
|
||||
### 4.4 Decay Slope Inference
|
||||
|
||||
**Exponential regression**:
|
||||
```
|
||||
Given: {(t_i, f_i)}_{i=1}^N from rolling window
|
||||
|
||||
Model: f(t) = f₀ * e^(-λt)
|
||||
|
||||
Log-transform: ln(f) = ln(f₀) - λt
|
||||
|
||||
Least squares:
|
||||
λ* = arg min Σ [ln(f_i) - (ln(f₀) - λt_i)]²
|
||||
```
|
||||
|
||||
### 4.5 Transition Probability
|
||||
|
||||
**Maximum likelihood estimate**:
|
||||
```
|
||||
P(B|A) = count(A→B) / count(A)
|
||||
|
||||
where:
|
||||
count(A→B) = # times B executed immediately after A
|
||||
count(A) = # times A executed
|
||||
```
|
||||
|
||||
### 4.6 Convergence Metric
|
||||
|
||||
**Coefficient of Variation**:
|
||||
```
|
||||
CV = σ / μ
|
||||
|
||||
where:
|
||||
σ = √(Var[metric]) = standard deviation
|
||||
μ = E[metric] = mean
|
||||
|
||||
Convergence achieved when: CV → 0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## V. RELATIONSHIP DIAGRAM
|
||||
|
||||
### 5.1 Component Dependencies
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Execution Event │
|
||||
│ (word executed) │
|
||||
└──────────────────────┬──────────────────────────────────────┘
|
||||
│
|
||||
┌───────────┴───────────┐
|
||||
│ │
|
||||
▼ ▼
|
||||
┌────────────────┐ ┌──────────────────┐
|
||||
│ Frequency │ │ Rolling Window │
|
||||
│ Increment │ │ Recording │
|
||||
│ (Loop #1) │ │ (Loop #2) │
|
||||
└────────┬───────┘ └─────────┬────────┘
|
||||
│ │
|
||||
│ │
|
||||
▼ ▼
|
||||
┌────────────────┐ ┌──────────────────┐
|
||||
│ Decay │ │ Inference │
|
||||
│ Application │ │ Engine │
|
||||
│ (Loop #3,#6) │ │ (Loop #5,#6) │
|
||||
└────────┬───────┘ └─────────┬────────┘
|
||||
│ │
|
||||
└───────────┬────────────┘
|
||||
│
|
||||
▼
|
||||
┌───────────────────────┐
|
||||
│ Hot-Words Cache │
|
||||
│ Reorganization │
|
||||
└───────────┬───────────┘
|
||||
│
|
||||
▼
|
||||
┌───────────────────────┐
|
||||
│ Optimized Lookup │
|
||||
│ (O(1) cache hit) │
|
||||
└───────────────────────┘
|
||||
```
|
||||
|
||||
### 5.2 Feedback Loop Interactions
|
||||
|
||||
```
|
||||
Execution → Frequency ↑ → Cache Rank ↑ → Lookup Speed ↑ → More Execution
|
||||
▲ │
|
||||
│ │
|
||||
└─────────────── (Positive Feedback) ────────────┘
|
||||
|
||||
Frequency ↑ → Decay ↑ → Frequency ↓ → Decay ↓ → Frequency Stabilizes
|
||||
▲ │
|
||||
│ │
|
||||
└──── (Negative Feedback) ────┘
|
||||
|
||||
Variance ↑ → Window Shrink → Variance ↓ → Window Stable
|
||||
▲ │
|
||||
│ │
|
||||
└──── (Negative Feedback) ──┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## VI. ONTOLOGICAL COMMITMENTS
|
||||
|
||||
### 6.1 Foundational Assumptions
|
||||
|
||||
1. **Frequency as Proxy for Importance**
|
||||
- Assumption: Frequently executed code is more important to optimize
|
||||
- Justification: Empirical validation (Zipf's law in execution patterns)
|
||||
|
||||
2. **Decay Models Temporal Relevance**
|
||||
- Assumption: Recent executions are more relevant than distant past
|
||||
- Justification: Locality of reference (temporal locality principle)
|
||||
|
||||
3. **Determinism Through Convergence**
|
||||
- Assumption: Adaptive systems can converge to deterministic steady states
|
||||
- Justification: Fixed-point theorems for contractive mappings
|
||||
|
||||
4. **Statistical Inference Validity**
|
||||
- Assumption: Execution patterns are statistically analyzable
|
||||
- Justification: Central Limit Theorem for large sample sizes
|
||||
|
||||
### 6.2 Scope Limitations
|
||||
|
||||
**What This Ontology DOES Cover**:
|
||||
- ✓ Execution frequency measurement and decay
|
||||
- ✓ Adaptive caching and inference mechanisms
|
||||
- ✓ Dynamical systems characterization
|
||||
- ✓ Statistical convergence properties
|
||||
|
||||
**What This Ontology DOES NOT Cover**:
|
||||
- ✗ Actual thermodynamic processes (metaphor only)
|
||||
- ✗ Machine learning or neural networks (no training)
|
||||
- ✗ Quantum computing (no quantum effects)
|
||||
- ✗ Biological neural systems (no biomimicry)
|
||||
|
||||
---
|
||||
|
||||
## VII. USAGE GUIDELINES
|
||||
|
||||
### 7.1 Academic Writing
|
||||
|
||||
**In Abstracts/Titles**: Use precise, non-metaphorical terms
|
||||
```
|
||||
✅ "Thermodynamically-Inspired Adaptive Runtime"
|
||||
❌ "Physics-Based Virtual Machine"
|
||||
```
|
||||
|
||||
**In Technical Sections**: Qualify metaphors explicitly
|
||||
```
|
||||
✅ "We employ a thermodynamic metaphor where execution frequency
|
||||
is treated as 'heat' that dissipates over time..."
|
||||
❌ "The physics model applies heat decay..."
|
||||
```
|
||||
|
||||
**In Formalism**: Use mathematical definitions, not analogies
|
||||
```
|
||||
✅ "Frequency evolves as f(t) = f₀ * e^(-λt)"
|
||||
❌ "Heat cools exponentially like in Newton's law"
|
||||
```
|
||||
|
||||
### 7.2 Code Comments
|
||||
|
||||
**In Source Code**: Use concrete terms from lexicon
|
||||
```c
|
||||
// ✅ GOOD: Increment execution frequency counter
|
||||
entry->execution_heat++;
|
||||
|
||||
// ❌ BAD: Increase temperature of word
|
||||
entry->execution_heat++; // heat up!
|
||||
```
|
||||
|
||||
### 7.3 Presentation/Talks
|
||||
|
||||
**Slides**: Use metaphor for intuition, then formalize
|
||||
```
|
||||
Slide 1: "Think of execution frequency like heat..."
|
||||
Slide 2: "Formally: f(t) = f₀ * e^(-λt)"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## VIII. REFERENCES
|
||||
|
||||
### 8.1 Foundational Concepts
|
||||
|
||||
- **Dynamical Systems**: Strogatz, S. (2015). *Nonlinear Dynamics and Chaos*
|
||||
- **Control Theory**: Åström, K. & Murray, R. (2008). *Feedback Systems*
|
||||
- **Statistical Inference**: Casella, G. & Berger, R. (2002). *Statistical Inference*
|
||||
- **Exponential Decay**: Standard mathematical function (e^(-λt))
|
||||
|
||||
### 8.2 Related Work
|
||||
|
||||
- **Trace-based JIT**: Bolz et al. (2009). "Tracing the Meta-Level: PyPy's Tracing JIT Compiler"
|
||||
- **Adaptive Systems**: Garlan et al. (2004). "Rainbow: Architecture-Based Self-Adaptation"
|
||||
- **Forth Optimization**: Ertl, M.A. (1996). "Stack Caching for Interpreters"
|
||||
|
||||
---
|
||||
|
||||
## 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-0.md`/`FABRIC-1.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-0.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-0.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-0.md` §3).
|
||||
*Measurement*: Proposed size 64 bytes (`FABRIC-0.md` §23.3, **not yet built** — see
|
||||
`FABRIC-1.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-0.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-0.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-0.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-0.md` §19.2).
|
||||
*Measurement*: Used for ranking and admission (denser evicts sparser), not computed by a
|
||||
separate scheduler — it is read, not decided (`FABRIC-0.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-0.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-0.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-0.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-0.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-0.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-0.md` §3, §13).
|
||||
*Measurement*: Nine header wires: identity, heat, TTL, pin, link, code field, mass,
|
||||
payload, contains (`FABRIC-0.md` §3, with amendments cited in place).
|
||||
*Category*: The Stadium's sole occupant type.
|
||||
*Known kinds (as of this writing)*: words (dictionary — fully migrated and live via
|
||||
`stadium_word_dispatch()`, `FABRIC-0.md` §16.3/§17.7), blocks (Artemis), messages (Hermes — shipped with a
|
||||
**different** shape than this header, see `FABRIC-1.md`'s §23.4 #2 closure), VMs (Tripod,
|
||||
`FABRIC-0.md` §20), dirty events (console, `FABRIC-0.md` §17.5). Five kinds, not four — an
|
||||
earlier draft undercounted (`FABRIC-0.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-0.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-0.md` §2, §17.6).
|
||||
*Measurement*: Per-VM quota over a single global cell pool, elastic under pressure,
|
||||
arbitrated by Hera (`FABRIC-0.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-0.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-0.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-0.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-1.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-1.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-1.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
|
||||
- Formal mathematical definitions
|
||||
- Relationship diagrams
|
||||
- Usage guidelines
|
||||
|
||||
---
|
||||
|
||||
## XI. ACKNOWLEDGMENTS
|
||||
|
||||
This ontology provides the formal conceptual framework for the StarForth project.
|
||||
It aims to eliminate ambiguity and enable precise academic discourse while
|
||||
acknowledging the metaphorical nature of certain conceptual mappings.
|
||||
|
||||
**License**: See ./LICENSE
|
||||
Reference in New Issue
Block a user