Aura/docs/plans/0036-sample-showcase-blueprint.md

# Sample Showcase Blueprint — Implementation Plan

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

**Goal:** Enrich the `aura graph` / `aura sweep` sample blueprint into a "trend +
momentum, weighted blend" strategy that demonstrates multiply-nested composites, a
multi-param node inside a composite, a multi-output (MACD-like) node, and `bind()`.

**Architecture:** A new `signals` composite (root → `signals` → {`trend` =
`sma_cross`, `momentum` = `macd`}, plus a `LinComb(3)` `blend`) replaces the bare
`sma_cross` at node 0 of `sample_blueprint_with_sinks`. Pure authoring over
already-shipped primitives — no engine/viewer change. The sweep re-paths its axes
to the new param-space; a longer warm-up stream lets the enriched signal run; the
render fixture is re-captured; a new headless guard protects depth-2 nesting.

**Tech Stack:** `crates/aura-cli/src/main.rs` (the sample + sweep + their in-crate
tests), `crates/aura-cli/tests/fixtures/sample-model.json` (render golden), a new
`crates/aura-cli/tests/` headless guard pair. Reuses `aura_std::LinComb` + the
existing `sma_cross`/`macd` builders. No change to `aura-engine` or
`graph-viewer.js`.

---

**Files this plan creates or modifies:**

- Modify: `crates/aura-cli/src/main.rs:17` — add `LinComb` to the `aura_std` import.
- Modify: `crates/aura-cli/src/main.rs` — add `fn signals(name: &str) -> Composite`
  and `fn showcase_prices() -> Vec<(Timestamp, Scalar)>`; swap node 0 of
  `sample_blueprint_with_sinks` (`:173`); re-path the `sweep_family` axes (`:228-230`)
  and swap its closure stream (`:236`).
- Modify: `crates/aura-cli/src/main.rs:503-540` — re-path the two in-crate tests
  (`sample_blueprint_with_sinks_bootstraps_runs_and_drains`,
  `sweep_report_renders_four_points_in_odometer_order`).
- Modify: `crates/aura-cli/tests/fixtures/sample-model.json` — re-captured enriched model.
- Create: `crates/aura-cli/tests/viewer_nested_depth.mjs` — headless depth-2 DOT-id guard.
- Create: `crates/aura-cli/tests/viewer_nested_depth.rs` — `.rs` wrapper that runs the `.mjs` under `node`.

**Untouched (must stay green):** `run_sample`/`sample_harness`, `run_macd`/`macd()`/
`macd_point`, `crates/aura-engine/src/graph_model.rs` `model_golden` (own minimal
`sample_root()`), `crates/aura-cli/assets/graph-viewer.js`, `crates/aura-cli/src/render.rs`.

**Parse-the-bytes gate (planner self-review item 9):** the project declares no
spec-validation parsers in its CLAUDE.md project facts → documented no-op. The
inlined Rust is source-language (the `implement` compile gate catches it, not the
parse gate); the `.mjs` is JS with no declared parser; the fixture JSON is
machine-generated (Task 3), not hand-inlined. Gate fires empty.

---

### Task 1: Enriched blueprint source

**Files:**
- Modify: `crates/aura-cli/src/main.rs:17` (import), plus new fns + the
  `sample_blueprint_with_sinks` node-0 swap (`:173`) + `sweep_family` axes (`:228-230`)
  and stream (`:236`).

- [ ] **Step 1: Add `LinComb` to the `aura_std` import**

Replace `crates/aura-cli/src/main.rs:17`:

```rust
use aura_std::{Ema, Exposure, Recorder, SimBroker, Sma, Sub};
```

with:

```rust
use aura_std::{Ema, Exposure, LinComb, Recorder, SimBroker, Sma, Sub};
```

- [ ] **Step 2: Add the `signals` composite builder**

Insert this fn immediately after `fn sma_cross(...)` (which ends at `:155`), before
`fn sample_blueprint_with_sinks`:

