# Composite Signature Render — Implementation Plan

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

**Goal:** Render a composite's blueprint definition as a typed signature title line
(`macd(fast:i64, slow:i64, signal:i64) -> (macd, signal, histogram)`) with param
names folded into leaf labels (`[EMA(fast)]`), ordered input slots as stubs
(`[Sub(#A,#B)]`), de-prefixed outputs (`[macd]`), and the `[param:*]` marker nodes
removed.

**Architecture:** Render-only. Two new helpers (`signature`, `leaf_label`) in
`graph.rs` + edits to `render_definition`; a `ScalarKind`→lowercase match (none
exists today); test/golden updates in `main.rs`; two stale doc-comment fixes. No
engine / `ParamAlias` / `param_space()` change. Task 1 changes only render code and
gates on `cargo build -p aura-cli` (the goldens go red and are re-captured in Task
2 — `cargo test` is NOT a Task-1 gate). Task 2 fixes the tests and runs the full
workspace triple.

**Tech Stack:** `crates/aura-cli/src/graph.rs`, `crates/aura-cli/src/main.rs`,
`crates/aura-core/src/node.rs` (doc comment).

---

**Files this plan creates or modifies:**

- Modify: `crates/aura-cli/src/graph.rs:16-18` (imports), `:101-137` (`render_definition` + doc), plus two new helpers
- Modify: `crates/aura-core/src/node.rs:93-101` (doc comment only)
- Modify: `crates/aura-cli/src/main.rs:393,394,428,429,452,581` (pins/needles), `:580-587` (MACD render test), `:483-521` (`blueprint_view_golden` re-capture)

---

## Task 1: graph.rs render change + doc fixes

**Files:**
- Modify: `crates/aura-cli/src/graph.rs:16-18,101-137`
- Modify: `crates/aura-core/src/node.rs:93-101`

- [ ] **Step 1: Add `ScalarKind` and `LeafFactory` to graph.rs imports**

`graph.rs:17`. Replace:

```rust
use aura_core::Node;
```

with:

```rust
use aura_core::{LeafFactory, Node, ScalarKind};
```

- [ ] **Step 2: Add the `signature` + `kind_str` helpers**

Insert immediately before `render_definition` (currently `graph.rs:106`, after the
doc comment is rewritten in Step 5 — insert these fns just above that doc comment at
`:101`):

```rust
/// `ScalarKind` as a lowercase type string for a signature (`i64`/`f64`/`bool`/
/// `timestamp`). The derived `Debug` gives PascalCase (`I64`), so this is explicit.
fn kind_str(kind: ScalarKind) -> &'static str {
    match kind {
        ScalarKind::I64 => "i64",
        ScalarKind::F64 => "f64",
        ScalarKind::Bool => "bool",
        ScalarKind::Timestamp => "timestamp",
    }
}

/// The composite's typed signature for the definition title:
/// `name(p1:kind, …) -> (o1, …)`. Param kinds come from the aliased interior leaf's
/// declared params; output **names only** (kinds need a pre-build factory interface,
/// #43). An empty alias list renders `name()`. Total: a malformed alias falls back
/// to `?` rather than panicking (compile is the validator, #41).
fn signature(c: &Composite) -> String {
    let params: Vec<String> = c
        .params()
        .iter()
        .map(|a| {
            let kind = c
                .nodes()
                .get(a.node)
                .and_then(|n| match n {
                    BlueprintNode::Leaf(f) => f.params().get(a.slot).map(|p| kind_str(p.kind)),
                    BlueprintNode::Composite(_) => None,
                })
                .unwrap_or("?");
            format!("{}:{}", a.name, kind)
        })
        .collect();
    let outs: Vec<String> = c.output().iter().map(|of| of.name.clone()).collect();
    format!("{}({}) -> ({})", c.name(), params.join(", "), outs.join(", "))
}
```

- [ ] **Step 3: Add the `leaf_label` helper**

Insert directly after `signature` (above the `render_definition` doc comment):

```rust
/// A leaf item's render label: `factory.label()` plus an optional `(...)` listing
/// its aliased param names, then its input-slot stubs (`#A`, `#B`, … one per wired
/// input slot, slot index → letter) when the leaf has more than one wired input
/// slot. Params and stubs are `; `-separated when both present; either alone has no
/// separator; neither yields the bare label. A node's wired slots are the distinct
/// `.slot` values targeting it across interior edges (`Edge.to == index`) and input
/// roles (`Role.targets` with `node == index`).
fn leaf_label(c: &Composite, index: usize, factory: &LeafFactory) -> String {
    let params: Vec<&str> = c
        .params()
        .iter()
        .filter(|a| a.node == index)
        .map(|a| a.name.as_str())
        .collect();

    let mut slots: Vec<usize> = Vec::new();
    for e in c.edges() {
        if e.to == index && !slots.contains(&e.slot) {
            slots.push(e.slot);
        }
    }
    for role in c.input_roles() {
        for t in &role.targets {
            if t.node == index && !slots.contains(&t.slot) {
                slots.push(t.slot);
            }
        }
    }
    slots.sort_unstable();
    let stubs: Vec<String> = if slots.len() > 1 {
        slots.iter().map(|s| format!("#{}", (b'A' + *s as u8) as char)).collect()
    } else {
        Vec::new()
    };

    let parts: Vec<String> = match (params.is_empty(), stubs.is_empty()) {
        (true, true) => return factory.label(),
        (false, true) => vec![params.join(", ")],
        (true, false) => vec![stubs.join(", ")],
        (false, false) => vec![params.join(", "), stubs.join(", ")],
    };
    format!("{}({})", factory.label(), parts.join("; "))
}
```

- [ ] **Step 4: Edit `render_definition` — title, leaf labels, drop param markers, de-prefix outputs**

`graph.rs:107-136`. Replace the leaf-label loop, the `[param:*]` loop, the output
loop, and the title.

Replace `:108-113` (the leaf loop):

```rust
    for inner in c.nodes() {
        labels.push(match inner {
            BlueprintNode::Leaf(factory) => factory.label(),
            BlueprintNode::Composite(inner_c) => inner_c.name().to_string(),
        });
    }
