Robert Allan JamesandClaude Sonnet 5
72487e7fff
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>
include/
Public headers for the hosted StarForth VM (src/). Kernel-only headers
live under include/starkernel/.
Core VM
vm.h— theVMstruct and all core types (DictEntry,DictPhysics, stacks, dictionary state); the central header most other files include.vm_api.h— external VM API surface.vm_host.h,vm_debug.h,startup.h,version.h— host integration, debug utilities, startup sequencing, version string.cli.h,repl.h,io.h,log.h— CLI parsing, REPL loop, I/O, logging.word_registry.h— word registration system shared by everysrc/word_source/*.cfile.compudynamics.h— the generic compudynamics module: tuning-word/config lookups (cd_tuning_word(),cd_tuning_vm()) consumed byssm_jacquard.c.
Memory / blocks
memory_management.h,dictionary_management.h— dictionary allocator and search.block_subsystem.h,blkcfg.h,blkio.h,blkio_factory.h— logical→ physical block mapper and pluggable block I/O backends (file/RAM).platform_alloc.h,platform_lock.h,platform_time.h— platform abstraction shims (hosted vs. kernel allocation/locking/timing).
Physics-driven adaptive runtime (7 feedback loops)
physics_runtime.h— main physics coordinator.physics_hotwords_cache.h— Loop #1, execution-heat hot-words cache.physics_metadata.h— per-wordDictPhysicsmetadata tracking.physics_pipelining_metrics.h— Loop #4, word-transition prediction.physics_execution_hooks.h— execution instrumentation hook points.rolling_window_of_truth.h,rolling_window_knobs.h— Loop #2 circular execution-history buffer and its tuning knobs.inference_engine.h— Loops #5/#6, window-width and decay-slope statistical inference.dictionary_heat_optimization.h— Loop #1 heat counters.ssm_jacquard.h— L8 Jacquard steady-state mode selector.doe_metrics.h— Design of Experiments (2^7 factorial) metrics.profiler.h— performance profiling hooks.
Arithmetic / codegen
q48_16.h— Q48.16 deterministic fixed-point arithmetic (used instead of IEEE-754 float specifically to keep cross-architecture behavior bit-identical).math_portable.h— portable math helpers.arch_detect.h,starforth_config.h— architecture detection and the build-flag fallback-default layer (used when a.cfile is compiled by hand withoutmake).vm_asm_opt.h,vm_asm_opt_arm64.h,vm_asm_opt_riscv64.h,vm_inner_interp_asm.h,vm_inner_interp_arm64.h,vm_inner_interp_riscv64.h— per-architecture assembler-optimized inner interpreter (USE_ASM_OPT=1).
See include/starkernel/README.md for the bare-metal kernel headers.