Robert Allan JamesandClaude Opus 5.5
2aa338483a
Replaces the global g_vm_interpret_depth test at both execute_colon_word() checkpoints (kernel-Hermes drain, switch-signal take) with sk_vm_owns_outermost_frame(vm): the VM physically owns the stack (sk_vm_switch_current_vm() == vm), is at its own outermost vm_interpret() frame (new per-VM VM.interpret_depth), and is not compiling. Once VMs interleave on their own native stacks, a global depth count across all VMs no longer means "this VM owns this stack"; this is the invariant it was approximating. The global and the old function stay until Stage I. Acceptance, all three ISAs, foreground with the framebuffer visible, coupled disk images reset before each: zero UNKNOWN WORD, zero self-test failures, dict_hash identical across ISAs and unchanged from the pre-Stage-A boot, and the live WIREBIND mint -> attach -> USE -> 1 2 + . -> 3 relay with stadium_conserved(self)=true. Logs: 20260923-140120 (amd64), -140654 (aarch64), -141303 (riscv64). FABRIC-3.8.md also records Captain Bob's ruling that preemption comes from the compudynamics, not the timer: principle 5 is corrected and the design question is opened as SS3.11, to be ruled before Stage C. Co-Authored-By: Claude Opus 5.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.