diff --git a/docs/specs/0042-seed-as-input.md b/docs/specs/0042-seed-as-input.md new file mode 100644 index 0000000..eb8514a --- /dev/null +++ b/docs/specs/0042-seed-as-input.md @@ -0,0 +1,318 @@ +# Seed-as-input: a seeded source whose stream is fully seed-determined — Design Spec + +**Date:** 2026-06-15 +**Status:** Draft — awaiting user spec review +**Authors:** orchestrator + Claude + +## Goal + +Make `RunManifest.seed` a *live captured input* (C12) instead of the dead `0` +it is today. Deliver the precondition for the Monte-Carlo family (#68) and +random param-sweep (#52): a **seeded source** — a producer whose entire output +stream is determined by a `u64` seed — wired so that the seed reaches +`RunManifest.seed` at the manifest-construction site. + +This is C12's reconciliation of stochastic runs with C1: a run is **bit-identical +for a fixed seed**, and the seed is a *captured input* like the data window or +the params, not hidden nondeterminism. A different seed gives a different — but +itself fully reproducible — run. + +Settled in the seeding issue (#66 body + its 2026-06-15 09:26 comment, authored +by the user): + +- **Fork B (settled).** The seed lives at the **recording / data-generation + edge, outside the engine graph**, and is recorded into `RunManifest.seed` at + the **manifest-construction site**. The engine event loop never sees a seed; it + drives `Source`s as it already does (C3/C6, no look-ahead). Determinism is + *preserved by* an explicit seed input, never *broken* — the seed perturbs the + data the engine replays, upstream of the engine. +- **The contract is a producer, never a `Vec`.** The seed→stream contract is + `Fn(u64) -> impl Source` (the `Source` trait at + `crates/aura-engine/src/harness.rs:57`, from #71), **never** + `fn seeded_prices(seed) -> Vec<(Timestamp, Scalar)>`. A `seed -> Vec` shape + would calcify eager into the whole Monte-Carlo family (#68 re-seeds N times); a + materialized-Vec definition is exactly the eager wall World-II's source seam + exists to avoid. A first cut MAY collect to a `VecSource` *internally*; the + contract's *signature* must not name `Vec`. + +## Non-goals + +- **No `aura run --seed` CLI flag this cycle.** The acceptance is bootstrap-level + determinism (two bootstraps, same seed → identical trace), which is pinned by + Rust tests against a seeded run path — not by a CLI surface. The Monte-Carlo + family (#68) consumes the seed→source contract *programmatically* (a `McFamily` + re-seeds N times, analog to `SweepFamily`), never via a CLI flag. A `--seed` + flag is a future demonstrator, deliberately out of scope here. +- **No Monte-Carlo family (#68) and no random sweep (#52).** This cycle ships + only their shared precondition — the seeded-source contract and a live + `manifest.seed`. The families are separate issues. +- **No typed param/seed space.** `RunManifest.seed` stays a bare `u64`, matching + the existing manifest shape. + +## Architecture + +Three pieces, each at its settled altitude. + +1. **A deterministic, dependency-free PRNG** (engine-side). The seed fully + determines the sequence; no external entropy, no global state, **bit-stable + across toolchains and crate versions**. Bit-stability is the substantive + reason for an in-house PRNG over a `rand`-family crate: the entire *value* of + seed-as-input is reproducibility (C1), and a crate whose generator algorithm + is not guaranteed stable across major versions would silently break a recorded + seed's reproducibility on a dependency bump. The workspace has no *direct* RNG + dependency today (only `getrandom`, transitively); a ~10-line SplitMix64 adds + no new direct dep and gives a documented, portable bit-exact stream. (This is the dependency-policy + per-case call: what a vetted crate would buy here — entropy sources, many + distributions — is precisely what C12 forbids inside a replay.) + +2. **A seeded synthetic price source** (engine-side, alongside the existing + `Source` producers `VecSource` / `M1FieldSource`). A `Fn(u64) -> impl Source` + producer: given a seed, it yields a deterministic synthetic M1 price walk as a + `Source`. The reference shape is RustAst's seeded synthetic OHLC generator + (`rtl/streams/register.rs`). The non-seed knobs (start price, length, step) + are config carried by a small spec value, so that **partially applying the + config yields the literal `Fn(u64) -> impl Source`** the MC family will hold + and vary. + +3. **The seed captured into the manifest** (CLI / harness-construction site, + outside the engine — Fork B). The CLI's `sim_optimal_manifest` gains a `seed` + parameter. It has **four** current callers, all seed-free today: `run_sample`, + `run_sample_real`, the sweep/showcase grid-report builder, and `run_macd`. + All four pass `0` and are unchanged in behaviour (so their currently-green + determinism tests — `run_sample_is_deterministic_and_non_trivial`, + `sweep_report_is_deterministic`, `run_macd_…_is_deterministic`, + `run_sample_real_streams_real_close_bars_deterministically` — stay green), + while a new seeded run path passes the real seed. This is the single site + where the seed that drove the run becomes the recorded `manifest.seed`. + +Placement rationale (C9 engine/project separation): the seeded source is +reusable World-layer data-generation infrastructure consumed by the orchestration +families (`SweepFamily`/`McFamily` live in `aura-engine`), not a CLI demo. It +belongs beside the other `Source` producers in `aura-engine`, the same category +as `VecSource`. The exact module (extend `harness.rs` vs a new `source` module) +is the planner's call. + +## Concrete code shapes + +### Worked example — what a consumer writes (the empirical evidence) + +The north-star consumer is the Monte-Carlo family (#68). What seed-as-input must +make writable is exactly this — a closure from seed to a runnable source, +re-seeded N times, every run reproducible and seed-tagged: + +```rust +// #68 will write (sketch — NOT part of this cycle, shown to justify the contract): +let spec = SyntheticSpec { start: 1.0, len: 64, step: 1 }; +let seed_to_source = |seed: u64| spec.source(seed); // Fn(u64) -> impl Source +for seed in 0..1_000 { + let report = run_seeded(seed, seed_to_source(seed)); // each run bit-identical for its seed + // report.manifest.seed == seed ← the captured input +} +``` + +If the contract were `seed -> Vec`, that loop would materialize 1000 price +vectors; with `impl Source` it streams each lazily (O(one window) resident). This +is why the contract names `Source`, not `Vec`. + +### Delivered this cycle — the seeded producer + +```rust +// aura-engine, beside VecSource. Before: no seeded source exists. + +/// A tiny, fully-deterministic, dependency-free PRNG (SplitMix64). The seed +/// completely determines the sequence; no external entropy, no global state. +/// Bit-stable across toolchains and crate versions — the property C1 needs for +/// seed-as-input reproducibility. +struct SplitMix64 { state: u64 } + +impl SplitMix64 { + fn new(seed: u64) -> Self { Self { state: seed } } + fn next_u64(&mut self) -> u64 { + self.state = self.state.wrapping_add(0x9E37_79B9_7F4A_7C15); + let mut z = self.state; + z = (z ^ (z >> 30)).wrapping_mul(0xBF58_476D_1CE4_E5B9); + z = (z ^ (z >> 27)).wrapping_mul(0x94D0_49BB_1331_11EB); + z ^ (z >> 31) + } + /// A uniform `f64` in `[0, 1)` from the top 53 bits. + fn next_f64(&mut self) -> f64 { + (self.next_u64() >> 11) as f64 / ((1u64 << 53) as f64) + } +} + +/// Config for a seeded synthetic price walk — everything *except* the seed. +/// Partially applying it (`|seed| spec.source(seed)`) is the `Fn(u64) -> impl +/// Source` contract the Monte-Carlo family consumes. +#[derive(Clone, Copy, Debug)] +pub struct SyntheticSpec { + pub start: f64, // opening price + pub len: usize, // number of M1 steps + pub step: i64, // timestamp increment per step +} + +impl SyntheticSpec { + /// Produce a synthetic price stream **fully determined by `seed`** (C12). + /// Returns a `Source` (the C3 ingestion producer), NOT a `Vec` — so a + /// Monte-Carlo family can re-seed without materializing N streams (#68). + /// A multiplicative random walk: each step a small seeded perturbation. + /// (First cut collects to a `VecSource` internally; the signature does not + /// name `Vec`, so a later lazy generator is a drop-in replacement.) + pub fn source(&self, seed: u64) -> impl Source { + let mut rng = SplitMix64::new(seed); + let mut price = self.start; + let stream: Vec<(Timestamp, Scalar)> = (0..self.len) + .map(|i| { + let shock = (rng.next_f64() - 0.5) * 0.004; // ±0.2% per step + price *= 1.0 + shock; + (Timestamp(i as i64 * self.step + 1), Scalar::F64(price)) + }) + .collect(); + VecSource::new(stream) + } +} +``` + +### Delivered this cycle — the seed captured into the manifest (Fork B site) + +```rust +// aura-cli. Before: +fn sim_optimal_manifest(params: Vec<(String, f64)>, window: (Timestamp, Timestamp)) -> RunManifest { + RunManifest { commit: …, params, window, seed: 0, broker: … } // seed hardcoded 0 +} + +// After: seed becomes a parameter — the single manifest-construction site that +// records the seed that drove the run (Fork B). Seed-free callers pass 0. +fn sim_optimal_manifest( + params: Vec<(String, f64)>, + window: (Timestamp, Timestamp), + seed: u64, +) -> RunManifest { + RunManifest { commit: …, params, window, seed, broker: … } +} + +/// The drained sink trace of a seeded run — the recorded rows of the equity and +/// exposure sinks. Exposed so the C1 seed-determinism property is testable at +/// the *trace* level (bit-identical rows), not only through the folded metrics +/// (a strictly weaker check: distinct traces can fold to equal 3-field metrics). +struct SeededTrace { + equity: Vec<(Timestamp, Vec)>, + exposure: Vec<(Timestamp, Vec)>, +} + +/// A seeded run of the sample harness: the synthetic stream is generated from +/// `seed`, that same seed is recorded into the manifest, and the drained sink +/// trace is returned alongside the report. Analog to `run_sample`, but every +/// byte of both the report and the trace is a function of `seed`. (The +/// trace-returning shape is new on the seeded path only; the four existing +/// run paths keep their `RunReport`-only return — no blast radius there.) +fn run_sample_seeded(seed: u64) -> (RunReport, SeededTrace) { + let (mut h, rx_eq, rx_ex) = sample_harness(); + let spec = SyntheticSpec { start: 1.0, len: 64, step: 1 }; + let window = (Timestamp(1), Timestamp((spec.len as i64 - 1) * spec.step + 1)); + h.run(vec![Box::new(spec.source(seed))]); + let eq_rows: Vec<(Timestamp, Vec)> = rx_eq.try_iter().collect(); + let ex_rows: Vec<(Timestamp, Vec)> = rx_ex.try_iter().collect(); + let metrics = summarize(&f64_field(&eq_rows, 0), &f64_field(&ex_rows, 0)); + let report = RunReport { + manifest: sim_optimal_manifest( + vec![("sma_fast".into(), 2.0), ("sma_slow".into(), 4.0), ("exposure_scale".into(), 0.5)], + window, + seed, // ← live, no longer 0 + ), + metrics, + }; + (report, SeededTrace { equity: eq_rows, exposure: ex_rows }) +} +``` + +All four existing call sites (`run_sample`, `run_sample_real`, the sweep/showcase +grid-report builder, `run_macd`) pass `seed: 0` and keep their byte-identical +output (seed-free synthetic / real runs stay `0`, as the manifest doc already +states). Only `run_sample_seeded` returns the trace alongside the report. + +## Components + +| Component | Where | Change | +|-----------|-------|--------| +| `SplitMix64` | aura-engine (private) | new — deterministic PRNG | +| `SyntheticSpec` + `::source(seed) -> impl Source` | aura-engine (`pub`) | new — the `Fn(u64) -> impl Source` contract | +| `sim_optimal_manifest` | aura-cli | gains a `seed: u64` param; all **four** existing callers (`run_sample`, `run_sample_real`, sweep grid-report, `run_macd`) pass `0` | +| `SeededTrace` + `run_sample_seeded` | aura-cli | new — the seeded run path; records the seed and returns the drained sink trace | +| `RunManifest.seed` | aura-engine (unchanged type) | no longer always `0`; now reachable as a live value | + +## Data flow + +``` +seed: u64 + │ + ├──> SyntheticSpec::source(seed) ──> impl Source ──> Harness::run(vec![..]) (engine: unchanged C3 merge / C6 loop) + │ │ + │ └──> sinks ──> RunMetrics + │ + └──> sim_optimal_manifest(.., seed) ──> RunManifest { seed, .. } + │ + RunReport { manifest, metrics } ┘ (manifest.seed == the seed that drove the run) +``` + +The seed forks once, upstream of the engine: into the data generator and into +the manifest. The engine loop is untouched — it sees only a `Source`. + +## Error handling + +No new failure modes. `len == 0` yields an empty `Source` (the engine already +handles an exhausted source: `run` breaks immediately, sinks drain empty — same +as any empty stream). The PRNG cannot fail (pure integer ops). The seed is a +plain `u64`; every value is valid. + +## Testing strategy + +RED-first. Two layers: + +**Producer unit tests (aura-engine):** + +1. `seeded_source_same_seed_same_stream` — drain `spec.source(7)` twice; the two + `Vec<(Timestamp, Scalar)>` streams are bit-identical. +2. `seeded_source_different_seed_differs` — `spec.source(1)` and `spec.source(2)` + drain to different streams. + +**End-to-end seed-as-input tests (aura-cli) — the issue's acceptance:** + +3. `same_seed_bit_identical_trace` — the `SeededTrace` (equity + exposure rows, + the recorded `(Timestamp, Vec)` vectors) returned by + `run_sample_seeded(42)` equals the `SeededTrace` of a second + `run_sample_seeded(42)`. The assertion is on the **rows themselves**, not on + the folded metrics — that is the literal "bit-identical sink trace" of + acceptance bullet 1, strictly stronger than a metrics comparison. +4. `different_seed_different_trace` — the `RunReport.metrics` of + `run_sample_seeded(1)` differs from that of `run_sample_seeded(2)`. + (Acceptance bullet 2 — different seeds perturb the trace.) +5. `seed_recorded_in_manifest` — `run_sample_seeded(7)`'s `RunReport.manifest.seed + == 7`. (Acceptance bullet 3 — no longer always `0`.) + +(Each test destructures the `(RunReport, SeededTrace)` tuple: test 3 reads the +trace, tests 4–5 read the report.) + +Determinism (C1) is the property under test throughout: a fixed seed is a fixed +run, a different seed a different-but-reproducible run. + +## Acceptance criteria + +From #66, RED-first: + +- [ ] Two bootstraps of the same blueprint with the same seed produce a + bit-identical sink trace. +- [ ] Two different seeds produce different traces. +- [ ] The seed that drove the run is recorded in `RunManifest.seed` (no longer + always `0`). + +Plus the contract invariant that makes this the right precondition for #68/#52: + +- [ ] The seed→stream contract has signature `Fn(u64) -> impl Source` — it does + **not** name `Vec` (a first impl may collect to `VecSource` internally). +- [ ] All four existing seed-free runs (`run_sample`, `run_sample_real`, the + sweep/showcase grid-report builder, `run_macd`) keep `manifest.seed == 0` + and byte-identical output (their determinism tests stay green). + +Contracts touched: **C12** (seed-as-input), **C1** (determinism preserved by an +explicit seed input, not broken), **C3** (the seeded source is an ordinary +ingestion-boundary `Source`).