# `aura graph` ASCII-DAG render — Implementation Plan

> **Parent spec:** `docs/specs/0013-aura-graph-ascii-dag.md`
>
> **For agentic workers:** REQUIRED SUB-SKILL: use the `implement` skill to run
> this plan. Steps use `- [ ]` checkboxes for tracking.

**Goal:** Render a wired graph as an ASCII DAG via an `aura graph [--compiled]`
subcommand so a mis-wiring becomes visible, with composites drawn as named
cluster boxes (blueprint view) or dissolved (compiled view).

**Architecture:** A non-load-bearing `label()` default method on the core `Node`
trait (aura-core) lets each node describe itself in one line with its params;
`Composite` gains an authored `name`; the engine exposes read-only graph-as-data
accessors and stays dependency-free; the `ascii-dag` adapter and the `aura graph`
subcommand live in aura-cli.

**Tech Stack:** aura-core (`Node` trait), aura-std (node `label()` overrides),
aura-engine (`blueprint.rs` accessors + `Composite.name`), aura-cli (`ascii-dag`
v0.9.1, new `graph.rs`), `docs/design/INDEX.md` (C8 refinement note).

---

## Files this plan creates or modifies

- Modify: `crates/aura-core/src/node.rs:65-68` — add `label()` default method to `trait Node`.
- Test: `crates/aura-core/src/node.rs:70-82` — default-label unit test.
- Modify: `docs/design/INDEX.md` (after line 238, before `### C9` at 240) — C8 refinement note.
- Modify: `crates/aura-std/src/sma.rs:22-46`, `sub.rs:27-47`, `exposure.rs:23-39`, `sim_broker.rs:59-85`, `add.rs:36-56`, `lincomb.rs:42-66`, `recorder.rs:31-58` — `label()` overrides.
- Test: `crates/aura-std/src/sma.rs:48` (tests module) — disambiguation test.
- Modify: `crates/aura-engine/src/blueprint.rs` — `Composite.name` field (54-59), widened `Composite::new` (64-71), accessors on `Composite` (61-90) and `Blueprint` (115-161), and the 7 `Composite::new` call sites (356, 433, 481, 513, 527, 541, 631).
- Create: `crates/aura-cli/src/graph.rs` — the ascii-dag adapter (`render_blueprint`, `render_flat_graph`).
- Modify: `crates/aura-cli/Cargo.toml:12-15` — add `ascii-dag = "0.9.1"`.
- Modify: `crates/aura-cli/src/main.rs` — imports (9-14), `mod graph;`, sample builders, `graph` dispatch arm + usage strings (114-126). `sample_harness` (42-78) and `run_sample` (83-112) are NOT touched.
- Test: `crates/aura-cli/src/main.rs:128-168` (tests module) — render tests.

---

## Task 1: `Node::label()` default method + C8 ledger refinement

**Files:**
- Modify: `crates/aura-core/src/node.rs:65-68`
- Test: `crates/aura-core/src/node.rs:70-82`
- Modify: `docs/design/INDEX.md` (after line 238)

- [ ] **Step 1: Write the failing test**

In `crates/aura-core/src/node.rs`, inside the existing `#[cfg(test)] mod tests` block (currently lines 70-82), add this test after `input_spec_carries_firing`:

```rust
    #[test]
    fn default_label_is_placeholder() {
        // A node that does not override label() falls back to the placeholder.
        struct Bare;
        impl Node for Bare {
            fn schema(&self) -> NodeSchema {
                NodeSchema { inputs: vec![], output: vec![] }
            }
            fn eval(&mut self, _ctx: Ctx<'_>) -> Option<&[Scalar]> {
                None
            }
        }
        assert_eq!(Bare.label(), "node");
    }
```

- [ ] **Step 2: Run test to verify it fails**

Run: `cargo test -p aura-core default_label_is_placeholder`
Expected: FAIL — compile error `no method named 'label' found for struct 'Bare'` (the default method does not exist yet).

- [ ] **Step 3: Add the `label()` default method**

In `crates/aura-core/src/node.rs`, change the `trait Node` body (lines 65-68) from:

