Claude
d6895bdd15
proof/FINDINGS.md's Isabelle/HOL word-source sweep (§1) found the two defects severe enough to actively corrupt the live Tripod multi-VM fleet: file-scope C statics standing in for state that belongs on struct VM. - vocabulary_words.c (highest severity in the sweep): forth_vocab/ context_vocab/current_vocab, context_var_addr/current_var_addr, the ctx_fc/forth_fc first-char search index, and the `initialized` guard were all process-wide statics. Only the first VM to touch any vocabulary word ever ran setup; every VM after that silently shared VM #1's dictionary-chain pointers and reused VM #1's byte-offset addresses as if valid in its own vm->memory. One VM's VOCABULARY/ DEFINITIONS/FORTH silently changed where every other VM looked up and defined words. - control_words.c: cf_stack/cf_sp/cf_last_mode (IF/THEN/BEGIN/DO/CASE compile-time nesting) and the LEAVE/ENDOF patch-site bookkeeping (leave_addrs/leave_sp/leave_mark_*, endof_addrs/endof_sp/endof_mark_*) were also process-wide statics. Two VMs compiling colon definitions at overlapping times would corrupt each other's nesting state. Both moved onto struct VM, following the existing hold_addr/hold_pos precedent in include/vm.h ("lives in each VM's own memory... so child VMs never alias Hera's buffer"): - New VocabularyState struct (vm->vocab): chain heads, VM-cell addresses, first-char index, initialized flag. - New ControlFlowState struct (vm->cf): cf_stack/cf_sp/cf_last_mode plus the LEAVE/ENDOF patch-site stacks. cf_tag_t/cf_item_t/CF_STACK_MAX moved from control_words.c into include/vm.h since they're now part of the struct VM field's type. - Sentinel fields (-1/-999, meaning "empty") explicitly initialized in both vm_init_with_host() implementations (hosted src/vm_bootstrap.c and kernel src/starkernel/vm/vm_bootstrap.c) alongside the existing dsp/rsp = -1 initialization, since the preceding zero-init leaves them at 0 rather than their empty sentinel. Every word function in both files already took VM *vm, so no call sites outside these two files needed to change; cf_push_item/cf_pop_item/ cf_peek_item gained a VM* parameter to reach vm->cf. Verified: hosted (amd64) and kernel (amd64, __STARKERNEL__) both build clean with -Wall -Werror after a full clean rebuild (struct VM's layout changed size, and this Makefile has no header-dependency tracking, so a stale incremental build would have linked mismatched object layouts). Hosted POST suite 1012/1012 passing (0 regressions). Manually exercised VOCABULARY/DEFINITIONS/FORTH/ORDER, and IF/ELSE, DO/LOOP/LEAVE, BEGIN/WHILE/REPEAT, and CASE/OF/ENDOF/ENDCASE (including nested DO with I/J) in the REPL -- all correct and unchanged from pre-refactor behavior. Note: a pre-existing CASE/ENDCASE default-clause bug (the code after the last OF...ENDOF pair does not correctly become the "default" value once DROP runs) was found while testing this refactor and confirmed present on unmodified master too -- not touched here, out of scope for this pass. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014Qf6YcnHgaEtEygq3knx19
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.