```

with (enumerate, fold via `leaf_label`):

```rust
    for (i, inner) in c.nodes().iter().enumerate() {
        labels.push(match inner {
            BlueprintNode::Leaf(factory) => leaf_label(c, i, factory),
            BlueprintNode::Composite(inner_c) => inner_c.name().to_string(),
        });
    }
```

Delete the `[param:*]` marker loop `:125-129` entirely:

```rust
    for a in c.params() {
        let p_id = labels.len();
        labels.push(format!("param:{}", a.name));
        edges.push((p_id, a.node));
    }
```

Replace the output marker label `:132`:

```rust
        labels.push(format!("out:{}", of.name));
```

with (drop the `out:` prefix):

```rust
        labels.push(of.name.clone());
```

Replace the title `:136`:

```rust
    format!("{}:\n{}", c.name(), render_flat(&labels, &edges))
```

with:

```rust
    format!("{}:\n{}", signature(c), render_flat(&labels, &edges))
```

- [ ] **Step 5: Fix the stale `render_definition` doc comment**

`graph.rs:101-105`. Replace:

```rust
/// Render one composite's interior as a flat graph: interior leaves as `[type]`,
/// nested composites as opaque `[name]`, plus an `[in:<name>]` entry marker per
/// input role (wired to its interior targets), a `[param:<name>]` marker per param
/// alias (wired to the leaf it relabels), and an `[out:<name>]` marker per
/// re-exported output field (wired from its producer). Prefixed `"<name>:\n"`.
```

with:

```rust
/// Render one composite's interior as a flat graph: interior leaves as
/// `[type(param…; #slot…)]` (aliased param names + ordered input-slot stubs folded
/// in via `leaf_label`), nested composites as opaque `[name]`, an `[in:<name>]`
/// entry marker per input role (wired to its interior targets), and an `[<name>]`
/// node per re-exported output field (wired from its producer). The title line is
/// the composite's typed `signature` (`name(p:kind, …) -> (out, …)`); params live
/// in the signature, not as marker nodes.
```

- [ ] **Step 6: Fix the stale `LeafFactory::label` doc comment**

`crates/aura-core/src/node.rs:93-101`. Replace:

```rust
    /// The param-generic render label for the blueprint view (C22 "structure
    /// before"): just the node type, e.g. `SMA`. A value-empty recipe has no
    /// values to show; the tunable knobs are surfaced by `Blueprint::param_space`,
    /// not in the graph. The label stays the bare type because the `ascii-dag`
    /// renderer writes a label verbatim on one line (no wrapping) and overlaps two
    /// wide sibling boxes inside a cluster subgraph — appending the knob names
    /// (`SMA(length)`) would garble the blueprint view, and domain labels grow
    /// unboundedly wide. The compiled view labels the built node valued (`SMA(2)`)
    /// via `Node::label`, unaffected.
```

with:

```rust
    /// The param-generic render label for the blueprint view (C22 "structure
    /// before"): just the node type, e.g. `SMA`. A value-empty recipe has no values
    /// to show; the tunable knobs are surfaced by `Blueprint::param_space`. The
    /// factory label stays the bare type because alias / handle names are a
    /// *composite-level* concept — the renderer folds them into the leaf label at
    /// the composite boundary (`render_definition`'s `leaf_label`), where the
    /// `(node, slot)` → name mapping lives, not on the standalone factory. (Wide
    /// labels are safe: both `aura graph` views are flat since cycle 0017 — no
    /// cluster subgraph, so no sibling-overlap garble.) The compiled view labels the
    /// built node valued (`SMA(2)`) via `Node::label`, unaffected.
```

- [ ] **Step 7: Build the CLI crate (compile gate; tests deferred to Task 2)**

Run: `cargo build -p aura-cli`
Expected: PASS — the render code compiles with the two new helpers, the imports, and
the edited `render_definition`. (`cargo test` is NOT run here: the goldens/needle
assertions are now stale and go red until Task 2 re-captures them. `cargo build`
does not compile the `#[cfg(test)]` module, so this gate is a clean compile check of
the render path.)

---