```rust
pub trait Node {
    fn schema(&self) -> NodeSchema;
    fn eval(&mut self, ctx: Ctx<'_>) -> Option<&[Scalar]>;
}
```

to:

```rust
pub trait Node {
    fn schema(&self) -> NodeSchema;
    fn eval(&mut self, ctx: Ctx<'_>) -> Option<&[Scalar]>;
    /// A one-line, **non-load-bearing** render label (C23): a debug symbol for
    /// tracing / graph rendering (#13), never read by the run loop and never
    /// part of wiring (which is by index). Overrides SHOULD carry the node's
    /// identifying params so identical node types disambiguate (`SMA(2)` vs
    /// `SMA(4)`). MUST be single-line (no `\n`): ascii-dag breaks box drawing on
    /// a multiline label. The default is a placeholder; every shipped node
    /// overrides it. Returns an owned `String` and takes `&self`, so `Node`
    /// stays object-safe and `Box<dyn Node>::label()` dispatches.
    fn label(&self) -> String {
        "node".to_string()
    }
}
```

- [ ] **Step 4: Run test to verify it passes**

Run: `cargo test -p aura-core default_label_is_placeholder`
Expected: PASS.

- [ ] **Step 5: Append the C8 refinement note to the ledger**

In `docs/design/INDEX.md`, immediately after the cycle-0006 realization paragraph that ends at line 238 (and before `### C9` at line 240), insert:

```markdown
**Refinement (Construction-layer milestone — render labels, 2026-06-05).** A node
additionally exposes `label() -> String`, a **single-line, non-load-bearing**
render symbol: a default trait method the run loop never calls (wiring is by
index, C23). Overrides carry the node's identifying params (`SMA(2)` vs `SMA(4)`)
so a graph render (C9 graph-as-data, #13) disambiguates identical node types and
surfaces a mis-wiring. Like `FieldSpec.name`, it is an informative debug symbol,
not part of the C8 dataflow contract — adding it changes no run behaviour.
```

- [ ] **Step 6: Verify the workspace still builds (default method breaks no caller)**

Run: `cargo build --workspace`
Expected: builds clean (the defaulted method adds no obligation to existing `impl Node`s).

---

## Task 2: aura-std `label()` overrides + disambiguation test

**Files:**
- Modify: `crates/aura-std/src/{sma,sub,exposure,sim_broker,add,lincomb,recorder}.rs`
- Test: `crates/aura-std/src/sma.rs:48` (tests module)

- [ ] **Step 1: Write the failing disambiguation test**

In `crates/aura-std/src/sma.rs`, inside the existing `#[cfg(test)] mod tests` (line 48), add:

```rust
    #[test]
    fn labels_carry_identifying_params() {
        use crate::{Add, Exposure, LinComb, Recorder, SimBroker, Sub};
        use aura_core::{Firing, ScalarKind};

        // the load-bearing payoff: two SMAs disambiguate by window
        assert_eq!(Sma::new(2).label(), "SMA(2)");
        assert_eq!(Sma::new(4).label(), "SMA(4)");
        // param-carrying single nodes
        assert_eq!(Exposure::new(0.5).label(), "Exposure(0.5)");
        assert_eq!(SimBroker::new(0.0001).label(), "SimBroker(0.0001)");
        // bare-kind nodes (identity is not a mis-wiring axis here, per spec)
        assert_eq!(Sub::new().label(), "Sub");
        assert_eq!(Add::new().label(), "Add");
        assert_eq!(LinComb::new(&[1.0, -1.0]).label(), "LinComb");
        let (tx, _rx) = std::sync::mpsc::channel();
        assert_eq!(Recorder::new(&[ScalarKind::F64], Firing::Any, tx).label(), "Recorder");
    }
```

- [ ] **Step 2: Run test to verify it fails**

Run: `cargo test -p aura-std labels_carry_identifying_params`
Expected: FAIL — assertions fail because every node currently returns the default `"node"` (e.g. `assert_eq!(Sma::new(2).label(), "SMA(2)")` sees `"node"`).