```rust
/// The blended signal: a trend leg (SMA-cross) and a momentum leg (MACD), combined
/// by a weighted sum. A multiply-nested composite (root → signals → {trend,
/// momentum}); the blend is a multi-param node living inside it, with one weight
/// bound as a structural constant (so it drops out of the sweepable surface).
fn signals(name: &str) -> Composite {
    Composite::new(
        name,
        vec![
            BlueprintNode::Composite(sma_cross("trend")), // 0 trend leg (one f64 "cross")
            BlueprintNode::Composite(macd("momentum")),   // 1 momentum leg (3 outputs)
            // 2 blend: Σ wᵢ·termᵢ over [trend.cross, momentum.histogram, momentum.signal].
            // weights[2] is bound (a fixed signal-line weight) → removed from param_space;
            // weights[0]/[1] stay tunable. `.named("blend")` makes the path signals.blend.*
            // (and renders the `blend:` prefix).
            LinComb::builder(3)
                .named("blend")
                .bind("weights[2]", Scalar::F64(0.5))
                .into(),
        ],
        vec![
            Edge { from: 0, to: 2, slot: 0, from_field: 0 }, // trend.cross        → blend.term[0]
            Edge { from: 1, to: 2, slot: 1, from_field: 2 }, // momentum.histogram → blend.term[1]
            Edge { from: 1, to: 2, slot: 2, from_field: 1 }, // momentum.signal    → blend.term[2]
        ],
        vec![Role {
            name: "price".into(),
            targets: vec![
                Target { node: 0, slot: 0 }, // price → trend role 0
                Target { node: 1, slot: 0 }, // price → momentum role 0
            ],
            source: None,
        }],
        vec![OutField { node: 2, field: 0, name: "signal".into() }],
    )
}
```

- [ ] **Step 3: Add the `showcase_prices` warm-up stream**

Insert this fn next to `signals` (anywhere in the non-test region; suggested: right
after `synthetic_prices`, which ends at `:36`):

```rust
/// A warm-up-adequate synthetic stream for the enriched sample/sweep: ~18 ticks
/// rising, falling, then rising again so the trend SMA spread and the MACD
/// EMA-of-EMA histogram both warm up and flip sign. It shares the proven warm-up
/// profile of `macd_prices` (the enriched sample embeds the same `macd` composite,
/// so it needs the same warm-up length); the flat `run_sample` keeps the shorter
/// `synthetic_prices`. Deterministic and fixed (C1).
fn showcase_prices() -> Vec<(Timestamp, Scalar)> {
    [
        1.0000_f64, 1.0008, 1.0021, 1.0039, 1.0062, 1.0090, 1.0083, 1.0061, 1.0034,
        1.0012, 0.9998, 1.0006, 1.0024, 1.0047, 1.0069, 1.0086, 1.0097, 1.0092,
    ]
    .iter()
    .enumerate()
    .map(|(i, &p)| (Timestamp(i as i64 + 1), Scalar::F64(p)))
    .collect()
}
```

- [ ] **Step 4: Swap node 0 of `sample_blueprint_with_sinks`**

Replace `crates/aura-cli/src/main.rs:173`:

```rust
            BlueprintNode::Composite(sma_cross("sma_cross")),
```

with:

```rust
            BlueprintNode::Composite(signals("signals")),
```

(The other four root nodes, the root edges `:179-184`, and the `price` role `:185-192`
are unchanged: `signals` re-exports a single f64 `"signal"`, the same one-output shape
`sma_cross` re-exported as `"cross"`, so `signals.out0 → Exposure` keeps working.)

- [ ] **Step 5: Re-path the `sweep_family` axes**

Replace the axis chain at `crates/aura-cli/src/main.rs:228-230`:

```rust
    bp.axis("sma_cross.fast.length", [2, 3])
        .axis("sma_cross.slow.length", [4, 5])
        .axis("exposure.scale", [0.5])
```

with the eight free-param axes (two real on the trend lengths, the rest singletons →
still 4 points; `signals.blend.weights[2]` is bound, so it is **not** an axis):

```rust
    bp.axis("signals.trend.fast.length", [2, 3])
        .axis("signals.trend.slow.length", [4, 5])
        .axis("signals.momentum.fast.length", [2])
        .axis("signals.momentum.slow.length", [4])
        .axis("signals.momentum.signal.length", [3])
        .axis("signals.blend.weights[0]", [1.0])
        .axis("signals.blend.weights[1]", [1.0])
        .axis("exposure.scale", [0.5])
```

- [ ] **Step 6: Swap the sweep closure's stream to `showcase_prices`**

In the same `sweep_family` closure, replace the single call at
`crates/aura-cli/src/main.rs:236`:

```rust
            let prices = synthetic_prices();
```

with:

```rust
            let prices = showcase_prices();
```

(The rest of the closure — window, run, drain, fold — is unchanged.)

- [ ] **Step 7: Build + clippy gate (source only)**

Run: `cargo build -p aura-cli`
Expected: compiles, `0 errors` (the in-crate tests still reference the old param
strings — they compile fine as data; they FAIL at test-time, which Task 2 fixes).

Run: `cargo clippy -p aura-cli --all-targets -- -D warnings`
Expected: clean — `signals` is used by the node-0 swap and `showcase_prices` by the
sweep closure, so no `dead_code` warning.

