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

Wiring-totality check: reject unwired or double-wired input ports — Design Spec

Date: 2026-06-14 Status: Draft — awaiting user spec review Authors: orchestrator + Claude

Narrowed scope of issue #65 (see the reconciliation comment on that issue). The original "promote names to load-bearing wiring keys / close the exposure-price swap structurally" framing is dropped: #64 (the typed-handle, named-port GraphBuilder, commit a6a314b) already moved authoring to handles + visible port names, so the residual same-kind swap is a valid-but-wrong name choice no structural check can catch, and a structural fix (per-port semantic tags) would push domain semantics into the deliberately domain-free engine (C10/C7). This cycle ships only the name-free half that stands on its own.

Goal

Make a graph that leaves an interior input slot unwired, or wires one slot from more than one producer, a compile-time error instead of a silently-wrong run. Today an unwired input slot is bootstrapped with an empty column (crates/aura-engine/src/harness.rs:138-148: every declared slot gets an AnyColumn and a SlotState { last_ts: i64::MIN }, fresh only when fed) — so a forgotten connection runs a deterministic but wrong backtest, and two producers into one slot is ill-formed (a slot holds exactly one column) yet uncompiled- against. A single new structural check at the existing compile boundary closes both, for both authoring surfaces, without touching the flat graph (C23).

Non-goal (explicitly out of scope, dropped this cycle): promoting port/field/node names to load-bearing wiring keys; node-name or port/field-name uniqueness; per-port semantic tags; and any claim of closing the SimBroker exposure/price swap. This spec is purely about wiring totality (every required slot wired exactly once), an index-based property.

Architecture

The check lives in one place: validate_wiring (crates/aura-engine/src/blueprint.rs:496), the pre-build structural validation that Composite::compile_with_params already calls once (blueprint.rs:201) and that already recurses into nested composites (blueprint.rs:540-543). A new check_ports_connected(nodes, edges, roles) added to that function therefore runs at every nesting level automatically, and — because the typed GraphBuilder lowers to Composite::new and is compiled through the same compile_with_params (no separate compile path) — it is inherited identically by the raw Composite::new path and the GraphBuilder::build() path with zero builder-side code. This is the same single-site, both-surfaces shape check_param_namespace_injective (blueprint.rs:409) already uses for the param address space; this is its wiring-side sibling.

Coverage is counted uniformly across the two wiring mechanisms: an interior Edge { to, slot } and a role Target { node, slot } each contribute one unit of coverage to the pair (node_index, slot). A composite's own input roles (Role, blueprint.rs:120) are coverage providers — their targets feed interior slots — never consumers: a composite's own open roles (source: None) are the legitimate "unwired here, wired by the enclosing graph" boundary and are not themselves subject to the rule; the root case is already guarded by the existing UnboundRootRole check (blueprint.rs:202-205). So the rule is scoped to interior nodes' input slots, and a role's source field is irrelevant to coverage counting (root-bound and nested-open roles count their targets the same).

The check is index-based and name-free; it reads only signature().inputs.len() and the existing index-wired Edge/Target, and emits nothing into the FlatGraph. C23 is untouched: it proves the existing raw-index wiring is total (every slot ≥1) and single-valued (every slot ≤1) without introducing a name.

Concrete code shapes

Worked acceptance example (criterion evidence) — a forgotten leg now fails fast

The empirical evidence the criterion demands: the SimBroker harness an author writes via the GraphBuilder, with the exposure leg forgotten. Today this compiles and runs a wrong equity curve (broker slot 0 fed an empty column); after this cycle it is rejected at compile.

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: the exposure producer is never connected to broker.input("exposure").
// (g.connect(expo.output("exposure"), broker.input("exposure")) is missing.)
g.connect(broker.output("equity"), eq.input("col[0]"));

// Every NAME resolves (both ports exist), so the builder succeeds:
let composite = g.build().expect("all port/field names resolve");
// The wiring-totality check fires at compile: broker's exposure slot is uncovered.
let compiled = composite.compile_with_params(&params);
assert!(matches!(compiled, Err(CompileError::UnconnectedPort { .. })));

The complementary double-wire, on the raw Composite::new surface (showing the same check guards the non-builder path) — one slot fed by an edge and a role target:

// broker input slot 1 ("price") is targeted by BOTH a role target and an edge.
let bp = Composite::new(
    "root",
    vec![/* ... exposure producer @0, broker @1, ... */],
    vec![Edge { from: 0, to: 1, slot: 1, from_field: 0 }],     // edge -> (broker, slot 1)
    vec![Role { name: "price".into(),
                targets: vec![Target { node: 1, slot: 1 }],     // role ALSO -> (broker, slot 1)
                source: Some(ScalarKind::F64) }],
    vec![/* output */],
);
assert!(matches!(bp.compile_with_params(&params),
                 Err(CompileError::DoubleWiredPort { node: 1, slot: 1 })));

Before → after: the new check (the load-bearing change)

New function, mirroring check_param_namespace_injective's single-pass shape:

/// 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 (runs a silent empty column); >1 = an ill-formed slot
/// (one slot holds one column). Index-based, name-free; presupposes in-range
/// edge/role indices (run after the existing index-range checks).
fn check_ports_connected(
    nodes: &[BlueprintNode],
    edges: &[Edge],
    roles: &[Role],
) -> Result<(), CompileError> {
    let mut coverage: HashMap<(usize, usize), usize> = 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(())
}

Call site, inside validate_wiring — after the existing edge/role/output index-range + kind checks (so all indices are known in-range) and before the nested-composite recursion, so it runs once per level:

fn validate_wiring(nodes, edges, roles, output) -> Result<(), CompileError> {
    // ... existing edge index+kind checks (blueprint.rs:506-517) ...
    // ... existing role target index+kind checks (blueprint.rs:520-531) ...
    // ... existing output re-export index checks (blueprint.rs:533-538) ...

    check_ports_connected(nodes, edges, roles)?;   // <-- NEW: totality, this level

    for item in nodes {                            // existing recursion (540-543)
        if let BlueprintNode::Composite(c) = item {
            validate_wiring(c.nodes(), c.edges(), c.input_roles(), c.output())?;
        }
    }
    Ok(())
}

Before → after: two new CompileError variants

pub enum CompileError {
    // ... existing variants (BadInteriorIndex, RoleKindMismatch, ...
    //     DuplicateParamPath, UnboundRootRole) unchanged ...

    /// 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 },
}

Components

• check_ports_connected (new, crates/aura-engine/src/blueprint.rs) — the coverage check above. Pure, pre-build, reads signature() only.
• validate_wiring (modified, blueprint.rs:496) — one new call after the index-range checks, before the recursion.
• CompileError (modified, blueprint.rs:465) — two new variants. The enum derives Debug, PartialEq, Eq; the new variants carry only usize fields, so the derives still hold (no manual impl).
• Design ledger (docs/design/INDEX.md) — a small realization note under C8 recording the new structural invariant (text below). No C23 amendment: names are not involved.

Ledger amendment (under C8, after the cycle-0027 realization block)

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

Data flow

Composite::compile_with_params → validate_wiring(nodes, edges, roles, output) → [existing index/kind checks] → check_ports_connected(nodes, edges, roles) → [recurse per nested composite] → (on Ok) UnboundRootRole check → lower_items → FlatGraph. The new check is a pure read over the same three slices validate_wiring already holds; it adds no data to the flat graph and no work to the run loop.

Error handling

Two new typed CompileError variants, each carrying the offending (node, slot) (per-level interior node index — the same addressing convention BadInteriorIndex-adjacent code uses). They surface from compile_with_params exactly like the existing construction-phase faults. No panics, no new error channel. When multiple slots are faulty, the first encountered (lowest node index, then lowest slot) is returned — deterministic by iteration order; callers that need all faults are out of scope (the existing variants are first-fault too).

Testing strategy

1. Unwired interior slot → UnconnectedPort. Build the forgotten-exposure-leg harness (the worked example above, builder surface) and a raw Composite::new variant; assert compile_with_params(&params) is Err(CompileError::UnconnectedPort { .. }) with the expected (node, slot).
2. Double-wired slot → DoubleWiredPort. The raw double-wire above (edge + role into one slot) and an edge+edge variant; assert Err(CompileError::DoubleWiredPort { node, slot }).
3. Nested-level enforcement. A composite whose interior leaves a slot unwired, nested inside a root whose own wiring is complete; assert the nested fault still surfaces (the recursion carries the check down).
4. Open-role boundary stays legal. A composite with an open input role (source: None) whose target feeds an interior slot compiles when used as a nested node with that role wired by the enclosing graph — the role-as-provider path is not mis-flagged as an unwired slot.
5. Regression — valid graphs still compile. The canonical harness (crates/aura-engine/src/test_fixtures.rs) and the builder harness (builder_harness_compiles_identically_to_hand_wired) still compile green; the aura-cli sample / sweep / param_space / render tests stay green.
6. C23 regression — flat graph byte-identical. For any graph that still compiles, the lowered FlatGraph is unchanged (the existing identity test covers this; the check adds nothing to lowering).