> If `LinComb::new` does not take `&[f64]`, read `crates/aura-std/src/lincomb.rs` for its real constructor signature and adjust the call in this test to construct a valid `LinComb`; the asserted label `"LinComb"` is unchanged.

- [ ] **Step 3: Add the `label()` override to each node**

In each file, add the `label()` method as the last method inside the `impl Node for <T>` block:

`crates/aura-std/src/sma.rs` (impl at 22-46, field `length` at line 10):
```rust
    fn label(&self) -> String {
        format!("SMA({})", self.length)
    }
```
`crates/aura-std/src/sub.rs` (impl at 27-47):
```rust
    fn label(&self) -> String {
        "Sub".to_string()
    }
```
`crates/aura-std/src/exposure.rs` (impl at 23-39, field `scale` at line 11):
```rust
    fn label(&self) -> String {
        format!("Exposure({})", self.scale)
    }
```
`crates/aura-std/src/sim_broker.rs` (impl at 59-85, field `pip_size` at line 37):
```rust
    fn label(&self) -> String {
        format!("SimBroker({})", self.pip_size)
    }
```
`crates/aura-std/src/add.rs` (impl at 36-56):
```rust
    fn label(&self) -> String {
        "Add".to_string()
    }
```
`crates/aura-std/src/lincomb.rs` (impl at 42-66):
```rust
    fn label(&self) -> String {
        "LinComb".to_string()
    }
```
`crates/aura-std/src/recorder.rs` (impl at 31-58):
```rust
    fn label(&self) -> String {
        "Recorder".to_string()
    }
```

- [ ] **Step 4: Run test to verify it passes**

Run: `cargo test -p aura-std labels_carry_identifying_params`
Expected: PASS.

- [ ] **Step 5: Verify the crate builds clean**

Run: `cargo build -p aura-std`
Expected: builds clean.

---

## Task 3: `Composite.name` + introspection accessors + thread the 7 call sites

**Files:**
- Modify: `crates/aura-engine/src/blueprint.rs` (struct 54-59, `new` 64-71, `impl Composite` 61-90, `impl Blueprint` 115-161, call sites 356/433/481/513/527/541/631)

- [ ] **Step 1: Add the `name` field to `Composite`**

In `crates/aura-engine/src/blueprint.rs`, change the `Composite` struct (lines 54-59) from:

```rust
pub struct Composite {
    nodes: Vec<BlueprintNode>,
    edges: Vec<Edge>,
    input_roles: Vec<Vec<Target>>,
    output: OutPort,
}
```

to:

```rust
pub struct Composite {
    name: String,
    nodes: Vec<BlueprintNode>,
    edges: Vec<Edge>,
    input_roles: Vec<Vec<Target>>,
    output: OutPort,
}
```

- [ ] **Step 2: Widen `Composite::new` to take a name**

Change `Composite::new` (lines 64-71) from:

```rust
    pub fn new(
        nodes: Vec<BlueprintNode>,
        edges: Vec<Edge>,
        input_roles: Vec<Vec<Target>>,
        output: OutPort,
    ) -> Self {
        Self { nodes, edges, input_roles, output }
    }
```

to:

```rust
    /// Build a composite from its authored name, interior items, interior edges
    /// (local indices), input roles, and output port. The `name` is a
    /// non-load-bearing render symbol (the cluster title for #13); it does not
    /// reach the flat graph (the boundary dissolves at inline, C23).
    pub fn new(
        name: impl Into<String>,
        nodes: Vec<BlueprintNode>,
        edges: Vec<Edge>,
        input_roles: Vec<Vec<Target>>,
        output: OutPort,
    ) -> Self {
        Self { name: name.into(), nodes, edges, input_roles, output }
    }
```

- [ ] **Step 3: Add read-only accessors to `Composite`**

In the `impl Composite` block (61-90), add these methods (e.g. after `new`, before `schema`):

