# 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.