From 132dee24376f436423865973ce3ae6f42e830fc4 Mon Sep 17 00:00:00 2001 From: Brummel Date: Tue, 30 Jun 2026 22:55:57 +0200 Subject: [PATCH] spec: 0093 sweep-from-blueprint (boss-signed) Cycle 2 of the World/C21 milestone (#166): `aura sweep --axis =` sweeps a loaded signal over its named param-space axes, reusing the existing stage1-r sweep machinery with the signal source swapped to cycle-1's wrap_stage1r seam, aggregating to a FamilyKind::Sweep family; each member manifest carries the shared topology_hash. Derivable extension, not a fork (recon + grounding confirm): the sweep is by-name param-space-driven (SweepBinder.axis / resolve_axes / bootstrap_with_cells), so a loaded blueprint's param_space slots in; wrap_stage1r nests an arbitrary signal; append_family is blueprint-agnostic. Scoped to sweep (the keystone family); MC / walk-forward over a loaded blueprint are the same machinery per verb and follow as a fast follow-on. Decisions recorded on #166. Boss-signed on a grounding-check PASS: all six load-bearing current-behaviour assumptions ratified by named green tests (wrap_stage1r arbitrary-signal nesting, the by-name param-space sweep, stage1_r_sweep_family, append_family/FamilyKind::Sweep, topology_hash, the .json-discriminator dispatch precedent). refs #166 --- docs/specs/0093-sweep-from-blueprint.md | 181 ++++++++++++++++++++++++ 1 file changed, 181 insertions(+) create mode 100644 docs/specs/0093-sweep-from-blueprint.md diff --git a/docs/specs/0093-sweep-from-blueprint.md b/docs/specs/0093-sweep-from-blueprint.md new file mode 100644 index 0000000..0a11097 --- /dev/null +++ b/docs/specs/0093-sweep-from-blueprint.md @@ -0,0 +1,181 @@ +# Sweep a harness family from a serialized blueprint (`aura sweep `) — Design Spec + +**Date:** 2026-06-30 +**Status:** Draft — awaiting grounding-check + sign-off +**Authors:** orchestrator + Claude +**Parent:** World/C21 milestone (run + orchestrate harness families from blueprint-data); reference issue #166 + +## Goal + +Sweep a loaded signal blueprint over its named param-space axes: + +``` +aura sweep --axis = [--axis = ...] [--name | --trace ] [--real [--from ] [--to ]] +``` + +loads the signal (`blueprint_from_json`), wraps it in the Stage-1-R scaffolding +via the cycle-1 `wrap_stage1r` seam, grids the user's by-name axes against the +wrapped graph's `param_space()`, runs one member per grid point (C1: members are +disjoint → the existing parallel sweep), and aggregates to a `FamilyKind::Sweep` +family — **byte-identical in shape** to the hard-wired `aura sweep --strategy +stage1-r` family. Each member's manifest carries `topology_hash` (the #158 anchor). + +This is cycle 2 of the World/C21 milestone: the World now orchestrates **families** +of harnesses built from blueprint-data, not just a single run (cycle 1). Monte-Carlo +and walk-forward over a loaded blueprint are the same machinery per verb and follow +as a fast follow-on (out of scope here; see § Out of scope). + +## Architecture + +The existing sweep is **param-space-driven and blueprint-agnostic**: +`stage1_r_sweep_family` (`crates/aura-cli/src/main.rs`) builds an open graph once, +reads `param_space()`, resolves named axes to param slots (`SweepBinder.axis(name, +values)` → `resolve_axes`, `crates/aura-engine/src/blueprint.rs`), and runs +`.sweep(|point| bootstrap_with_cells(point))` over the grid, draining each member to +a `RunReport`; `Registry::append_family` (`crates/aura-registry/src/lineage.rs`) +persists the members. + +Cycle 2 swaps the **signal source** only: instead of the hard-wired +`stage1_signal()` / `stage1_r_graph(None, None, …)`, the open graph is +`wrap_stage1r(loaded_signal, …)` (cycle 1's seam, which nests an arbitrary signal +Composite — `main.rs:2775`, `g.add(BlueprintNode::Composite(signal))` — and exposes +its open params in the wrapped `param_space()`). The axes are **user-supplied by +name** (a loaded signal is arbitrary, not only stage1-r's `fast`/`slow`), resolved +against that `param_space()` by the existing by-name `resolve_axes`. The +member-construction, the parallel sweep, the drain, and the family aggregation are +**reused unchanged**. + +The only additions: (1) a `.json`-discriminator `aura sweep ` arm (mirror +of cycle 1's `aura run ` arm, `main.rs:3576`), (2) `--axis =` +parsing into `Vec<(String, Vec)>`, (3) each member's manifest carries +`topology_hash(&loaded_signal)` (one computation, shared across members — same signal +topology, only params vary; `member_key` distinguishes members). The hard-wired +`--strategy` sweep path stays untouched (#159). + +## Concrete code shapes + +### The user-facing program (the criterion's evidence) + +```console +$ aura sweep sma_cross.json --axis fast.length=2,3,4 --axis slow.length=8,16 --name xfam +# wraps the loaded signal once, grids fast.length × slow.length (6 members), runs them, +# aggregates to a Sweep family; each member manifest carries the shared topology_hash. +$ aura runs families +{"family_id":"xfam-0","kind":"Sweep","members":6,...} +``` + +### The sweep-blueprint arm (mirror of the cycle-1 run arm) + +```rust +// in the ["sweep", rest @ ..] dispatch, before parse_sweep_args (main.rs ~:3620): +if let Some(path) = + rest.first().filter(|a| a.ends_with(".json") && std::path::Path::new(a).is_file()) +{ + let doc = std::fs::read_to_string(path).unwrap_or_else(|e| { eprintln!("aura: {path}: {e}"); std::process::exit(2); }); + let signal = blueprint_from_json(&doc, &|t| std_vocabulary(t)).unwrap_or_else(|e| { eprintln!("aura: {path}: {e:?}"); std::process::exit(2); }); + let SweepBlueprintArgs { axes, name, persist, data } = parse_sweep_blueprint_args(&rest[1..]) + .unwrap_or_else(|msg| { eprintln!("aura: {msg}"); std::process::exit(2); }); + run_blueprint_sweep(signal, &axes, &name, persist, data); + return; +} +``` + +### The member-build (reuse the `stage1_r_sweep_family` pattern, swap the source) + +```rust +/// Sweep a loaded signal over user-named axes, reusing the stage1-r sweep +/// machinery with the signal source swapped to `wrap_stage1r(signal, …)`. Each +/// member manifest carries the signal's topology_hash (shared; member_key +/// distinguishes members). +fn run_blueprint_sweep(signal: Composite, axes: &[(String, Vec)], name: &str, persist: bool, data: DataSource) { + let topo = topology_hash(&signal); + // build wrap_stage1r(signal, …) ONCE (open params = the loaded signal's open params), + // read param_space(), resolve the by-name `axes` against it (the existing resolve_axes — + // an unknown axis name errors), .sweep(|point| bootstrap_with_cells(point) → run → drain + // → RunReport with manifest.topology_hash = Some(topo)), then append_family(name, + // FamilyKind::Sweep, &reports). The channel/reducer threading mirrors stage1_r_sweep_family. +} +``` + +The before→after on `RunManifest.topology_hash` is none — the field shipped cycle +0092; this cycle only sets it `Some(topo)` inside the member loop. + +## Components + +- **CLI** (`main.rs`): the `aura sweep ` `.json`-discriminator arm + + `parse_sweep_blueprint_args` (`--axis name=csv` repeatable → `Vec<(String, + Vec)>`; `--name`/`--trace`; the existing `--real`/`--from`/`--to` data + flags). A malformed/duplicate axis or a bad csv errors with a named message. +- **`run_blueprint_sweep`** (`main.rs`): the member-construction + sweep + aggregation, + mirroring `stage1_r_sweep_family` with the signal source = `wrap_stage1r(loaded, …)` + and the per-member `topology_hash`. +- Reused unchanged: `wrap_stage1r` (cycle 1), `SweepBinder` / `resolve_axes` / + `bootstrap_with_cells` (`blueprint.rs`), `append_family` / `FamilyKind::Sweep` + (`lineage.rs`), `topology_hash` (cycle 1). + +## Data flow + +`` → `blueprint_from_json` → `Composite` (signal) → +`wrap_stage1r` → open wrapped `Composite` → `param_space()` → `SweepBinder` grids +the by-name axes → per grid point: `bootstrap_with_cells(point)` → `Harness` → run → +drain → `RunReport{manifest{…, topology_hash}, metrics}` → `append_family(Sweep)` → +`families.jsonl`. + +## Error handling + +- Missing/unreadable file, `LoadError` (malformed / `UnknownNodeType` / + `UnsupportedVersion`) → named message, non-zero exit (mirror cycle 1). +- An `--axis ` that does not resolve against the loaded blueprint's + `param_space()` → a clean error naming the unknown axis (the existing + `resolve_axes` failure), exit non-zero — not a panic. +- A malformed/empty/duplicate `--axis` or csv value → a named usage error. + +## Testing strategy + +- **Family-equivalence (the keystone):** a sweep over a serialized signal produces a + `FamilyKind::Sweep` family whose members' metrics equal the equivalent hard-wired + stage1-r sweep over the SAME signal + grid (the loaded path and the hard-wired path + agree, C1), and each member manifest carries the shared `topology_hash`. Compare via + the member reports / `families.jsonl`. +- **member_key distinguishes; hash is shared:** all members carry the same + `topology_hash`; their `member_key`s differ. +- **Unknown axis errors cleanly:** `--axis nope=1,2` over a signal without a `nope` + param → a named error, non-zero exit, no panic. +- **E2E (binary):** `aura sweep tests/fixtures/stage1_signal.json --axis fast.length=2,4 + --name f` exits 0 and persists a 2-member Sweep family (`aura runs families` shows + `"kind":"Sweep","members":2`); an unknown-node blueprint fails clean. +- The hard-wired `aura sweep --strategy stage1-r` path is unchanged (its tests stay green). + +## Acceptance criteria + +- [ ] `aura sweep --axis = …` builds each member via the + cycle-1 `wrap_stage1r` seam over the loaded signal and aggregates to a + `FamilyKind::Sweep` family, byte-identical in shape to the hard-wired sweep. +- [ ] Each member manifest carries `topology_hash` = SHA256 of the loaded signal's + canonical form; all members share it; `member_key` distinguishes members. +- [ ] Member metrics equal the equivalent hard-wired stage1-r sweep over the same + signal + grid (C1). +- [ ] An unknown `--axis` name fails clean (named error, non-zero), not a panic. +- [ ] The hard-wired `--strategy` sweep path is untouched (#159); its tests stay green. + +## Out of scope (named homes) + +- **Monte-Carlo / walk-forward over a loaded blueprint** — the same machinery per + verb (`run_walkforward` / the mc path + the `.json`-discriminator pattern); a fast + follow-on cycle, not this one. +- **Axes as composable builder tools** (nesting / chaining orchestration) — the + follow-on composable-orchestration surface (charter), not this cycle. +- **A content-id that covers harness-structural variants** — #158 (the hash covers + the signal only; fine here, since a sweep varies params, not topology). + +## Feature-acceptance (project criterion, applied) + +- **Audience reaches for it:** a researcher who serialized a strategy and ran it once + (cycle 1) naturally wants to *sweep* it over a parameter grid without re-authoring + Rust — `aura sweep sma_cross.json --axis fast.length=2,3,4` is exactly that. +- **Improves correctness / removes redundancy:** it makes a serialized topology + *swept* and the members reproducible (`topology_hash`), and reuses the existing + sweep machinery rather than a second implementation. +- **Reintroduces no failure class:** node logic stays Rust (C17); the resolver + resolves only compiled-in types (invariant 9, fails clean); members are disjoint + and deterministic (C1); the deploy artifact stays frozen (research-plane, invariant 8).