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

Rename FABRIC series: FABRIC.md->0, FABRIC-2.md->1, FABRIC-3.md->2, FABRIC-4.md unchanged

Browse Source 
FABRIC.md -> FABRIC-0.md
FABRIC-2.md -> FABRIC-1.md
FABRIC-3.md -> FABRIC-2.md (the current/living document)
FABRIC-4.md unchanged (new #3 to follow separately)

Every cross-reference repo-wide updated to match, including doc-comment
citations inside kernel source (.c/.h) files -- done via an ordered
placeholder substitution (FABRIC-3.md->placeholder2, FABRIC-2.md->
placeholder1, FABRIC.md->placeholder0, then placeholders resolved to
final names) in a single pass per file to avoid double-shifting
already-renamed references.

One line in capsules/font.4th grew past the 64-char block-format limit
as a side effect of the longer filename; shortened it and reverified
with mkcapsule --lint (34/34 pass) before rebuilding.

Verified 3-arch boot to ok> (amd64/aarch64/riscv64, each in the
foreground) after the fix; logs and DoE CSVs from this session's
verification runs included per this repo's own audit-artifact
convention.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019YcT3H2PQeyujrzjqS3Var
This commit is contained in:
Robert Allan James
2026-09-04 11:22:51 -04:00
co-authored by Claude Sonnet 5
parent ff2941dfb9
commit b031b802e3
128 changed files with 37154 additions and 9572 deletions
Download Patch File Download Diff File Expand all files Collapse all files
include/starkernel/vm/stadium.h
+22 -22
View File
@@ -22,11 +22,11 @@
*/
/**
* stadium.h - The Stadium cell and header (FABRIC.md §3, punch list item 3.1)
* stadium.h - The Stadium cell and header (FABRIC-0.md §3, punch list item 3.1)
*
* A cell is one of exactly two things: a patron header, or a continuation
* cell owned by exactly one patron. The union is closed, two-valued, and
* fixed at build time -- not a type field. See FABRIC.md §3.
* fixed at build time -- not a type field. See FABRIC-0.md §3.
*/
#ifndef STARKERNEL_VM_STADIUM_H
@@ -37,7 +37,7 @@
#include <stddef.h>
#include <stdint.h>
#include "starforth_config.h" /* STADIUM_CONTAINS_DEPTH_MAX, STADIUM_CAPACITY_TICK, STADIUM_MEMORY_PERCENT */
#include "starkernel/vm_uuid.h" /* VMUuid -- FABRIC.md item 3.8 */
#include "starkernel/vm_uuid.h" /* VMUuid -- FABRIC-0.md item 3.8 */
#define STADIUM_CELL_BYTES 64
@@ -47,10 +47,10 @@
#define STADIUM_CONTAINS_NONE ((uint32_t)-1)
/* `flags` bit 0 -- pinned, exempt from eviction/reap. Moved here from a
* stadium.c-private #define (FABRIC-3.md §H.12 step 3) so session.c's pin-
* stadium.c-private #define (FABRIC-2.md §H.12 step 3) so session.c's pin-
* authority choke point (session_set_pinned()/session_is_pinned()) can
* write/read this same bit without a duplicate definition. Session is
* authoritative for every EXTERNAL reader (FABRIC-3.md §H.10) -- this bit
* authoritative for every EXTERNAL reader (FABRIC-2.md §H.10) -- this bit
* on the raw patron header stays a mirrored copy purely for the Stadium
* engine's own internal eviction/admission logic (stadium.c), which must
* stay self-contained and not call back into session.c. */
@@ -58,7 +58,7 @@
/*
* StadiumPatronHeader - one member of the closed two-valued cell union
* (FABRIC.md §3). Nine wires: identity, heat, TTL, pin (a bit in `flags`),
* (FABRIC-0.md §3). Nine wires: identity, heat, TTL, pin (a bit in `flags`),
* link, code field (`behaviour`), mass, payload, contains. `flags` bit 0 is
* `pin`; the remaining bits are reserved. `behaviour` is the closed code-field
* enumeration (§18.3) -- not yet defined, item 3.3's scope.
@@ -102,7 +102,7 @@ typedef struct {
/*
* StadiumCell - the closed two-valued union itself (§3). Which member is
* valid for a given array slot is NOT stored in the cell -- FABRIC.md's item
* valid for a given array slot is NOT stored in the cell -- FABRIC-0.md's item
* 3.1 amendment to §3 rules this an external side bitmap, one bit per cell,
* kept outside the cell array. Declared here as the indexing contract this
* type expects; item 3.2 (boot-time allocation) allocates the bitmap itself.
@@ -122,7 +122,7 @@ typedef char stadium_cell_size_check[(sizeof(StadiumCell) == STADIUM_CELL_BYTES)
* implemented. STADIUM_CONTAINS_DEPTH_MAX still has no consumer (item 3.5
* for the depth cap, not yet implemented). STADIUM_CAPACITY_TICK was wired
* in 2026-08-15 (capsule_vm_physics.c's vm_physics_heartbeat_tick(), see
* FABRIC-2.md F.2/§12 Q5) -- this check now proves a real, live constant
* FABRIC-1.md F.2/§12 Q5) -- this check now proves a real, live constant
* is sane, not just a placeholder, same discipline already applied to the
* byte-count checks above.
*/
@@ -139,7 +139,7 @@ typedef char stadium_capacity_tick_configured_check[(STADIUM_CAPACITY_TICK > 0)
*/
/*
* stadium_boot_init - Boot-time allocation (FABRIC.md item 3.2, §17.6 position
* stadium_boot_init - Boot-time allocation (FABRIC-0.md item 3.2, §17.6 position
* (b)). Sizes the global cell array from the memory budget actually observed
* at boot -- STADIUM_MEMORY_PERCENT of kmalloc_get_stats().free_bytes at the
* point of the call, rounded down to whole STADIUM_CELL_BYTES cells -- rather
@@ -205,7 +205,7 @@ StadiumCell *stadium_cells(void);
uint8_t *stadium_header_bitmap(void);
/*
* StadiumBehaviour - the closed code-field enumeration (FABRIC.md §13, §18.3).
* StadiumBehaviour - the closed code-field enumeration (FABRIC-0.md §13, §18.3).
* The engine dispatches on this tag and never asks a patron what kind it is
* -- §3's entire point. Two patrons may share a tag: a VM's tag is COOL, the
* same tag a word carries (§18.3). Mapped from §17.1's patron table:
@@ -241,7 +241,7 @@ typedef enum {
void stadium_dispatch(size_t cell_index, StadiumBehaviour behaviour);
/*
* stadium_density - Heat / mass for the patron header at cell_index (FABRIC.md
* stadium_density - Heat / mass for the patron header at cell_index (FABRIC-0.md
* §19.2, §19.3). Read, not computed by a scheduler: both operands already
* live in the header, so this is a division on demand, not maintained
* bookkeeping. Result stays valid Q48.16, since heat is already Q48.16 and
@@ -276,7 +276,7 @@ uint64_t stadium_density(size_t cell_index);
#define STADIUM_HERA_CELL_INDEX ((size_t)0)
/*
* stadium_birth_hera - Admits Hera as a real resident of cell 0 (FABRIC.md
* stadium_birth_hera - Admits Hera as a real resident of cell 0 (FABRIC-0.md
* item 3.6's invariant, actually enforced -- item 4.1 found that nothing had
* ever called this until a word patron was about to become the first-ever
* occupant of cell 0 by accident via the free list). Candidate: identity 0,
@@ -300,7 +300,7 @@ int stadium_birth_hera(void);
/*
* stadium_reservoir_pull - Transfers up to `amount` (Q48.16) out of vm_id's
* reservoir (FABRIC.md §17.7's reservoir mechanism). Clamped to what the
* reservoir (FABRIC-0.md §17.7's reservoir mechanism). Clamped to what the
* reservoir actually holds -- never goes negative, never invents heat.
* Returns the amount actually pulled, which may be less than requested (or
* 0, e.g. a drained reservoir or an unknown vm_id). Callers that go on to
@@ -345,7 +345,7 @@ uint64_t stadium_reservoir_peek(VMUuid vm_id);
* stadium_quota_slot_for_vm - Read-only: vm_id's quota slot index (0 to
* stadium_max_vm_count()-1), for callers outside stadium.c that need to key
* their own per-VM state the same way stadium.c's internal arrays already
* do (FABRIC.md §25.5 item 4.2 -- stadium_words.c's word_id -> cell_index
* do (FABRIC-0.md §25.5 item 4.2 -- stadium_words.c's word_id -> cell_index
* map needs this to stop colliding across VMs; word_id is scoped per-VM,
* not globally unique, so a single shared map aliases different VMs' words
* onto each other's Stadium cells and reservoirs).
@@ -357,7 +357,7 @@ int stadium_quota_slot_for_vm(VMUuid vm_id);
/*
* stadium_resident_sum - Read-only: sum of heat across every cell currently
* resident AND owned by vm_id's own quota (FABRIC.md §25.5 item 4.2 --
* resident AND owned by vm_id's own quota (FABRIC-0.md §25.5 item 4.2 --
* boot diagnostics need this filtered per-VM once a second VM holds a
* quota; summing every resident cell regardless of owner, as the pre-4.2
* diagnostic did, mixes two VMs' conservation totals together).
@@ -369,7 +369,7 @@ int stadium_quota_slot_for_vm(VMUuid vm_id);
uint64_t stadium_resident_sum(VMUuid vm_id);
/*
* stadium_evict - Reap the patron header at cell_index (FABRIC.md §17.2:
* stadium_evict - Reap the patron header at cell_index (FABRIC-0.md §17.2:
* "reap means leaves the floor, not destroyed"). Dispatches its behaviour
* (§18.3), clears its item-3.1 discriminator bit, zeroes its header, and
* (item 3.7) returns the freed cell to the free list of whichever VM's
@@ -377,7 +377,7 @@ uint64_t stadium_resident_sum(VMUuid vm_id);
* record, not passed by the caller.
*
* PANICS (does not return) if cell_index == STADIUM_HERA_CELL_INDEX and the
* cell is actually resident -- FABRIC.md §20.5 #3: Hera is pinned (§3), but
* cell is actually resident -- FABRIC-0.md §20.5 #3: Hera is pinned (§3), but
* pinning alone is a silent guarantee, and item 3.6 requires a hard
* assertion at the eviction site rather than relying on pin holding. This
* check runs BEFORE the pin/contains checks below, deliberately: if pin were
@@ -399,7 +399,7 @@ int stadium_evict(size_t cell_index);
/*
* StadiumVMQuota - per-VM ownership of a subset of the global cell array
* (FABRIC.md §22.3, item 3.7: "each VM holds its own free-list head index
* (FABRIC-0.md §22.3, item 3.7: "each VM holds its own free-list head index
* into the global array"). Linearly searched by vm_id -- a VMUuid (item 3.8)
* can't be used as a direct array index anyway. Was a small, compile-time-
* bounded table (linear scan "costs nothing" at the old default of 4);
@@ -415,7 +415,7 @@ int stadium_evict(size_t cell_index);
/*
* stadium_admit - Place a candidate patron header into the Stadium, scoped
* to vm_id's quota (FABRIC.md §19.3, §22.3, item 3.7).
* to vm_id's quota (FABRIC-0.md §19.3, §22.3, item 3.7).
*
* Pops vm_id's free-list head first (O(1)) if non-empty. Only if that VM's
* free list is exhausted does this fall back to eviction -- scoped to that
@@ -468,7 +468,7 @@ size_t stadium_admit(VMUuid vm_id, const StadiumPatronHeader *candidate);
/*
* stadium_grant_quota - One-time initial quota grant for a newly born VM
* (FABRIC.md item 4.1a). NOT item 1.3's recurring capacity-transfer
* (FABRIC-0.md item 4.1a). NOT item 1.3's recurring capacity-transfer
* arbitration -- that mechanism (density-gradient-driven, per capacity-tick)
* stays unbuilt and its "how much moves" question stays open. This is the
* narrower, one-time event: the same shape as Hera's own whole-pool grant at
@@ -496,7 +496,7 @@ size_t stadium_admit(VMUuid vm_id, const StadiumPatronHeader *candidate);
int stadium_grant_quota(VMUuid new_vm_id, VMUuid from_vm_id);
/*
* stadium_cell_heat_get - Read a resident cell's own heat (FABRIC.md item
* stadium_cell_heat_get - Read a resident cell's own heat (FABRIC-0.md item
* 4.2's fourth ruling). Requires cell_index to be resident AND owned by
* vm_id's quota -- returns 0 otherwise (out of range, not resident, or
* belongs to a different VM), same ambiguity-with-a-genuine-zero already
@@ -513,7 +513,7 @@ uint64_t stadium_cell_heat_get(VMUuid vm_id, size_t cell_index);
/*
* stadium_cell_heat_set - Write a resident cell's own heat, reconciling the
* reservoir delta atomically (FABRIC.md item 4.2's fourth ruling). Same
* reservoir delta atomically (FABRIC-0.md item 4.2's fourth ruling). Same
* ownership requirement as stadium_cell_heat_get(). If new_heat is higher
* than the cell's current heat, pulls the exact difference from vm_id's own
* reservoir first -- refuses (returns -1, no mutation) if the reservoir
include/starkernel/vm/stadium_blocks.h
+1 -1
View File
@@ -22,7 +22,7 @@
*/
/**
* stadium_blocks.h - Block patrons on the Stadium (FABRIC-3.md §B/§D,
* stadium_blocks.h - Block patrons on the Stadium (FABRIC-2.md §B/§D,
* MIGRATE punch-list item)
*
* The block-specific layer on top of the generic L0 engine (stadium.h), same
include/starkernel/vm/stadium_words.h
+8 -8
View File
@@ -22,7 +22,7 @@
*/
/**
* stadium_words.h - Word patrons on the Stadium (FABRIC.md §17.3/§17.7,
* stadium_words.h - Word patrons on the Stadium (FABRIC-0.md §17.3/§17.7,
* punch list item 4.1)
*
* The word-specific layer on top of the generic L0 engine (stadium.h).
@@ -57,7 +57,7 @@
* first; guarded internally as a no-op if already initialized. Nothing
* calls it twice today.
*
* item 4.2 (FABRIC.md §25.5): the map is keyed by quota slot, not just
* item 4.2 (FABRIC-0.md §25.5): the map is keyed by quota slot, not just
* word_id -- word_id is assigned per-VM (vm->next_word_id), not globally
* unique, so a single shared word_id -> cell_index map aliased different
* VMs' words onto each other's Stadium cells and reservoirs the moment a
@@ -67,7 +67,7 @@
void stadium_words_init(void);
/*
* stadium_word_dispatch - The per-dispatch entry point (FABRIC.md §17.7),
* stadium_word_dispatch - The per-dispatch entry point (FABRIC-0.md §17.7),
* called once per DictEntry touched at each of vm_core.c's three
* physics_execution_heat_increment() call sites -- deliberately mirroring
* that function's existing call pattern 1:1, including the entry != canon
@@ -80,7 +80,7 @@ void stadium_words_init(void);
* STADIUM_WORD_HEAT_QUANTUM from the reservoir into the cell -- clamped to
* what the reservoir actually holds AND to a floor of Q48_ONE / 3 that
* word-execution admission alone may never dip the reservoir below
* (FABRIC.md §25.7, Captain Bob's ruling 2026-08-06: this pull fires on
* (FABRIC-0.md §25.7, Captain Bob's ruling 2026-08-06: this pull fires on
* EVERY dispatch, not just first admission, and without a floor exhausts a
* VM's entire reservoir in ~32 dispatches, starving any application-level
* economy -- e.g. item 4.2's Hermes -- sharing the same VM's reservoir).
@@ -102,7 +102,7 @@ void stadium_words_init(void);
*
* @param vm_id Owning VM -- vm->stadium_vm_id at every call site.
* Scopes the word_id -> cell_index lookup to this
* VM's own quota slot (item 4.2, FABRIC.md §25.5) so
* VM's own quota slot (item 4.2, FABRIC-0.md §25.5) so
* two VMs' independently-numbered word_ids cannot
* alias onto each other's cells/reservoirs.
* @param word_id The dispatching DictEntry's stable word_id.
@@ -123,7 +123,7 @@ void stadium_word_dispatch(VMUuid vm_id, uint32_t word_id, uint64_t heartbeat_ti
* the map entry. No-op if word_id is not resident, out of range, or vm_id
* holds no Stadium quota.
*
* @param vm_id Owning VM -- vm->stadium_vm_id (item 4.2, FABRIC.md §25.5:
* @param vm_id Owning VM -- vm->stadium_vm_id (item 4.2, FABRIC-0.md §25.5:
* scopes the lookup to this VM's own word_slots, same
* reason stadium_word_dispatch() takes it).
* @param word_id The DictEntry's word_id, about to be recycled.
@@ -136,7 +136,7 @@ void stadium_word_forget(VMUuid vm_id, uint32_t word_id);
* own word_slots map) -- NOT messages/channels/other application residents,
* which stadium_resident_sum() (stadium.h, item 4.2) mixes in alongside
* everything else a VM owns. Exists so a VM's own application-level
* conservation check (e.g. Hermes's HERMES-K, FABRIC.md §25.7, Captain
* conservation check (e.g. Hermes's HERMES-K, FABRIC-0.md §25.7, Captain
* Bob's ruling 2026-08-06) can add this as an explicit term instead of
* silently omitting word-execution heat it has no other way to see.
*
@@ -168,7 +168,7 @@ void stadium_words_stats(VMUuid vm_id, uint64_t *promotions, uint64_t *evictions
* Σ(resident heat) + reservoir against Q48_ONE as a conservation check --
* not required by the acceptance text, but the mechanism proves nothing if
* this silently doesn't hold. The heat sum is scoped to vm_id's own quota
* (stadium_resident_sum(), item 4.2, FABRIC.md §25.5) so two VMs' checks
* (stadium_resident_sum(), item 4.2, FABRIC-0.md §25.5) so two VMs' checks
* close independently instead of mixing both VMs' resident heat together.
*
* @param vm_id The VM whose reservoir to read (vm_uuid_hera() today).