Discovered live while implementing what was 4.3.5a (PLIC bring-up,
renumbered 4.3.5b): riscv64 never activates its own page table
(load_cr3() is a no-op outside __x86_64__, arch.c's Sv39/SATP setup is
an explicit stub), so firmware's own mapping -- which doesn't cover the
PLIC's MMIO window -- is what's live for the kernel's whole lifetime.
Confirmed via a live store-page-fault, not inferred. Per Captain Bob's
ruling: stop, scope as its own item, decide the fix (Bare mode vs. real
Sv39) in a future session rather than embedded in the PLIC item.
4.3.5b-4.3.5e renumbered accordingly (4.3.5f was 4.3.5e); no items were
executed under the old numbering, so this is free to do cleanly now.
Documentation only. PLIC driver code (plic.c/plic.h, interrupts.c/
apic.c wiring, Makefile.starkernel) is written and reviewed but stays
uncommitted -- it cannot be verified until 4.3.5a unblocks it, and
riscv64 currently hangs in the fatal exception handler with it applied.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Punch list §25 item 4.3.5 complete.
New ioapic.c/i8042.c drivers (MADT-derived I/O APIC base, no hardcoded
constants) plus a KBD-SCAN/KBD-DEBUG diagnostic word pair. Three real
bugs found and fixed en route, all blocking this item's own acceptance:
a fatal LAPIC spurious-vector crash (nothing had driven a real external
interrupt through the I/O APIC before), OVMF leaving the keyboard device
itself scanning-disabled (0xF4 fix), and isr.S's stub table only having
individually-numbered stubs through vector 32 -- everything above that,
including our IRQ1 vector 33, silently reported as vector 255 regardless
of which IDT slot actually fired. Verified live via QEMU sendkey against
KBD-SCAN: correct XT Set-1 make/break codes for two different keys.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Recorded per Captain Bob's direction so the order survives between
sessions. Neither glyph rendering nor REPL is scoped yet -- each gets
Done-when criteria at its own checkpoint per 25.0 rule 2.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Next after the 4.3.4 checkpoint. amd64 needs an I/O APIC (none exists;
legacy PIC is permanently masked), riscv64 needs a PLIC (external
interrupts were never enabled in Phase 0), aarch64 needs GIC SPI
routing (0.6 scoped PPI-only). Documentation only, no code.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Reversing the earlier decision to track fb/ in git (made when first
setting up the directory for item 4.3.2). Captain Bob: these are
disposable screenshots for eyeballing framebuffer output during Console
work, never meant to be committed. Removed from git tracking (git rm
--cached) and added to .gitignore; files that still exist locally are
untouched, deletions already made locally are left as-is.
Also fixes item 4.3.4's amd64-only blind spot found in the process:
aarch64/riscv64 had no framebuffer device at all (GOP: protocol not
found) -- the "all three architectures boot clean" checks run all session
were REPL/dict_hash parity, a different thing from GOP presence, and
conflating the two was an error. Added -device ramfb (EDK2's
firmware-only GOP framebuffer) to both architectures' qemu targets in
Makefile.starkernel. Both now report GOP: linear framebuffer found at
800x600; cube rendering verified correct on both (screenshots not
committed, per the untrack above -- verified visually this session).
Standard three-arch acceptance boot re-run afterward, all clean,
dict_hash identical and unchanged from before this fix.
Adds VERT/EDGE/CUBE to capsules/fabric.4th (blocks 4913-4915). VERT
( n -- x y z ) reads bits 0/1/2 of a corner index as the X/Y/Z sign
(+-CS from center), so all 8 cube corners come from one word. EDGE
resolves both corners via VERT and calls LINE; CUBE is 12 EDGE calls
(4 bottom, 4 top, 4 vertical).
First item in the 4.3.3.x sequence with no new bug found -- a small signal
that Q.TO-INT, the VARIABLE alignment fix, and the LINE-STUCK? cap were
the real gaps rather than something still lurking in LINE/PROJECT/CART-Y.
Verified live on amd64: a centered, half-size-100 cube renders correctly
-- front/back face squares, back face offset diagonally up-right by
exactly the 45-degree cavalier projection's depth term, all 12 edges
connecting at the right corners.
All three architectures boot clean to ok> with the DoE completing;
dict_hash identical across all three and unchanged from 4.3.3a/4.3.3b.
FABRIC.md item 4.3.4 marked done. This is the checkpoint -- 4.3.x
groundwork stops here for review per this item's own acceptance criterion.
Adds LINE (Bresenham in raster space, endpoints projected once each --
valid because the cavalier projection is linear), CIRCLE/ELLIPSE
(36-segment polygon approximation), and ARC (18 segments over a caller
radian range) to capsules/fabric.4th (blocks 4903-4912). TO-RASTER
factored out of CART-PLOT (same behavior) so LINE can reuse the
projection+flip for both endpoints.
Found mid-implementation: colon definitions cannot span block boundaries
in this capsule loader -- verified with a throwaway test capsule, the
continuation lands in a [CAPSULE][DEFER] path that never resolves. LINE's
body is split across LINE-SETUP/LINE-DONE?/LINE-STUCK?/LINE-STEP, each
self-contained within its block, rather than one long definition.
A fourth real bug, serious this time: CIRCLE's first live test rendered
only one quadrant, then hung the VM for several minutes on a follow-up
call. Root cause: q48_to_u64() (include/q48_16.h and
include/starkernel/q48_16.h, backing Q.TO-INT) did an unsigned logical
shift, corrupting any negative Q48.16 value into a huge garbage integer
instead of sign-extending -- inevitable once Q.SIN/Q.COS leave the first
quadrant. That garbage became a bogus LINE target with no bound on
LINE-STEP's Bresenham loop. Fixed q48_to_u64 to shift through a signed
int64_t intermediate (bit-identical for the non-negative case). Also added
LINE-STUCK? (LSTEPS vs FB-WIDTH+FB-HEIGHT, the true worst case for an
on-screen line) as a defense-in-depth cap against any future bad target.
Verified live on amd64 after both fixes: -65536 Q.TO-INT . now prints -1;
LINE/CIRCLE/ARC/ELLIPSE all complete without hanging or erroring, and a
combined screendump shows all four rendering correctly and distinctly.
All three architectures boot clean to ok> with the DoE completing;
dict_hash identical across all three and unchanged from 4.3.3a (expected
-- fabric.4th isn't loaded at boot, and the Q.TO-INT fix doesn't change
dictionary structure).
FABRIC.md item 4.3.3b marked done with full acceptance evidence.
Adds q48_reduce_angle() (range-reduce a signed Q48.16 angle into
[-PI_Q48, PI_Q48] via one integer division plus a bounded fix-up loop) and
q48_sin_approx/q48_cos_approx (Taylor series, terms n=3,5,7,9,11 for sin
and n=2,4,6,8,10 for cos, early exit below 10). Q.SIN/Q.COS registered as
FORTH words in q48_words.c, same pattern as Q.LOG/Q.EXP/Q.SQRT.
Found mid-implementation: this codebase has two independent Q48.16
implementations -- src/word_source/q48_16_words.c (hosted/vendored) and
src/starkernel/math/q48_16.c (kernel-only; the kernel build does not
compile the former at all). The hosted build linked fine after the first
pass; the kernel build failed with undefined references until the same
two functions were added to both .c files and both q48_16.h headers
(include/q48_16.h and include/starkernel/q48_16.h). Not fixed at the root
-- Q.LOG/Q.EXP/Q.SQRT already had this same four-file duplication,
unremarked until now -- just navigated correctly for this item.
Verified live on amd64 via serial injection: sin/cos at 0, +-pi/2, pi, and
3pi (range-reduction across multiple turns) all match expected values
within Taylor-series truncation error (<0.2%).
All three architectures boot clean to ok> with the DoE completing;
dict_hash identical across all three (0x291a660b05fa7b52).
FABRIC.md item 4.3.3a marked done with full acceptance evidence.
Adds Module 28 (framebuffer_words.c/.h): PLOT ( x y color -- ), FB-WIDTH,
FB-HEIGHT -- raw hardware-boundary C primitives, kernel-only, no-op on
hosted builds, same pattern as every other module.
Adds capsules/fabric.4th (blocks 4900-4902, mkcapsule --lint clean):
COS45/Z->DELTA/PROJECT/CART-Y/CART-PLOT -- the 45-degree cavalier
orthographic projection and Y-flip, in FORTH per the compose-in-FORTH-first
rule (this is policy, not hardware access).
Found and fixed a second real bug while live-testing CART-PLOT over the
serial socket: defining_word_variable() (defining_words.c) captured
vm->here as a VARIABLE's address with no alignment call first, while
vm_load_cell/vm_store_cell require 8-byte-aligned addresses. This capsule's
VARIABLE ZD landed misaligned (945) purely by chance of what preceded it;
other capsules' variables happened to land aligned by luck, not guarantee.
Real deviation from FORTH-83/ANS, which specifies VARIABLE reserves an
aligned cell. Fixed with vm_align(vm) before capturing addr -- ALIGN
already existed as a word but VARIABLE wasn't calling it.
Verified end-to-end on amd64 via manual serial injection + QEMU screendump:
plotted 4 marker points (origin, +100 X, +100 Y, +50 Z) and confirmed all
landed at hand-calculated raster coordinates, including the diagonal
up-right shift for the Z-axis point -- the projection math is correct, not
just non-crashing. fb/fabric-test-cart-plot.png. 4.3.1's corner diagnostic
still renders correctly in the same shot, confirming no regression.
All three architectures (amd64/aarch64/riscv64) boot clean to ok> with the
DoE completing; dict_hash identical across all three
(0xc7f9adf885e306d2), confirming parity is unaffected.
FABRIC.md item 4.3.3 marked done with full acceptance evidence.
Scoping discussion for 4.3.3 (Cartesian coordinate machinery) surfaced a
larger ask: a full geometry drawing wordset (circles, arcs, ellipses,
radian-based trig), which doesn't exist anywhere in this codebase yet.
Split per the one-task-per-checkbox rule rather than overloading 4.3.3:
- 4.3.3 stays scoped to single-point plumbing: PLOT/FB-WIDTH/FB-HEIGHT (C,
raw hardware boundary) plus PROJECT/CART-Y/CART-PLOT (FORTH, capsules/
fabric.4th, blocks 4900+), per compose-in-FORTH-first.
- 4.3.3a (new): Q.SIN/Q.COS in q48_16.c, Taylor series, same pattern as the
file's existing Q.LOG/Q.EXP/Q.SQRT.
- 4.3.3b (new): LINE/CIRCLE/ARC/ELLIPSE in FORTH, built on 4.3.3 + 4.3.3a.
Also settled: projection angle is true 45 degree cavalier (not 2:1
isometric); "1080p" is a sizing sanity check only, not a hardcoded
constraint (Q48.16's 48 integer bits comfortably cover it).
Adds fb_draw_orientation_test() (framebuffer.c/.h): fills the four raster
corners RED/GREEN/BLUE/YELLOW via fb_fill_rect. Wired into kernel_main.c
calling fb_init() directly -- console_fb_init()/vt100_init() removed from
the boot path, since vt100.c/console.c are superseded by the Console
drawing-fabric redesign (FABRIC.md ss27) and should not be exercised even
incidentally.
The diagnostic caught a real, pre-existing bug on its first run: framebuffer.c's
pack_pixel() had its FB_PIXEL_RGBX32/FB_PIXEL_BGRX32 branches swapped relative
to UEFI GOP's own byte-order naming convention, producing a clean R<->B channel
swap (G unaffected). Spatial placement was already correct -- no flip/rotation.
Fixed by swapping pack_pixel's two return bodies to match framebuffer.h's
already-correct doc comments; kernel_main.c's GOP-format switch needed no change.
Also item 4.3.2 -- QEMU screenshot capability. scripts/qemu_screenshot.sh
already existed (monitor socket + socat + HMP screendump), just unwired and
unused this session. Redirected its PNG output to a new top-level fb/
directory (tracked in git, not logs/, not a gitignored temp dir) and added a
python3+PIL fallback for PPM->PNG conversion since imagemagick isn't
installed here. Left as a standalone script for now, not wired into a
Makefile target.
FABRIC.md items 4.3.1 and 4.3.2 marked done with acceptance evidence.
Visual cue between 4.3.4 and 4.4 so it's clear at a glance where the
growing 4.3.x Console slice ends and 4.4 begins, without reusing the
document's --- convention (reserved for ## section breaks).
The prior commit bundled four separate tasks (test pattern, screenshot
capability, coordinate machinery, cube checkpoint) into a single numbered
list inside one checkbox, violating the punch list's own convention of one
task per box. Split into four checkboxes and updated §27 to match.
Documents the actual hardware-boundary state (framebuffer already wired via
console_fb_init, raw pixel primitives already exist), the missing QEMU
screenshot capability, and the coordinate-system decisions made in
discussion: bottom-left origin, Y-up, Z as depth-into-screen, fixed
orthographic projection as a placeholder (angle still open). Acceptance is
a cube on screen; fonts/scrolling/message-protocol are later 4.3.x items.
CONSOLE.md superseded as a rough prior draft, not edited further. Console
design now lives in FABRIC.md going forward. 4.3.1 is the first slice:
framebuffer sanity check, QEMU screenshot capability, Cartesian/Z coordinate
machinery, and a cube as the first real exercise of the projection math.
Migrates Hermes's message/channel lifecycle onto the Stadium's unified
heat/capacity economy: MSG-ALLOC/FREE-NODE and CH-ALLOC/FREE-NODE now
route entirely through stadium_admit()/stadium_evict(), replacing the
old local free-list + independent heat-field mechanism. Eight
kernel-only STADIUM-* FORTH primitives (ADMIT, EVICT, RES@, RES-PULL,
RES-PUSH, HEAT@, HEAT!, WORD-HEAT), VM.stadium_vm_id threaded through
all three vm_core.c dispatch sites (replacing item 4.1's hardcoded
vm_uuid_hera()), and the stadium_owner[idx] fix so evict-credit lands
in the VM that actually admitted a patron, not whoever owned cell 0.
This session's own contribution, on top of that pre-existing
implementation: found and fixed two bugs blocking the item's own K≡1.0
conservation self-check (HERMES-K was reading 0, not 65536):
- Q.SLOT admission-heat fix (capsules/hermes/init.4th): MSG-SEND/
CH-ACCEPT admitted with Q.1 (the entire fleet-wide "1.0" unit) per
item, a leftover from before the Stadium migration when each
message/channel had its own unconstrained heat field. Instantly
drained the shared, finite reservoir.
- Reservoir floor for word-execution admission (stadium_words.c):
stadium_word_dispatch() (item 4.1) pulls STADIUM_WORD_HEAT_QUANTUM on
every word dispatch, not just first admission -- exhausts a VM's
entire reservoir in ~32 dispatches, starving any application-level
economy sharing that VM's reservoir before it gets a chance to pull
anything. word_dispatch_pull() now clamps word-execution's own pulls
to leave a Q48_ONE/3 floor (same fair-share figure COMMON-CH's own
floor already uses); application-level pulls are unaffected.
- STADIUM-WORD-HEAT primitive + stadium_words_resident_heat(): the
floor deliberately leaves word-execution residents holding real
heat, invisible to HERMES-K's original formula (MSG+CH+reservoir,
no term for word patrons). Adding this term closes K to exactly
65536 on all three architectures.
Also rules on two open scope questions in FABRIC.md: MBR-ALLOC/
MBR-FREE-NODE stay off the Stadium (membership records have no heat
field, never did -- the acceptance bullet's inclusion of them was a
completeness gesture predating a check of the actual layout), and
records the effort number (12 implementation files, +759/-120 lines).
Verified: all three architectures boot clean, full self-test passes,
Stadium conservation closes exactly (resident_sum + reservoir =
Q48_ONE) at both the C/Stadium level and the FORTH-level HERMES-K
check.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
vm_find_word() and dict_find_word_heat_aware() reference the same extern
globals (sf_fc_list/sf_fc_count/sf_fc_cap) but GCC compiled cross-TU
references to them with GOT-indirect addressing (R_X86_64_REX_GOTPCRELX)
under -fPIC. This freestanding, statically-linked UEFI PE image has no
dynamic linker to populate a GOT, so those reads silently returned NULL
instead of the array's real address -- amd64-only, and exquisitely
sensitive to unrelated code-size changes since the choice between direct
and GOT-indirect addressing is a per-call-site GCC heuristic.
Fix: -fno-pic -fno-pie for amd64 only (ARCH_CFLAGS, overriding
COMMON_CFLAGS's -fPIC, which riscv64's -shared loader link still needs).
Also removes -DPLATFORM_TIME_NO_INLINE, a prior one-off workaround for
the identical bug applied to sf_monotonic_ns() specifically, now
redundant. Adds R_X86_64_PC32/R_X86_64_PLT32 handling to
elf_apply_relocations() as a robustness fix for the non-monolithic
split-build path (dead code for the current monolithic boot, where OVMF's
own PE loader relocates the image, not this loader).
Verified: all three architectures boot clean and pass the full item-4.2
Hermes self-test, including MSG-DELIVER-ALL, which previously triggered
the corruption on amd64 only. Write-up in FABRIC.md under item 4.2.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Punch list §25 item 4.2 acceptance amended (scoping only, no code).
Found while reading Hermes's actual implementation (capsules/hermes/init.4th):
MSG-COOL-ALL/CH-COOL-ALL mutate each live node's own heat field every
HERMES-TICK, and MSG-TOTAL-HEAT/CH-TOTAL-HEAT sum it -- none of the original
five primitives expose a resident cell's heat at all. Ruled: STADIUM-HEAT@
(read) and STADIUM-HEAT! (write, reconciling the reservoir delta atomically
in C -- same shape as stadium_word_dispatch()'s own cooling code, so
conservation is never left to FORTH to get right). Cooling cadence stays in
Hermes's own HERMES-TICK loop, not a new C-side per-tick sweep -- matches
HERMES.md's language constraint. Primitive surface is now seven, not five;
Done-when updated to match.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Punch list §25 item 4.1a complete.
New prerequisite item, found while scoping 4.2: no quota-granting mechanism
existed at all. Adds stadium_grant_quota(new_vm_id, from_vm_id) -- a
one-time initial grant at birth, distinct from item 1.3's still-unbuilt
recurring capacity-transfer arbitration. Splits the donor's free list evenly
by cell count, reassigns stadium_owner[] for every moved cell, and grants
the new VM a fresh Q48_ONE reservoir (not a split of the donor's -- per-VM
conservation, same pattern as Hera's own boot grant). Wired into every baby
VM's birth in capsule_birth.c.
Verified via a boot-time self-test in kernel_main.c using a synthetic
identity (not the real UUID pool, not a real capsule birth -- item 0.1's
Hera-alone pruning stays intact). All three architectures booted to ok> with
identical output: grant OK, Hera reservoir=0 (already fully committed to
resident words, correctly unchanged), test-vm reservoir=65536 (fresh
Q48_ONE). dict_hash identical across all three and unchanged from item 4.1's
baseline (0x3d4e1daf289da94f) -- confirms no dictionary word was added.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Punch list §25 new item inserted before 4.2 (scoping only, no code).
Found while scoping 4.2: no quota-granting mechanism exists at all --
quota_slot_for_vm() refuses every non-Hera vm_id by design, and both
stadium_admit()'s doc and item 3.2's DONE note defer per-VM free lists to
"when Hera assigns a VM its quota," which nothing builds. Distinguished from
item 1.3's still-open recurring capacity-transfer arbitration: this is
Hermes's one-time initial grant at birth, same shape as Hera's own
whole-pool grant at stadium_boot_init(), not an instance of the open
recurring loop. Ruled: reservoir is not split (Hermes gets her own fresh
Q48_ONE, per-VM conservation per stadium.c's own invariant comment); cell
count is an even split of Hera's current free list, touching no resident
(including pinned cell 0). 4.2 is marked blocked on this item.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Punch list §25 item 4.2 acceptance amended (scoping only, no code).
Found while scoping the C/FORTH primitive layer: all three
stadium_word_dispatch() call sites in vm_core.c hardcode vm_uuid_hera(),
already flagged inline as this item's job, but fixing it needs a running
VM* to know its own identity -- VMUuid exists only on VMRegistryEntry, never
on VM itself. Ruled: add a VMUuid field to VM under __STARKERNEL__ (Option
A), set once at birth from the same VMRegistryEntry.vm_id already assigned,
not threaded through the call chain (Option B). Done-when extended with a
Hermes-word-heat-lands-in-Hermes's-own-reservoir check.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Punch list §25 item 4.2 complete (scoping only, no code).
Two rulings taken before implementation starts: the stadium_owner[idx]
fix (§25.7) is explicitly folded into 4.2's scope rather than split out,
since a second VM with a quota is what makes the bug live; the C/FORTH
boundary is a small new kernel-only FORTH primitive layer
(STADIUM-ADMIT/EVICT/RES@/RES-PULL/RES-PUSH), registered like BIRTH/RUN/USE,
the only new C this item may add per HERMES.md's language constraint.
Surfaces two open questions for implementation time rather than resolving
them by assumption: the STADIUM_BEHAVIOUR_DELIVER/EXPIRE mapping for
messages/channels, and whether this dissolves HERMES.md's G8 deferral.
States Done-when acceptance, including the explicit effort-number report
§10 calls for.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Punch list §25 item 4.1 complete.
Replaces the round-robin hotwords cache with Stadium density-ranked
admission/eviction on the kernel side, via the §17.7 reservoir mechanism and a
kernel-side word_id -> cell_index map (no DictEntry change, dict_hash
untouched). Adds stadium_birth_hera() to close the cell-0 panic hazard,
STADIUM_WORD_HEAT_QUANTUM/STADIUM_WORD_COOL_RATE_Q48 Kconfig knobs (flagged
untuned), and a stadium_word_forget() FORGET coherence hook to close a
recycled-word_id aliasing gap.
Verified: all five hotwords_cache_* call sites in dictionary_management.c
bypassed under __STARKERNEL__; word dispatch feeds the Stadium at all three
vm_core.c physics_execution_heat_increment() sites; hosted make unaffected;
all three architectures booted to ok> with matching dict_hash
(0x3d4e1daf289da94f) and matching conservation stats (promotions=354
evictions=0, resident_sum=65536 reservoir=0 sum=65536).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Records two decisions and restates item 4.1's Done-when criteria now that
§17.7 is DECIDED: word identity maps to a Stadium cell via a kernel-side
word_id -> cell_index table in stadium.c, not a new DictEntry field, keeping
the shared vendored struct and dict_hash untouched; acceptance no longer
leans on the old cache's HotwordsStats (being retired kernel-side, not
extended) but on new Stadium-side counters, the hosted build staying
unaffected, and a three-arch boot with dict_hash matching the pre-4.1
baseline.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
3d73b8e described stadium_admit()'s O(N) scans as the typical cost, sourced
from item 3.5's commit note written before item 3.7 landed the per-VM free
lists. Reading stadium.c:312-381 directly: the free-list pop is the primary
path (O(1), no scan), and the fallback scan only triggers once a VM's own
floor is full, scoped to that VM's residents only, never the global array.
Option B is better justified than originally written, not just corrected.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Resolves the last open question: vm_physics_touch()'s O(n) proportional
fan-out (justified there only by rare fleet touches) isn't viable at word
dispatch frequency. Instead each VM's inner Stadium gets one reservoir
scalar; touch/cool/evict are all O(1) two-party transfers against it,
mirroring Hera's structural role at the fleet level rather than
peer-to-peer redistribution. Admission is the starter grant itself
(Option B): execution_heat stays fully inert in kernel builds, matching
the one-governor rule already committed, at the cost of running
stadium_admit()'s existing O(N) scan on every cold-word dispatch until
item 3.5's free list lands -- accepted debt, not a new gap. Corrects
abb1d92's invariant wording: residents sum to less than Q48_ONE, with
the reservoir holding the remainder.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
The Stadium cell's heat field (stadium.h:64, item 3.1) was already declared
Q48.16 conserved share of 1.0, citing §19.1, before this section was reopened.
L0 already has a real conservation mechanism (items 3.4/3.5 consume it); it
has just never been fed. execution_heat and Stadium heat are two different
fields with two different jobs -- item 4.1 feeds the second, not converts the
first. Resolves the promotion-threshold, dict_hash-baseline, parity, and
new-loop questions on that basis; states an explicit one-governor-per-build
rule mirroring §17.3. The per-dispatch transfer rule and its cost remain
open and still block item 4.1.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Captain Bob rejected the simple q48_from_u64() scale for converting
execution_heat into the Stadium's heat field, wanting real conservation
for word heat mirroring §19.1's fleet invariant. That conflicts with the
existing absolute promotion threshold (execution_heat > 50) and moves
dict_hash, both load-bearing. Paper only -- item 4.1 does not resume
until this section reads DECIDED.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Punch list §25 item 3.8 complete. Added after starting item 4.1
surfaced the need to thread a vm_id into stadium_admit()'s new quota
parameter; Captain Bob ruled UUID/GUID rather than keeping the
narrower uint32_t.
New VMUuid type (vm_uuid.h/vm_uuid.c): two uint64_t halves, RFC-4122-
shaped for logging. Not real randomness -- checked directly against
QEMU 10.2.1's actual CPU feature set: amd64 RDRAND and riscv64 Zkr are
both real, available features here; aarch64 has no RNG property on any
CPU model including "max" (verified exhaustively via QMP
query-cpu-model-expansion). Captain Bob ruled a uniform fallback
across all three ISAs rather than a per-architecture split.
Fallback is a deterministic PRNG (splitmix64) seeded from the Mama
capsule's content hash, pre-filling a 16-entry FIFO pool at boot and
refilling with another batch of the same stream when exhausted --
exactly the shape requested. Same capsule booted twice produces the
same id sequence, preserving the dict_hash reproducibility this
session has relied on throughout.
Hera keeps a fixed, reserved all-zero id, not drawn from the pool --
capsule_birth.c uses vm_id == 0 as a load-bearing sentinel in three
places (KILL protection x2, fleet heat-fanout parent-chain
terminator), found by reading before writing any code.
Two real sentinel-collision bugs caught before shipping, same class as
STADIUM_CONTAINS_NONE: vm_uuid_none() (all-ones, not all-zero) for
"not yet assigned"/"no VM" placeholders; confirmed item 3.7's quota
table already used an in_use boolean rather than a vm_id sentinel, so
no second collision was actually possible there -- the dead,
never-referenced STADIUM_QUOTA_SLOT_EMPTY macro was removed.
Blast radius larger than first scoped, flagged mid-work rather than
silently absorbed: capsule_vm_physics.c/.h (the fleet heat-transfer
layer item 2.1 modified earlier this session) has its own vm_id-keyed
node table and walks parent_vm_id chains through the same identity
space, so it needed the same change, plus its callers in
mama_forth_words.c and sk_vm_bootstrap.c.
One live FORTH word contract changed, by explicit ruling: CAPSULE-BIRTH
was ( capsule-id -- vm-id ), a single cell -- can't hold 128 bits.
Captain Bob picked pushing two cells ("there is doubles support in the
FORTH std word set anyway"): ( capsule-id -- vm-id-hi vm-id-lo ).
MAMA-VM-ID changed the same way: ( -- 0 0 ).
Verified: full (not standalone-file) kernel rebuild to catch cross-file
breakage given the size of this change -- it surfaced the
capsule_vm_physics.c blast radius a narrower check would have missed.
Three-architecture boot (amd64, aarch64, riscv64), all reaching ok>
with identical dict_hash=0x3d4e1daf289da94f matching the item-3.7
baseline.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Elevates §17.3 from LEANING to DECIDED, settled on paper before item
4.1's code per Captain Bob's request. The core claim (replace
round-robin eviction with Stadium density ranking) already argued for
itself in this section; what was missing was the hosted/kernel split
§25.5's "never two live heat mechanisms at once" implied but never
resolved.
Grounded in code, not policy: dictionary_management.c calls
hotwords_cache_lookup()/evict_*() unconditionally in the word-lookup
path (not gated by ENABLE_HOTWORDS_CACHE at the call sites), and that
file is vendored shared source required to work in both hosted and
kernel builds. The Stadium is kernel-only by construction of
everything built through item 3.7. ENABLE_HOTWORDS_CACHE already
defaults off in both Makefiles today (Kconfig.physics, verified
against both Makefiles directly).
Resolution: kernel builds retire the old cache's effect once item 4.1
lands (Stadium takes over, old call sites bypassed under
__STARKERNEL__ regardless of the Kconfig setting); hosted builds are
unchanged, no Stadium is built for them. Item 4.1 decides the exact
bypass mechanism, not invented here.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Punch list §25 item 3.7 complete. Added to §25.4 after starting item
4.1 surfaced it as an unbuilt prerequisite -- 3.6's earlier "Phase 3
core complete" claim is corrected in this same commit.
StadiumVMQuota table (size STADIUM_MAX_VM_COUNT, linearly searched by
vm_id -- capsule_birth.c's vm_id is monotonic and never reused, so it
cannot index a table directly, and a 4-entry scan costs nothing). New
per-cell stadium_owner byte array records which quota a cell belongs
to, needed so eviction returns a freed cell to the correct VM's list
and so eviction search stays scoped to the evicting VM's own residents
(quota isolation).
Free-list linkage reuses each cell's `link` field as a next-free
pointer while unresident -- link is documented only as generic "index
into the Stadium, not a pointer," so this is a repurposing, not a
header change. Does not answer the separate, still-open question of
which field carries a multi-cell patron's first continuation-cell
index; item 3.5's mass != 1 refusal stands exactly as it was.
Boot-time: every cell chained into one list in ascending index order,
granted whole to vm_id 0 (Hera), the only VM that exists. Ascending
order preserves item 3.6's "Hera is patron zero" invariant once real
birth-wiring lands.
stadium_admit()'s signature changed to take vm_id -- a change to code
shipped in item 3.5, amended there. Pops the calling VM's free-list
head first (O(1)); only falls back to a same-VM-scoped eviction search
if empty.
Caught a real bug before the boot run: the header zero-fill on
eviction (and the initial free-list build) both left contains == 0,
but 0 is Hera's valid index -- the same collision item 3.1's
STADIUM_CONTAINS_NONE fix addressed, recurring at a new site. Fixed by
explicitly setting contains = STADIUM_CONTAINS_NONE at both free-list
sites.
Explicitly out of scope, reported not invented: granting quota to any
VM other than Hera is capacity arbitration (item 1.3 left "how much
moves per transfer" open). stadium_owner is set once at boot and never
rewritten, so quota_slot_for_vm() refuses every vm_id != 0 permanently
until item 4.2 adds the grant path and owner-array writes.
Verified: three-architecture boot (amd64, aarch64, riscv64), all
reaching ok> with identical dict_hash=0x3d4e1daf289da94f matching the
item-3.6 baseline.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Punch list §25 item 3.6 complete. Phase 3 (§25.4) core is now done:
items 3.1-3.6 all closed.
stadium_evict() now panics via sk_hal_panic() if a resident cell 0
(Hera, patron zero by construction of §6's boot order) is ever
selected for eviction. Placement is deliberate: the check runs before
the pin/contains refusal checks, not after -- if it ran after, a
wrongly-cleared pin would let the ordinary refusal path quietly return
-1 instead of ever reaching the panic, defeating the point of a check
that's supposed to be independent of pin holding.
Per §20.5 #3's explicit wording, not implemented as a filter:
stadium_admit()'s least-dense search is unchanged, still relying on
the general pin skip from item 3.5. Adding a second filter there would
have done exactly what that section warns against ("filtering hides
the bug, asserting reports it").
The panic path is, and will remain, unexercised by the acceptance
mechanism: sk_hal_panic() halts the machine, and triggering it
deliberately is incompatible with the three-arch boot being this
project's sole acceptance test. Correctness rests on the placement
argument, not a test -- same honesty precedent as items 3.4 and 3.5's
other unexercised paths.
Verified: three-architecture boot (amd64, aarch64, riscv64), all
reaching ok> with identical dict_hash=0x3d4e1daf289da94f matching the
item-3.5 baseline.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Punch list §25 item 3.5 complete.
stadium_admit(candidate) places into an unused cell if one exists (no
comparison needed), otherwise finds the least-dense resident -- skipping
pinned and contains-gated patrons, which are never eviction candidates
-- and evicts it only if the candidate is strictly denser, per §19.3.
stadium_evict(cell_index) dispatches the departing patron's behaviour
before clearing its slot, per §17.2.
Caught a real bug before it ran: the first draft used contains == 0 to
mean "holds nothing," but cell index 0 is a valid index (Hera, item
3.6). Fixed with a proper sentinel, STADIUM_CONTAINS_NONE (UINT32_MAX).
A second-pass review found mass was not accounted for: both functions
handled exactly one cell regardless of the candidate's stated mass,
which leaks cells on eviction of any mass > 1 patron and breaks
capacity conservation. Fixed by refusing any candidate with mass != 1
-- multi-cell patrons need the per-VM free lists item 3.2 already
deferred (§22.3), not built here.
Documented, not fixed: the discriminator bitmap can't distinguish free
from continuation cells, so the free-cell scan reads continuation-cell
payload bytes under the header layout -- latent since nothing creates
continuation cells yet, and the mass != 1 refusal keeps it provably
latent. Superseded by the free list when it exists.
Unexercised at runtime: nothing calls either function yet (no real
patron kind is wired to the Stadium). No self-test added -- filling
~74,000+ cells to reach the eviction-on-full branch was judged
impractical, following item 2.2's own precedent for its unexercised
fleet-full path.
Verified: three-architecture boot (amd64, aarch64, riscv64), all
reaching ok> with identical dict_hash=0x3d4e1daf289da94f matching the
item-3.4 baseline.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Punch list §25 item 3.4 complete.
stadium_density(cell_index) reads a header's heat and mass and returns
heat / mass -- a division on demand from fields already stored in the
cell, matching §19.3's "read, not computed by a scheduler" literally.
Stays valid Q48.16 without a special fixed-point routine, since heat
is already Q48.16 and mass is a plain integer divisor.
mass == 0 and an out-of-range cell_index both return 0 rather than
dividing by zero -- an empty or never-admitted slot has no footprint
to be dense within.
Deliberately not built here, per the item's own wording: finding the
densest or least-dense resident (§19.3's admission/eviction
comparison) is item 3.5's scope, not this one's. Nothing calls
stadium_density() yet either.
Verified: three-architecture boot (amd64, aarch64, riscv64), all
reaching ok> with identical dict_hash=0x3d4e1daf289da94f matching the
item-3.3 baseline.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Punch list §25 item 3.3 complete.
StadiumBehaviour (stadium.h) enumerates exactly the four tags §18.3
already names -- MIGRATE, DELIVER, EXPIRE, COOL -- mapped from §17.1's
patron table: blocks->MIGRATE, messages->DELIVER, ACLs->EXPIRE, words
and VMs both->COOL. Nothing invented; the tag set and mapping were
already in the document.
stadium_dispatch(cell_index, behaviour) dispatches on the tag only,
never asks what kind of patron departed. Handlers are stubs -- the
real actions belong to subsystems not yet migrated onto the Stadium
(Phase 4). Nothing calls stadium_dispatch() yet; item 3.5 is its first
consumer.
The switch is exhaustive with no default case, making §13's "closed
enumeration, fixed at build time" a compiler-enforced property under
this project's -Wall -Werror rather than just prose. Verified live:
temporarily deleted the COOL case, rebuild failed with
error: enumeration value 'STADIUM_BEHAVIOUR_COOL' not handled in
switch [-Werror=switch], restored it, confirmed clean again.
The header's behaviour field stays uint8_t, not the enum type itself,
since C does not guarantee an enum's underlying type and that field's
offset is load-bearing for item 3.1's validated 64-byte layout.
Verified: three-architecture boot (amd64, aarch64, riscv64), all
reaching ok> with identical dict_hash=0x3d4e1daf289da94f matching the
item-3.2 baseline.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Punch list §25 item 3.2 complete.
stadium_boot_init() (src/starkernel/vm/stadium.c) sizes the global
cell array at boot from a real memory-budget query rather than a
hardcoded count: pmm_get_stats().free_bytes at the point of
allocation, times the new STADIUM_MEMORY_PERCENT Kconfig symbol
(default 1%), rounded down to whole 64-byte cells. Matches §17.6's
position (b) literally. Also allocates the header/continuation
discriminator bitmap item 3.1 declared but did not allocate. Both are
kmalloc'd and explicitly zero-filled (kmalloc does not zero).
Called from kernel_main.c immediately before sk_vm_bootstrap_parity(),
i.e. before any VM exists (§6). Failure is soft -- logs and continues,
does not halt boot -- matching the existing precedent one line below
it (VM bootstrap parity failure does the same).
Added a "Stadium: N cells (M KB)" boot console line at the allocation
site so the acceptance logs are evidence the array was actually
allocated, not just that the kernel still boots -- the same blind spot
item 3.1's uncompiled-header gap exposed.
Verified: three-architecture boot (amd64, aarch64, riscv64), all
reaching ok> with identical dict_hash=0x3d4e1daf289da94f matching the
item-3.1 baseline, and the Stadium boot line confirmed present in all
three serial logs (amd64: 74234 cells/4639 KB, aarch64: 161329
cells/10083 KB, riscv64: 76122 cells/4757 KB).
Not built here, reported per §25.0 rule 3: per-VM free lists (§22.3)
-- granted when Hera assigns quota, not this item's scope.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Punch list §25 item 3.1 re-closed after reopening.
Items 1.1 and 1.4's resolutions both explicitly named this item as
where their Kconfig symbols would be implemented, but 3.1's own stated
scope never mentioned them, so the first close missed both:
- STADIUM_CONTAINS_DEPTH_MAX (default 5) -- item 1.1's contains-chain
depth cap. No consumer yet; reap-gating enforcement is item 3.5.
- STADIUM_CAPACITY_TICK (default 1000) -- item 1.4's capacity
arbitration cadence in virtual ticks. No consumer yet; capacity
arbitration itself is not on the punch list.
Both added following STADIUM_MAX_VM_COUNT's exact pattern:
Kconfig.kernel entry, Makefile.starkernel kconfig_int +
VM_FEATURE_FLAG_VARS forwarding, starforth_config.h fallback default.
stadium.h now includes starforth_config.h and carries two more
C99-portable compile-time checks proving both symbols are defined and
sane, same discipline as the byte-count checks. Declaration only --
not inventing the consuming logic to close this out early.
Verified: three-architecture boot (amd64, aarch64, riscv64), all
reaching ok> with identical dict_hash=0x3d4e1daf289da94f, re-run after
the reopening.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Punch list §25.7 addition, not a punch list item.
Captain Bob flagged the existing "fleet heat leaks on every multi-VM
touch" entry (§20.2/§25.7) as worth a pinned reminder: it's currently
invisible because Tripod is pruned to Hera alone (item 0.1), so
others_total is always 0 and the leaky division path never executes.
It becomes reachable, and measurable, only once Phase 4 restores
Hermes/Artemis -- so a clean item-5.1 DoE re-run before that point
would be a false negative on VM-CONSERVED?, not evidence the
conservation law holds. Still reported-not-scheduled on purpose.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Punch list §25 item 3.1 complete.
Defines StadiumPatronHeader and StadiumContinuationCell in new
include/starkernel/vm/stadium.h, unioned as StadiumCell per §3's
closed two-valued union. src/starkernel/vm/stadium.c added to
Makefile.starkernel's LOADER_EXTRA_SRCS/KERNEL_EXTRA_SRCS so the
header's compile-time size checks are actually compiled, not merely
included by something that never builds.
Discriminator ruled an external side bitmap (Captain Bob), not a
header field -- amended into §3 and §23.3 before this code was
written. Item 3.1 declares the bitmap's purpose/indexing in a comment
only; allocating it is item 3.2's scope.
Both cell shapes counted for real at exactly 64 bytes with zero
compiler-inserted padding (three C99-portable negative-array-size
assertions -- no _Static_assert, this project targets C99). Header
matches §23.3's original 32+32 split unchanged, since the
discriminator moving outside the cell left nothing to compete for that
space. Continuation cell matches item 1.12's 4+60 figure unchanged for
the same reason.
Verified the size assertion is actually live: broke it to 63,
confirmed the build failed with the expected negative-array-size
error, restored it, confirmed a clean compile.
Verified: three-architecture boot (amd64, aarch64, riscv64), all
reaching ok> with identical dict_hash=0x3d4e1daf289da94f matching the
item-2.2 baseline. Confirmed stadium.o present in both obj/loader/vm
and obj/kernel/vm post-build on amd64, closing the gap the item-2.2 WIP
exposed (an uncompiled header proves nothing).
Left open, not fabricated: §23.4 #2 ("does a typical message fit in
one cell") is unanswerable today -- no message patron struct exists
anywhere in this tree yet.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Punch list §25.7 addition, not a punch list item.
Captain Bob flagged mid-item-3.1 that the physics-flavored vocabulary
(heat, mass, density, patron, Stadium) needs a glossary making explicit
these are named analogies, not physical claims -- and that the growing
set of Kconfig build knobs needs the same terminology discipline so
code, Kconfig help text, and this document don't drift apart. Captured
per §25.7's rule: not fixed, not assigned, becomes an item only if
Captain Bob says so.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Wires the birth-refusal check into capsule_birth_baby(): calls
vm_registry_live_count() (added in the prior WIP commit) between
capsule validation and vm_registry_alloc(), returning the new
CAPSULE_RUN_ERR_FLEET_FULL and logging via
capsule_parity_log_birth_failed() before any EMBRYO registry slot is
consumed.
Also fixes a gap in that WIP commit: STADIUM_MAX_VM_COUNT was only
ever defined via a Kconfig .config-driven -D flag, with no fallback
default the way every sibling knob in starforth_config.h has -- a
build with no .config present (this one) failed with the macro
undeclared. Added STARFORTH_CONFIG_STADIUM_MAX_VM_COUNT_DEFAULT (4,
matching Kconfig.kernel) following the existing HEARTBEAT_INFERENCE_FREQUENCY
pattern exactly.
All three architectures boot clean to ok> with dict_hash=0x3d4e1daf289da94f,
matching the item-0.10/2.1 baseline. FABRIC.md item 2.2 checked off.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Punch list §25 item 2.1 complete.
vm_physics_touch() no longer takes a wall-clock timestamp -- it reads
fleet_heartbeat_tick_count internally, which is execution-paced
(vm_runtime.c:143), not wall-clock. VMPhysics.last_active_ns ->
last_active_tick, VMFleetTouchSample.elapsed_us -> elapsed_ticks, and a
new explicit `touched` flag replaces the old `> 0` sentinel (tick 0 is
a legitimate value a first touch can land on, unlike wall-clock ns).
Verified: three-architecture boot (amd64 x2, aarch64, riscv64), all
reaching ok> with identical dict_hash=0x3d4e1daf289da94f matching the
item-0.10 baseline. No new compiler warnings in the touched files.
Honestly flagged, not fixed: with Tripod pruned to Hera alone (item
0.1), vm_physics_touch()'s fan-out has no other live VM to pull heat
from, so the fleet-heat-sum acceptance criterion is trivially satisfied
rather than genuinely stress-tested -- a real check needs Phase 4's
multi-VM fleet. fleet_transfer_slope_q48's seed (65536/3) was
calibrated for elapsed microseconds and has not been re-fit for elapsed
ticks; left as-is rather than guessed, deferred to item 5.1's DoE work.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Punch list §25 items 1.8, 1.9, 1.10, 1.12 complete.
1.8 -- block content hash is computed once, at the migration boundary,
as part of the MIGRATE code field; audit retention of the old hash is
an Artemis-layer question, out of scope for the Stadium (§5).
1.9 -- confirmed factually (not decided): vm_dict_resolve_in_bucket()
keeps both old and new definitions resident with newest-wins shadowing,
no GC on redefinition.
1.10 -- closed as no. Identity elision either reintroduces the
per-kind branch §18.3 forbids, or breaks lookups (name, LBN) that
words and blocks already depend on outside the Stadium. Stays a fixed,
always-present 8-byte field for every kind.
1.12 -- linked, not contiguous. Forced by §22.3's already-decided
disjoint per-VM free list, which gives no adjacency guarantee.
4-byte next-index, 60 usable bytes per continuation cell, 18
continuation cells for a 1024-byte block. Completes §23.3's sizing
table and unblocks item 3.1.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Punch list §25 item 1.7 complete.
Bounded rather than permanently prohibited, consistent with item 1.1's
treatment of containment depth. Default 2 matches §21's already-decided
two-level structure; enforced by explicit refusal at VM-birth time if a
birth would exceed the configured depth.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Punch list §25 item 1.6 complete.
Confirms §20.4's proposal as decided: mass = the quota Hera allocated,
not a fixed one-cell footprint. Already implied by §22's elasticity
mechanism and §24.3, and already assumed by items 1.2-1.5 -- this
closes the formal "proposal" flag to match.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Punch list §25 item 1.5 complete.
Bound defaults to 4 (Tripod's known topology), Kconfig-tunable,
explicitly a placeholder pending a later DoE campaign for an idealized
default. Fixed for the machine's lifetime once set at build. Corrects
the document's own "coldest-VM-reaped is consistent with §19.3" claim,
which doesn't survive §20.2's cold-start birth rule -- birth is
refused at the bound instead, and reaping stays Hera's deliberate act.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Punch list §25 item 1.4 complete.
Capacity-tick gets its own named constant, defaulted to 1000 virtual
ticks -- grounded in the existing HEARTBEAT_INFERENCE_FREQUENCY
precedent at capsule_vm_physics.c:434-441 rather than an invented
number, well past §12 Q5's order-of-magnitude minimum.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Punch list §25 item 1.3 complete.
Cadence (capacity-tick, a coarser multiple of the virtual tick) carries
the "sustained density" requirement; the decision itself is a pure
least-dense/densest comparison, no tuned threshold. Transfer amount per
event is reported as unresolved, not invented -- out of this item's scope.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Punch list §25 item 1.2 complete.
Floor = max(mass of pinned patrons, one message-sized cell); both terms
derived rather than a tuned constant, closing the zero-pinned-patrons
reachability deadlock the first term alone would leave open.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Punch list §25 item 1.1 complete.
Adds the ninth wire `contains` to §3, resolves §8's open exclusivity
question as containment with a gated reap rule, bounds chain depth at
5 (Kconfig-tunable), and notes the distinction from item 1.7's separate
VM-tree-recursion question.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
