Aura/docs/plans/0040-wiring-totality-check.md

# Wiring-totality check — Implementation Plan

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

**Goal:** Reject a graph that leaves an interior input slot unwired or wires one
slot from more than one producer, at compile time, via a single name-free
structural check in `validate_wiring`.

**Architecture:** A new `check_ports_connected(nodes, edges, roles)` is added to
`validate_wiring` (crates/aura-engine/src/blueprint.rs), after the existing
index/kind checks and before the nested-composite recursion. It counts coverage of
each `(interior-node, slot)` uniformly across interior edges and role targets, and
rejects any interior input slot covered 0 times (`UnconnectedPort`) or >1 times
(`DoubleWiredPort`). Because `validate_wiring` is called once from
`compile_with_params` and recurses, both the raw `Composite::new` path and the
`GraphBuilder::build()` path inherit it at every nesting level. The blast radius is
exactly four currently-green tests (empirically probed), fixed here.

**Tech Stack:** `crates/aura-engine/src/blueprint.rs` (the check, the two
`CompileError` variants, raw-surface tests, four flipped-test fixes),
`crates/aura-engine/src/builder.rs` (one builder-surface test), `docs/design/INDEX.md`
(C8 realization note).

---

**Files this plan creates or modifies:**

- Modify: `crates/aura-engine/src/blueprint.rs` — add two `CompileError` variants
  (~:489), add `check_ports_connected` + its call site in `validate_wiring`
  (~:538/:546), re-wire 3 negative tests (~:1382/:1452/:1473), fully wire 1
  param-order test (~:1877), add 5 raw-surface tests (test module).
- Modify: `crates/aura-engine/src/builder.rs` — add 1 builder-surface negative test
  (after `builder_harness_compiles_identically_to_hand_wired`, ~:272).
- Modify: `docs/design/INDEX.md` — add the C8 cycle-0040 realization note (after the
  cycle-0027 realization block, ~:316).

---

### Task 1: The wiring-totality check (two variants + the function + call site)

**Files:**
- Modify: `crates/aura-engine/src/blueprint.rs:489` (CompileError), `:538`/`:546`
  (validate_wiring + new fn)

- [ ] **Step 1: Add the two `CompileError` variants**

In `crates/aura-engine/src/blueprint.rs`, replace:

```rust
    /// A root input role `role` has no bound source (`source: None`) — an open port
    /// at the root, which has no enclosing graph to wire it. Only a fully source-
    /// bound composite is runnable.
    UnboundRootRole { role: usize },
}
```

with:

```rust
    /// A root input role `role` has no bound source (`source: None`) — an open port
    /// at the root, which has no enclosing graph to wire it. Only a fully source-
    /// bound composite is runnable.
    UnboundRootRole { role: usize },
    /// An interior node's input `slot` is covered by no edge and no role target — a
    /// required port left unconnected (it would bootstrap a silent empty column).
    UnconnectedPort { node: usize, slot: usize },
    /// An interior node's input `slot` is covered by more than one edge/role target
    /// combined — a slot holds exactly one column, so >1 producer is ill-formed.
    DoubleWiredPort { node: usize, slot: usize },
}
```

- [ ] **Step 2: Add `check_ports_connected` and call it from `validate_wiring`**

In `crates/aura-engine/src/blueprint.rs`, replace the tail of `validate_wiring`:

```rust
    // recurse into nested composites
    for item in nodes {
        if let BlueprintNode::Composite(c) = item {
            validate_wiring(c.nodes(), c.edges(), c.input_roles(), c.output())?;
        }
    }
    Ok(())
}
```

with (insert the call before the recursion, and define the new fn right after):

