Aura/docs/design/contracts/c12-atomic-sim-unit.md

C12 — The atomic sim unit and the four orchestration axes

Guarantee. The atomic unit is (frozen topology + param-set + data-window + RNG-seed) → deterministic run → metrics. Parameters are typed, ranged, runtime values injected at graph build — no recompile per param-set; the optimizer sees a generic vector of typed ranges. A bound blueprint param is that param's default: "open" means must be bound by an axis, "bound" means default, overridable by an axis, so a campaign axis (param-sweep) may name a bound param — the family boundary re-opens it on the probe and on every member reload, and the axis binds it per cell; exec's blueprint leg still requires every param resolved (a truly open param refuses), and its own --override NODE.PARAM=VALUE (#246 residue, #319) reopens exactly the named bound param for that one execution — the single-member analogue of a campaign axis. The reopened execution's topology_hash stays the base document's own — reference semantics, not the reopened topology's (#343, revised; full clause in C24's "Reproduction identity"). Identity is untouched: content_id_of (crates/aura-research/src/lib.rs) is the one hashing primitive, read directly off the authored document by aura_runner::member's run_signal_r/run_blueprint_member — where the manifest's topology_hash is computed inline by default (run_signal_r's topo: Option<&str> parameter's None arm, every caller but one; #319 Task 9 retired the CLI-side wrapper that used to duplicate this one call), or supplied by the caller as a ready reference-semantics hash (Some, #343 revised — exec's override branch passes the loaded base document's own id, computed before reopen_all, so the SAME value reaches both the record line and the trace-store persistence) — never a re-opened probe either way, and each member manifest records its per-cell bindings (#246, ratified 2026-07-12; the restriction this amends — axes bind only open knobs — was an implementation consequence of bind() shrinking the param surface, not a recorded decision). Raw data is shared read-only across sims via Arc<[T]> (the data-server is built for this). Four axes orchestrate the atomic unit: (1) param-sweep (grid/random), (2) optimization (argmax metric), (3) walk-forward (rolling in-sample optimize + out-of-sample test), (4) Monte-Carlo (N seeded realizations perturbing input). MC = sweep over seeds; each realization is itself deterministic given its seed.

Forbids. Baking a specific search strategy (Bayesian/genetic) into the primitive — those are pluggable policies atop the atomic unit; recompiling on a param change.

Why. A stable primitive + orchestration axes keeps "wahnsinnig schnell" (embarrassingly parallel across the unit) cleanly separated from search policy. Seed-as-input reconciles Monte-Carlo with C1. The "frozen topology" of the atomic unit is one harness instance, selected by the harness's structural axes (C20); the structural experiment matrix is the outer orchestration over this dimension, the tuning sweep the inner (C19/C20).

Current state

Harness::run is typed as a producer seam — the object-safe Source trait (peek/next, plus bounds and a resident_records() residency probe; crates/aura-engine/src/harness.rs) that the k-way merge drives (C3). Two source shapes back it. The eager load_m1_window/close_stream path (crates/aura-ingest/src/lib.rs), wrapped as VecSource, materializes a whole stream and is retained for bounded loads. The streaming M1FieldSource (crates/aura-ingest/src/lib.rs) pulls a data-server window lazily, borrowing one Arc<[M1Parsed]> chunk per pull (zero-copy within a source) and decoding each Scalar on demand, so its source ring is resident O(one chunk), not O(window length) — resident_records() is a per-source bound, not whole-process RSS.

Raw-data sharing is realized both within and across sims. The data-server's FileCache retains each window's parsed chunks read-only for the pass, so process residency is O(records-touched) — the replay-many sharing model, not a leak. Across sims, the sweep / Monte-Carlo / walk-forward families (axes 2–4) build their members over one shared Arc<DataServer> (one FileCache; crates/aura-ingest/src/lib.rs), so a window is parsed once and every member's M1FieldSource borrows the same cached Arc<[M1Parsed]> chunks. The single-pass parse cost of a window is tracked as #95.

Axis 1 (param-sweep) is built. GridSpace enumerates a cartesian lattice over discrete per-slot value-lists; RandomSpace draws N seeded points over typed continuous ParamRanges (I64 inclusive [lo,hi], F64 half-open [lo,hi)), validated against the param-space before any run; a ListSpace enumerates an explicit point list. All implement the Space trait the disjoint sweep / run_indexed core is generic over (crates/aura-engine/src/sweep.rs), so every enumeration runs through one execution path (C1: results in enumeration order, not completion order). The other axes are realized as families over that core: walk_forward + WindowRoller (crates/aura-engine/src/walkforward.rs) for the rolling in-sample/out-of-sample split, monte_carlo (crates/aura-backtest/src/mc.rs) for the seed sweep; optimization is argmax over a sweep's metrics, a policy atop the core rather than a baked-in strategy. The seeded sampler reuses the bit-stable SplitMix64 (crates/aura-analysis/src/lib.rs) as a code-path-disjoint instance from the data-edge seed RNG (the source-seam firewall, #52/#71: they share only the u64 type, never a path).

See also

• C1
• C11
• C18
• C19
• C20
• C23

History: c12-atomic-sim-unit.history.md