Robert Allan JamesandClaude Sonnet 5
1b2f0677de
Punch list §25 item 3.1 re-closed after reopening. Items 1.1 and 1.4's resolutions both explicitly named this item as where their Kconfig symbols would be implemented, but 3.1's own stated scope never mentioned them, so the first close missed both: - STADIUM_CONTAINS_DEPTH_MAX (default 5) -- item 1.1's contains-chain depth cap. No consumer yet; reap-gating enforcement is item 3.5. - STADIUM_CAPACITY_TICK (default 1000) -- item 1.4's capacity arbitration cadence in virtual ticks. No consumer yet; capacity arbitration itself is not on the punch list. Both added following STADIUM_MAX_VM_COUNT's exact pattern: Kconfig.kernel entry, Makefile.starkernel kconfig_int + VM_FEATURE_FLAG_VARS forwarding, starforth_config.h fallback default. stadium.h now includes starforth_config.h and carries two more C99-portable compile-time checks proving both symbols are defined and sane, same discipline as the byte-count checks. Declaration only -- not inventing the consuming logic to close this out early. Verified: three-architecture boot (amd64, aarch64, riscv64), all reaching ok> with identical dict_hash=0x3d4e1daf289da94f, re-run after the reopening. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
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.