```rust
    /// The authored render name (cluster title, #13). Non-load-bearing.
    pub fn name(&self) -> &str {
        &self.name
    }
    /// The interior blueprint items (read-only graph-as-data, C9).
    pub fn nodes(&self) -> &[BlueprintNode] {
        &self.nodes
    }
    /// The interior edges (local indices).
    pub fn edges(&self) -> &[Edge] {
        &self.edges
    }
    /// The input roles: role `r` fans into `input_roles()[r]` interior targets.
    pub fn input_roles(&self) -> &[Vec<Target>] {
        &self.input_roles
    }
    /// The single exposed output port.
    pub fn output(&self) -> OutPort {
        self.output
    }
```

- [ ] **Step 4: Add read-only accessors to `Blueprint`**

In the `impl Blueprint` block (115-161), add (e.g. after `new` at 118):

```rust
    /// The top-level blueprint items (read-only graph-as-data, C9).
    pub fn nodes(&self) -> &[BlueprintNode] {
        &self.nodes
    }
    /// The declared sources.
    pub fn sources(&self) -> &[SourceSpec] {
        &self.sources
    }
    /// The top-level edges (blueprint-level indices).
    pub fn edges(&self) -> &[Edge] {
        &self.edges
    }
```

- [ ] **Step 5: Thread a name into all 7 `Composite::new` call sites**

All 7 are inside the `#[cfg(test)] mod tests` block. Add a leading string argument to each:

- Line 356 (`composite_schema_derives_role_and_output_kinds`): `Composite::new(` → `Composite::new(\n            "c",`
- Line 433 (`fan_composite()` helper): first arg `"fan"`.
- Line 481 (`outer` in `nested_composite_inlines`): first arg `"outer"`.
- Line 513 (`bad_interior_index_rejected`): first arg `"c"`.
- Line 527 (`role_kind_mismatch_rejected`): first arg `"c"`.
- Line 541 (`output_port_out_of_range_rejected`): first arg `"c"`.
- Line 631 (`sma_cross(fast, slow)` helper): first arg `"sma_cross"`.

Concretely, e.g. for `fan_composite` (433):
```rust
    fn fan_composite() -> Composite {
        Composite::new(
            "fan",
            vec![pass1(), pass1(), join2()],
            vec![
                Edge { from: 0, to: 2, slot: 0, from_field: 0 },
                Edge { from: 1, to: 2, slot: 1, from_field: 0 },
            ],
            vec![vec![Target { node: 0, slot: 0 }, Target { node: 1, slot: 0 }]],
            OutPort { node: 2, field: 0 },
        )
    }
```
and for `sma_cross` (631):
```rust
    fn sma_cross(fast: usize, slow: usize) -> Composite {
        Composite::new(
            "sma_cross",
            vec![Sma::new(fast).into(), Sma::new(slow).into(), Sub::new().into()],
            vec![
                Edge { from: 0, to: 2, slot: 0, from_field: 0 },
                Edge { from: 1, to: 2, slot: 1, from_field: 0 },
            ],
            vec![vec![Target { node: 0, slot: 0 }, Target { node: 1, slot: 0 }]],
            OutPort { node: 2, field: 0 },
        )
    }
```
Apply the same one-line leading-argument insertion at 356, 481, 513, 527, 541.

- [ ] **Step 6: Run the engine tests (all `Composite::new` sites threaded, accessors compile)**

Run: `cargo test -p aura-engine`
Expected: PASS — all existing blueprint tests (including `composite_sma_cross_runs_bit_identical_to_hand_wired`, `single_composite_inlines_with_offset_fan_and_output`, `nested_composite_inlines`) stay green; the crate compiles with the widened signature.

- [ ] **Step 7: Confirm the engine took no external dependency**

Run: `grep -nE '^\s*(ascii|[a-z].*=.*version|[a-z].*=.*")' crates/aura-engine/Cargo.toml`
Expected: only the `aura-core` path dependency (and `aura-std` under `[dev-dependencies]`); no `ascii-dag`, no crates.io version dep. (C16 preserved.)

---

## Task 4: aura-cli — `ascii-dag` dep, `graph.rs` adapter, sample builder, dispatch

**Files:**
- Modify: `crates/aura-cli/Cargo.toml:12-15`
- Create: `crates/aura-cli/src/graph.rs`
- Modify: `crates/aura-cli/src/main.rs` (imports 9-14, `mod graph;`, sample builders, dispatch 114-126)