```rust
    // wiring totality: every interior input slot covered by exactly one wiring act
    check_ports_connected(nodes, edges, roles)?;
    // recurse into nested composites
    for item in nodes {
        if let BlueprintNode::Composite(c) = item {
            validate_wiring(c.nodes(), c.edges(), c.input_roles(), c.output())?;
        }
    }
    Ok(())
}

/// Every interior node's every declared input slot must be covered by exactly one
/// wiring act — one interior edge OR one role target, counted uniformly. Zero = a
/// forgotten connection (would bootstrap a silent empty column); >1 = an ill-formed
/// slot (a slot holds one column). Index-based, name-free; presupposes in-range
/// edge/role indices (runs after the existing index-range checks). Mirrors the
/// single-site shape of `check_param_namespace_injective` (the wiring-side sibling).
fn check_ports_connected(
    nodes: &[BlueprintNode],
    edges: &[Edge],
    roles: &[Role],
) -> Result<(), CompileError> {
    let mut coverage: std::collections::HashMap<(usize, usize), usize> =
        std::collections::HashMap::new();
    for e in edges {
        *coverage.entry((e.to, e.slot)).or_insert(0) += 1;
    }
    for role in roles {
        for t in &role.targets {
            *coverage.entry((t.node, t.slot)).or_insert(0) += 1;
        }
    }
    for (n, item) in nodes.iter().enumerate() {
        for slot in 0..item.signature().inputs.len() {
            match coverage.get(&(n, slot)).copied().unwrap_or(0) {
                1 => {}
                0 => return Err(CompileError::UnconnectedPort { node: n, slot }),
                _ => return Err(CompileError::DoubleWiredPort { node: n, slot }),
            }
        }
    }
    Ok(())
}
```

- [ ] **Step 2b: Make `derive_signature` bounds-total (the check exposes a latent panic)**

`check_ports_connected` (and the existing edge/role checks) compute `signature()` on
every interior node *before* the recursion validates that node's interior. For a
structurally-invalid composite (an out-of-range `OutField` or role target), the
current `derive_signature` indexes unguarded and **panics** instead of letting
`validate_wiring`'s guarded loops report `OutputPortOutOfRange` / `BadInteriorIndex`.
Make the two indexers bounds-total (a placeholder kind for an invalid index; the real
fault is still reported by `validate_wiring`).

In `crates/aura-engine/src/blueprint.rs`, replace the `output` map in `derive_signature`:

```rust
            let kind = c.nodes()[of.node].signature().output[of.field].kind;
```

with:

```rust
            // bounds-total: a structurally-invalid OutField (out-of-range node/field)
            // yields a placeholder kind, never a panic — the real fault is reported by
            // validate_wiring's guarded output check (OutputPortOutOfRange). signature()
            // is computed speculatively by the parent's edge/role/connectivity checks
            // before the recursion validates this composite's interior (cycle 0040).
            let kind = c
                .nodes()
                .get(of.node)
                .and_then(|n| n.signature().output.get(of.field).map(|f| f.kind))
                .unwrap_or(ScalarKind::F64);
```

and replace `interior_slot_kind`'s body:

```rust
    nodes[t.node].signature().inputs[t.slot].kind
```

with:

```rust
    // bounds-total: a target into a missing node/slot yields a placeholder kind, never a
    // panic — the real fault is reported by validate_wiring's guarded index checks.
    nodes
        .get(t.node)
        .and_then(|n| n.signature().inputs.get(t.slot).map(|p| p.kind))
        .unwrap_or(ScalarKind::F64)
```

- [ ] **Step 3: Build and confirm exactly the four expected flips**

Run: `cargo build -p aura-engine`
Expected: builds with 0 errors (the two `usize`-only variants break no derive or
exhaustive match; `HashMap` is used by its full path, no new import).

Run: `cargo test -p aura-engine 2>&1 | tail -3`
Expected: `test result: FAILED. ... 4 failed ...` — and the four are exactly
`bad_interior_index_rejected`, `role_kind_mismatch_rejected`,
`output_port_out_of_range_rejected`, and
`param_space_mirrors_compiled_flat_node_param_order_under_nesting`. (Any other
failure is an un-enumerated flip — STOP and re-survey; the probe established these
four are the complete set.)

---

### Task 2: Re-wire the three under-wired negative tests (covering root role)

