From cd9f7e4ea37067637fe651242bcd44625b6c7776 Mon Sep 17 00:00:00 2001 From: Brummel Date: Mon, 15 Jun 2026 23:16:51 +0200 Subject: [PATCH] plan: 0046 sweep named-binding Three tasks for spec 0046. T1: zip_params (aura-core), RED-first. T2: GridSpace retains its ParamSpec list + SweepFamily carries it + named_params (aura-engine), RED-first, with the aura-registry optimize-test SweepFamily literal threaded in the same task. T3: sim_optimal_manifest typed-Scalar migration + all eight call sites (aura-cli), behaviour-preserving. Each signature/field change threads every one of its sites within its own task, before that task's workspace compile gate. refs #57 --- docs/plans/0046-sweep-named-binding.md | 534 +++++++++++++++++++++++++ 1 file changed, 534 insertions(+) create mode 100644 docs/plans/0046-sweep-named-binding.md diff --git a/docs/plans/0046-sweep-named-binding.md b/docs/plans/0046-sweep-named-binding.md new file mode 100644 index 0000000..d1f2279 --- /dev/null +++ b/docs/plans/0046-sweep-named-binding.md @@ -0,0 +1,534 @@ +# Sweep named-binding — Implementation Plan + +> **Parent spec:** `docs/specs/0046-sweep-named-binding.md` +> +> **For agentic workers:** REQUIRED SUB-SKILL: use the `implement` skill to run +> this plan. Steps use `- [ ]` checkboxes for tracking. + +**Goal:** Replace the three open-coded `param_space()`-name re-zips in the CLI +with one derived projection (`zip_params`) and make a returned `SweepFamily` +self-describing (`named_params`), without touching the run-closure signature. + +**Architecture:** A free function `zip_params(space, point) -> Vec<(String, +Scalar)>` in aura-core pairs names with a positional point. `GridSpace` retains +the `ParamSpec` list it already receives in `new()`; `SweepFamily` carries it +(stamped once in `sweep_with_threads`) and exposes `named_params(i)`. The CLI's +`sim_optimal_manifest` takes typed `Scalar` pairs and collapses to f64 +internally; all eight of its call sites migrate. Behaviour-preserving: +`SweepPoint`, enumeration, and the closure bound are untouched. + +**Tech Stack:** aura-core (`node.rs`, `lib.rs`), aura-engine (`sweep.rs`), +aura-registry (`lib.rs` test), aura-cli (`main.rs`). + +--- + +**Files this plan creates or modifies:** + +- Modify: `crates/aura-core/src/node.rs` — add free fn `zip_params` + a unit-test module +- Modify: `crates/aura-core/src/lib.rs:42` — add `zip_params` to the `node` re-export +- Modify: `crates/aura-engine/src/sweep.rs` — `GridSpace.space` + `param_specs()`; `SweepFamily.space` + `named_params()`; stamp in `sweep_with_threads`; import `zip_params`; 2 tests +- Modify: `crates/aura-registry/src/lib.rs:278` — thread `space: vec![]` into the `optimize` test's `SweepFamily` literal +- Modify: `crates/aura-cli/src/main.rs` — `sim_optimal_manifest` input type + 8 call sites; import `zip_params` + +--- + +## Task 1: `zip_params` (aura-core) + +**Files:** +- Modify: `crates/aura-core/src/node.rs` (ParamSpec at :67-71; module imports at :13) +- Modify: `crates/aura-core/src/lib.rs:42` + +- [ ] **Step 1: Write the failing tests** + +Append to `crates/aura-core/src/node.rs` (end of file): + +```rust +#[cfg(test)] +mod zip_params_tests { + use super::{zip_params, ParamSpec}; + use crate::{Scalar, ScalarKind}; + + #[test] + fn zip_params_pairs_names_with_values_in_slot_order() { + let space = vec![ + ParamSpec { name: "fast".into(), kind: ScalarKind::I64 }, + ParamSpec { name: "scale".into(), kind: ScalarKind::F64 }, + ]; + let point = vec![Scalar::I64(2), Scalar::F64(0.5)]; + assert_eq!( + zip_params(&space, &point), + vec![ + ("fast".to_string(), Scalar::I64(2)), + ("scale".to_string(), Scalar::F64(0.5)), + ], + ); + } + + #[test] + fn zip_params_matches_hand_zip() { + let space = vec![ + ParamSpec { name: "a".into(), kind: ScalarKind::I64 }, + ParamSpec { name: "b".into(), kind: ScalarKind::I64 }, + ]; + let point = vec![Scalar::I64(7), Scalar::I64(9)]; + let hand: Vec<(String, Scalar)> = + space.iter().zip(&point).map(|(ps, v)| (ps.name.clone(), *v)).collect(); + assert_eq!(zip_params(&space, &point), hand); + } +} +``` + +- [ ] **Step 2: Run tests to verify they fail** + +Run: `cargo test -p aura-core zip_params` +Expected: FAIL — compile error `cannot find function `zip_params` in this scope` / +unresolved import `super::zip_params` (E0432/E0425); `zip_params` does not exist yet. + +- [ ] **Step 3: Add the function and re-export it** + +`Scalar` is already in scope in `node.rs` (its `use crate::{Ctx, Scalar, ScalarKind};` +at line 13). Add this free function to `crates/aura-core/src/node.rs` (immediately +after the `ParamSpec` struct, ~line 71): + +```rust +/// Pair each param-space name with the co-indexed positional value — the +/// inverse of positional binding (C23): names are a derived view, not identity. +/// `space` and `point` are co-indexed in `param_space()` slot order; a length +/// mismatch (contract violation) truncates to the shorter, never panics. +pub fn zip_params(space: &[ParamSpec], point: &[Scalar]) -> Vec<(String, Scalar)> { + space.iter().zip(point).map(|(ps, v)| (ps.name.clone(), *v)).collect() +} +``` + +Then add `zip_params` to the node re-export in `crates/aura-core/src/lib.rs:42`. +Change: + +```rust +pub use node::{FieldSpec, Firing, Node, NodeSchema, ParamSpec, PortSpec, PrimitiveBuilder}; +``` + +to: + +```rust +pub use node::{ + zip_params, FieldSpec, Firing, Node, NodeSchema, ParamSpec, PortSpec, PrimitiveBuilder, +}; +``` + +- [ ] **Step 4: Run tests to verify they pass** + +Run: `cargo test -p aura-core zip_params` +Expected: PASS — 2 tests (`zip_params_pairs_names_with_values_in_slot_order`, +`zip_params_matches_hand_zip`). + +--- + +## Task 2: `GridSpace` retains specs; `SweepFamily` carries them + `named_params` (aura-engine), with the aura-registry literal threaded + +**Files:** +- Modify: `crates/aura-engine/src/sweep.rs` (imports :7; `GridSpace` :14-17; `GridSpace::new` :24-44; `SweepFamily` :106-109; `sweep_with_threads` :169-182; test module :184+) +- Modify: `crates/aura-registry/src/lib.rs:278` (the `optimize` test's `SweepFamily` literal) + +- [ ] **Step 1: Write the failing tests** + +Add to the `#[cfg(test)] mod tests` in `crates/aura-engine/src/sweep.rs` (after +`sweep_equals_n_independent_runs`, ~line 326). These reuse the existing +`composite_sma_cross_harness`, `sma_cross_grid`, and `run_point` helpers: + +```rust + #[test] + fn sweep_family_carries_param_space() { + let space = composite_sma_cross_harness().0.param_space(); + let family = sweep(&sma_cross_grid(), run_point); + assert_eq!(family.space, space); + } + + #[test] + fn family_named_params_round_trips() { + let space = composite_sma_cross_harness().0.param_space(); + let family = sweep(&sma_cross_grid(), run_point); + // odometer-first point is [I64(2), I64(4), F64(0.5)] + let expected: Vec<(String, Scalar)> = space + .iter() + .cloned() + .zip(family.points[0].params.clone()) + .map(|(ps, v)| (ps.name, v)) + .collect(); + assert_eq!(family.named_params(0), expected); + assert_eq!(family.named_params(0)[0].1, Scalar::I64(2)); + } +``` + +- [ ] **Step 2: Run tests to verify they fail** + +Run: `cargo test -p aura-engine sweep_family_carries_param_space` +Expected: FAIL — compile error `no field `space` on type `&SweepFamily`` (E0609); +the field does not exist yet. + +- [ ] **Step 3: Retain the specs on `GridSpace`** + +Import `zip_params` in `crates/aura-engine/src/sweep.rs:7`. Change: + +```rust +use aura_core::{ParamSpec, Scalar, ScalarKind}; +``` + +to: + +```rust +use aura_core::{zip_params, ParamSpec, Scalar, ScalarKind}; +``` + +Change the `GridSpace` struct (`sweep.rs:14-17`): + +```rust +#[derive(Debug)] +pub struct GridSpace { + axes: Vec>, +} +``` + +to: + +```rust +#[derive(Debug)] +pub struct GridSpace { + space: Vec, + axes: Vec>, +} +``` + +In `GridSpace::new`, change the final constructor (`sweep.rs:43`) from +`Ok(Self { axes })` to: + +```rust + Ok(Self { space: space.to_vec(), axes }) +``` + +Add a `param_specs` accessor inside `impl GridSpace` (next to `points`): + +```rust + /// The param-space (names + kinds) this grid was validated against, retained + /// for the family to carry — the derived-name source (C23: names, not identity). + pub fn param_specs(&self) -> &[ParamSpec] { + &self.space + } +``` + +- [ ] **Step 4: Carry the space on `SweepFamily` + add `named_params`; stamp it** + +Change the `SweepFamily` struct (`sweep.rs:106-109`): + +```rust +#[derive(Clone, Debug, PartialEq)] +pub struct SweepFamily { + pub points: Vec, +} +``` + +to: + +```rust +#[derive(Clone, Debug, PartialEq)] +pub struct SweepFamily { + pub space: Vec, + pub points: Vec, +} + +impl SweepFamily { + /// The i-th point's params paired with their names — a derived view over the + /// carried param-space (reuses [`zip_params`]); no new per-point state. + pub fn named_params(&self, i: usize) -> Vec<(String, Scalar)> { + zip_params(&self.space, &self.points[i].params) + } +} +``` + +Change the family assembly in `sweep_with_threads` (`sweep.rs:175-181`) from: + +```rust + SweepFamily { + points: points + .into_iter() + .zip(reports) + .map(|(params, report)| SweepPoint { params, report }) + .collect(), + } +``` + +to: + +```rust + SweepFamily { + space: space.param_specs().to_vec(), + points: points + .into_iter() + .zip(reports) + .map(|(params, report)| SweepPoint { params, report }) + .collect(), + } +``` + +- [ ] **Step 5: Thread the new field into the aura-registry test literal** + +The field addition breaks the `SweepFamily { points: vec![..] }` literal in the +`optimize` test (`crates/aura-registry/src/lib.rs:278`). `optimize`/`rank_by` +read only `.points[].report`, so an empty space suffices. Change: + +```rust + let family = SweepFamily { + points: vec![ + point(0.0, 1.0), // 0: also-ran + point(10.0, 3.0), // 1: tied max, earliest -> the winner + point(20.0, 2.0), // 2: also-ran + point(30.0, 3.0), // 3: tied max, but later -> must lose the tie + ], + }; +``` + +to: + +```rust + let family = SweepFamily { + space: vec![], + points: vec![ + point(0.0, 1.0), // 0: also-ran + point(10.0, 3.0), // 1: tied max, earliest -> the winner + point(20.0, 2.0), // 2: also-ran + point(30.0, 3.0), // 3: tied max, but later -> must lose the tie + ], + }; +``` + +- [ ] **Step 6: Compile the whole workspace (incl. tests) to confirm the field is fully threaded** + +Run: `cargo test --workspace --no-run` +Expected: builds with 0 errors (aura-engine assembly + aura-registry test literal +both threaded; the aura-cli still compiles — it constructs no `SweepFamily` +literal). + +- [ ] **Step 7: Run the new tests to verify they pass** + +Run: `cargo test -p aura-engine sweep_family_carries_param_space` +Expected: PASS — 1 test. + +Run: `cargo test -p aura-engine family_named_params_round_trips` +Expected: PASS — 1 test. + +- [ ] **Step 8: Verify the determinism guard still passes** + +Run: `cargo test -p aura-engine family_is_deterministic_across_thread_counts` +Expected: PASS — 1 test (enumeration untouched; the new `space` field is equal +across thread counts for the same grid). + +--- + +## Task 3: Migrate `sim_optimal_manifest` to typed `Scalar` pairs + all 8 call sites (aura-cli) + +Behaviour-preserving migration (no new RED test): the manifest's stored +`params: Vec<(String, f64)>` is byte-identical before and after; the existing +CLI E2E suite is the regression guard. + +**Files:** +- Modify: `crates/aura-cli/src/main.rs` (imports :16; `sim_optimal_manifest` :130-142; closures :386-392, :503-509, :530-536; literal callers :161, :224, :613, :869, :970) + +- [ ] **Step 1: Import `zip_params`** + +Change `crates/aura-cli/src/main.rs:16`: + +```rust +use aura_core::{Firing, Scalar, ScalarKind, Timestamp}; +``` + +to: + +```rust +use aura_core::{zip_params, Firing, Scalar, ScalarKind, Timestamp}; +``` + +- [ ] **Step 2: Change `sim_optimal_manifest` to take typed pairs, collapsing f64 internally** + +Change `crates/aura-cli/src/main.rs:130-142`: + +```rust +fn sim_optimal_manifest( + params: Vec<(String, f64)>, + window: (Timestamp, Timestamp), + seed: u64, +) -> RunManifest { + RunManifest { + commit: option_env!("AURA_COMMIT").unwrap_or("unknown").to_string(), + params, + window, + seed, + broker: "sim-optimal(pip_size=0.0001)".to_string(), + } +} +``` + +to: + +```rust +fn sim_optimal_manifest( + params: Vec<(String, Scalar)>, + window: (Timestamp, Timestamp), + seed: u64, +) -> RunManifest { + // The lossy f64 collapse lives here — the manifest field (the deferred typed + // param-space precursor) owns its own lossiness; callers pass typed Scalars. + let params = params.into_iter().map(|(n, s)| (n, scalar_as_param_f64(&s))).collect(); + RunManifest { + commit: option_env!("AURA_COMMIT").unwrap_or("unknown").to_string(), + params, + window, + seed, + broker: "sim-optimal(pip_size=0.0001)".to_string(), + } +} +``` + +- [ ] **Step 3: Migrate the three sweep closures to `zip_params`** + +In `sweep_family` (`main.rs:386-392`), delete the hand-zip and pass `zip_params`. +Change: + +```rust + let params = space + .iter() + .zip(point) + .map(|(ps, v)| (ps.name.clone(), scalar_as_param_f64(v))) + .collect(); + RunReport { + manifest: sim_optimal_manifest(params, window, 0), + metrics: summarize(&equity, &exposure), + } +``` + +to: + +```rust + RunReport { + manifest: sim_optimal_manifest(zip_params(&space, point), window, 0), + metrics: summarize(&equity, &exposure), + } +``` + +In `sweep_over` (`main.rs:503-509`), the block is byte-identical to +`sweep_family`'s. Change: + +```rust + let params = space + .iter() + .zip(point) + .map(|(ps, v)| (ps.name.clone(), scalar_as_param_f64(v))) + .collect(); + RunReport { + manifest: sim_optimal_manifest(params, window, 0), + metrics: summarize(&equity, &exposure), + } +``` + +to: + +```rust + RunReport { + manifest: sim_optimal_manifest(zip_params(&space, point), window, 0), + metrics: summarize(&equity, &exposure), + } +``` + +In `run_oos` (`main.rs:530-536`), the zip is over the `params` argument into +`named`. Change: + +```rust + let named = space + .iter() + .zip(params) + .map(|(ps, v)| (ps.name.clone(), scalar_as_param_f64(v))) + .collect(); + let report = RunReport { + manifest: sim_optimal_manifest(named, window, 0), + metrics: summarize(&equity, &exposure), + }; +``` + +to: + +```rust + let report = RunReport { + manifest: sim_optimal_manifest(zip_params(&space, params), window, 0), + metrics: summarize(&equity, &exposure), + }; +``` + +- [ ] **Step 4: Migrate the five literal callers to `Scalar` values** + +In `run_sample` (`main.rs:161`), `run_sample_real` (`main.rs:224`), `mc_family` +(`main.rs:613`), and `run_sample_seeded` (`main.rs:970`) — each passes the same +3-tuple. Change every occurrence of: + +```rust + vec![ + ("sma_fast".to_string(), 2.0), + ("sma_slow".to_string(), 4.0), + ("exposure_scale".to_string(), 0.5), + ], +``` + +to: + +```rust + vec![ + ("sma_fast".to_string(), Scalar::F64(2.0)), + ("sma_slow".to_string(), Scalar::F64(4.0)), + ("exposure_scale".to_string(), Scalar::F64(0.5)), + ], +``` + +In `run_macd` (`main.rs:869`), the 4-tuple incl. `ema_signal`. Change: + +```rust + vec![ + ("ema_fast".to_string(), 2.0), + ("ema_slow".to_string(), 4.0), + ("ema_signal".to_string(), 3.0), + ("exposure_scale".to_string(), 0.5), + ], +``` + +to: + +```rust + vec![ + ("ema_fast".to_string(), Scalar::F64(2.0)), + ("ema_slow".to_string(), Scalar::F64(4.0)), + ("ema_signal".to_string(), Scalar::F64(3.0)), + ("exposure_scale".to_string(), Scalar::F64(0.5)), + ], +``` + +- [ ] **Step 5: Compile the whole workspace (incl. tests)** + +Run: `cargo test --workspace --no-run` +Expected: builds with 0 errors (all 8 `sim_optimal_manifest` call sites migrated, +incl. the `#[cfg(test)]` helper `run_sample_seeded`). + +- [ ] **Step 6: Verify behaviour-preservation via the existing E2E suite** + +Run: `cargo test -p aura-cli run_sample_is_deterministic_and_non_trivial` +Expected: PASS (the manifest params for the sample run are unchanged). + +Run: `cargo test -p aura-cli sweep_report_renders_four_points_in_odometer_order` +Expected: PASS (the `aura sweep` output is byte-identical). + +Run: `cargo test -p aura-cli run_macd_compiles_from_nested_composite_and_is_deterministic` +Expected: PASS (the 4-tuple `run_macd` manifest is unchanged). + +- [ ] **Step 7: Full workspace suite + lint** + +Run: `cargo test --workspace` +Expected: PASS — all tests green (no regressions; the two new aura-engine tests +and two new aura-core tests included). + +Run: `cargo clippy --workspace --all-targets -- -D warnings` +Expected: clean — 0 warnings.