---

### Task 2: Re-path the in-crate tests

**Files:**
- Modify: `crates/aura-cli/src/main.rs:503-517` (`sample_blueprint_with_sinks_bootstraps_runs_and_drains`)
- Modify: `crates/aura-cli/src/main.rs:519-540` (`sweep_report_renders_four_points_in_odometer_order`)

- [ ] **Step 1: Re-path + re-stream the bootstrap-runs-drains test**

Replace the body of `sample_blueprint_with_sinks_bootstraps_runs_and_drains`
(`:507-514`) — set all eight free params via `.with()` (the bound `weights[2]` is
NOT set) and run the warm-up stream:

```rust
        let (bp, rx_eq, rx_ex) = sample_blueprint_with_sinks();
        let mut h = bp
            .with("signals.trend.fast.length", 2)
            .with("signals.trend.slow.length", 4)
            .with("signals.momentum.fast.length", 2)
            .with("signals.momentum.slow.length", 4)
            .with("signals.momentum.signal.length", 3)
            .with("signals.blend.weights[0]", 1.0)
            .with("signals.blend.weights[1]", 1.0)
            .with("exposure.scale", 0.5)
            .bootstrap()
            .expect("sample blueprint compiles under a valid point");
        h.run(vec![showcase_prices()]);
```

(The two `assert!(... drained empty)` lines at `:515-516` are unchanged — the
18-tick stream warms every leg, so both sinks drain non-empty.)

- [ ] **Step 2: Re-path the sweep-report odometer assertions**

Replace the four param-row assertions at `crates/aura-cli/src/main.rs:530-533` with
the re-pathed rows (param-space render order: trend.fast, trend.slow, momentum
fast/slow/signal, blend weights[0]/[1], exposure.scale — the two trend lengths vary,
trend.slow fastest, the rest constant). Each row is one contiguous string:

```rust
        assert!(lines[0].contains(r#""params":[["signals.trend.fast.length",2.0],["signals.trend.slow.length",4.0],["signals.momentum.fast.length",2.0],["signals.momentum.slow.length",4.0],["signals.momentum.signal.length",3.0],["signals.blend.weights[0]",1.0],["signals.blend.weights[1]",1.0],["exposure.scale",0.5]]"#), "line0: {}", lines[0]);
        assert!(lines[1].contains(r#""params":[["signals.trend.fast.length",2.0],["signals.trend.slow.length",5.0],["signals.momentum.fast.length",2.0],["signals.momentum.slow.length",4.0],["signals.momentum.signal.length",3.0],["signals.blend.weights[0]",1.0],["signals.blend.weights[1]",1.0],["exposure.scale",0.5]]"#), "line1: {}", lines[1]);
        assert!(lines[2].contains(r#""params":[["signals.trend.fast.length",3.0],["signals.trend.slow.length",4.0],["signals.momentum.fast.length",2.0],["signals.momentum.slow.length",4.0],["signals.momentum.signal.length",3.0],["signals.blend.weights[0]",1.0],["signals.blend.weights[1]",1.0],["exposure.scale",0.5]]"#), "line2: {}", lines[2]);
        assert!(lines[3].contains(r#""params":[["signals.trend.fast.length",3.0],["signals.trend.slow.length",5.0],["signals.momentum.fast.length",2.0],["signals.momentum.slow.length",4.0],["signals.momentum.signal.length",3.0],["signals.blend.weights[0]",1.0],["signals.blend.weights[1]",1.0],["exposure.scale",0.5]]"#), "line3: {}", lines[3]);
```

(Lines `:520-529` — the 4-line count, the `{"manifest":{"commit":"` prefix check —
and the metric-key block `:534-539` are unchanged: structurally still 4 points with
the same metric keys.)

- [ ] **Step 3: Run the in-crate tests**

Run: `cargo test -p aura-cli`
Expected: PASS — including `sample_blueprint_with_sinks_bootstraps_runs_and_drains`,
`sweep_report_renders_four_points_in_odometer_order`, `sweep_report_is_deterministic`
(re-runs the enriched sweep; deterministic), and the untouched `run_sample_*` /
`run_macd_*` / `macd_param_space_*` tests. (The integration guards still read the
not-yet-re-captured fixture — they stay green on the old fixture until Task 3.)

Note: if a `sweep_report` row mismatches at runtime, the param **names** are fixed
(param-space order above) — re-capture only the **values/order** by reading the
actual failing-assert output (`{}` prints the real line) and correcting that row;
do not change the param names.

---