- [ ] **Step 1: Add the `ascii-dag` dependency**

In `crates/aura-cli/Cargo.toml`, under `[dependencies]` (currently the three path deps at 12-15), add:

```toml
ascii-dag = "0.9.1"
```

- [ ] **Step 2: Create the adapter module `crates/aura-cli/src/graph.rs`**

```rust
//! The `aura graph` ASCII-DAG adapter (#13): turns the engine's graph-as-data
//! (C9) into an `ascii_dag::Graph` rendered to a `String`. Two views:
//! `render_blueprint` draws composites as named cluster boxes (pre-inline);
//! `render_flat_graph` draws the flat post-inline graph (boundaries dissolved,
//! C23). Rendering reads structure + node `label()`s only — never `eval`.
//!
//! ascii-dag borrows its node/subgraph labels as `&'a str`, so each function
//! first materializes the owned label `String`s (which outlive the `Graph`),
//! then borrows into them. `RenderMode::Vertical` is mandatory: Horizontal
//! collapses a fan-out onto one path.

use ascii_dag::graph::{Graph, RenderMode};
use aura_core::Node;
use aura_engine::{Blueprint, BlueprintNode, Edge, SourceSpec, Target};

/// How one top-level blueprint item maps into display nodes (blueprint view).
enum ItemDisplay {
    /// A leaf is one display node at this id.
    Leaf(usize),
    /// A composite is a cluster of interior leaf display ids; its output port and
    /// input roles resolve edges crossing its boundary.
    Composite {
        interior_ids: Vec<usize>,
        output_interior: usize,
        input_roles: Vec<Vec<Target>>,
    },
}

/// The display id an edge *from* this item originates at (its producer).
fn producer_id(d: &ItemDisplay) -> usize {
    match d {
        ItemDisplay::Leaf(id) => *id,
        ItemDisplay::Composite { interior_ids, output_interior, .. } => interior_ids[*output_interior],
    }
}

/// The display id(s) an edge *into* this item at `slot` reaches (its consumers).
/// A composite input role fans into several interior targets.
fn consumer_ids(d: &ItemDisplay, slot: usize) -> Vec<usize> {
    match d {
        ItemDisplay::Leaf(id) => vec![*id],
        ItemDisplay::Composite { interior_ids, input_roles, .. } => {
            input_roles[slot].iter().map(|t| interior_ids[t.node]).collect()
        }
    }
}

/// Blueprint view: composites become labelled cluster boxes (pre-inline, C9).
pub fn render_blueprint(bp: &Blueprint) -> String {
    let mut labels: Vec<String> = Vec::new();
    let mut sg_names: Vec<String> = Vec::new();
    let mut memberships: Vec<(usize, Vec<usize>)> = Vec::new();
    let mut edges: Vec<(usize, usize)> = Vec::new();
    let mut item_display: Vec<ItemDisplay> = Vec::with_capacity(bp.nodes().len());

    // pass 1: assign display ids + labels; open a subgraph per composite; record
    // interior edges (the interior ids are in hand here).
    for item in bp.nodes() {
        match item {
            BlueprintNode::Leaf(node) => {
                let id = labels.len();
                labels.push(node.label());
                item_display.push(ItemDisplay::Leaf(id));
            }
            BlueprintNode::Composite(c) => {
                let mut interior_ids = Vec::with_capacity(c.nodes().len());
                for inner in c.nodes() {
                    match inner {
                        BlueprintNode::Leaf(node) => {
                            let id = labels.len();
                            labels.push(node.label());
                            interior_ids.push(id);
                        }
                        BlueprintNode::Composite(_) => unimplemented!(
                            "cycle 0013 renders leaf-interior composites (the built-in \
                             sample); nested-composite cluster rendering is a follow-up"
                        ),
                    }
                }
                for e in c.edges() {
                    edges.push((interior_ids[e.from], interior_ids[e.to]));
                }
                let sg = sg_names.len();
                sg_names.push(c.name().to_string());
                memberships.push((sg, interior_ids.clone()));
                item_display.push(ItemDisplay::Composite {
                    interior_ids,
                    output_interior: c.output().node,
                    input_roles: c.input_roles().to_vec(),
                });
            }
        }
    }

    // sources as producer display nodes (unnamed in the data model -> label by kind)
    let mut source_ids: Vec<usize> = Vec::with_capacity(bp.sources().len());
    for src in bp.sources() {
        let id = labels.len();
        labels.push(format!("source:{:?}", src.kind));
        source_ids.push(id);
    }

    // top-level edges, resolved through composite boundaries
    for e in bp.edges() {
        let from = producer_id(&item_display[e.from]);
        for to in consumer_ids(&item_display[e.to], e.slot) {
            edges.push((from, to));
        }
    }
    // source -> target edges
    for (src, &sid) in bp.sources().iter().zip(&source_ids) {
        for t in &src.targets {
            for to in consumer_ids(&item_display[t.node], t.slot) {
                edges.push((sid, to));
            }
        }
    }

    // build the borrowed-label Graph (labels + sg_names are final & owned)
    let mut g = Graph::with_mode(RenderMode::Vertical);
    for (id, l) in labels.iter().enumerate() {
        g.add_node(id, l);
    }
    let sg_ids: Vec<usize> = sg_names.iter().map(|n| g.add_subgraph(n)).collect();
    for (sg, members) in &memberships {
        g.put_nodes(members).inside(sg_ids[*sg]).expect("valid subgraph placement");
    }
    for (from, to) in edges {
        g.add_edge(from, to, None);
    }
    g.render()
}

