Robert Allan JamesandClaude Sonnet 5
43aa0a2a36
Punch list §25 item 0.7 complete. This is what finally makes items 0.5 and 0.6 provably work end to end. apic_timer_start(): writes CNTP_TVAL_EL0 (or CNTHP_TVAL_EL2 at EL2 -- aarch64_current_el(), same EL-aware discipline as 0.4-0.6) to s_timer_period_tsc, then CTL.ENABLE=1/IMASK=0, followed by an ISB. The ISB is not decorative: confirmed against Linux's own arch_timer_reg_write_cp15() (arch/arm64/include/asm/arch_timer.h) that only the *control* register write needs synchronising before the enable/mask state is guaranteed visible to the interrupt pipeline -- TVAL/CVAL writes do not carry the same requirement, which is why apic_timer_rearm() omits it. TVAL is architecturally 32-bit but MSR-to-system-register is always a 64-bit instruction form -- passing a uint32_t operand directly failed to build (-Wasm-operand-widths). Fixed by truncating to 32 bits ourselves then zero-extending back to 64 for the operand, which supplies explicit, provably-correct zeros in the RES0 upper field rather than depending on unverified hardware behaviour -- Linux's own driver never exercises this path (it always uses the 64-bit CVAL form instead), so there was no local source to confirm the alternative against. apic_timer_rearm() (new): re-writes TVAL only, no ISB needed. TVAL is relative to "now," not an absolute deadline like riscv64's SBI interface (item 0.3), so there is no drift-correction bookkeeping -- each write means "N ticks from this instant." Wired into aarch64_irq_handler() and called *first*, before heartbeat_tick(), matching riscv64_timer_rearm()'s ordering discipline exactly: the ARM Generic Timer does not auto-reload, so a return path that skips this leaves the interrupt condition latched, which the GIC would redeliver the instant it's EOI'd -- a real storm, the same class of failure item 0.6's verification investigated (and that time found absent, because nothing was armed yet). Verified: builds clean; every generated instruction checked against disassembly, not just reviewed by eye (both EL branches, correct TVAL/CTL register names, single shared ISB in apic_timer_start(), no ISB in apic_timer_rearm()). Boots to ok> with no regression, dict_hash 0x3d4e1daf289da94f unchanged. Rate measured directly against real wall-clock time via QEMU's own -d int trap trace (same method as riscv64's item 0.3), two independent windows: 1,090 interrupts over 11.05 s (98.679 Hz) and 4,031 over 40.88 s (98.614 Hz) -- consistent across both, so this is a real, small, systematic bias (~1.3-1.4% slow), not measurement noise from polling granularity, which would have shrunk with the longer window and did not. Attributed to genuine per-interrupt service latency: TVAL is rewritten mid-ISR, so the trampoline save/restore, GICC_IAR read, EL branch and GICC_EOIR write all lengthen the effective period slightly versus the nominal 10 ms, inherent to any relative-countdown re-arm scheme. Reported as measured, not smoothed over. The interrupt sustained continuously across both windows with no stall and no storm, which is the primary evidence re-arm-every-tick is correct; the small rate bias is overhead, not a defect. 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.