### Task 3: Re-capture the `sample-model.json` fixture

**Files:**
- Modify: `crates/aura-cli/tests/fixtures/sample-model.json`

- [ ] **Step 1: Add a temporary capture test**

Insert into `crates/aura-cli/src/main.rs` `mod tests` (e.g. after
`sample_blueprint_with_sinks_bootstraps_runs_and_drains`):

```rust
    #[test]
    fn capture_sample_model_tmp() {
        println!("AURA_MODEL_CAPTURE:{}", aura_engine::model_to_json(&sample_blueprint()));
    }
```

- [ ] **Step 2: Capture the enriched model into the fixture**

Run (one positional filter; prefix-grep isolates the model line, strip it, write the file):

```
cargo test -p aura-cli capture_sample_model_tmp -- --nocapture 2>/dev/null \
  | grep '^AURA_MODEL_CAPTURE:' | sed 's/^AURA_MODEL_CAPTURE://' \
  > crates/aura-cli/tests/fixtures/sample-model.json
```

Expected: `crates/aura-cli/tests/fixtures/sample-model.json` is one line of valid
JSON whose root node `"0"` is now `{"comp":"signals"}` and whose `"composites"`
object carries `signals`, `trend`, `momentum` (and no longer a top-level
`sma_cross`). Verify it parses:

Run: `node -e "JSON.parse(require('fs').readFileSync('crates/aura-cli/tests/fixtures/sample-model.json','utf8')); console.log('OK valid JSON')"`
Expected: `OK valid JSON`

- [ ] **Step 3: Remove the temporary capture test**

Delete the `capture_sample_model_tmp` test added in Step 1.

- [ ] **Step 4: Confirm the fixture consumers stay green**

Run: `cargo test -p aura-cli --test viewer_dot`
Expected: PASS (the re-captured fixture still yields valid Graphviz ids at depth 1;
`viewer_dot.rs` is the `.rs` wrapper that runs `viewer_dot_ids.mjs`).

Run: `cargo test -p aura-cli render_html_is_self_contained`
Expected: PASS (the live render still contains `"type":"Exposure"` and starts at `{"root":`).

---

### Task 4: Depth-2 render guard

**Files:**
- Create: `crates/aura-cli/tests/viewer_nested_depth.mjs`
- Create: `crates/aura-cli/tests/viewer_nested_depth.rs`

- [ ] **Step 1: Write the headless depth-2 guard**

Create `crates/aura-cli/tests/viewer_nested_depth.mjs`:

```javascript
// Headless depth-2 nesting guard for the `aura graph` viewer (graph-viewer.js).
//
// Property protected: the viewer renders MULTIPLY-nested composites — a composite
// inside a composite inside the root — with valid Graphviz node identifiers at
// every depth. genDot builds ids as `n` + the node-key path joined by `__`
// (graph-viewer.js: `cid = "n" + cpath.join("__")`), so a depth-2 interior node
// gets a three-segment id like `n0__0__0`. A digit-led non-numeral id (`0__0__0`)
// would be misparsed by Graphviz and collapse the interior; this guard pins that
// the `n`-prefix rule holds at depth 2, beyond the depth-1 viewer_dot_ids.mjs guard.
//
// It loads the real viewer module and the re-captured sample fixture (which is now
// the enriched root → signals → {trend, momentum} graph), then EXPANDS RECURSIVELY:
// discover the top-level expandable (signals), expand, re-discover the newly
// revealed expandables (trend, momentum), expand those — until none remain — and
// asserts (a) every DOT id is valid and (b) at least one three-segment (depth-2) id
// was actually produced, so the guard cannot pass vacuously on a flat model.

import { createRequire } from "node:module";
import { readFileSync } from "node:fs";
import { fileURLToPath } from "node:url";
import { dirname, join } from "node:path";

const require = createRequire(import.meta.url);
const here = dirname(fileURLToPath(import.meta.url));

const model = JSON.parse(readFileSync(join(here, "fixtures", "sample-model.json"), "utf8"));

// Stub the global BEFORE requiring the viewer (mirrors the browser bootstrap).
global.window = { AURA_MODEL: model };
const { normalizeModel, genDot } = require(join(here, "..", "assets", "graph-viewer.js"));
const ROOT = normalizeModel(model).root;

// Expand every expandable composite, re-discovering deeper ones each pass, until
// the expandable set stops growing (reaches every nesting level).
let expanded = new Set();
let dot = "";
for (let pass = 0; pass < 16; pass++) {
  const g = genDot(ROOT, "root", expanded, false);
  dot = g.dot;
  const fresh = g.expandable.filter((id) => !expanded.has(id));
  if (!fresh.length) break;
  fresh.forEach((id) => expanded.add(id));
}

// Collect every node identifier referenced in the final DOT (node-def lines + edge
// endpoints), mirroring viewer_dot_ids.mjs.
const ids = new Set();
for (const m of dot.matchAll(/^\s*([^\s\[]+)\s*\[label=/gm)) ids.add(m[1]);
for (const m of dot.matchAll(/(\S+?):[a-z]\w*:[a-z]\s*->\s*(\S+?):[a-z]\w*:[a-z]/g)) {
  ids.add(m[1]);
  ids.add(m[2]);
}

const QUOTED = /^".*"$/s;
const NUMERAL = /^-?(\.[0-9]+|[0-9]+(\.[0-9]*)?)$/;
const BARE = /^[A-Za-z_][A-Za-z0-9_]*$/;
const isValid = (id) => QUOTED.test(id) || NUMERAL.test(id) || BARE.test(id);

const bad = [...ids].filter((id) => !isValid(id));
if (bad.length) {
  console.error(
    "INVALID DOT node identifier(s) at nesting depth — Graphviz will misparse a\n" +
    "digit-prefixed, non-numeral id and collapse the nested composite:\n  " +
    bad.map((id) => JSON.stringify(id)).join("\n  ")
  );
  process.exit(1);
}

// Anti-vacuous: at least one three-segment (depth-2) id must exist, proving the
// guard actually expanded two composite levels (root → signals → trend/momentum).
const depth2 = [...ids].filter((id) => /^n\d+__\d+__\d+/.test(id));
if (!depth2.length) {
  console.error(
    "no depth-2 (three-segment `nA__B__C`) id found — the guard did not reach two\n" +
    "nesting levels; the fixture is not multiply-nested or the expand loop stalled."
  );
  process.exit(1);
}

console.log(`OK — ${ids.size} DOT ids valid; ${depth2.length} reached nesting depth 2.`);
process.exit(0);
```

