# Param-sweep grid — Iteration 2 (`aura sweep` CLI demonstrator) — Implementation Plan

> **Parent spec:** `docs/specs/0028-param-sweep-grid.md`
>
> **For agentic workers:** REQUIRED SUB-SKILL: use the `implement` skill to run
> this plan. Steps use `- [ ]` checkboxes for tracking.

**Goal:** Make the iteration-1 sweep primitive visible without writing Rust — an
`aura sweep` subcommand that runs the built-in sample over a small built-in grid
and prints one JSON line per point.

**Architecture:** All edits live in `crates/aura-cli/src/main.rs` plus a golden in
`crates/aura-cli/tests/cli_run.rs`. A `sample_blueprint_with_sinks()` factory
holds the sample topology and returns the two Recorder receivers (today
`build_sample` drops them); `build_sample` is re-expressed on top of it so the
`aura graph` path is unchanged. A pure `sweep_report() -> String` declares the
grid, calls the engine `sweep()` with a per-point build→run→drain→summarize
closure, and renders each `SweepPoint` via a hand-rolled `sweep_point_to_json`
(C14, no serde — mirrors `RunReport::to_json`'s token rules). The `main()`
dispatch grows a `["sweep"]` arm.

**Tech Stack:** `crates/aura-cli` (`main.rs` subcommand + helpers, `tests/cli_run.rs`
golden); consumes the iter-1 engine exports `GridSpace`/`sweep`/`SweepPoint` and
the existing `f64_field`/`summarize`/`synthetic_prices`/`sma_cross` surface.

---

**Files this plan creates or modifies:**

- Modify: `crates/aura-cli/src/main.rs:11-17` — extend the `use` blocks
  (`ParamSpec` from aura-core; `GridSpace`, `sweep`, `SweepPoint` from
  aura-engine).
- Modify: `crates/aura-cli/src/main.rs:160-194` — add `sample_blueprint_with_sinks()`;
  re-express `build_sample()` on top of it.
- Modify: `crates/aura-cli/src/main.rs:352` — extend `USAGE`.
- Modify: `crates/aura-cli/src/main.rs:359-368` — add the `["sweep"]` dispatch arm.
- Modify: `crates/aura-cli/src/main.rs` (new fns `sweep_report`,
  `sweep_point_to_json`, `json_string`, `scalar_token`) + its `#[cfg(test)]` module.
- Modify: `crates/aura-cli/tests/cli_run.rs` — add the `aura sweep` process golden.

---

## Task 1: `sample_blueprint_with_sinks` factory (sinks reachable for draining)

**Files:**
- Modify: `crates/aura-cli/src/main.rs:160-194`

- [ ] **Step 1: Write the failing test (RED)**

In `crates/aura-cli/src/main.rs`, inside the existing `#[cfg(test)] mod tests {
… }` block (around `main.rs:371-459`), add this test:

```rust
    #[test]
    fn sample_blueprint_with_sinks_bootstraps_runs_and_drains() {
        // the factory returns the two Recorder receivers (build_sample drops them),
        // so a caller can bootstrap one point, run it, and drain both sinks.
        let (bp, rx_eq, rx_ex) = sample_blueprint_with_sinks();
        let mut h = bp
            .bootstrap_with_params(vec![Scalar::I64(2), Scalar::I64(4), Scalar::F64(0.5)])
            .expect("sample blueprint compiles under a valid point");
        h.run(vec![synthetic_prices()]);
        assert!(!rx_eq.try_iter().collect::<Vec<_>>().is_empty(), "equity sink drained empty");
        assert!(!rx_ex.try_iter().collect::<Vec<_>>().is_empty(), "exposure sink drained empty");
    }
```

- [ ] **Step 2: Run the test to verify it fails (RED)**

Run: `cargo test -p aura-cli --bin aura sample_blueprint_with_sinks`
Expected: FAIL — compile error, `cannot find function sample_blueprint_with_sinks`
in this scope.

- [ ] **Step 3: Add the factory and re-express `build_sample` (GREEN)**

In `crates/aura-cli/src/main.rs`, replace the current `build_sample` function
(`main.rs:160-189`, the one that constructs two channels and drops the receivers
at `let (tx_eq, _rx_eq) = …` / `let (tx_ex, _rx_ex) = …`) with the factory plus a
thin `build_sample` that discards the receivers:

```rust
/// The sample signal-quality blueprint (value-empty) **with its two recording
/// sinks reachable**: returns the equity + exposure receivers a per-point sweep
/// run drains (the SMA lengths + exposure scale are injected at compile via the
/// point vector). The single source of the sample topology — `build_sample`
/// (the `aura graph` entry) is expressed on top of it.
#[allow(clippy::type_complexity)]
fn sample_blueprint_with_sinks() -> (
    Composite,
    Receiver<(Timestamp, Vec<Scalar>)>,
    Receiver<(Timestamp, Vec<Scalar>)>,
) {
    let (tx_eq, rx_eq) = mpsc::channel();
    let (tx_ex, rx_ex) = mpsc::channel();
    let bp = Composite::new(
        "sample",
        vec![
            BlueprintNode::Composite(sma_cross("sma_cross")),
            Exposure::builder().into(),
            SimBroker::builder(0.0001).into(),
            Recorder::builder(vec![ScalarKind::F64], Firing::Any, tx_eq).into(),
            Recorder::builder(vec![ScalarKind::F64], Firing::Any, tx_ex).into(),
        ],
        vec![
            Edge { from: 0, to: 1, slot: 0, from_field: 0 }, // spread   -> Exposure
            Edge { from: 1, to: 2, slot: 0, from_field: 0 }, // exposure -> broker slot 0
            Edge { from: 2, to: 3, slot: 0, from_field: 0 }, // equity   -> sink
            Edge { from: 1, to: 4, slot: 0, from_field: 0 }, // exposure -> sink
        ],
        vec![Role {
            name: "price".into(),
            targets: vec![
                Target { node: 0, slot: 0 }, // price -> sma_cross role 0
                Target { node: 2, slot: 1 }, // price -> SimBroker price slot
            ],
            source: Some(ScalarKind::F64),
        }],
        vec![], // params: the interior sma_cross carries the aliases
        vec![], // output: the root ends in sinks, no re-export
    );
    (bp, rx_eq, rx_ex)
}

/// The sample blueprint without its sink receivers — the `aura graph` render
/// entry, which never runs the graph (so the receivers are dropped).
fn build_sample() -> Composite {
    sample_blueprint_with_sinks().0
}
```

(The `sample_blueprint()` wrapper at `main.rs:192-194` — `fn sample_blueprint()
-> Composite { build_sample() }` — is unchanged.)

- [ ] **Step 4: Run the test to verify it passes (GREEN)**

Run: `cargo test -p aura-cli --bin aura sample_blueprint_with_sinks`
Expected: PASS — 1 test (`sample_blueprint_with_sinks_bootstraps_runs_and_drains`).

- [ ] **Step 5: Graph non-regression + lint gate**

Run: `cargo test -p aura-cli`
Expected: PASS — the whole aura-cli suite green, **including** the existing graph
golden `graph_emits_self_contained_html_viewer` in `tests/cli_run.rs` (proves the
`build_sample` re-expression did not change the rendered sample topology).

Run: `cargo clippy -p aura-cli --all-targets -- -D warnings`
Expected: clean.

---

## Task 2: `sweep` subcommand — grid, render, and the JSON goldens

**Files:**
- Modify: `crates/aura-cli/src/main.rs:11-17` (imports), `:352` (USAGE),
  `:359-368` (dispatch), plus new fns + tests
- Modify: `crates/aura-cli/tests/cli_run.rs`

- [ ] **Step 1: Write the `sweep_point_to_json` byte-pin test (RED)**

In `crates/aura-cli/src/main.rs`, inside the `#[cfg(test)] mod tests { … }` block,
add this test (a hand-constructed point, so the exact bytes — including the
`12.0 -> 12` / `0.5` token rules — are pinned):

```rust
    #[test]
    fn sweep_point_to_json_renders_canonical_form() {
        let space = vec![
            ParamSpec { name: "sma_cross.fast".into(), kind: ScalarKind::I64 },
            ParamSpec { name: "sma_cross.slow".into(), kind: ScalarKind::I64 },
            ParamSpec { name: "scale".into(), kind: ScalarKind::F64 },
        ];
        let pt = SweepPoint {
            params: vec![Scalar::I64(2), Scalar::I64(4), Scalar::F64(0.5)],
            // fully-qualified: RunMetrics is needed only by this test, so it is not
            // imported into production (where it would be an unused import — the
            // production code reads `pt.metrics` by field, never naming the type).
            metrics: aura_engine::RunMetrics { total_pips: 12.0, max_drawdown: 1.0, exposure_sign_flips: 1 },
        };
        assert_eq!(
            sweep_point_to_json(&pt, &space),
            r#"{"params":{"sma_cross.fast":2,"sma_cross.slow":4,"scale":0.5},"metrics":{"total_pips":12,"max_drawdown":1,"exposure_sign_flips":1}}"#,
        );
    }
```

`SweepPoint` and `ParamSpec` reach this test via the existing `use super::*`
(both are added to production imports in Step 3); `Scalar`/`ScalarKind` are
already in `super` (`main.rs:11`). `RunMetrics` is fully-qualified above, so it
needs no import.

- [ ] **Step 2: Run the test to verify it fails (RED)**

Run: `cargo test -p aura-cli --bin aura sweep_point_to_json`
Expected: FAIL — compile error, `cannot find function sweep_point_to_json` /
`cannot find type SweepPoint` / `cannot find value ParamSpec` (the helpers and
imports do not exist yet).

- [ ] **Step 3: Extend the imports + write the JSON helpers (GREEN for Step 1)**

In `crates/aura-cli/src/main.rs`, change the aura-core import (`main.rs:11`) to add
`ParamSpec`:

```rust
use aura_core::{Firing, ParamSpec, Scalar, ScalarKind, Timestamp};
```

and the aura-engine import (`main.rs:12-15`) to add `GridSpace`, `sweep`, and
`SweepPoint` (NOT `RunMetrics` — it is used only by the Step-1 test, which
fully-qualifies it, so importing it here would be an unused import in the
production build):

```rust
use aura_engine::{
    f64_field, summarize, sweep, BlueprintNode, Composite, Edge, FlatGraph, GridSpace, Harness,
    OutField, ParamAlias, Role, RunManifest, RunReport, SourceSpec, SweepPoint, Target,
};
```

Then add the three render helpers (place them next to the other sample helpers,
e.g. directly after `sample_blueprint()` near `main.rs:194`):

```rust
/// Render one swept point as one canonical JSON object (C14, hand-rolled — the
/// engine's `json_str` is private, so the rules of `RunReport::to_json` are
/// mirrored here, not called): `{"params":{name:value,…},"metrics":{…}}`. Param
/// names come from `param_space()` zipped onto the point vector; `f64` fields use
/// the round-trippable shortest form, so a whole-valued float renders without a
/// fractional part (`12.0` -> `12`).
fn sweep_point_to_json(pt: &SweepPoint, space: &[ParamSpec]) -> String {
    let mut params = String::from("{");
    for (i, (ps, v)) in space.iter().zip(&pt.params).enumerate() {
        if i > 0 {
            params.push(',');
        }
        params.push_str(&json_string(&ps.name));
        params.push(':');
        params.push_str(&scalar_token(*v));
    }
    params.push('}');
    format!(
        "{{\"params\":{params},\"metrics\":{{\"total_pips\":{tp},\"max_drawdown\":{dd},\"exposure_sign_flips\":{fl}}}}}",
        tp = pt.metrics.total_pips,
        dd = pt.metrics.max_drawdown,
        fl = pt.metrics.exposure_sign_flips,
    )
}

/// Minimal JSON string rendering: wrap in quotes, escape `"` and `\` (mirrors the
/// engine's private `json_str`; our param names contain neither, but the escape
/// keeps the helper honest).
fn json_string(s: &str) -> String {
    let mut out = String::with_capacity(s.len() + 2);
    out.push('"');
    for c in s.chars() {
        match c {
            '"' => out.push_str("\\\""),
            '\\' => out.push_str("\\\\"),
            _ => out.push(c),
        }
    }
    out.push('"');
    out
}

/// One scalar as its JSON value token: an integer for `I64`, the shortest
/// round-trippable form for `F64`, `true`/`false` for `Bool`, the epoch-ns
/// integer for a `Timestamp`.
fn scalar_token(v: Scalar) -> String {
    match v {
        Scalar::I64(n) => n.to_string(),
        Scalar::F64(f) => f.to_string(),
        Scalar::Bool(b) => b.to_string(),
        Scalar::Ts(t) => t.0.to_string(),
    }
}
```

- [ ] **Step 4: Run the byte-pin test to verify it passes (GREEN)**

Run: `cargo test -p aura-cli --bin aura sweep_point_to_json`
Expected: PASS — 1 test (`sweep_point_to_json_renders_canonical_form`).

- [ ] **Step 5: Add `sweep_report`, the dispatch arm, and the usage string**

In `crates/aura-cli/src/main.rs`, add the `sweep_report` function (e.g. directly
after `scalar_token`):

```rust
/// Run the built-in sample over a small built-in grid (fast ∈ {2,3},
/// slow ∈ {4,5}, scale ∈ {0.5} — 4 points) and render one JSON line per point in
/// enumeration (odometer) order. Pure + deterministic (C1): the same build yields
/// the same report. Each point builds a fresh blueprint (fresh sink channels),
/// bootstraps it under the point vector, runs it, and folds the drained sinks to
/// metrics — the per-point closure the engine `sweep` drives disjointly.
fn sweep_report() -> String {
    let space = sample_blueprint_with_sinks().0.param_space();
    let grid = GridSpace::new(
        &space,
        vec![
            vec![Scalar::I64(2), Scalar::I64(3)], // fast  ∈ {2, 3}
            vec![Scalar::I64(4), Scalar::I64(5)], // slow  ∈ {4, 5}
            vec![Scalar::F64(0.5)],               // scale ∈ {0.5}
        ],
    )
    .expect("the built-in grid matches the sample param-space");
    let family = sweep(&grid, |point| {
        let (bp, rx_eq, rx_ex) = sample_blueprint_with_sinks();
        let mut h = bp
            .bootstrap_with_params(point.to_vec())
            .expect("grid points are kind-checked against param_space");
        h.run(vec![synthetic_prices()]);
        let equity = f64_field(&rx_eq.try_iter().collect::<Vec<_>>(), 0);
        let exposure = f64_field(&rx_ex.try_iter().collect::<Vec<_>>(), 0);
        summarize(&equity, &exposure)
    });
    let mut out = String::new();
    for pt in &family.points {
        out.push_str(&sweep_point_to_json(pt, &space));
        out.push('\n');
    }
    out
}
```

Change the `USAGE` const (`main.rs:352`) to advertise the new form:

```rust
const USAGE: &str = "usage: aura run [--macd] | aura graph | aura sweep";
```

Add the `["sweep"]` arm to the `match` in `main()` (`main.rs:359-368`), beside the
`["graph"]` arm:

```rust
        ["sweep"] => print!("{}", sweep_report()),
```

(The strict-trailing-token contract is inherited for free: `aura sweep extra`
does not match `["sweep"]` and falls through to the `_` usage-error arm.)

- [ ] **Step 6: Write the `sweep_report` structure goldens (RED then GREEN)**

In `crates/aura-cli/src/main.rs`, inside `#[cfg(test)] mod tests { … }`, add:

```rust
    #[test]
    fn sweep_report_renders_four_points_in_odometer_order() {
        let out = sweep_report();
        let lines: Vec<&str> = out.lines().collect();
        assert_eq!(lines.len(), 4, "one JSON line per grid point; got: {out:?}");
        // params byte-pinned per line: odometer order (last axis fastest) + the
        // param-name and value-token rules. Metric *values* are left to the
        // determinism check below (they are computed f64s, not predictable here).
        assert!(lines[0].starts_with(
            r#"{"params":{"sma_cross.fast":2,"sma_cross.slow":4,"scale":0.5},"metrics":{"#
        ));
        assert!(lines[1].starts_with(
            r#"{"params":{"sma_cross.fast":2,"sma_cross.slow":5,"scale":0.5},"metrics":{"#
        ));
        assert!(lines[2].starts_with(
            r#"{"params":{"sma_cross.fast":3,"sma_cross.slow":4,"scale":0.5},"metrics":{"#
        ));
        assert!(lines[3].starts_with(
            r#"{"params":{"sma_cross.fast":3,"sma_cross.slow":5,"scale":0.5},"metrics":{"#
        ));
        for line in &lines {
            assert!(line.contains(r#""total_pips":"#), "missing total_pips: {line}");
            assert!(line.contains(r#""max_drawdown":"#), "missing max_drawdown: {line}");
            assert!(line.contains(r#""exposure_sign_flips":"#), "missing flips: {line}");
            assert!(line.ends_with('}'), "line not closed: {line}");
        }
    }

    #[test]
    fn sweep_report_is_deterministic() {
        // C1 at the CLI edge: the same build yields a bit-identical report.
        assert_eq!(sweep_report(), sweep_report());
    }
```

Run: `cargo test -p aura-cli --bin aura sweep_report`
Expected: PASS — 2 tests (`sweep_report_renders_four_points_in_odometer_order`,
`sweep_report_is_deterministic`). (If run before Step 5's `sweep_report` exists,
this fails to compile — that is the RED state.)

- [ ] **Step 7: Write the `aura sweep` process golden (RED then GREEN)**

In `crates/aura-cli/tests/cli_run.rs`, append:

```rust
#[test]
fn sweep_prints_four_json_lines_and_exits_zero() {
    let out = Command::new(BIN).arg("sweep").output().expect("spawn aura sweep");
    assert!(out.status.success(), "exit status: {:?}", out.status);

    let stdout = String::from_utf8(out.stdout).expect("utf-8 stdout");
    // one JSON line per grid point (4-point built-in grid), each terminated by a
    // newline from `sweep_report`.
    assert_eq!(stdout.lines().count(), 4, "stdout was: {stdout:?}");
    // the first line is the first odometer point (fast=2, slow=4), params pinned.
    assert!(
        stdout.lines().next().unwrap().starts_with(
            "{\"params\":{\"sma_cross.fast\":2,\"sma_cross.slow\":4,\"scale\":0.5},\"metrics\":{"
        ),
        "got: {stdout}"
    );
}

#[test]
fn sweep_with_trailing_token_is_strict_and_exits_two() {
    // strict-arg reading (#16): an unexpected trailing token is a usage error.
    let out = Command::new(BIN).args(["sweep", "extra"]).output().expect("spawn aura");
    assert_eq!(out.status.code(), Some(2), "exit status: {:?}", out.status);
}
```

Run: `cargo test -p aura-cli --test cli_run sweep`
Expected: PASS — 2 tests (`sweep_prints_four_json_lines_and_exits_zero`,
`sweep_with_trailing_token_is_strict_and_exits_two`).

- [ ] **Step 8: Full workspace build + test + lint gate**

Run: `cargo build --workspace`
Expected: success.

Run: `cargo test --workspace`
Expected: PASS — the whole suite green, including the new aura-cli `sweep` tests
and all pre-existing tests (no regression — the engine sweep tests from iter 1,
the `aura run`/`aura graph` goldens, the MACD tests).

Run: `cargo clippy --workspace --all-targets -- -D warnings`
Expected: clean (no warnings).