Blast radius (empirically enumerated — fixed in this iteration, not deferred)

The authoritative blast radius was determined by a throwaway probe (the check implemented, cargo test --workspace --no-fail-fast run, then discarded): exactly four currently-green tests flip, all in crates/aura-engine/src/blueprint.rs (119 passed, 4 failed; every other crate — including the aura-cli sample/sweep/param_space/ render tests — stays green). Three are negative tests that wrap a single-role composite c in a root with empty edges and empty roles (vec![BlueprintNode::Composite(c)], vec![], vec![], vec![]), leaving the root's one interior node (a composite exposes one derived input port per role, blueprint.rs:76-99) uncovered, so check_ports_connected — running at the root level before the recursion — returns UnconnectedPort { node: 0, slot: 0 } and pre-empts the deeper fault each targets:

• bad_interior_index_rejected (~1372) — asserts BadInteriorIndex (a fault inside c).
• role_kind_mismatch_rejected (~1440) — asserts RoleKindMismatch { role: 0 }.
• output_port_out_of_range_rejected (~1463) — asserts OutputPortOutOfRange.

The fourth is a compile-success param-order test, param_space_mirrors_compiled_flat_node_param_order_under_nesting (~1856), which today compiles a deliberately under-wired nested graph just to read its flat param order: the inner strategy composite (~1877) holds [Composite(fast_slow), LinComb(2)] but wires neither of LinComb's two term inputs, and the root (~1885) wraps strategy with empty edges/roles, leaving strategy's price input uncovered too. The new check rejects it (UnconnectedPort) where it currently returns Ok.

Resolution (in this iteration):

• The three negative tests: give each root a covering input Role whose target is c's input slot (Role { name: "src".into(), targets: vec![Target { node: 0, slot: 0 }], source: Some(ScalarKind::F64) }, mirroring the existing covering-role pattern at ~1414). The root level then passes and the recursion surfaces the intended deep fault (the index/kind/output checks run before c's own connectivity check), so each STILL asserts its original variant.
• The fourth (param-order) test: fully wire the contrived graph — fan fast_slow's output into both LinComb terms (Edge { from: 0, to: 1, slot: 0, from_field: 0 } and Edge { from: 0, to: 1, slot: 1, from_field: 0 } in strategy) and add a covering root role for strategy's price input. Wiring does not change node order or params, so the asserted param_space == compiled-flat-param-order equality is unchanged; only the graph becomes valid.

These fixtures merely relied incidentally on under-wiring being accepted, which this cycle makes invalid — the load-bearing test maintenance a new structural invariant entails.

Two adjacent negative tests are safe by ordering and need no change: compile_rejects_kind_mismatch_without_building (~2013) — the edge kind-check fires before check_ports_connected; and unbound_root_role_is_rejected (~2042) — its root slot is covered by its role target, and UnboundRootRole is checked after validate_wiring returns. The fully-wired Composite-wrap tests (blueprint.rs ~1146, 1247, 1285, 1292, 1337) all carry a covering root role/edge and stay green.

Acceptance criteria

• check_ports_connected exists in validate_wiring; the two CompileError variants exist; both the raw Composite::new and the GraphBuilder::build() surfaces reject an unwired and a double-wired slot (proved by a negative test on each surface for at least UnconnectedPort, and at least one DoubleWiredPort test).
• The nested-level test (3) and the open-role-boundary test (4) pass.
• All four empirically-enumerated blast-radius tests are fixed and green: the three negative tests (bad_interior_index_rejected, role_kind_mismatch_rejected, output_port_out_of_range_rejected) re-wired with a covering root role and still asserting their original deep-fault variant; and the param-order test (param_space_mirrors_compiled_flat_node_param_order_under_nesting) fully wired and still asserting its param_space == compiled-flat-param-order equality.
• The full existing suite stays green (regression 5) and the flat graph is byte-identical for graphs that still compile (regression 6).
• The C8 ledger realization note is landed.
• cargo test --workspace green; cargo clippy --workspace --all-targets -D warnings clean.