- [ ] **Step 2: Write the `.rs` wrapper**

Create `crates/aura-cli/tests/viewer_nested_depth.rs` (mirrors `viewer_name_prefix.rs`):

```rust
//! Integration guard: the `aura graph` viewer renders multiply-nested composites
//! (a composite inside a composite inside the root) with valid Graphviz node ids
//! at every depth.
//!
//! Like `viewer_dot_ids.rs`/`viewer_dot.rs`, the property lives in JavaScript
//! (`genDot` in assets/graph-viewer.js), so this shells out to `node` running the
//! headless guard `tests/viewer_nested_depth.mjs`, which loads the real viewer
//! module and the re-captured sample fixture and expands it recursively to depth 2.
//!
//! `node` is REQUIRED: if it is not on PATH this test FAILS (a skipped guard is
//! not a guard).

use std::path::PathBuf;
use std::process::Command;

#[test]
fn viewer_renders_nested_composites_to_depth_2_with_valid_ids() {
    let script = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
        .join("tests")
        .join("viewer_nested_depth.mjs");
    assert!(
        script.exists(),
        "guard script missing at {}",
        script.display()
    );

    let out = match Command::new("node").arg(&script).output() {
        Ok(out) => out,
        Err(e) => panic!(
            "node is required for the viewer depth-2 nesting guard but could not be run \
             ({e}); install Node.js or ensure `node` is on PATH"
        ),
    };

    let stdout = String::from_utf8_lossy(&out.stdout);
    let stderr = String::from_utf8_lossy(&out.stderr);
    assert!(
        out.status.success(),
        "viewer depth-2 nesting guard failed (exit {:?}).\n--- node stdout ---\n{stdout}\n--- node stderr ---\n{stderr}",
        out.status.code()
    );
}
```

- [ ] **Step 3: Run the new guard**

Run: `cargo test -p aura-cli --test viewer_nested_depth`
Expected: PASS — `OK — N DOT ids valid; M reached nesting depth 2.` (M ≥ 1). This
confirms the depth-2 nesting renders with valid ids against the re-captured fixture.

---

### Task 5: Workspace gate

**Files:** none (verification only).

- [ ] **Step 1: Full build**

Run: `cargo build --workspace`
Expected: compiles, `0 errors`.

- [ ] **Step 2: Full test suite**

Run: `cargo test --workspace`
Expected: PASS — all crates, including the re-pathed in-crate tests, the re-captured
fixture consumers, the new `viewer_nested_depth` guard, and the untouched engine
`model_golden` / `nested_composite_inlines` / `param_space_*` tests.

- [ ] **Step 3: Clippy**

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