FABRIC.md item 4.5d Finding 4: lidt()'s inline asm used a register-only
("r") constraint on the idtr pointer, never telling GCC the asm
dereferences the pointee. At -O2 this let the compiler treat the
256-entry idt[] population loop and idtr_desc's field writes as dead
stores and eliminate them entirely, loading IDTR from uninitialized
stack instead of the real table -- a #GP on the first APIC timer tick
that happened to land on garbage. Same bug class as the earlier
muldiv64 fix (b43e51a): an inline-asm constraint too weak for what the
asm actually touches, invisible at -O0, live at -O2.
Fixed by switching to a memory operand ("m"(*idtr_desc)), matching how
Linux's own load_idt() is written. aarch64/riscv64 checked for the same
pattern -- neither has it, both install their vector/trap tables
entirely in hand-written .S.
Verified: all three architectures boot clean to ok>, POST Failed: 0,
identical dict-hashes across all three under -O2, zero new warnings
vs an -O0 baseline (amd64 3040/3040, aarch64 3041/3041 serial,
riscv64 3037/3037). -O2/-U_FORTIFY_SOURCE landed permanently in
COMMON_CFLAGS.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Computed the loader's true runtime relocation delta to correctly correlate
fault addresses (the running image is starkernel_loader.efi, a relocated
PE, not the separately-linked starkernel_kernel.elf assumed at first).
Fault RIP decodes to log_message()'s entry -- coincidental, not causal,
since it's called on nearly every HADES dispatch during word registration.
Used QEMU's monitor for -d exec,int tracing. Late-start tracing (stop right
before the danger zone to keep trace size down) failed twice -- the window
between a detectable checkpoint and the crash is shorter than host-side
reaction latency. Fell back to full-boot tracing from -S (~2.7GB per
attempt, not committed). That trace shows an unremarkable, normal-looking
repeating three-block loop immediately before the fault, then "Servicing
hardware INT=0x20" (APIC_TIMER_VECTOR) with IDT already showing limit=0 at
that instant.
Ruled out a second illegitimate lidt call (only one call site exists
anywhere, one-time M4 boot setup; searched the trace for any later
execution of that address range and found none). Not yet established: the
actual corrupting write. Documented two remaining explanations (earlier
silent corruption vs. a genuine TCG artifact) and that pinpointing the
exact instruction needs GDB-level single-stepping, a bigger tooling step
than attempted this session.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Used QEMU-side instrumentation (-d int tracing, plus a working chardev-based
monitor -- the older bareword -monitor syntax silently fails on QEMU
10.2.1) as directed. The PM Timer "stall" was never a hang: it was a #DE
divide error cascading to a triple fault, which -no-reboot converts into a
silent clean QEMU exit -- indistinguishable from a hang without tracing,
and why arch_relax() (solving a hang that didn't exist) had no effect.
Root cause and fix documented in full (also see commit b43e51a).
With the fix, amd64 boot at -O2 now proceeds far past the original stall --
through capsule birth and into Hermes's word registration -- before hitting
a second, different fault (Finding 4): a direct #GP at IDT index 32
(APIC_TIMER_VECTOR), not yet root-caused. Same silent-triple-fault-exit
shape, so this was very likely bundled into "the hang" before tracing
distinguished the two separate bugs.
-O2 reverted again (uncommitted); muldiv64's fix is kept, real and
independently verified at unchanged -O0 on all three architectures.
Routine three-arch artifacts from this session's verification runs
included.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
FABRIC.md item 4.5d: root-caused the -O2 boot stall via QEMU '-d int'
tracing -- not a hang. It's a genuine divide-error (#DE) cascading through
a double fault into a triple fault, which -no-reboot converts into a
silent, clean QEMU exit (indistinguishable from a hang without tracing).
muldiv64()'s inline asm declared RDX as a plain output ("=d"(hi)), which
only tells GCC "I want RDX's value after this block" -- nothing told it
that mulq writes RDX *before* divq needs to read a *different* value (the
divisor c) out of it. Nothing stopped the register allocator from placing
c itself in RDX, which mulq then overwrites with the product's high 64
bits before divq ever reads it. Confirmed via the fault's register state:
RAX=0xe8d4a51000 (=1000*1e9 exactly, product fits in the low 64 bits, so
mulq's high-word output is 0) -- if c got allocated to RDX, divq then
divides by that corrupted 0, exactly matching #DE. Worked by accident at
-O0 (different, more conservative allocation); -O2 actually hit it.
A unsigned __int128 rewrite was tried first but needs libgcc's __udivti3
for the general 128-bit case, undefined in this freestanding build -- not
viable, same class of problem as the earlier putc/getc finding. Fixed
instead by declaring rdx a pure clobber rather than an output, the same
pattern the Linux kernel's own mul_u64_u64_div_u64 uses -- a clobber tells
GCC the register is used internally for the whole block and must never be
allocated to any operand, which is the guarantee the previous constraint
list was missing.
Also added a defensive end_tsc<start_tsc guard in the caller
(calibrate_tsc_with_pmtimer): this file's own comments already flag TSC
non-monotonicity as a real risk under TCG hypervisor mode, and an
underflowed delta_tsc would hit the same class of quotient-overflow #DE.
Not the bug that was found, but a real latent risk given what this
function's own documentation already says about the environment.
Verified: with -O2 (uncommitted, not yet reintroduced) this specific stall
is gone -- boot now proceeds far past this point, through capsule birth
and into Hermes's word registration, before hitting a second, different,
not-yet-root-caused fault (write-up follows). Three-arch acceptance boot
clean at unchanged -O0 (this fix doesn't change -O0 behavior, only
prevents UB that only manifested under optimization).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Follow-up probing narrowed Finding 3's behavior (inconsistent stall point
run-to-run: sometimes reaches iters=1000/delta=951 before stopping,
sometimes never gets past iters=0 even after a 400-second bounded wait) but
didn't pin the mechanism.
Tested the strongest available hypothesis: single-threaded TCG scheduling
starvation from an -O2-tightened spin loop, based on a real precedent --
calibrate_apic_timer() (apic.c) already calls arch_relax() every iteration
of its own spin-wait; calibrate_tsc_with_pmtimer() never had it. Added the
same call, matching that precedent exactly. Result: no change, same exact
stall point on a fresh 60-second bounded wait. Reverted.
Stopping here per this document's own §25.0 rule 5 -- root-causing further
needs either deeper TCG/QEMU internals knowledge or a different diagnostic
approach (host-side instrumentation) than another guess-and-check pass.
Makefile.starkernel and timer.c both back to committed -O0 state, confirmed
booting clean.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Finding 2 (putc/getc) fixed via shim.c backfill (previous commit). With
both Finding 1 (-U_FORTIFY_SOURCE) and Finding 2 fixed, amd64 links clean
at -O2 -- rigorously confirmed zero new warnings by diffing normalized
warning text between -O0 and -O2 builds (empty diff, ~3040 pre-existing
warnings in vendored code unchanged).
New Finding 3, not fixed, now blocking: amd64 boot stalls for minutes
inside calibrate_tsc_with_pmtimer() (timer.c:560-589) at -O2 -- a
mainline busy-wait loop reading the ACPI PM Timer via genuinely-volatile
inl() until 1000 real ticks elapse, bounded by a 5M-iteration timeout. A
one-shot diagnostic probe (reverted after capture) caught exactly one
checkpoint in 55 seconds of observation, then nothing -- not yet
root-caused whether this is the 5M-iteration timeout itself taking several
minutes to exhaust under -O2, or a genuine non-terminating condition.
Makefile.starkernel reverted to -O0 again; nothing broken landed in
history. Routine artifacts from this session's boot attempts included.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
FABRIC.md item 4.5d: GCC's -O2 folds putchar(c)/fputc(c,stdout) call sites
into putc(c,stdout), and getchar() into getc(stdin) -- neither symbol was
ever needed at -O0 because that fold pass is inactive there. Both are thin
wrappers reusing the existing putchar()/getchar() implementations exactly
(putc -> console_putc via putchar; getc -> the existing "no stdin in
kernel" -1/EOF stub via getchar), not new behavior.
Harmless at the current -O0 build (nothing calls these symbols directly at
-O0); this is prep for enabling optimization, verified against a clean
amd64 boot at unchanged -O0.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Attempting -O2 on amd64 surfaced two link-time findings, neither of which
was warnings the way 4.5d's own text anticipated:
1. Fixed: -O2 broke the link with __printf_chk/__memset_chk/__fread_chk/
__snprintf_chk undefined references across five vendored word_source
files. Root cause: those files unconditionally #include real glibc
headers (no __STARKERNEL__ guard), which under Ubuntu's default
_FORTIFY_SOURCE and -O2's __OPTIMIZE__ rewrite printf/etc. call sites to
_chk variants that shim.c's freestanding backfill never provided --
worked by accident at -O0 where the macros stay dormant. Fixed by adding
-U_FORTIFY_SOURCE, the standard fix for this exact situation in
freestanding/kernel builds.
2. Not fixed, blocking: with fortification disabled, plain putc/getc turned
up as genuinely undefined -- shim.c never backfilled those, only printf/
snprintf. -O0 doesn't need these symbols for reasons not fully
established (GCC's -O2 function-splitting visibly clones at least one
call site); this needs a real design decision (backfill shim.c vs. guard
the call sites out of __STARKERNEL__ builds), not a mechanical flag.
Makefile.starkernel reverted to the committed -O0 state (the -O2 change was
uncommitted, so a plain git restore -- nothing broken landed in history).
4.5d stays open pending Finding 2's resolution.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
-O2 over -O1/-Og: no optimization level has a verified track record here,
so pick the one that actually solves the motivating problem (4.4g's
fb_scroll_rows() stall needs real loop batching -Og doesn't reliably do)
and matches what both sibling Makefiles already default to.
No LTO yet: deliberately deferred, not rejected -- stacking a second risky
change (LTO, which CLAUDE.md already documents has broken this exact
codebase before) on top of a first-ever optimization pass would make any
4.5e failure ambiguous between two causes. Isolate them.
No -DNDEBUG: checked, not assumed. Zero runtime assert() calls exist
anywhere in the kernel build -- the two "assert(" hits found are a
_Static_assert pair (compile-time, ungated regardless) and a comment. The
freestanding assert.h shim is itself unconditional and ignores NDEBUG too.
Nothing for the flag to affect; copying it by habit would have been exactly
the cargo-culting this item warned against.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Marks 4.5b done with the verification record (three log dirs, all reaching
[Hera] ok> at unchanged -O0). Routine artifacts from this session's
three-arch runs: capsules/BLOCK_MAP.md, disk/artemis.img, DOE CSVs, QEMU
serial logs.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Written directly in ISR context on all three architectures
(heartbeat_tick(), heartbeat.c:163) and read directly by mainline
(heartbeat_ticks(), including the busy-wait at kernel_main.c:880) without
being volatile -- worked by accident at -O0, would be a real bug once the
kernel builds with optimization (item 4.5). Every other field in this
struct is mainline-only (heartbeat_service()'s deferred window/variance/
trust processing), so only this one field needed the qualifier.
Punch list item 4.5b complete.
Three-arch acceptance boot clean at unchanged -O0 (no behavior change
intended yet -- this is prep for enabling optimization, not the switch
itself).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Read every interrupt/exception vector handler on amd64, aarch64, and
riscv64, and every global or static variable each one touches directly or
through a called function, checked against its volatile declaration.
One confirmed hazard, matching what 4.5 already reported: TimeTrustState.
ticks is written in ISR context on all three architectures and read by
mainline (including a busy-wait) without being volatile.
Everything else checked out for one of three reasons, each verified by
reading the actual read/write sites rather than assumed: already correctly
volatile (g_sk_fault_word, g_spurious_count, g_plic_claim_count, the
heartbeat.c top/bottom-half handoff, i8042.c's ring buffer, virtio_input.c's
diagnostic counters); write-once during init then single-context for the
rest of boot, so never actually concurrent (each arch's timer-calibration
state, virtio_input.c's device-routing globals); or ISR-reachable only on
the fatal exception path, which halts the core permanently afterward so
there's no return to mainline to race with (console/framebuffer state).
Full findings recorded in FABRIC.md as 4.5a's inventory. No code changed --
investigation only, per the item's own scope.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Captain Bob 2026-08-11: no other item gets worked until 4.5a-4.5f (the
-O0-kernel fix) are done.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Captain Bob: the -O0-kernel finding (with its 4.5a-4.5f scoping) takes
priority over Artemis-last, so it moves up to 4.5 and Artemis moves down
to 4.6. Updated the three other places in this document that referenced
"the 4.5 Artemis boundary" by number to point at 4.6 instead, with a note
on the renumbering history for anyone reading those passages later.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Scoping only, per Captain Bob's explicit instruction -- nothing implemented.
Breaks the -O0-kernel finding into six sequential, individually-committable
items matching this document's §25.0 rule-1 discipline (same treatment 4.4
itself got before 4.4a onward):
4.6a full ISR-global volatile audit (investigation only), 4.6b fix whatever
4.6a finds (starting from the one already-confirmed TimeTrustState.ticks
hazard), 4.6c decide the actual -O flags and record the reasoning before
touching the Makefile, 4.6d apply them and get a clean three-arch build,
4.6e the real three-arch acceptance boot (a kernel that has only ever run
at -O0 has no track record at any other level), 4.6f retry 4.4g's reorder
now that optimization exists to make it viable.
Also flagged, not scoped: the ACL-RWT DoE campaign's overhead numbers were
all measured at -O0; nobody has asked whether they still hold once the
kernel builds differently.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Attempted 4.4g's console_fb_init() reorder twice this session: once bare,
once with the fb_scroll_rows() volatile fix applied. Both stalled boot
indefinitely (12,000+ lines logged, still running after 3 minutes vs. a
normal few-second boot) instead of completing. Root cause traced past the
scroll fix to Makefile.starkernel building the kernel at -O0 -- no
optimization flag has ever been configured there, verified against the
file's full git history (17 commits, only ever one unrelated host-tool -O2
line). Both the kernel's own vendored hosted Makefile and the standalone
StarForth repo's Makefile default to -O2 (up to -O3/-flto on faster
targets); Makefile.starkernel was written fresh for the bare-metal target
and never got that ladder.
Documented as new item 4.6: enabling optimization is not a safe drop-in
change on its own. Found one confirmed, isolated correctness hazard first --
TimeTrustState.ticks (timer.h:90) is written directly in ISR context on all
three architectures (heartbeat.c:163) and read directly by mainline
(heartbeat.c:200-202, including a busy-wait in kernel_main.c:880) without
being volatile, unlike every other ISR-shared global checked
(g_spurious_count, g_plic_claim_count, g_pending_counter/g_pending_valid/
g_adaptive_period_ns are all correctly volatile already). Reverted the
console_fb_init() reorder itself (uncommitted, so a plain git restore) --
4.4g stays open pending 4.6.
Both the reorder attempts' logs (stalled, never reached ok>) and this
session's routine three-arch artifacts (capsules/BLOCK_MAP.md, disk/
artemis.img, DOE CSV) are committed as audit trail per CLAUDE.md.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Found while investigating item 4.4g's boot stall (moving console_fb_init()
earlier caused a >3-minute hang scrolling the fleet-birth transcript). The
GOP framebuffer is mapped write-back RAM (vmm.c:350-363), not
cache-disabled MMIO with side effects, so there's no correctness reason for
the scroll/fill loops to force one un-batchable volatile access per pixel.
g_fb.base stays volatile for other call sites; this function now casts to a
plain pointer for its bulk copy only.
Confirmed this alone does not fix the 4.4g stall -- the kernel builds at
-O0 (no optimization flag anywhere in Makefile.starkernel), so nothing
here gets vectorized regardless of the qualifier. That's now documented as
its own item, FABRIC.md 4.6. Keeping this fix regardless: it's correct on
its own terms independent of 4.4g's outcome.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Three-arch acceptance boot (amd64/aarch64/riscv64) clean, all reaching
[Hera] ok>, plus amd64 screendump evidence for each item -- checking off
4.4c (console_fb_init wiring), 4.4d ([VMName] prefix reaching the
framebuffer), 4.4e (\r/\n fix), and 4.4f (glyph-flip fix, previous commit).
Screendump verification itself stays amd64-only pending future
aarch64/riscv64 screendump tooling; Captain Bob accepted that gap as
non-blocking for these checkboxes.
4.4g reframed from "anomaly, not root-caused" to a design decision: traced
the missing hundreds of lines of boot output to console_fb_init() running
after capsule_birth_mama() (which births the whole Tripod fleet and their
self-tests) rather than before it, so that output is serial-only by
construction -- not a scroll/CSI-parser bug. Left unchecked pending a call
on whether to reorder console_fb_init() earlier in boot.
Also commits routine artifacts from this session's three-arch runs:
capsules/BLOCK_MAP.md (regenerated manifest), disk/artemis.img (Artemis
writes on every boot), DOE CSVs, and the corresponding QEMU serial logs.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
font_8x16_data stores each glyph's 16 scanline bytes bottom-to-top, not
top-to-bottom -- confirmed by hand-decoding 'A' (0x41) and 'T' (0x54): both
only produce their correct letterform when the row order is reversed.
fb_draw_glyph() mapped glyph row 0 to the cell's top pixel row, which was
wrong for this table. Flip the row-to-pixel mapping instead of touching the
4096-byte font data; every glyph now renders right-side up.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
fb_draw_orientation_test() was a one-time diagnostic for 4.3.1 (raw GOP
framebuffer wiring), already [x] done. With 4.4c's vt100 console now live,
the corner blocks just obscure real console output in every screendump.
Function definition left in framebuffer.c/framebuffer.h for future reuse;
only the boot-time call site is removed.
Also commits routine log/manifest housekeeping: capsules/BLOCK_MAP.md
(regenerated by mkcapsule on each build), the amd64 probe logs from before
today's outage, and the screendump logs + evidence screenshot from this
session's 4.4c/4.4d/4.4e verification.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
4.4c/4.4d's fix was screendump-verified on amd64: the framebuffer console
mechanism works and [VMName] genuinely reaches the screen for the first
time. Verifying that screendump surfaced three more issues, each given its
own item per SS25.0 rule 3 rather than folded in silently:
- 4.4e (fixed this session, see prior commit): console_putc() forwarded raw
'\n' to vt100_putc() without '\r', corrupting line-start columns.
- 4.4f (open, not root-caused): character glyphs render vertically flipped.
- 4.4g (open, not root-caused): most of the framebuffer stays blank despite
hundreds of lines of boot output that should have scrolled through it.
Confirmed via a second screendump after the 4.4e fix that 4.4f and 4.4g are
both independent of the \r/\n bug -- unchanged before and after.
Added evidence/ as a new tracked location for durable proof screenshots,
distinct from the existing gitignored fb/ (disposable local eyeballing,
per the 2026-08-07 decision to stop tracking it). Linked from the relevant
4.4c/4.4d/4.4e/4.4f/4.4g entries.
4.4c and 4.4d remain unchecked -- their Done-when criteria require a
three-arch screendump match against the serial log, not yet attempted on
aarch64/riscv64.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
console_putc() mirrored raw '\n' to vt100_putc() while raw_putc() (serial
path) auto-injects '\r' before '\n'. vt100_putc()'s '\n' handler only
increments the row, never resets the column, so every line after the first
started at whatever column the previous line ended on instead of column 0 --
confirmed by screendump as diagonal text scatter across the framebuffer.
Latent since this code was written; invisible until 4.4c turned the
framebuffer console on for the first time.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
console_fb_init() (which calls vt100_init()) was never called anywhere in the
boot sequence -- only raw fb_init() ran, so vt100_putc() no-op'd on every
call and no console output (REPL, POST, boot logs) ever reached the
framebuffer, only the corner orientation-test blocks. Replace the raw
fb_init() call in kernel_main_deep() with console_fb_init() so the
framebuffer console actually comes up (4.4c).
emit_prefix() also wrote the "[VMName] " bracket text via raw_putc() only
(serial), never vt100_putc(), so the bracketed VM name never reached the
screen even once the framebuffer console was live. Mirror console_putc()'s
existing serial/framebuffer split there too (4.4d).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Found while screendump-verifying the prefix fix (now 4.4d): kernel_main.c
deliberately never calls console_fb_init(), so vt100_init() never runs and
vt100_putc() no-ops on every call -- no console output has ever reached the
framebuffer, only fb_init()'s own corner self-test blocks. ROADMAP.md's
obsolete M8 section claimed this path was already live; that was never
actually screendump-verified.
Records Captain Bob's stated end goal (2026-08-11): framebuffer console and
serial console must be functional identically. 4.4c wires that in.
Only uncommitted items were renumbered; 4.4/4.4a/4.4b keep their IDs.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Found while scoping color application (now 4.4d): console.c's emit_prefix()
writes [VMName] directly via raw_putc(), serial-only -- it never calls
vt100_putc(), so the bracketed VM name has never actually reached the
framebuffer despite 4.4a's serial-verified "regression: clean" note. Given
its own item (4.4c) per §25.0 rule 3 rather than folded in silently.
Only uncommitted items (old 4.4c-4.4n, none yet [x]) were renumbered;
4.4/4.4a/4.4b keep their IDs since they're already committed. Also fixed one
stale reference in §27.8's narrative that still pointed at the old
CANVAS-geometry item by its pre-breakdown ID (4.4b -> 4.4k).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Punch list §25 item 4.4b complete.
Investigation only, no code. draw_cursor_glyph() (vt100.c:125) already
draws through g_vt.fg/g_vt.bg via fb_draw_glyph(), and apply_sgr() already
parses true 24-bit-color SGR (ESC[38;2;R;G;Bm) -- color reaches the screen
today independent of which font renders the glyph. 4.4c can proceed without
waiting on 4.4d/4.4e.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Punch list §25 item 4.4a complete.
Removed the manually-built <Name>)ok>/zuse)ok> prompt suffix from
sk_repl_step()/sk_repl_run() -- console.c's console_putc() already emits a
"[VMName] " prefix at line-start, so the old code was double-printing the
name for non-Hera VMs ("[Hermes] Hermes)ok> "). Now prints only "ok> " and
lets the existing prefix supply the bracket. emergency_console/zuse_session
security semantics unchanged, display-only. Verified: all three
architectures boot live to "[Hera] ok>" (logs/20260811-073408 amd64,
logs/20260811-073448 aarch64, logs/20260811-073542 riscv64).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Punch list §25 item 4.4 complete.
Design-only, no code. Format [VM name] ok>; ok> reuses existing
FB_ANSI_PALETTE[14] bright cyan (0x55FFFF); [VM name] gets a fresh literal
orange (0xFFA500), since no orange exists in the ANSI palette. Verified: no
implementation, just literal values checked against the existing codebase
constants and written into FABRIC.md for 4.4a/4.4c to consume.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Expands the single 4.4 REPL item into a granular punch list matching the
4.3.5/4.3.6-series style: prompt format+color (4.4-4.4c), VT100 ANSI/SGR
engine retargeted onto TrueType (4.4d-4.4f), CANVAS geometry (4.4g-4.4k),
scrollback+toggle (4.4l-4.4m), and the blocked (user) prompt segment (4.4n).
Corrects the font_8x16/TTF handoff boundary: the embedded VT100 path renders
everything through and including POST (which runs after the capsule/VM
bootstrap, per CLAUDE.md), not just pre-bootstrap M1-M6 messages as
originally scoped -- TTF-TEXT takes over only once POST completes.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
FABRIC.md: renumber Artemis-last boundary 4.4 -> 4.5, add new 4.4 REPL item
(console visual design scoped this session -- CANVAS is one shared region
above the REPL strip, 640x480 scroll box centered within it, stroke font,
ANSI color, VM-identity + ACL-identity prompt segments, ~1000-line
scrollback), linked to repl-mockup.png.
ROADMAP.md: mark M8 section OBSOLETE -- replaced by FABRIC.md 4.4, kept for
history only.
ttf_words.c: TTF-TEXT's y argument now Cartesian (origin bottom-left of the
physical framebuffer, y increasing upward) instead of raw framebuffer
coordinates, translated once via fb_height() - y. Verified via amd64
screendump (logs/20260811-070418/), text renders right-side-up with
increasing y moving up the screen.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Not implementation -- documentation-only. M8 is tracked outside Stadium
(FABRIC.md §27.5), so this scoping lives in docs/lithosananke/ROADMAP.md
rather than as new FABRIC.md 4.3.x items.
Read the code before scoping, not assumed: the REPL already works
interactively over serial (sk_repl_run(), repl.c) with working
backspace/echo, and its on-screen text already renders via the existing
VT100 console (vt100_init()/font_8x16.c) independent of both the stroke
font and TrueType work -- neither was ever a REPL-strip prerequisite.
What's actually missing: sk_readline()'s console_getc() is
serial-UART-only, never touches KEY-EVENT (4.3.5f); KEY/?TERMINAL
(io_words.c) are dead stubs (KEY calls a getchar() hardcoded to EOF in
shim.c, ?TERMINAL always returns false).
Resolved design decisions: minimal US-QWERTY scancode->ASCII layout
with shift-state tracking (KEY-EVENT carries no modifier state today);
merge keyboard into console_getc()'s poll with serial staying a
co-equal source, not replaced (the entire acceptance/DoE harness
injects over the serial socket -- breaking that breaks make qemu,
DOE_INJECT, and every screendump technique used throughout 4.3.x); wire
KEY/?TERMINAL to the same merged source for FORTH-79 compliance;
CANVAS viewport sizing last, since it's presentation not input
plumbing. Extended scancodes, autorepeat-as-character-repeat, arrow-key
history explicitly out of scope for the "minimal" bar.
FABRIC.md's existing "not yet scoped" notes (4.3.5f's landing-point
note, 4.3.7f's closing note) updated to point here rather than
duplicating the design content.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Punch list §25 item 4.3.7f complete. No code changes -- ttf.c/ttf.h/
ttf_words.c unchanged since 4.3.7e; this is verification only, same
posture as 4.3.6g.
Three-arch acceptance boot clean (standard make ARCH=<arch> clean qemu,
run in order, one at a time): all three reached [Hera] ok> cleanly,
logs committed under logs/20260810-231553(amd64)/231640(aarch64)/
231739(riscv64).
One screendump per architecture, identical TTF-TEXT command sequence
(S" Hi 4.3.7e!" 200 200 28 16777215 TTF-TEXT) via monitor-socket +
serial-injection, same pattern as 4.3.7c/e. All three show the string
rendered legibly with correct mixed-case/digit/punctuation glyphs and
identical monospace spacing.
TrueType rendering (4.3.7-4.3.7f) is now complete, adjunct to the
stroke font per §27.7 decision #4. Stopping here before scoping REPL
wiring (M8), per this item's own posture matching 4.3.6g.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Punch list §25 item 4.3.7e complete. New src/word_source/ttf_words.c
registers TTF-TEXT ( c-addr u x y size color -- ): lazily loads the v1
default font capsule + raster cache once, decodes UTF-8 (C
reimplementation mirroring capsules/fabric.4th's DECODE-UTF8 exactly),
looks up each glyph's cached bitmap, blits via fb_put_pixel, advances
the pen by the glyph's real hmtx advance width scaled to pixels.
Necessary plumbing: ttf_parse() now also locates hhea/hmtx, and
ttf_glyph_advance_width() reads a glyph's advance width -- required for
this item's own "proportional spacing correct" acceptance clause, no
advance-width data existed anywhere else in the parser. Verified in
tools/ttftest.c: A/a/0/space all read advance_width=600, correctly
uniform since JetBrainsMono-Regular.ttf is monospace.
(x,y) is raster pixel space (top-left origin, Y-down), deliberately not
the stroke font TEXT's Cartesian Y-up convention -- recorded explicitly
in ttf_words.h, not conflated.
Verified live, amd64, screendump: injected
S" Hi 4.3.7e!" 200 200 28 16777215 TTF-TEXT over a serial socket after
boot, no error, captured a screendump showing the string rendered
legibly with correct mixed-case/digit/punctuation glyphs and even
spacing. TTF-TEXT is this item's permanent deliverable, not a
throwaway probe. Compile-checked clean on all three architectures.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Punch list §25 item 4.3.7d complete. ttf_raster_cache_get() looks up
(font, codepoint, size_px) in a caller-owned fixed slot array, evicting
round-robin once full, rasterizing into a slot on a miss.
Verified live in tools/ttftest.c: an identical (font, 'A', 24px) call
made twice returns was_hit=0 then was_hit=1, and the slot's own hits
counter reads exactly 1 afterward -- checked programmatically. A
different-codepoint call misses again, proving the key actually
discriminates. Wall-clock timing (miss 0.040ms vs hit 0.001ms) is
printed as informational corroboration only, not the load-bearing
check.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Punch list §25 item 4.3.7c complete. ttf_rasterize_glyph() flattens
quadratic-Bezier contours (fixed 8-segment subdivision, matching
CIRCLE/ELLIPSE's fixed-segment precedent) and fills them into a
caller-supplied bitmap via even-odd scanline fill, no AA. A local
signed Q48.16 multiply (q48_smul) handles negative outline coordinates,
since the shared q48_mul/q48_div are unsigned-only.
Verified two ways: tools/ttftest.c's ASCII-art dump + structural checks
for 'A'/'.'/'a', all recognizable and passing; and a live amd64
screendump via a throwaway TTF-PROBE word (loaded the font capsule,
rasterized 'A', blit via fb_put_pixel), showing a clearly legible 'A'
on the CANVAS -- probe reverted immediately after capture, only the
permanent ttf.c/ttf.h rasterizer remains. Compile-checked clean on all
three architectures (hal/*.c wildcard); this item's own acceptance is
the amd64 screendump, not a three-arch boot (that's 4.3.7f).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
mkcapsule.c already ingests arbitrary non-.4th files as raw byte blobs
(validate_forth_blocks only applies to .4th filenames), so no hex/base64
text-encoding or tool changes are needed -- corrects the design premise
in FABRIC.md's 4.3.7b item text (see the FABRIC.md correction note this
commit carries). ttf_load_from_capsule() resolves the font capsule by
name, validates its content hash, and points ttf_font_t at the capsule
arena bytes directly, zero-copy.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
ttf_glyph_outline() decodes simple-glyph flag/coordinate runs and
recursively resolves composite components into a caller-supplied point/
contour-end buffer, in Q48.16. Composite scale/rotation/skew transforms
are rejected with TTF_ERR_UNSUPPORTED rather than mis-rendered, since the
shared q48_mul/q48_div are unsigned-only; translation-only composites
(the only kind the v1 glyph repertoire uses) apply cleanly via q48_add.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Freestanding C module resolving a Unicode codepoint (cmap format 4) to a
glyph index and its outline header (contour count, bounding box), verified
against an independent from-scratch Python reference reader via
tools/ttftest.c. Not yet wired into the boot path or capsule system.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Punch list §25 item 4.3.6g complete. Fixed the cross-arch bug found
while first attempting this checkpoint: aarch64 and riscv64 both boot
an 800x600 ramfb device (confirmed empirically for both, not assumed),
against amd64's 1280x800 GOP framebuffer -- the original verification
grid's Y coordinates ran off the top of the smaller screens. Rebuilt
the grid to fit 800x600, safe on amd64's larger screen too.
All 113 glyphs confirmed legible and correctly positioned on all three
architectures, one screendump each, from the identical FORTH command
sequence. No code changes -- font.4th/fabric.4th are unchanged since
4.3.6f; this is verification only.
Three-arch acceptance boot clean, Stadium conservation unchanged.
Stroke font (4.3.6-4.3.6g) is now complete. Per this item's own
posture, stopping here before scoping REPL wiring (M8) -- 4.3.7
(TrueType, adjunct) is the scoped-but-not-started next work.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Not implementation -- documentation-only. Reviewing the 4.3.6 stroke
font's full 113-glyph repertoire (mid-4.3.6g checkpoint) prompted the
decision to add TrueType rendering as an adjunct path rather than
continue refining strokes alone. Stroke font stays; nothing reverted.
Adds 4.3.7-4.3.7f (parser core, outline extraction, font data
ingestion, rasterization, glyph cache, TTF-TEXT entry point,
three-arch checkpoint) plus §27.7 documenting four resolved design
decisions: C implementation layer, Q48.16 fixed-point (not float --
confirmed real via Makefile.starkernel grep that GAP-B2's hypothesized
FP-register-clobber-on-interrupt risk is real on all three
architectures, not just hypothetical), capsule-block-encoded font
data, and TrueType as the primary text path once built.
4.3.6g itself stays open -- paused mid-verification when a real
cross-arch framebuffer-resolution difference (aarch64 800x600 ramfb
vs amd64 1280x800 GOP) surfaced; not yet re-run with corrected
coordinates.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Punch list §25 item 4.3.6f complete. TEXT ( c-addr u x y size color -- )
walks a UTF-8 byte string, decoding one codepoint at a time via
DECODE-UTF8, drawing each via DRAW-GLYPH, and accumulating the cursor
X by the glyph's em-advance scaled to pixels. Uses 2>R/2R> to stash
the DECODE-UTF8 remainder off the data stack while DRAW-GLYPH's args
are pushed.
Defined in font.4th, not fabric.4th, so its compiled DRAW-GLYPH call
binds to the real definition, not fabric.4th's 4.3.6b placeholder --
same early-binding constraint as DISPATCH-GLYPH itself.
Verified live: a string mixing ASCII, Latin-1 (degree sign), and
General Punctuation (em dash) renders correctly in one TEXT call with
proportional spacing, no overlap.
Three-arch acceptance boot clean, Stadium conservation unchanged.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Punch list §25 item 4.3.6e complete. Optional capsule, not wired into
the boot chain, overriding DISPATCH-UPPER's codepoint 65 (G-A) with a
marked alternate glyph while every other letter falls through to
font.4th's originals unchanged.
Corrects §27.6.5: redefining the DISPATCH-* bucket word alone is not
enough, since DISPATCH-GLYPH/DRAW-GLYPH are themselves compiled early
against font.4th's own dispatch words (same early-binding finding as
4.3.6c, one layer up). Verified both ways: the partial override (bucket
word only) left DRAW-GLYPH still drawing the original glyph; redefining
DISPATCH-GLYPH/DRAW-GLYPH too made the override take effect.
Three-arch acceptance boot clean, Stadium conservation unchanged.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Punch list §25 item 4.3.6d complete. Both capsules now EXEC via
Hera's Mama IDENTITY capsule (init.4th block 2049), loading on every
normal boot instead of manual serial injection. Verified by booting
with zero injected commands and calling DRAW-GLYPH directly.
Three-arch acceptance boot clean, Stadium conservation unchanged.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Punch list §25 item 4.3.6c complete. Digits, upper/lowercase, ASCII
punctuation, Latin-1 Supplement, and General Punctuation, each a
stroke-drawing word in the 4.3.6 em-square convention.
Corrected mid-build: the first pass used G-LINE only, missing that
CIRCLE/ARC/ELLIPSE already existed (4.3.3b). Reworked all round shapes
to use them via new em-square-aware wrappers (G-CIRCLE/G-ARC/G-ELLIPSE/
EM-R, fabric.4th 5000-5002), bounded to quarter/half/three-quarter/
full sweeps to avoid unbounded per-glyph angle tuning. font.4th also
redefines DISPATCH-GLYPH/DRAW-GLYPH themselves, not just the six
DISPATCH-* bucket words, since fabric.4th's originals were compiled
early against the 4.3.6b placeholders (CASE early-binding, §27.6.5).
Three-arch acceptance boot clean, Stadium conservation unchanged.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Punch list §25 item 4.3.6b complete.
capsules/fabric.4th blocks 4921-4924: DISPATCH-GLYPH routing via
WITHIN to six bucket words (DISPATCH-DIGIT/-UPPER/-LOWER/
-ASCII-PUNCT/-LATIN1/-GENPUNCT), TOFU fallback, DRAW-GLYPH. Buckets
carry one placeholder stroke word each (G-TEST-*), not the real
113-glyph set -- that's item 4.3.6c's scope, deliberately deferred.
Also: merged two lines in block 4920 (DECODE-UTF8) to fit mkcapsule's
real 64-char x 16-line block limit once a trailing blank separator
line is counted against it -- mechanical reformat, re-verified via a
DECODE-UTF8 regression check (65/176/8212, unchanged).
Verified live on amd64: one representative codepoint per bucket plus
one out-of-range codepoint, all seven DRAW-GLYPH results matched
expected exactly (400/600/450/250/550/700/500-TOFU). Three-arch
acceptance boot clean, Stadium conservation unaffected.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Punch list §25 item 4.3.6a complete.
capsules/fabric.4th blocks 4918-4920: UTF8-SEQ-LEN/UTF8-CONT? verbatim
from §27.6.2, DECODE-UTF8 dispatching to four UTF8-ASSEMBLE-N helpers
(1/2/3/4-byte). Factored into helpers after the single-word draft hit
mkcapsule's real 64-char x 16-line block limit. Verified live on
amd64: a 6-byte test buffer (ASCII + deg-sign + em-dash) decoded to
65/176/8212 across three sequential calls, exact match against
hand-computed codepoints, buffer fully consumed. Three-arch acceptance
boot clean, Stadium conservation unaffected.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Punch list §25 item 4.3.6 complete.
capsules/fabric.4th blocks 4916-4917: EM-UNITS, GOX/GOY/GSIZE/GCOLOR,
EM-X/EM-Y/G-LINE per §27.6.1, scaling/translating em-square strokes
into CART-PLOT screen coordinates via */. Verified live on amd64 via
a temporary probe (built, run once, reverted): two G-LINE test shapes
at GSIZE 100 and GSIZE 50, one leg each exercising a negative em-y
value chosen to hit */'s truncate-toward-zero behaviour, not a
multiple of EM-UNITS. Screendump pixel-bbox extraction matched
hand-calculated raster coordinates exactly on both shapes. Three-arch
acceptance boot clean, Stadium conservation unaffected
(resident_sum=43691 reservoir=21845 sum=65536 on all three).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
CaptainBob.png: untracked repo-root image, added per Captain Bob's
direction.
logs/20260808-002843/riscv64/: a riscv64 boot log from ~00:28, minutes
after the committed 4.3.5 acceptance boots. Not cited anywhere in
FABRIC.md. It ends in the scause=0xF store-page-fault at 0x0c201000
that item 4.3.5a later formally traced to riscv64 having no
software-controlled paging -- an earlier, informal hit of the same
bug, predating 4.3.5a's own cited diagnostic logs (10:19am+).
Committed for the audit record per this repo's "logs are committed
artifacts" convention, superseded by but not duplicating 4.3.5a's
own logs.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Expands the previously sparse \xc2\xa727.6 to match the derivation depth of
\xc2\xa727.3/\xc2\xa727.5.1/\xc2\xa727.5.2 -- worked line items, not just prose scoping.
Every primitive used (*/, WITHIN, CASE/OF/ENDOF, CREATE, EXECUTE, ',
LSHIFT/RSHIFT/AND/OR) was confirmed against src/word_source/*.c before
being used in a formula; no $/0x hex literal syntax exists in this tree,
so all formulas use decimal only.
Concrete design landed, in order derived:
- EM-UNITS 1000, standard Type1/OpenType em-square proportions; EM-X/
EM-Y/G-LINE scale-and-translate into CART-PLOT space via */ (noting
*/'s "avoid overflow" rationale is vestigial at this VM's 64-bit
cell_t width -- not a bug, just an observation)
- UTF-8 decoder: full bit-level 1/2/3/4-byte assembly formulas. Found
mid-derivation that the 3-byte path is v1-required, not future-i18n-
only -- smart quotes/dashes/ellipsis are Unicode General Punctuation
(U+2000-206F), NOT Latin-1 Supplement despite the original framing
lumping them together
- Dispatch: bucketed CASE/OF/ENDOF chains (DISPATCH-DIGIT/-UPPER/-LOWER/
-ASCII-PUNCT/-LATIN1/-GENPUNCT) routed by WITHIN range checks, chosen
over a flat 256-entry xt-table despite the table composing more
cleanly with override -- explicit tradeoff, not an oversight
- Glyph-word contract ( -- em-advance ), TOFU placeholder for misses,
~8-10 block budget estimate for dispatch alone
- Character list corrected and finalized: 113 glyphs (95 ASCII + 11
Latin-1 Supplement + 7 General Punctuation), itemized
- User font override: found CASE's early binding means redefining a
single glyph word does NOT retroactively change an already-compiled
DISPATCH-* caller (same binding behavior 4.3.3b found for CART-PLOT).
Resolved: override replaces a whole DISPATCH-* bucket word, not
individual glyphs -- explicit granularity tradeoff for keeping CASE
- TEXT entry point sketched at algorithm level
DECODE-UTF8's exact byte-consumption stack mechanics and TEXT's loop
are deliberately left as algorithm-level spec, not final FORTH -- this
project's history (VARIABLE alignment, Q.TO-INT sign bug) shows exactly
this class of stack/precision bug surfaces only under live testing, not
design review; presenting untested stack-juggling code as settled would
be the "confidently wrong" mistake \xc2\xa725.0 rule 4 warns against.
Punch-list items 4.3.6-4.3.6g (\xc2\xa725.5) updated to match: concrete Done-
when criteria replacing several that were previously vague or TBD
(4.3.6b now names the six buckets; 4.3.6c names the 113-glyph list;
4.3.6e goes from "TBD" to a real, testable override-mechanism
criterion; 4.3.6f requires proportional-width verification). Still no
implementation -- scoping and derivation only, per \xc2\xa725.0 rule 2.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Punch list \xc2\xa725.5 additions (4.3.6-4.3.6g, unchecked) and new \xc2\xa727.6
rationale section, scoped per the 2026-08-07 sequencing note. Captures
requirements dictated this session: UTF-8-aware decoding, ASCII + Latin-1
typographic repertoire for v1, i18n-ready codepoint-indexed design, one
capsule per font-set (not per glyph), a default system font wired into
init.4th's boot chain as early as the capsule/VM bootstrap allows, with
user-font-override support -- additive to, not replacing, the existing
font_8x16.c VT100 console path. Flags two open items found while scoping
rather than deciding them unilaterally: an unused encoding field on
block_subsystem.h, and the open call on which capsule file eventually
houses the glyph data. No implementation yet -- scoping only, per \xc2\xa725.0
rule 2.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Background-session edits were being forced into an isolated git worktree,
defaulting to a branch off origin/master -- which has none of this
branch's FABRIC.md content -- conflicting with this repo's subversion-
style workflow (commit directly to the working branch, no side branches
without explicit permission). Sets worktree.bgIsolation: none so
background-session edits land directly in the shared checkout, consistent
with the existing CLAUDE.md policy.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Punch list §25 item 4.3.5f complete. Keyboard-input slice done.
New KEY-EVENT ( -- keycode pressed -1 | 0 ) converges amd64's i8042,
riscv64's and aarch64's virtio-keyboard-pci behind one shape. Translation
needed is minimal: XT Set-1 make codes and Linux input keycodes are
numerically identical across the standard 84-key block (a documented
historical property of the Linux input subsystem, confirmed against this
host's own headers and this tree's own prior live observations), so amd64
needs two lines, riscv64/aarch64 need none. Verified live with a real
keypress on all three architectures: identical "-1 1 30" output everywhere.
Three-arch acceptance boot clean.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Punch list §25 item 4.3.5e complete.
Extended virtio_input.c with a GIC-routed interrupt path alongside 4.3.5c's
PLIC one -- same capability walk, feature negotiation, eventq handling
(confirming §27.5.1's prediction that these items would share most of the
driver). aarch64_irq_handler() dispatches to virtio_input_isr() before its
EOIR write, same claim-dispatch-complete ordering riscv64 uses. Verified
with a real QEMU sendkey keypress: exact KEY_A/press match, two real
interrupts serviced, identical result to riscv64. Found (not fixed) an
unrelated pre-existing bug: BYE's cold-reset path faults on aarch64,
discovered incidentally since nobody had exercised it from a monitored
session before. Three-arch acceptance boot clean.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Punch list §25 item 4.3.5d complete.
New apic_spi_enable(intid) generalizes item 0.6's PPI-only sequence to one
explicit SPI (IPRIORITYR/ISENABLER/ITARGETSR, ICFGR read-checked not
written). Verified via a software-pended SPI (GICD_ISPENDR, no device
needed) through the existing generic IRQ dispatch, which needed no changes.
Found and fixed a real bug during verification: PSTATE.I is still set at
apic_init()'s point in boot, so the first self-test run correctly latched
but never took the interrupt. Self-test code reverted after capturing
evidence -- interrupts.c has zero net diff, only apic_spi_enable() remains,
unused until 4.3.5e. Three-arch acceptance boot clean.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Punch list §25 item 4.3.5c complete.
Amended from a nonexistent MMIO transport to PCI (matching the board's
actual virtio-blk-pci precedent). New virtio-input driver: eventq with
pre-posted buffers, PLIC source computed at runtime from PCI slot/pin
(derived live from this host's QEMU riscv64 DTB), mandatory ISR-status
read, PCI interrupt-disable-bit check. New VKBD-EVENT/VKBD-DEBUG FORTH
words. Verified with a real QEMU sendkey keypress: exact KEY_A/press
match, two real interrupts serviced, zero exceptions. Three-arch
acceptance boot clean.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Punch list §25 item 4.3.5b complete.
sie.SEIE enabled, PLIC threshold/claim/complete wired into the trap
handler. Verified with a UART-loopback synthetic interrupt (PLIC has no
software set-pending register, unlike GICv2): claim_count=1, last_irq=10,
IIR confirms genuine receive-data cause, byte matched exactly. Self-test
code run once for evidence then fully reverted, per Captain Bob's ruling;
only the permanent substrate remains, no source enabled by default.
Three-arch acceptance boot clean, zero exceptions.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Punch list §25 item 4.3.5a complete.
Firmware (EDK2 RISC-V) leaves Sv57 paging active at kernel entry with an
identity mapping that has at least one confirmed hole (PLIC threshold
register). Verified live before acting: satp.MODE/PPN and __kernel_start's
address confirmed identity mapping; switched to Bare mode (csrw satp, x0 +
sfence.vma) in arch_early_init(), ahead of pmm_init()/vmm_init().
Three-arch acceptance boot clean, zero exceptions; riscv64's PLIC_THRESHOLD
write now survives (PLIC driver code itself lands separately with 4.3.5b).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Live-probed GICD_ITARGETSR before starting 4.3.5d/e; survived cleanly,
unlike riscv64's PLIC (4.3.5a). Decoded QEMU's own virt DTB for the PCI
slot->SPI interrupt-map routing table and closed-form formula. Amended
4.3.5d's circular acceptance criterion to a synthetic GICD_ISPENDR probe
(mirrors 4.3.5b's fix for the same problem), and wrote the full 4.3.5e
virtio-input execution plan: device ID 0x1052, the real virtio_input_event
struct, the mandatory ISR-status read, and the pci_enable() interrupt-
disable-bit gap.
Log: logs/20260808-093228/aarch64/.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
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>
Three-arch acceptance run (amd64/aarch64/riscv64) after adding -device
ramfb to aarch64/riscv64, plus the interactive GOP-verification and cube
sessions on both.
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.
Three-arch acceptance run (amd64/aarch64/riscv64) plus the interactive
sessions used to test LINE/CIRCLE/ARC/ELLIPSE, the block-span test, and
verify the Q.TO-INT fix.
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.
Screenshots stay tracked in git, same as before -- just organized so
verification images are easy to find per architecture as Console work
progresses across all three ISAs. scripts/qemu_screenshot.sh (amd64-only)
now writes into fb/amd64/.
Three-arch acceptance run (amd64/aarch64/riscv64) plus the interactive
fabric.4th verification sessions used to test CART-PLOT and find the
VARIABLE alignment bug.
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.
Serial logs and DoE run CSVs from this session's acceptance-test boots
(the amd64 GOT-indirect-addressing fix and item 4.2's Hermes-native-
on-the-Stadium work) -- committed per the standing convention that
these are audit artifacts, not scratch output.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
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>
No shift primitive existed anywhere in the vendored VM word set. Adds
both as FORTH-83-extension words next to INVERT, guarded against stack
underflow and out-of-range shift counts (u >= 64).
Their absence was masking a real bug: capsules/hermes/init.4th's
CH-MINT-ID (item 4.2) calls LSHIFT to pack a 64-bit channel ID, which
was silently tripping the capsule loader's forward-reference retry
logic and splicing CH-REQUEST's body into CH-MINT-ID's definition.
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>
