claude
9eb6d6b4f6
Slice 8, closing the #319 retirement's prose and bench debt. Bench argv rides exec (fixed_cost single-run probe, campaign surfaces, and the seed helper that still called the retired sweep at runtime — caught by the bench run itself); all five fingerprints unchanged against the committed baselines, confirming record-line parity through the retirement. Live docs (README, authoring guide, project layout, glossary) describe only exec + campaign documents + graph introspect --params; three glossary entries explicitly mark their verb retired. Ledger amendments per the C29 discipline — C25's executor-verb-set re-settled (exec + the --override residue), C14's dual grammar reduced to the one dispatch, C24's document-built runs/families + gated-intake route list (lockstep with the code comment), C12's override clause and identity anchor repointed to the runner-layer hash computation, C18/C22/C27/C01 mention rewrites — superseded sentences moved verbatim to the history sidecars (c25's created). Stale dual-grammar doc comment on is_blueprint_file rewritten. refs #319
71 lines
4.0 KiB
Markdown
71 lines
4.0 KiB
Markdown
# 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
|
|
campaign cell's `sqn` within its sweep stage vs the same params re-run
|
|
through `exec`'s blueprint leg with `--override`, #319), 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 `PlannedCell`s, 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](c04-cycle-granularity.md) — tie determinism preserves this contract; the
|
|
source-index tie-break is what keeps the merge order deterministic.
|
|
- [C11](c11-sources-record-replay.md), [C12](c12-atomic-sim-unit.md) —
|
|
recorded/pinned inputs are how nondeterministic sources become explicit inputs;
|
|
the harness is the atomic disjoint unit.
|
|
- [C23](c23-graph-compilation.md) — the raw-index compilation primitive; names
|
|
survive only as non-load-bearing debug symbols.
|
|
|
|
> History: [c01-determinism.history.md](c01-determinism.history.md)
|