Robert Allan JamesandClaude Sonnet 5
4485c3893b
Addresses items #1 (partial) and #2 of docs/working/archive/session-logs/2026-07-24-punch-list.md. docs/lithosananke/hosted-acceptance-test/README.md: - riscv64 leg used riscv64-linux-gnu-gcc, which fails to build this tree (nanosleep visibility under -std=c99). Replaced with the working clang-18 --target=riscv64-linux-gnu --sysroot=/usr/riscv64-linux-gnu invocation, verified end-to-end. - All three arch sections referenced a -c "<script>" flag that has never existed in cli.c/main.c. Corrected to the working `echo "..." | starforth -s` pattern, verified on all three architectures. - Updated Prerequisites: qemu-user alone is sufficient (guest binaries are static; qemu-user-static provides static *emulators*, not required here). Source fixes (ported from the old pre-split monorepo's master, commit 4db9946a, where they were made but never carried over to this line): - src/math_portable.c: `-100LL << 16` is UB (shifting a negative value) under clang's -Wshift-negative-value; changed to `-(100LL << 16)`. - src/physics_pipelining_metrics.c: removed dead q48_mul_q48() (-Wunused-function under clang; GCC doesn't flag this by default). - src/word_source/editor_words.c: removed dead set_scr() (same reason). These three were required just to get the documented clang build to compile at all. The punch list's higher-severity item — a genuine SIGSEGV-causing register-reuse hazard in vm_pop_asm/vm_rpop_asm (include/vm_asm_opt_riscv64.h) — is intentionally NOT included here; it's a separate, more careful change and isn't required for this build to succeed (latent only under clang; this repo's kernel build uses GCC). Verified: all three hosted builds compile and run correctly (amd64 native, aarch64 via qemu-aarch64, riscv64 via qemu-riscv64), each printing "3 Goodbye!" for the piped `1 2 + . BYE` script. All three Makefile.starkernel builds (amd64/aarch64/riscv64) still compile cleanly with these shared vendored-source changes. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
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.