## Task 2: main.rs tests + goldens + workspace gate

**Files:**
- Modify: `crates/aura-cli/src/main.rs:393,394,428,429,452` (pins/needles), `:580-587` (MACD render test), `:483-521` (`blueprint_view_golden`)

- [ ] **Step 1: Update the four non-MACD title pins (`name:` → `name(`)**

The title format changed from `name:` to `name(…) -> (…):`, so every
`.matches("<name>:")` count assert must repin to `"<name>("` (the new title is the
only place `name(` occurs; opaque main nodes are `[name]`, no paren).

`main.rs:393` — replace:

```rust
        assert_eq!(out.matches("sma_cross:").count(), 1, "definition not rendered once:\n{out}");
```

with:

```rust
        assert_eq!(out.matches("sma_cross(").count(), 1, "definition not rendered once:\n{out}");
```

`main.rs:428` — replace `out.matches("outer:")` with `out.matches("outer(")` (keep
the rest of the line identical). `main.rs:429` — replace `out.matches("inner:")`
with `out.matches("inner(")`. `main.rs:452` — replace `out.matches("dup:")` with
`out.matches("dup(")`.

- [ ] **Step 2: Update the definition needle array**

`main.rs:394`. Replace:

```rust
        for needle in ["[SMA]", "[Sub]", "[in:price]", "[out:cross]"] {
```

with (the Sub now shows its two ordered inputs; the output marker is de-prefixed):

```rust
        for needle in ["[SMA]", "[Sub(#A,#B)]", "[in:price]", "[cross]"] {
```

- [ ] **Step 3: Rewrite the MACD definition render assertions**

`main.rs:580-587`. Replace:

```rust
        assert!(out.contains("[macd]"), "missing opaque macd node:\n{out}");
        assert_eq!(out.matches("macd:").count(), 1, "macd defined once:\n{out}");
        assert!(out.contains("[EMA]"), "macd interior must show EMA leaves:\n{out}");
        assert!(out.contains("[in:price]"), "named MACD input role: {out}");
        assert!(out.contains("[param:fast]"), "aliased fast length: {out}");
        assert!(out.contains("[param:slow]"), "aliased slow length: {out}");
        assert!(out.contains("[param:signal]"), "aliased signal length: {out}");
```

with:

```rust
        assert!(out.contains("[macd]"), "missing opaque macd node:\n{out}");
        assert_eq!(out.matches("macd(").count(), 1, "macd defined once:\n{out}");
        assert!(
            out.contains("macd(fast:i64, slow:i64, signal:i64) -> (macd, signal, histogram)"),
            "typed signature line: {out}"
        );
        assert!(out.contains("[EMA(fast)]"), "fast EMA folds its param: {out}");
        assert!(out.contains("[EMA(slow)]"), "slow EMA folds its param: {out}");
        assert!(out.contains("[EMA(signal)]"), "signal EMA folds its param: {out}");
        assert!(out.contains("[Sub(#A,#B)]"), "Sub shows its two ordered inputs: {out}");
        assert!(out.contains("[in:price]"), "named MACD input role: {out}");
        assert!(!out.contains("[param:"), "param marker nodes removed: {out}");
        assert!(!out.contains("[out:"), "output prefix dropped: {out}");
```

- [ ] **Step 4: Re-capture `blueprint_view_golden` wholesale**

Run: `cargo test -p aura-cli blueprint_view_golden`
Expected: FAIL — the `where:` definition section drifted (`sma_cross:` →
`sma_cross() -> (cross):`, `[Sub]` → `[Sub(#A,#B)]`, `[out:cross]` → `[cross]`).
Read the assertion's "left" (actual) rendered string and replace the entire
`expected` raw-string literal (`main.rs:488-519`) with the actual bytes verbatim —
do NOT hand-edit field-by-field. Re-run: PASS.

- [ ] **Step 5: Confirm `compiled_view_golden` byte-identical (C23 guard)**

Run: `cargo test -p aura-cli compiled_view_golden`
Expected: PASS with NO edit to the golden (`main.rs:529-547`). The compiled view does
not render a composite definition, so it must be untouched. If it drifts, STOP — that
is a bug, not a re-capture.

- [ ] **Step 6: Full workspace triple (-D warnings)**

Run: `cargo build --workspace && cargo test --workspace && cargo clippy --workspace --all-targets -- -D warnings`
Expected: all PASS — every test green (the five repins, the needle update, the MACD
assertions, both goldens), no clippy warnings. Spot-check the acceptance evidence:

Run: `cargo run -q -p aura-cli -- graph --macd`
Expected: the definition title reads
`macd(fast:i64, slow:i64, signal:i64) -> (macd, signal, histogram):`, the EMAs read
`[EMA(fast)]`/`[EMA(slow)]`/`[EMA(signal)]`, the Subs read `[Sub(#A,#B)]`, outputs
read `[macd]`/`[signal]`/`[histogram]`, and no `[param:*]` marker appears.

Run: `cargo run -q -p aura-cli -- run --macd`
Expected: deterministic JSON, `total_pips` and `exposure_sign_flips` unchanged from
before (render-only change does not touch the run).