/// Compiled view: the flat post-inline graph (no clusters; boundaries dissolved,
/// C23). Each `Box<dyn Node>` labels itself; node display id = node index.
pub fn render_flat_graph(nodes: &[Box<dyn Node>], sources: &[SourceSpec], edges: &[Edge]) -> String {
    let mut labels: Vec<String> = nodes.iter().map(|n| n.label()).collect();
    let source_base = labels.len();
    for src in sources {
        labels.push(format!("source:{:?}", src.kind));
    }

    let mut g = Graph::with_mode(RenderMode::Vertical);
    for (id, l) in labels.iter().enumerate() {
        g.add_node(id, l);
    }
    for e in edges {
        g.add_edge(e.from, e.to, None);
    }
    for (i, src) in sources.iter().enumerate() {
        for t in &src.targets {
            g.add_edge(source_base + i, t.node, None);
        }
    }
    g.render()
}
```

- [ ] **Step 3: Declare the module and widen the imports in `main.rs`**

At the top of `crates/aura-cli/src/main.rs`, after the doc comment and before the `use` block, add:

```rust
mod graph;
```

Then change the `aura_engine` import (lines 10-12) to add the blueprint types:

```rust
use aura_engine::{
    f64_field, summarize, Blueprint, BlueprintNode, Composite, Edge, Harness, OutPort,
    RunManifest, RunReport, SourceSpec, Target,
};
```

- [ ] **Step 4: Add the sample-blueprint builders to `main.rs`**

Add these free functions (e.g. just below `run_sample` at line 112, leaving `sample_harness`/`run_sample` untouched):

```rust
/// The SMA-cross signal as a named composite (price -> fast/slow SMA -> spread).
/// CLI-local sample builder; the engine ships no sample (the duplication with
/// `blueprint.rs`'s test helper is the dedup tracked in #14).
fn sma_cross(name: &str, fast: usize, slow: usize) -> Composite {
    Composite::new(
        name,
        vec![Sma::new(fast).into(), Sma::new(slow).into(), Sub::new().into()],
        vec![
            Edge { from: 0, to: 2, slot: 0, from_field: 0 },
            Edge { from: 1, to: 2, slot: 1, from_field: 0 },
        ],
        vec![vec![Target { node: 0, slot: 0 }, Target { node: 1, slot: 0 }]],
        OutPort { node: 2, field: 0 },
    )
}

