claude
8688a60ded
The single-file ledger had grown to 2968 lines / ~42k tokens, mixing current design law with accreted history: 59 cycle-stamped realization blocks, 18 [HISTORY] passages, 22 supersession markers, and the C10 / C22 / C24 reframe sagas layered several supersessions deep. A code-grounding audit (31 agents, adversarially verified) confirmed 11 defects stated as current truth: stale crate homes from the C28 #288 roster split (cost nodes, PositionManagement, PositionEvent, Session), the renamed InputSpec->PortSpec, the pre-#241 project model in C16 and the open-threads section, a stale HarnessKind retirement deferral in C24, and three C28-internal inconsistencies. New shape, per the ailang precedent: - INDEX.md stays the sole addressable entry point: foundation, external components, a C-id-keyed contract map (one line per contract), and only the genuinely open architectural threads. - contracts/cNN-<slug>.md carries each contract's current truth only: Guarantee / Forbids / Why with ratified refinements integrated, plus a code-anchored Current state. All confirmed defects are fixed here; crate anchors were re-verified against the tree. - contracts/cNN-<slug>.history.md (18 sidecars) and INDEX.history.md preserve every superseded block verbatim, stamps and issue refs intact, under a frozen-record banner. Nothing was deleted: superseded design intent remains an addressable working-tree artifact, off the per-cycle audit walk. - Ledger discipline is now stated in INDEX.md: live files are edited in place at cycle close, superseded text moves verbatim to the sidecar, and a supersession marker in a live file is itself an audit finding. Every contract file was verified against its old text by an independent zero-loss pass (statement-by-statement) plus a code-accuracy spot check; C-ids and contract titles are unchanged, so existing C-id citations in code, tests, and issues resolve as before.
3.9 KiB
C1 — Determinism and disjoint parallelism
Guarantee. A backtest is a deterministic, synchronous, non-concurrent event
loop that reaches a unique state after each input tick. Same input (incl. seed)
→ bit-identical run. Two backtests are fully disjoint and run concurrently
without locking. The bit-identity is per run: one backtest of given (inputs,
seed) reproduces byte-for-byte. It does not extend to a derived metric
recomputed for the same params by two different command paths (e.g. a swept
member's sqn vs the same cell re-run under aura generalize), which may differ
by floating-point reassociation (≤1 ULP) because the two paths accumulate the
same logical reduction in a different operation order (IEEE-754 non-associativity).
C1 governs the determinism of a single run, not the cross-command bit-identity of
a re-derived statistic. (fieldtest 0078, ratified.)
Forbids. Concurrency within a single sim; any nondeterministic input that is not captured as an explicit input (see C11, C12).
Why. Real money rides on backtest results; reproducibility and an audit trail are non-negotiable. Speed comes from parallelism across sims, which disjointness makes lock-free.
Current state
The per-run event loop is Harness::run (crates/aura-engine/src/harness.rs):
each cycle picks the live source head with the smallest (timestamp, source index), pops one record, increments cycle_id, and forwards the value —
allocating nothing per cycle beyond a reused scratch buffer. A single run is
fully sequential, so its output is bit-identical by construction; the
end-of-stream finalize pass runs after the loop and adds no within-sim
concurrency.
Cross-sim parallelism spans the sweep/member/window fan-out and campaign cells
(#277). The campaign executor execute (crates/aura-campaign/src/exec.rs)
flattens the (strategy, instrument, window, regime) cell matrix into
document-order PlannedCells, groups them by instrument ordinal, and walks
sequential chunks of K instrument groups — --parallel-instruments
(DEFAULT_PARALLEL_INSTRUMENTS = 4, crates/aura-campaign/src/lib.rs). K is a
structural bound on distinct resident instruments — the RAM lever for the
external data-server's per-reference file retention (~1.4 GB per instrument on
the reference dataset), not a pool-worker count. Within a chunk, cells run
concurrently via rayon::par_iter on the process-global pool shared with the
member/window fan-out, and results are written into document-order slots, so
outputs stay byte-identical across worker counts and bounds.
Two scheduling-dependent carve-outs sit outside the per-run bit-identity, which
governs successful runs. On the run-fatal path (non-containable faults, e.g. a
dead registry store) a shared AtomicBool abort flag latches, and the propagated
fault is the lowest document-order fault among the cells that completed before
the latch; the set of per-cell family lines already written by then is
scheduling-dependent — inert, because no campaign-run record is written on that
path and store reads are name-keyed, never line-ordered.
Duplicate campaign instruments are refused at both the validate tier
(crates/aura-campaign/src/lib.rs, a seen_instruments scan) and the executor's
preflight: the per-cell registry family name embeds the raw instrument string,
so name uniqueness is what keeps concurrent appends from racing one name's
run-index assignment.
See also
- C4 — tie determinism preserves this contract; the source-index tie-break is what keeps the merge order deterministic.
- C11, C12 — recorded/pinned inputs are how nondeterministic sources become explicit inputs; the harness is the atomic disjoint unit.
- C23 — the raw-index compilation primitive; names survive only as non-load-bearing debug symbols.
History: c01-determinism.history.md