# v3/CLAUDE.md -- loaded when working under v3/ (moved from .claude/CLAUDE.md, 2026-11-06)

## Physics-Driven Adaptive Runtime

Uses thermodynamic metaphors as modeling language (see `ONTOLOGY.md`):

1. **Loop #1 — Execution Heat** (`dictionary_heat_optimization.c`) — frequency counter per word
2. **Loop #2 — Rolling Window** (`rolling_window_of_truth.c`) — circular buffer, execution history
3. **Loop #3 — Linear Decay** — quiescent words lose heat over time
4. **Loop #4 — Pipelining** (`physics_pipelining_metrics.c`) — word-to-word transition prediction
5. **Loop #5 — Window Width Inference** (`inference_engine.c`) — Levene's test, binary chop
6. **Loop #6 — Decay Slope Inference** (`inference_engine.c`) — exponential regression
7. **Loop #7 — Adaptive Heartrate** (`HeartbeatState`) — background tick coordinator

**L8 Jacquard Mode Selector** (`ssm_jacquard.c`) — a 128-state, 7-bit loop-gate selector.
In this repo it now has a real per-VM heat channel into fleet-wide tuning (VM Fleet
Attractor physics — see `docs/working/architecture/VM-FLEET-ATTRACTOR-DESIGN-20260705.md`),
replacing hardcoded compudynamics constants with a dynamically-inferred rate.

## Critical Implementation Details

### DoE CSV Output Suppression

Intentionally suppressed as of 2025-12-08. See `v3/src/main.c:390-396`:
- Metrics still collected via `metrics_from_vm()`
- CSV row was redundant with internal VM metrics
- To re-enable: add a `--csv-export` flag or write to a file

### Heartbeat Instrumentation (Planned)

`HeartbeatTickSnapshot` and `tick_buffer` are declared in `v3/include/vm.h`,
but `heartbeat_export_csv()` is **not yet implemented**.

### Word Statistics Output

`WORD-ENTROPY` prints execution heat statistics to stdout. Kept enabled in DoE mode
intentionally (diagnostic value outweighs noise cost).

### StarKernel M7 Parity

`parity.c` logs every VM birth and execution with: VM ID, capsule hash, dictionary hash.
This enables offline determinism verification — an independent system can load the same
capsule and compare dict hashes. Zero-deviation means 0% algorithmic variance.