/// The sample signal-quality blueprint, parameterized by the SMA windows so a
/// test can author a deliberately swapped variant. Recorders need a channel to
/// construct; the receivers are dropped because the render never runs the graph.
fn build_sample(fast: usize, slow: usize) -> Blueprint {
    let (tx_eq, _rx_eq) = mpsc::channel();
    let (tx_ex, _rx_ex) = mpsc::channel();
    Blueprint::new(
        vec![
            BlueprintNode::Composite(sma_cross("sma_cross", fast, slow)),
            Exposure::new(0.5).into(),
            SimBroker::new(0.0001).into(),
            Recorder::new(&[ScalarKind::F64], Firing::Any, tx_eq).into(),
            Recorder::new(&[ScalarKind::F64], Firing::Any, tx_ex).into(),
        ],
        vec![SourceSpec {
            kind: ScalarKind::F64,
            targets: vec![
                Target { node: 0, slot: 0 }, // price -> sma_cross role 0
                Target { node: 2, slot: 1 }, // price -> SimBroker price slot
            ],
        }],
        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
        ],
    )
}

/// The built-in sample rendered by `aura graph`.
fn sample_blueprint() -> Blueprint {
    build_sample(2, 4)
}
```

- [ ] **Step 5: Add the `graph` dispatch arm + usage strings**

Change the `main()` match block (lines 114-126) from:

```rust
    match args.next().as_deref() {
        // strict: a bare `run` proceeds; a trailing token falls through to the
        // usage-error path rather than masquerading as a successful run (#16).
        Some("run") if args.next().is_none() => println!("{}", run_sample().to_json()),
        Some("--help") | Some("-h") => println!("usage: aura run"),
        _ => {
            eprintln!("aura: usage: aura run");
            std::process::exit(2);
        }
    }
```

to:

```rust
    match args.next().as_deref() {
        // strict: a bare `run` proceeds; a trailing token falls through to the
        // usage-error path rather than masquerading as a successful run (#16).
        Some("run") if args.next().is_none() => println!("{}", run_sample().to_json()),
        Some("graph") => {
            // `--compiled` selects the flat post-inline view; default is the
            // clustered blueprint view. Strictness beyond this stays minimal (#16).
            let compiled = args.next().as_deref() == Some("--compiled");
            let bp = sample_blueprint();
            let out = if compiled {
                let (nodes, sources, edges) = bp.compile().expect("valid sample blueprint");
                graph::render_flat_graph(&nodes, &sources, &edges)
            } else {
                graph::render_blueprint(&bp)
            };
            println!("{out}");
        }
        Some("--help") | Some("-h") => println!("usage: aura run | aura graph [--compiled]"),
        _ => {
            eprintln!("aura: usage: aura run | aura graph [--compiled]");
            std::process::exit(2);
        }
    }
```

- [ ] **Step 6: Build aura-cli and smoke-test both views**

Run: `cargo build -p aura-cli`
Expected: builds clean (downloads/compiles `ascii-dag` v0.9.1 on first build).

Run: `cargo run -q -p aura-cli -- graph`
Expected: prints an ASCII DAG to stdout containing `sma_cross`, `SMA(2)`, `SMA(4)`, `Sub`, `Exposure(0.5)`, `SimBroker(0.0001)`, `Recorder`.

Run: `cargo run -q -p aura-cli -- graph --compiled`
Expected: prints an ASCII DAG containing `SMA(2)`/`SMA(4)` but NOT `sma_cross` (boundary dissolved).

---

## Task 5: render tests (concern-defining + structure pins + frozen golden)

**Files:**
- Test: `crates/aura-cli/src/main.rs:128-168` (tests module)

- [ ] **Step 1: Add the swapped-variant builder (test-only) and the failing tests**

In `crates/aura-cli/src/main.rs`, inside the existing `#[cfg(test)] mod tests` (128-168), add the test-only swapped builder and the render tests:

