Claude
c36bd99e1e
proof/FINDINGS.md's Isabelle/HOL word-source sweep (§4) flagged five real defects; this fixes all five and records resolution in that doc: - EXECUTE (system_words.c): cast a popped cell straight to a DictEntry* and called through it with only a null check. Now validates via a new shared vm_dict_entry_ok(), promoted out of starforth_words.c's ENTROPY@/ENTROPY! guard (dictionary_management.c) so EXECUTE gets the same live-entry check. - ? and DUMP (format_words.c): dereferenced the popped cell as a raw host pointer, bypassing vm_addr_ok entirely (out-of-VM-bounds read). Both now go through VM_ADDR/vm_addr_ok/vm_load_cell/vm_ptr like every other memory word (@, `,`, editor_words.c). - TYPE (io_words.c): bounds check computed addr+count in signed 64-bit arithmetic, which can overflow and bypass the check on large operands. Replaced with vm_addr_ok(), which is written to avoid that overflow. - DECIMAL/HEX/OCTAL (format_words.c): wrote only the BASE memory cell, never vm->base, the host-mirror field number-output words actually read via current_base() -- so these words silently affected number parsing but never printing. Now call the existing vm_set_base() (previously only used at boot init), which updates both. vm_get_base/vm_set_base promoted to public declarations in include/vm.h. - ALIGN vs ALLOT/,/C,/2, (dictionary_words.c): disagreed on dictionary growth ceiling (2MB vs 5MB). Investigated which was correct rather than blindly widening: vm_get_block_addr() maps block N to vm->memory + N*BLOCK_SIZE across the full 5MB arena, and USER_BLOCKS_START (block 2048) lines up exactly with DICTIONARY_MEMORY_SIZE -- so ALLOT/,/C,/2, letting `here` grow past 2MB could silently corrupt live block/user data sharing that memory. Tightened ALLOT/,/C,/2, to DICTIONARY_MEMORY_SIZE to match ALIGN. Verified: hosted (amd64) and kernel (amd64, __STARKERNEL__) both build clean with -Wall -Werror; hosted POST suite 1012/1012 passing (0 regressions); manually exercised EXECUTE, ?/DUMP, TYPE, HEX/DECIMAL/OCTAL, and large-ALLOT rejection in the REPL. 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.