Robert Allan JamesandClaude Sonnet 5
cabb0e8bd4
Punch list §25 item 0.6 complete. Ruling applied (AskUserQuestion, this session): DTB is confirmed unreachable on this system's aarch64 firmware too (qemu-efi-aarch64 2025.11-3ubuntu7, same finding as riscv64's item 0.3), so GICD/GICC base addresses and the timer PPI are named QEMU-virt constants with a recorded caveat, not DTB-discovered as the item originally asked. Nothing here was recalled from memory. Base addresses (GICD 0x08000000, GICC 0x08010000) and the timer PPI (30, non-secure EL1 physical) were read out of QEMU 10.2.1's own internal devicetree via `qemu-system-aarch64 -machine virt,dumpdtb=...`, decoded with this tree's own fdt.c reader rather than a new tool -- correct for this exact QEMU version, not assumed stable across others. Bonus finding from the same dump: PPI 26 for the EL2 hypervisor timer, which item 0.7 will need for its EL2 path. Register offsets within each block (GICD_CTLR, GICC_IAR, etc.) are GICv2 architectural constants, not board-specific, and were cross-checked against Linux's own arm-gic.h driver header rather than recalled either. Acceptance amended before implementing (§25.0 "when an item is genuinely wrong"): the original text required observing a delivered-and-acknowledged timer interrupt, which cannot happen within this item's own scope -- apic_timer_start() (item 0.7) is still the no-op stub, so nothing arms the timer. This is the same defect the earlier review's C2 fix already applied to items 0.2 and 0.5; it was missed here. Acceptance is now: GIC initialises without fault, the IAR/EOIR path is wired into aarch64_irq_handler() and ready, boots with no regression -- item 0.7's tick-advance is what proves delivery, exactly as 0.5 already defers to 0.7. EL-aware (B3, same discipline as items 0.4/0.5): apic_init() selects PPI 30 or 26 from aarch64_current_el(), decided once and cached, not re-derived per interrupt. aarch64_irq_handler() now does real work: reads GICC_IAR (the GICv2 acknowledgement step), dispatches to heartbeat_tick() when the INTID matches the timer PPI, and always completes with GICC_EOIR (INTID 1023 = spurious handled per the GICv2 spec, not as a special case of "unrecognised"). This mirrors exactly how riscv64's item 0.2 built full cause-dispatch logic before its timer was armed in 0.3. Investigated and resolved a real scare during verification: QEMU's `-d int` trace showed 1,728 "Taking exception 5 [IRQ]" events by the time boot reached the prompt, which looked exactly like an interrupt storm (hypothesis: EDK2 firmware leaves CNTP_CTL_EL0 enabled with a stale comparator, and enabling the GIC path exposes it before item 0.7 reprograms the timer). A direct one-shot probe inside aarch64_irq_handler() itself -- ground truth for whether this code path runs at all -- fired zero times across a clean, bounded boot. The trace events were almost certainly from EDK2 firmware's own internal timer usage during its own boot phase, before control passes to this kernel; the earlier conclusion was drawn from the external trace alone without checking that distinction, and the probe (not the trace) is what settled it. Probe code fully reverted; not part of the commit. Verified: builds clean, boots to ok> with no regression, dict_hash 0x3d4e1daf289da94f unchanged from the item 0.1-0.5 baseline, EL banner and IDT-installed lines still print in order, GIC init line confirms PPI 30 selected. Only aarch64-scoped files touched; amd64/riscv64 not rebuilt. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
src/
Hosted StarForth VM implementation (compiled by the root Makefile).
Bare-metal kernel sources live in src/starkernel/; FORTH word
implementations in src/word_source/; the test harness in
src/test_runner/; platform shims in src/platform/.
Entry point / interpreter core
main.c— CLI entry point, VM init, DoE mode dispatch.vm.c— interpreter loop, stacks, dictionary state (the central runtime file).vm_api.c— external VM API implementation.vm_bootstrap.c— VM bootstrap initialization.vm_debug.c— debugging utilities.vm_time.c— time-related VM operations.vm_internal.h— internal-only declarations shared across thevm_*.cfiles, not part of the publicinclude/vm_api.hsurface.repl.c— REPL read-eval-print loop.cli.c— CLI argument parsing.io.c— I/O operations.log.c— logging infrastructure.
Memory / dictionary / blocks
memory_management.c— dictionary allocator.dictionary_management.c— dictionary allocation and search.dictionary_heat_optimization.c— Loop #1 execution-heat tracking.word_registry.c— word registration system.block_subsystem.c— logical→physical block mapper.blkio_file.c,blkio_ram.c,blkio_factory.c— block I/O backends (file-backed, RAM-backed) and the factory that selects between them.stack_management.c— stack operations.
Physics-driven adaptive runtime (7 feedback loops)
physics_runtime.c— main physics coordinator.physics_hotwords_cache.c— Loop #1 hot-words caching.physics_metadata.c— per-word metadata tracking.physics_pipelining_metrics.c— Loop #4 word-transition prediction.physics_execution_hooks.c— execution instrumentation.rolling_window_of_truth.c— Loop #2 circular execution-history buffer.inference_engine.c— Loops #5/#6, statistical inference (window-width, decay-slope).ssm_jacquard.c— L8 Jacquard steady-state mode selector; consumescompudynamics.cfor tuning-word/config lookups.compudynamics.c— generic compudynamics module (cd_tuning_word(),cd_tuning_vm()); the score/UCB/reward/weight constants for the L8 adaptive table live here, not inssm_jacquard.c.heartbeat_export.c— heartbeat metrics export (CSV export function itself not yet implemented — seedocs/working/architecture/heartbeat_csv_export.md).
Math / measurement
math_portable.c— portable math functions.profiler.c— performance profiling.doe_metrics.c— Design of Experiments metrics (2^7 factorial).
Any .bak file alongside a .c file here (doe_metrics.c.bak,
inference_engine.c.bak, vm.c.bak) is a pre-edit backup left by a past
maintenance script (see scripts/remove_loop_conditionals.sh), not a
build input.