diff --git a/docs/plans/0036-sample-showcase-blueprint.md b/docs/plans/0036-sample-showcase-blueprint.md new file mode 100644 index 0000000..6a78edd --- /dev/null +++ b/docs/plans/0036-sample-showcase-blueprint.md @@ -0,0 +1,497 @@ +# 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.