```rust
    /// The sample authored with fast/slow SMA windows swapped — the mis-wiring
    /// the render must surface. Test-only: nothing outside tests builds it.
    fn sample_blueprint_swapped() -> Blueprint {
        build_sample(4, 2)
    }

    #[test]
    fn blueprint_view_shows_cluster_and_param_labels() {
        let out = graph::render_blueprint(&sample_blueprint());
        // the composite renders as a named cluster box
        assert!(out.contains("sma_cross"), "missing composite name:\n{out}");
        // param-carrying labels disambiguate the two SMAs
        assert!(out.contains("SMA(2)"), "missing SMA(2):\n{out}");
        assert!(out.contains("SMA(4)"), "missing SMA(4):\n{out}");
        for needle in ["Sub", "Exposure(0.5)", "SimBroker(0.0001)", "Recorder"] {
            assert!(out.contains(needle), "missing {needle}:\n{out}");
        }
    }

    #[test]
    fn compiled_view_dissolves_the_composite_boundary() {
        let bp = sample_blueprint();
        let (nodes, sources, edges) = bp.compile().expect("valid sample");
        let out = graph::render_flat_graph(&nodes, &sources, &edges);
        // node labels survive inlining...
        assert!(out.contains("SMA(2)") && out.contains("SMA(4)"), "labels lost:\n{out}");
        // ...but the composite cluster name does NOT (boundary dissolved, C23)
        assert!(!out.contains("sma_cross"), "compiled view must not show the cluster:\n{out}");
    }

    #[test]
    fn swapped_sma_inputs_render_differently() {
        // the property the cycle exists to buy: a mis-wiring is no longer invisible.
        let correct = graph::render_blueprint(&sample_blueprint());
        let swapped = graph::render_blueprint(&sample_blueprint_swapped());
        assert_ne!(correct, swapped, "a fast/slow SMA swap must change the render");
    }
```

- [ ] **Step 2: Run the tests to verify they pass**

Run: `cargo test -p aura-cli blueprint_view_shows_cluster_and_param_labels compiled_view_dissolves_the_composite_boundary swapped_sma_inputs_render_differently`
Expected: PASS (all three). (`render_blueprint`/`render_flat_graph`/`sample_blueprint` already exist from Task 4; this task only adds tests + the test-only swapped builder.)

- [ ] **Step 3: Freeze the full-byte golden snapshots**

The exact rendered bytes are ascii-dag's deterministic Sugiyama layout — capture them from the now-green render rather than hand-authoring them.

Run: `cargo run -q -p aura-cli -- graph`
Copy the exact stdout. Add this test to the same `mod tests`, pasting the captured bytes as the `EXPECTED` literal (use a raw string `r#"..."#` if the output contains `"`; preserve a trailing newline if `render()` emits one):

```rust
    #[test]
    fn blueprint_view_golden() {
        let out = graph::render_blueprint(&sample_blueprint());
        let expected = "<<paste the exact captured `aura graph` stdout here>>";
        assert_eq!(out, expected, "blueprint render drifted; re-capture if intended");
    }
```

Then run: `cargo run -q -p aura-cli -- graph --compiled`, and add the twin:

```rust
    #[test]
    fn compiled_view_golden() {
        let bp = sample_blueprint();
        let (nodes, sources, edges) = bp.compile().expect("valid sample");
        let out = graph::render_flat_graph(&nodes, &sources, &edges);
        let expected = "<<paste the exact captured `aura graph --compiled` stdout here>>";
        assert_eq!(out, expected, "compiled render drifted; re-capture if intended");
    }
```

> The `<<paste ...>>` markers are filled with the captured deterministic output in this step — they are a capture instruction, not shipped code. Do NOT commit the test with the marker text still in place; the test must hold the real bytes and go green.

- [ ] **Step 4: Run the golden tests to verify they pass**

Run: `cargo test -p aura-cli blueprint_view_golden compiled_view_golden`
Expected: PASS (the literals match the captured render; determinism makes this stable).

- [ ] **Step 5: Full workspace gate**

Run: `cargo test --workspace`
Expected: PASS — all tests across aura-core/std/engine/cli green, including the pre-existing non-regression tests `composite_sma_cross_runs_bit_identical_to_hand_wired` and `run_sample_is_deterministic_and_non_trivial`.

Run: `cargo clippy --workspace --all-targets -- -D warnings`
Expected: no warnings (the test-only `sample_blueprint_swapped` is exercised by `swapped_sma_inputs_render_differently`, so no dead-code warning).

Run: `cargo build --workspace`
Expected: builds clean.