Each wraps a faulty composite `c` in a root with empty edges + empty roles, so the
new check pre-empts the deep fault with `UnconnectedPort` at the root level. Add a
covering root role targeting `c`'s one input slot (mirroring the existing pattern at
blueprint.rs:1414). The deep fault then surfaces via the recursion (the index/kind/
output checks inside `validate_wiring(c)` run before `c`'s own connectivity check),
so each STILL asserts its original variant.

**Files:**
- Modify: `crates/aura-engine/src/blueprint.rs:1382`, `:1452`, `:1473`

- [ ] **Step 1: Re-wire `bad_interior_index_rejected`**

Replace:

```rust
        let bp = Composite::new(
            "root",
            vec![BlueprintNode::Composite(c)],
            vec![],
            vec![],
            vec![], // output
        );
        // the Ok arm holds Box<dyn Node> (not Debug), so assert via the Err arm.
        assert_eq!(bp.compile().err(), Some(CompileError::BadInteriorIndex));
```

with:

```rust
        let bp = Composite::new(
            "root",
            vec![BlueprintNode::Composite(c)],
            vec![],
            vec![Role { name: "src".into(), targets: vec![Target { node: 0, slot: 0 }], source: Some(ScalarKind::F64) }],
            vec![], // output
        );
        // the Ok arm holds Box<dyn Node> (not Debug), so assert via the Err arm.
        assert_eq!(bp.compile().err(), Some(CompileError::BadInteriorIndex));
```

- [ ] **Step 2: Re-wire `role_kind_mismatch_rejected`**

Replace:

```rust
        let bp = Composite::new(
            "root",
            vec![BlueprintNode::Composite(c)],
            vec![],
            vec![],
            vec![], // output
        );
        // the Ok arm holds Box<dyn Node> (not Debug), so assert via the Err arm.
        assert_eq!(bp.compile().err(), Some(CompileError::RoleKindMismatch { role: 0 }));
```

with:

```rust
        let bp = Composite::new(
            "root",
            vec![BlueprintNode::Composite(c)],
            vec![],
            vec![Role { name: "src".into(), targets: vec![Target { node: 0, slot: 0 }], source: Some(ScalarKind::F64) }],
            vec![], // output
        );
        // the Ok arm holds Box<dyn Node> (not Debug), so assert via the Err arm.
        assert_eq!(bp.compile().err(), Some(CompileError::RoleKindMismatch { role: 0 }));
```

- [ ] **Step 3: Re-wire `output_port_out_of_range_rejected`**

(This is the test whose deep fault is an out-of-range OUTPUT field. The covering role
forces the root's role-kind loop to compute `c.signature()`, which only stays
panic-free because of the `derive_signature` guard in Task 1 Step 2b; the recursion
then reports `OutputPortOutOfRange` as before.)

Replace:

```rust
        let bp = Composite::new(
            "root",
            vec![BlueprintNode::Composite(c)],
            vec![],
            vec![],
            vec![], // output
        );
        // the Ok arm holds Box<dyn Node> (not Debug), so assert via the Err arm.
        assert_eq!(bp.compile().err(), Some(CompileError::OutputPortOutOfRange));
```

with:

```rust
        let bp = Composite::new(
            "root",
            vec![BlueprintNode::Composite(c)],
            vec![],
            vec![Role { name: "src".into(), targets: vec![Target { node: 0, slot: 0 }], source: Some(ScalarKind::F64) }],
            vec![], // output
        );
        // the Ok arm holds Box<dyn Node> (not Debug), so assert via the Err arm.
        assert_eq!(bp.compile().err(), Some(CompileError::OutputPortOutOfRange));
```

- [ ] **Step 4: Verify the three pass**

Run: `cargo test -p aura-engine bad_interior_index_rejected`
Expected: PASS (`1 passed`).
Run: `cargo test -p aura-engine role_kind_mismatch_rejected`
Expected: PASS (`1 passed`).
Run: `cargo test -p aura-engine output_port_out_of_range_rejected`
Expected: PASS (`1 passed`).

---

### Task 3: Fully wire the param-order nesting test

`param_space_mirrors_compiled_flat_node_param_order_under_nesting` compiles a
deliberately under-wired `strategy` (LinComb's two `term` inputs never fed) only to
read its flat param order. Fully wire it: fan `fast_slow`'s output into both LinComb
terms, and add a covering root role for `strategy`'s `price` input. Wiring changes no
node and no param, so the asserted `space == from_flat` equality is unchanged.

**Files:**
- Modify: `crates/aura-engine/src/blueprint.rs:1877`

- [ ] **Step 1: Wire the `strategy` edges and the root role**

In the function `param_space_mirrors_compiled_flat_node_param_order_under_nesting`,
replace (this span is unique to that function — it ends with the
`"nested composite compiles"` compile line, which the sibling param-order test lacks):

```rust
        let strategy = Composite::new(
            "strategy",
            vec![BlueprintNode::Composite(fast_slow), LinComb::builder(2).into()],
            vec![],
            vec![Role { name: "price".into(), targets: vec![Target { node: 0, slot: 0 }], source: None }],
            vec![OutField { node: 0, field: 0, name: "out".into() }],
        );
        let bp = Composite::new(
            "root",
            vec![BlueprintNode::Composite(strategy)],
            vec![],
            vec![],
            vec![], // output
        );

        // the aggregated, path-qualified projection (borrows; take it first since
        // compile() consumes self — same ordering as the single-level mirror test)
        let space = bp.param_space();

        // the same blueprint, compiled to its flat node array; each flat node's
        // own declared params, concatenated in flat-node order
        let flat = bp.compile_with_params(&[Scalar::I64(2), Scalar::I64(4), Scalar::F64(1.0), Scalar::F64(-1.0)]).expect("nested composite compiles");
```

with:

```rust
        let strategy = Composite::new(
            "strategy",
            vec![BlueprintNode::Composite(fast_slow), LinComb::builder(2).into()],
            // fan fast_slow's output into both LinComb terms so every interior slot
            // is wired (the totality check, cycle 0040); param order is unaffected.
            vec![
                Edge { from: 0, to: 1, slot: 0, from_field: 0 },
                Edge { from: 0, to: 1, slot: 1, from_field: 0 },
            ],
            vec![Role { name: "price".into(), targets: vec![Target { node: 0, slot: 0 }], source: None }],
            vec![OutField { node: 0, field: 0, name: "out".into() }],
        );
        let bp = Composite::new(
            "root",
            vec![BlueprintNode::Composite(strategy)],
            vec![],
            vec![Role { name: "price".into(), targets: vec![Target { node: 0, slot: 0 }], source: Some(ScalarKind::F64) }],
            vec![], // output
        );

        // the aggregated, path-qualified projection (borrows; take it first since
        // compile() consumes self — same ordering as the single-level mirror test)
        let space = bp.param_space();

        // the same blueprint, compiled to its flat node array; each flat node's
        // own declared params, concatenated in flat-node order
        let flat = bp.compile_with_params(&[Scalar::I64(2), Scalar::I64(4), Scalar::F64(1.0), Scalar::F64(-1.0)]).expect("nested composite compiles");
```

- [ ] **Step 2: Verify it passes**

Run: `cargo test -p aura-engine param_space_mirrors_compiled_flat_node_param_order_under_nesting`
Expected: PASS (`1 passed`).

---

### Task 4: New raw-surface tests (unwired, double-wired, nested, open-role boundary)

Add these five tests to the `#[cfg(test)] mod tests` block in
`crates/aura-engine/src/blueprint.rs` (alongside the existing negative tests). They
use the in-module helpers `pass1()` (one f64 input "in", one output) and `sink_f64()`
(one f64 input "in", no output), and the in-scope `Composite`, `Edge`, `Role`,
`Target`, `OutField`, `BlueprintNode`, `CompileError`, `ScalarKind`.

**Files:**
- Modify: `crates/aura-engine/src/blueprint.rs` (test module)

- [ ] **Step 1: Add the five tests**

```rust
    #[test]
    fn unconnected_interior_slot_rejected() {
        // pass1 is fed by a role; sink_f64's one input is left unwired -> rejected.
        let bp = Composite::new(
            "root",
            vec![pass1(), sink_f64()],
            vec![],
            vec![Role { name: "src".into(), targets: vec![Target { node: 0, slot: 0 }], source: Some(ScalarKind::F64) }],
            vec![],
        );
        assert_eq!(
            bp.compile().err(),
            Some(CompileError::UnconnectedPort { node: 1, slot: 0 })
        );
    }

    #[test]
    fn double_wired_slot_rejected_edge_and_role() {
        // sink_f64's one input is targeted by BOTH an edge (from pass1) and a role.
        let bp = Composite::new(
            "root",
            vec![pass1(), sink_f64()],
            vec![Edge { from: 0, to: 1, slot: 0, from_field: 0 }],
            vec![
                Role { name: "src".into(), targets: vec![Target { node: 0, slot: 0 }], source: Some(ScalarKind::F64) },
                Role { name: "extra".into(), targets: vec![Target { node: 1, slot: 0 }], source: Some(ScalarKind::F64) },
            ],
            vec![],
        );
        assert_eq!(
            bp.compile().err(),
            Some(CompileError::DoubleWiredPort { node: 1, slot: 0 })
        );
    }

    #[test]
    fn double_wired_slot_rejected_two_edges() {
        // two producers' edges land on sink_f64's single input slot.
        let bp = Composite::new(
            "root",
            vec![pass1(), pass1(), sink_f64()],
            vec![
                Edge { from: 0, to: 2, slot: 0, from_field: 0 },
                Edge { from: 1, to: 2, slot: 0, from_field: 0 },
            ],
            vec![
                Role { name: "a".into(), targets: vec![Target { node: 0, slot: 0 }], source: Some(ScalarKind::F64) },
                Role { name: "b".into(), targets: vec![Target { node: 1, slot: 0 }], source: Some(ScalarKind::F64) },
            ],
            vec![],
        );
        assert_eq!(
            bp.compile().err(),
            Some(CompileError::DoubleWiredPort { node: 2, slot: 0 })
        );
    }

    #[test]
    fn unconnected_slot_in_nested_composite_rejected() {
        // inner composite c: pass1 (fed by c's role) + sink_f64 (interior slot
        // unwired). The root covers c's one input, so the fault surfaces only via
        // the recursion into c -> UnconnectedPort at c's interior index (1, 0).
        let c = Composite::new(
            "c",
            vec![pass1(), sink_f64()],
            vec![],
            vec![Role { name: "in".into(), targets: vec![Target { node: 0, slot: 0 }], source: None }],
            vec![OutField { node: 0, field: 0, name: "out".into() }],
        );
        let bp = Composite::new(
            "root",
            vec![BlueprintNode::Composite(c)],
            vec![],
            vec![Role { name: "src".into(), targets: vec![Target { node: 0, slot: 0 }], source: Some(ScalarKind::F64) }],
            vec![],
        );
        assert_eq!(
            bp.compile().err(),
            Some(CompileError::UnconnectedPort { node: 1, slot: 0 })
        );
    }

    #[test]
    fn open_role_provider_is_not_flagged_unconnected() {
        // a composite whose OPEN input role (source: None) feeds its interior slot,
        // used as a nested node with that role covered by the enclosing root, must
        // compile — the open role is a provider, not an unwired consumer.
        let c = Composite::new(
            "c",
            vec![pass1()],
            vec![],
            vec![Role { name: "in".into(), targets: vec![Target { node: 0, slot: 0 }], source: None }],
            vec![OutField { node: 0, field: 0, name: "out".into() }],
        );
        let bp = Composite::new(
            "root",
            vec![BlueprintNode::Composite(c)],
            vec![],
            vec![Role { name: "src".into(), targets: vec![Target { node: 0, slot: 0 }], source: Some(ScalarKind::F64) }],
            vec![],
        );
        assert!(bp.compile().is_ok(), "open role as provider must not be mis-flagged");
    }
```

- [ ] **Step 2: Verify the five pass**

Run: `cargo test -p aura-engine unconnected_interior_slot_rejected`
Expected: PASS (`1 passed`).
Run: `cargo test -p aura-engine double_wired_slot_rejected_edge_and_role`
Expected: PASS (`1 passed`).
Run: `cargo test -p aura-engine double_wired_slot_rejected_two_edges`
Expected: PASS (`1 passed`).
Run: `cargo test -p aura-engine unconnected_slot_in_nested_composite_rejected`
Expected: PASS (`1 passed`).
Run: `cargo test -p aura-engine open_role_provider_is_not_flagged_unconnected`
Expected: PASS (`1 passed`).

---

### Task 5: Builder-surface forgotten-leg test

Mirror `builder_harness_compiles_identically_to_hand_wired` but omit the
exposure→broker connection: every name resolves so `build()` succeeds, but
`compile_with_params` rejects the uncovered broker exposure slot. Proves the
`GraphBuilder` surface inherits the check.

**Files:**
- Modify: `crates/aura-engine/src/builder.rs` (test module, after
  `builder_harness_compiles_identically_to_hand_wired`)

- [ ] **Step 1: Add the test**

```rust
    #[test]
    fn unconnected_port_rejected_on_builder_surface() {
        use crate::CompileError;
        use aura_core::Scalar;
        // The forgotten-exposure-leg harness: every port/field name resolves, so
        // build() succeeds; but broker.input("exposure") is never connected, so the
        // wiring-totality check rejects it at compile (broker is node 1, slot 0).
        let (tx_eq, _r1) = mpsc::channel();
        let mut g = GraphBuilder::new("root");
        let expo = g.add(Exposure::builder());
        let broker = g.add(SimBroker::builder(0.0001));
        let eq = g.add(Recorder::builder(vec![ScalarKind::F64], Firing::Any, tx_eq));
        let price = g.source_role("price", ScalarKind::F64);
        g.feed(price, [expo.input("signal"), broker.input("price")]);
        // BUG: g.connect(expo.output("exposure"), broker.input("exposure")) missing.
        g.connect(broker.output("equity"), eq.input("col[0]"));
        let compiled = g
            .build()
            .expect("all port/field names resolve")
            .compile_with_params(&[Scalar::F64(0.5)]);
        assert_eq!(
            compiled.err(),
            Some(CompileError::UnconnectedPort { node: 1, slot: 0 })
        );
    }
```

- [ ] **Step 2: Verify it passes**

Run: `cargo test -p aura-engine unconnected_port_rejected_on_builder_surface`
Expected: PASS (`1 passed`).

---

### Task 6: C8 ledger realization note

**Files:**
- Modify: `docs/design/INDEX.md:316` (after the cycle-0027 realization block, before
  the blank line preceding `### C9`)

- [ ] **Step 1: Insert the cycle-0040 realization note**

Find the end of the C8 "Realization (cycle 0027 — name input ports…)" block (the
paragraph ending "…a name-consuming validation is its own future cycle.", ~line 316),
and insert a blank line then this paragraph immediately after it:

```text
**Realization (cycle 0040 — wiring totality: every input slot connected exactly
once, #65).** The node contract's "the engine provides a window into each input"
presupposes each input is actually fed; until now an unwired interior input slot was
accepted and bootstrapped to a silent empty column (`harness.rs`), and two producers
into one slot — ill-formed, since a slot holds one column — was likewise
uncompiled-against. Cycle 0040 makes a valid graph **total and single-valued** over
its interior input slots: `check_ports_connected` (in `validate_wiring`, run at every
nesting level) requires every interior node's every declared input slot to be covered
by **exactly one** wiring act — one interior `Edge { to, slot }` or one role
`Target { node, slot }`, edges and role targets counted uniformly. Zero coverage is
`CompileError::UnconnectedPort`, more than one is `CompileError::DoubleWiredPort`. A
composite's **own** input roles (`source: None`) are coverage *providers* — the
wired-by-enclosing boundary, the root case already guarded by `UnboundRootRole` —
never consumers, so only interior input slots are subject to the rule. There is **no
optional-input concept**: every declared input port is required (no shipped node runs
meaningfully without one; an unwarmed mode-A input is *wired-but-not-yet-valued*, not
unwired). The check is **index-based and name-free** — it touches no name machinery
and emits nothing into the flat graph, so C23 is untouched (it proves the existing
raw-index wiring is total and single-valued). Inherited identically by the raw
`Composite::new` path and the `GraphBuilder::build()` path (both compile via
`compile_with_params`).
```

- [ ] **Step 2: Confirm the note landed**

Run: `grep -c "cycle 0040 — wiring totality" docs/design/INDEX.md`
Expected: `1`

---

### Task 7: Full-suite + lint gate

**Files:** none (verification only)

- [ ] **Step 1: Full workspace test**

Run: `cargo test --workspace 2>&1 | grep -E "test result:" | grep -v "0 failed" | head`
Expected: no output (every `test result:` line reports `0 failed`).

- [ ] **Step 2: Clippy**

Run: `cargo clippy --workspace --all-targets -- -D warnings`
Expected: finishes with 0 warnings/errors.