# Node-instance naming — Implementation Plan > **Parent spec:** `docs/specs/0031-node-instance-naming.md` > > **For agentic workers:** REQUIRED SUB-SKILL: use the `implement` skill to run > this plan. Steps use `- [ ]` checkboxes for tracking. **Goal:** Give every blueprint node a name (default = its lowercased type label), make `param_space()` uniformly `.`, re-key fan-in distinguishability onto the node name, and remove the index-addressed `ParamAlias` overlay. **Architecture:** `PrimitiveBuilder` (aura-core) gains an instance-name slot (`name: Option`, `.named()`, `node_name()`). `blueprint.rs` (aura-engine) inserts the node-name segment in `collect_params`, re-keys `signature_of` and the fan-in predicate onto the node name, and drops `ParamAlias` / `Composite.params` / the `Composite::new` 5th argument / `aliases_on` / `check_alias_indices`. Removing the argument is a compile-coupled change, so every in-workspace `Composite::new` caller and `ParamAlias` reference migrates in the same task; the `cargo build --workspace` gate enumerates completeness. **Tech Stack:** Rust. `crates/aura-core/src/node.rs`, `crates/aura-engine/src/{blueprint.rs, lib.rs, graph_model.rs, sweep.rs}`, `crates/aura-cli/src/main.rs`, `crates/aura-cli/tests/cli_run.rs`, `docs/design/INDEX.md`. --- **Files this plan creates or modifies:** - Modify: `crates/aura-core/src/node.rs:77-116` — `PrimitiveBuilder` instance-name mechanism - Test: `crates/aura-core/src/node.rs` (mod tests, ~:190) — `node_name()` default + override - Modify: `crates/aura-engine/src/blueprint.rs` — `collect_params` (:688-730), `signature_of` (:546-590), `leaf_has_unaliased_param`→`leaf_has_param` (:674-686), `check_composite_fan_in` (:635-672), `check_fan_in_distinguishability` (:616-628), `Composite` struct (:137-144) + `Composite::new` (:151-160) + `params()` (:180-184) + `param_space()` call (:197); REMOVE `ParamAlias` (:121-130), `aliases_on` (:592-598), `check_alias_indices` (:600-614) - Test: `crates/aura-engine/src/blueprint.rs` (mod tests) — new path-shape / default-name / forcing-function / paramless tests; update the mirror + `top_level` + `signature_of` tests; remove the alias-semantics tests - Modify: `crates/aura-engine/src/lib.rs:41-42` — drop the `ParamAlias` / `aliases_on` / `signature_of` re-export of the retired overlay - Modify: `crates/aura-engine/src/graph_model.rs` — `ParamAlias` import (:235) + `Composite::new` fixtures (:274,:302,:326,:344) + alias literals (:287-288): structural migration only - Modify: `crates/aura-engine/src/sweep.rs` — `ParamAlias` import (:173) + `Composite::new` fixtures (:276,:306) + alias literals (:289-290): structural migration only - Modify: `crates/aura-cli/src/main.rs` — `sma_cross` sample (:137-155), root harness (:170), EMA/MACD composite (:338,:382), sweep goldens (:537-540), `.axis()` block (:229-231), single-run `.with()` (:516-518), MACD param assertion (:597-599), `ParamAlias` import (:14) - Modify: `crates/aura-cli/tests/cli_run.rs:214` — the sweep-golden twin (lockstep with main.rs:537-540) - Modify: `docs/design/INDEX.md` — amend C9 (:367-375) and C23 (:359-366, :813-851) **Out of scope (do NOT touch):** `crates/aura-cli/tests/fixtures/sample-model.json` and the `model_to_json` golden at `graph_model.rs:430` — `model_to_json` emits the **type** label (`b.label()` → `"SMA"`) and factory param names (`"length"`), which are alias-independent and node-name-independent; this cycle does not change the JSON model surface, so those goldens stay byte-identical. The `fieldtests/` crates are frozen non-workspace records — not built or gated by `cargo --workspace`. --- ## Task 1: `PrimitiveBuilder` instance-name mechanism (aura-core) Additive — no existing call site breaks (`PrimitiveBuilder::new` keeps its signature; the new field defaults internally). **Files:** - Modify: `crates/aura-core/src/node.rs:77-116` - Test: `crates/aura-core/src/node.rs` (mod tests) - [ ] **Step 1: Write the failing test** Add to the `mod tests` block in `crates/aura-core/src/node.rs` (near the existing `primitive_builder_label_is_the_bare_type` at ~:196): ```rust #[test] fn node_name_defaults_to_lowercased_type_label() { // unnamed → the type label, ASCII-lowercased verbatim (no snake_case) let unnamed = PrimitiveBuilder::new( "SimBroker", NodeSchema::default(), |_| panic!("not built in this test"), ); assert_eq!(unnamed.node_name(), "simbroker"); // explicit name overrides let named = PrimitiveBuilder::new( "SMA", NodeSchema::default(), |_| panic!("not built in this test"), ) .named("fast"); assert_eq!(named.node_name(), "fast"); } ``` - [ ] **Step 2: Run test to verify it fails** Run: `cargo test -p aura-core node_name_defaults_to_lowercased_type_label` Expected: compile error / FAIL — no method `node_name` / `named` on `PrimitiveBuilder`. - [ ] **Step 3: Write minimal implementation** In `crates/aura-core/src/node.rs`, add a `name: Option` field to `PrimitiveBuilder` (struct at :77-84), initialise it in `new` (:90-96), and add the two methods. Concretely: Struct — add the field: ```rust pub struct PrimitiveBuilder { name: &'static str, // existing: the type label instance_name: Option, // NEW: the optional instance name schema: NodeSchema, build: Box Box>, } ``` `new` — initialise the new field (`instance_name: None`): ```rust pub fn new( name: &'static str, schema: NodeSchema, build: impl Fn(&[Scalar]) -> Box + 'static, ) -> Self { Self { name, instance_name: None, schema, build: Box::new(build) } } ``` Add the two methods (near `label()` at :113): ```rust /// Set this node instance's name. Must be non-empty. pub fn named(mut self, name: &str) -> Self { debug_assert!(!name.is_empty(), "node name must be non-empty"); self.instance_name = Some(name.to_string()); self } /// The resolved node name: the explicit instance name if set, else the /// type label ASCII-lowercased verbatim (e.g. "SimBroker" -> "simbroker"). pub fn node_name(&self) -> String { self.instance_name .clone() .unwrap_or_else(|| self.name.to_ascii_lowercase()) } ``` - [ ] **Step 4: Run test to verify it passes** Run: `cargo test -p aura-core node_name_defaults_to_lowercased_type_label` Expected: PASS. - [ ] **Step 5: Build the crate (additive, no caller breakage)** Run: `cargo build -p aura-core` Expected: 0 errors (the new field is internal; `new` still takes 3 args). --- ## Task 2: Engine mechanism, overlay removal, and the full compile-coupled migration (aura-engine + aura-cli) This is one task by necessity: dropping the `Composite::new` 5th argument and the `ParamAlias` struct breaks every caller at once, so all callers + the struct removal + the dependent test-string updates land together under one `cargo build/test --workspace` gate (planner self-review #7). **Files:** `crates/aura-engine/src/blueprint.rs`, `lib.rs`, `graph_model.rs`, `sweep.rs`; `crates/aura-cli/src/main.rs`, `crates/aura-cli/tests/cli_run.rs`. - [ ] **Step 1: Write/replace the executable-spec tests (the RED side)** In `crates/aura-engine/src/blueprint.rs` `mod tests`, add the new behaviour tests. These assert the post-change strings, so they fail (or do not compile) until the logic + signature land in Steps 2-7. Use named SMAs and the **new** 5-arg `Composite::new` (no `params` arg): ```rust #[test] fn named_siblings_path_qualify_with_node_segment() { use aura_std::{Sma, Sub}; // two SMAs, named fast/slow, feeding a Sub, under composite "sma_cross" let cross = Composite::new( "sma_cross", vec![ Sma::builder().named("fast").into(), Sma::builder().named("slow").into(), Sub::builder().into(), ], vec![ Edge { from: 0, to: 2, slot: 0, from_field: 0 }, Edge { from: 1, to: 2, slot: 1, from_field: 0 }, ], vec![Role { name: "price".into(), targets: vec![Target { node: 0, slot: 0 }, Target { node: 1, slot: 0 }], source: None, }], vec![OutField { node: 2, field: 0, name: "cross".into() }], ); let names: Vec = cross.param_space().into_iter().map(|p| p.name).collect(); assert_eq!(names, ["sma_cross.fast.length", "sma_cross.slow.length"]); } #[test] fn unnamed_single_primitive_uses_lowercased_type_label_segment() { use aura_std::Sma; let bp = Composite::new( "root", vec![Sma::builder().into()], vec![], vec![], vec![], ); assert_eq!(bp.param_space()[0].name, "sma.length"); } #[test] fn unnamed_same_type_param_bearing_fan_in_is_rejected() { use aura_std::{Sma, Sub}; let bp = Composite::new( "sma_cross", vec![Sma::builder().into(), Sma::builder().into(), Sub::builder().into()], vec![ Edge { from: 0, to: 2, slot: 0, from_field: 0 }, Edge { from: 1, to: 2, slot: 1, from_field: 0 }, ], vec![Role { name: "price".into(), targets: vec![Target { node: 0, slot: 0 }, Target { node: 1, slot: 0 }], source: None, }], vec![OutField { node: 2, field: 0, name: "cross".into() }], ); // both SMAs default to "sma" → collide → fan-in indistinguishable assert_eq!(bp.compile().err(), Some(CompileError::IndistinguishableFanIn { node: 2 })); } #[test] fn named_param_bearing_fan_in_bootstraps() { use aura_std::{Sma, Sub}; let bp = Composite::new( "sma_cross", vec![ Sma::builder().named("fast").into(), Sma::builder().named("slow").into(), Sub::builder().into(), ], vec![ Edge { from: 0, to: 2, slot: 0, from_field: 0 }, Edge { from: 1, to: 2, slot: 1, from_field: 0 }, ], vec![Role { name: "price".into(), targets: vec![Target { node: 0, slot: 0 }, Target { node: 1, slot: 0 }], source: None, }], vec![OutField { node: 2, field: 0, name: "cross".into() }], ); // distinct node names → fan-in distinguishable → compiles assert!(bp.compile().is_ok()); } ``` Keep `interchangeable_fan_in_allowed` (:1561) — two **paramless** same-type siblings stay legal; after migration its fixture's `Composite::new` loses the 5th arg but the assertion (compiles OK) is unchanged. - [ ] **Step 2: Run the new tests to verify they fail** Run: `cargo test -p aura-engine named_siblings_path_qualify_with_node_segment` Expected: FAIL — either a compile error (5-arg `Composite::new` not yet in effect) or an assertion mismatch (`sma_cross.length` vs `sma_cross.fast.length`). - [ ] **Step 3: Rewrite `collect_params` to insert the node segment uniformly** Replace `collect_params` (:688-730) with the node-segment form (drop the `aliases` parameter; a primitive contributes `..`): ```rust fn collect_params(items: &[BlueprintNode], prefix: &str, out: &mut Vec) { for item in items { match item { BlueprintNode::Primitive(b) => { let node = if prefix.is_empty() { b.node_name() } else { format!("{prefix}.{}", b.node_name()) }; for p in b.params() { out.push(ParamSpec { name: format!("{node}.{}", p.name), kind: p.kind }); } } BlueprintNode::Composite(c) => { let child = if prefix.is_empty() { c.name().to_string() } else { format!("{prefix}.{}", c.name()) }; collect_params(c.nodes(), &child, out); } } } } ``` Update the `param_space()` call site (:197) to drop `&self.params`: ```rust collect_params(&self.nodes, "", &mut out); ``` - [ ] **Step 4: Re-key `signature_of` and the fan-in predicate onto the node name** `signature_of` (:546-590): drop the `aliases: &[ParamAlias]` parameter and the `aliases_on` loop (:559-563); the per-node component becomes the full node name (so two `"sma"` collide, `"fast"`/`"slow"` differ). Keep the `-> String` return. Replace the primitive arm's initial-building with the node name: ```rust pub fn signature_of(nodes: &[BlueprintNode], edges: &[Edge], roles: &[Role], node: usize) -> String { let mut sig = match &nodes[node] { BlueprintNode::Primitive(b) => b.node_name(), // was: type initial + alias initials BlueprintNode::Composite(c) => c.name().to_string(), }; // recurse over inputs exactly as today (edges feeding `node`), appending each // input's signature_of(...) in slot order: for e in inputs_of(edges, node) { // same input-gathering as today sig.push_str(&signature_of(nodes, edges, roles, e.from)); } sig } ``` (Match the existing recursion shape at :559-590; only the per-node head and the removed `aliases` param change.) `leaf_has_unaliased_param` (:674-686) → `leaf_has_param`: drop the `aliases` arg and the `aliased` subtraction (:681-682); it is now true iff the leaf node has ≥1 param: ```rust fn leaf_has_param(nodes: &[BlueprintNode], node: usize) -> bool { matches!(&nodes[node], BlueprintNode::Primitive(b) if !b.params().is_empty()) } ``` `check_composite_fan_in` (:635-672): drop the `param_aliases` parameter; remove the `check_alias_indices` call (:644); update the two helper calls (:651-652): ```rust signature_of(nodes, edges, input_roles, e.from), leaf_has_param(nodes, e.from), ``` `check_fan_in_distinguishability` (:616-628): drop `c.params()` from the `check_composite_fan_in(...)` call (:623). The `IndistinguishableFanIn { node }` construction (:666) is unchanged. - [ ] **Step 5: Remove the overlay (struct, field, arg, helpers, alias tests)** - Delete `pub struct ParamAlias { … }` (:121-130). - Delete the `params: Vec` field from `Composite` (:142) and the `pub fn params(&self) -> &[ParamAlias]` accessor (:180-184). - Change `Composite::new` (:151-160) to a 5-arg signature (drop `params`): ```rust pub fn new( name: impl Into, nodes: Vec, edges: Vec, input_roles: Vec, output: Vec, ) -> Self { Self { name: name.into(), nodes, edges, input_roles, output } } ``` - Delete `aliases_on` (:592-598) and `check_alias_indices` (:600-614). Keep the `CompileError::BadInteriorIndex` variant (:458) — it is still used by the other index checks (:498-515, :872-914); only the dangling-alias path that produced it is gone. - Delete the alias-semantics tests: `param_alias_relabels_param_space_name_in_place` (:1991-2022), `partial_aliasing_relabels_only_the_named_slot` (:2087-2113), `out_of_range_param_alias_rejected` (:2024-2057), `unaliased_params_keep_factory_names` (:2059-…). Their behaviour no longer exists. - Amend the alias-overlay comment at :803-810 to describe node-name qualification. - [ ] **Step 6: Update the engine `lib.rs` re-export** In `crates/aura-engine/src/lib.rs:41-42`, remove `ParamAlias` (and `aliases_on` if re-exported) from the `pub use blueprint::{…}` list. Keep `signature_of`, `Composite`, `Role`, `OutField`, `BindError`, etc. (Quote: drop exactly the `ParamAlias`/`aliases_on` identifiers from the brace list.) - [ ] **Step 7: Mechanically migrate every in-workspace `Composite::new` call site + `ParamAlias` reference** Drop the 5th (`params`) argument from **every** `Composite::new(...)` call, and remove every `ParamAlias { … }` literal / import, across the workspace. The recon hand-list (advisory; the compile gate is authoritative): - `crates/aura-engine/src/blueprint.rs` tests: the ~46 `Composite::new` call sites enumerated by recon (e.g. :1273, :1301, …, :2363) lose their 5th arg; the alias literals at :1312-1313, :1759-1760, :2006-2007, :2037, :2100, :2192-2193, :2319-2321 are removed (or replaced with `.named(...)` on the relevant builder where a same-type param-bearing fan-in fixture would otherwise become `IndistinguishableFanIn`). - `crates/aura-engine/src/graph_model.rs`: import (:235), `Composite::new` fixtures (:274,:302,:326,:344), alias literals (:287-288) — drop the arg; where a fixture fans in two same-type param-bearing leaves, add `.named("a")`/`.named("b")` so it still compiles. **Do not** change the expected JSON golden at :430 (it pins `"type":"SMA"` + `["length","i64"]`, which `model_to_json` still emits). - `crates/aura-engine/src/sweep.rs`: import (:173), fixtures (:276,:306), alias literals (:289-290) — same treatment. - `crates/aura-cli/src/main.rs`: import (:14) removed; `sma_cross` (:137-155) — the two `ParamAlias{name:"fast"/"slow"}` (:150-151) become `.named("fast")` / `.named("slow")` on the two `Sma::builder()` (:140-ish) and the `params` arg is dropped; root harness (:170) drops its `vec![]` params arg; EMA/MACD composite (:338,:382) — its EMA-leg aliases (:363-365) become `.named(...)` on the EMA builders, params arg dropped. - [ ] **Step 8: Update the path-string assertions in the engine tests** - `param_space_mirrors_compiled_flat_node_param_order` (:1958, assertion :1981-1984): the fixture's two SMAs become `.named("fast")`/`.named("slow")`, the Exposure node stays default-named; the expected vector changes from `["sma_cross.fast", "sma_cross.slow", "scale"]` to `["sma_cross.fast.length", "sma_cross.slow.length", "exposure.scale"]`. The **kind-by-slot** part of the assertion (the load-bearing arity/order invariant) is unchanged. - `param_space_mirrors_compiled_flat_node_param_order_under_nesting` (:2177, assertion :2236-2239): name the fixture's SMAs; the kind-only assertion stays; any old alias literals (:2192-2193) are removed. - `param_space_is_flat_path_qualified_and_slot_disambiguated` (:2116, assertion :2152-2160): name the two SMAs; the expected strings gain the node segment (e.g. `strategy.fast_slow.fast.length` / `…slow.length` per the chosen fixture names). - `top_level_leaf_params_are_unqualified` (:2243-2256): **invert** the pin — the assertion at :2255 becomes `assert_eq!(space[0].name, "sma.length")` (root node now carries its name segment). Rename the test to `top_level_leaf_params_carry_the_node_segment` to reflect the inverted intent. - `signature_of_is_type_initial_plus_aliases_plus_recursive_inputs` (:1289-1297) + `macd_like_signature_fixture` (:1299-1317): rename to `signature_of_is_node_name_plus_recursive_inputs`; the fixture's EMA builders are default-named (`"ema"`) or `.named(...)`; the expected signature strings (:1294, :1296) are recomputed from the node-name head (no longer `"Efp"` / `"SEfpEsp"`). Compute the new expected strings from the rewritten `signature_of` and pin them exactly. - `indistinguishable_fan_in_rejected` (:1531-1559): stays green (`IndistinguishableFanIn { node: 2 }`); update the fixture comment (:1533-1534) from "unaliased" to "both default to `sma`". (This test overlaps `unnamed_same_type_param_bearing_fan_in_is_rejected` from Step 1 — keep both or fold into one; do not leave a duplicate name.) - [ ] **Step 9: Migrate the CLI sweep goldens (both files, lockstep)** - `crates/aura-cli/src/main.rs`: the `.axis(...)` block (:229-231) → `.axis("sma_cross.fast.length", …).axis("sma_cross.slow.length", …).axis("exposure.scale", …)`; the single-run `.with(...)` block (:516-518) → the same three names; the sweep golden assertions (:537-540) → `"params":{"sma_cross.fast.length":N,"sma_cross.slow.length":N,"exposure.scale":0.5}`; the MACD param assertion (:597-599) gains the node segments for its EMA knobs + `exposure.scale`. - `crates/aura-cli/tests/cli_run.rs:214`: the **twin** golden — replace `"params":{"sma_cross.fast":2,"sma_cross.slow":4,"scale":0.5}` with `"params":{"sma_cross.fast.length":2,"sma_cross.slow.length":4,"exposure.scale":0.5}`. Keep the substring contiguous on one line (self-review #6). - [ ] **Step 10: Workspace build + test + clippy gate (the completeness enumerator)** Run: `cargo build --workspace` Expected: 0 errors. (Any remaining un-migrated `Composite::new` caller or `ParamAlias` reference surfaces here — fix it, re-run, until 0 errors. This gate is the authoritative completeness check for the compile-coupled migration.) Run: `cargo test --workspace` Expected: PASS — all new tests green, the mirror/top_level/signature tests green with their updated strings, the CLI goldens green with the migrated names, the `model_to_json` goldens green **unchanged**. Run: `cargo clippy --workspace --all-targets -- -D warnings` Expected: 0 warnings. --- ## Task 3: Amend the design ledger (C9, C23) Doc-only; no compile coupling. **Files:** `docs/design/INDEX.md` - [ ] **Step 1: Amend C9 (fan-in distinguishability)** In `docs/design/INDEX.md`, the C9 fan-in refinement paragraph (:367-375): replace the rationale that keys distinguishability on "equal recursive signatures (type initial + alias initials + …)" and fires "when at least one colliding source carries an **unaliased param slot**" with the node-name keying: colliding sources are those with equal recursive **node-name** signatures; the collision is `IndistinguishableFanIn` when at least one carries a **param** (a param-bearing same-name collision), resolved by giving the colliding nodes distinct names. Paramless interchangeable same-name sources stay legal. - [ ] **Step 2: Amend C23 (named boundary projections)** In the C23-related prose at :359-366 and :813-851: strike the `ParamAlias` param-overlay from the named-projection set (the param projection is retired; `Role.name` input roles and `OutField.name` outputs remain). Note that node names join the same non-load-bearing debug-symbol class (construction-time identity, dropped at lowering; the flat graph stays wired by raw index). Remove the sentence referencing the dangling-alias `BadInteriorIndex` compile check (:362-364) — that path is gone with the overlay. - [ ] **Step 3: Verify the ledger references no retired symbol** Run: `grep -nE "ParamAlias|unaliased|aliases_on|check_alias_indices" docs/design/INDEX.md` Expected: no remaining references to the retired overlay (or only historical "was retired in cycle 0031" notes if added deliberately).