# Node Tunable-Parameter Declaration — Implementation Plan > **Parent spec:** `docs/specs/0015-node-param-declaration.md` > > **For agentic workers:** REQUIRED SUB-SKILL: use the `implement` skill to run > this plan. Steps use `- [ ]` checkboxes for tracking. **Goal:** A node declares its tunable parameters in its C8 schema (`ParamSpec`, a third `NodeSchema` field), and `Blueprint::param_space()` aggregates every node's params into one flat, path-qualified, inspectable param-space. **Architecture:** Two layers on existing machinery. `aura-core` gains the `ParamSpec` type and the `NodeSchema.params` field; the shipped `aura-std` nodes declare their tunable knobs. `aura-engine` gains a read-only `Blueprint::param_space()` that walks the graph-as-data (using the already-public `Composite::name()` as path prefix) in the same deterministic depth-first order `lower_items` uses — a parallel projection that leaves `compile`/`inline_composite` (and the flat graph) untouched. **Tech Stack:** Rust workspace — `aura-core` (node contract), `aura-std` (7 nodes), `aura-engine` (blueprint/compile). Param identity is positional (slot), name a non-load-bearing path-qualified debug symbol (C23). **Sequencing note (compile-gate ordering):** adding the non-`Default` `params` field makes every `NodeSchema { .. }` literal a compile error until updated. The 19 workspace literals span three crates; each crate's literals are repaired *inside* the crate's own task, and the per-crate build gate is `-p ` (a partial build) until Task 4 finishes the workspace-wide build. `crates/aura-cli` and `crates/aura-ingest` construct **zero** `NodeSchema` literals (recon-verified), so they need no change and compile clean once the others do. --- ## Files this plan creates or modifies - Modify: `crates/aura-core/src/node.rs:6-7` — stale module doc-comment update - Modify: `crates/aura-core/src/node.rs:38-53` — add `ParamSpec`, add `NodeSchema.params` - Modify: `crates/aura-core/src/node.rs:99-100` — `Bare` test fixture literal gains `params` - Modify: `crates/aura-core/src/lib.rs:42` — re-export `ParamSpec` - Modify: `crates/aura-std/src/{sma,exposure,lincomb}.rs` — declare params (+ `ParamSpec` import) - Modify: `crates/aura-std/src/{sub,add,sim_broker,recorder}.rs` — `params: vec![]` - Test: `crates/aura-std/src/sma.rs` — per-node declaration test (Sma/Exposure/LinComb + empty nodes) - Modify: `crates/aura-engine/src/blueprint.rs:113` — `Composite::schema()` adds `params: vec![]` - Modify: `crates/aura-engine/src/blueprint.rs:{373,419,438,453}` — 4 test fixtures gain `params: vec![]` - Modify: `crates/aura-engine/src/harness.rs:{358,384,406,436,474,498}` — 6 test fixtures gain `params: vec![]` - Modify: `crates/aura-engine/src/blueprint.rs:140-158` — add `Blueprint::param_space()` + `collect_params` helper - Modify: `crates/aura-engine/src/lib.rs:44` — re-export `ParamSpec` - Test: `crates/aura-engine/src/blueprint.rs` — nested-aggregation, top-level-unqualified, determinism, empty --- ## Task 1: `aura-core` — `ParamSpec` type + `NodeSchema.params` field **Files:** - Modify: `crates/aura-core/src/node.rs` - Modify: `crates/aura-core/src/lib.rs:42` - [ ] **Step 1: Add the `ParamSpec` type** In `crates/aura-core/src/node.rs`, immediately after the `FieldSpec` struct (ends at line 42), insert: ```rust /// One declared tunable parameter of a node (C8/C12): its render name and scalar /// kind. The name is a **non-load-bearing** debug symbol (path-qualified at /// aggregation, as `FieldSpec.name` already is); a param's identity is its /// positional slot in the blueprint's aggregated param-space (C23 — by index, not /// by name). Unlike `FieldSpec.name` (`&'static str`), the name is a `String`: a /// vector knob carries a runtime index (`weights[0]`) and aggregation prefixes the /// composite path (`strategy.weights[0]`). Permitted kinds: `I64`/`F64`/`Bool`; /// `Timestamp` is a structural axis (C20), never a numeric knob. #[derive(Clone, Debug, PartialEq, Eq)] pub struct ParamSpec { pub name: String, pub kind: ScalarKind, } ``` - [ ] **Step 2: Add the `params` field to `NodeSchema`** In the same file, the `NodeSchema` struct (lines 49-53) becomes: ```rust #[derive(Clone, Debug, PartialEq, Eq)] pub struct NodeSchema { pub inputs: Vec, pub output: Vec, pub params: Vec, } ``` - [ ] **Step 3: Update the stale module doc-comment** In the same file, replace lines 6-7: ```rust //! Tunable params (C12/C19) are deliberately not part of the schema yet — see //! spec 0002's "Out of scope". ``` with: ```rust //! Tunable params (C12/C19) are declared via `params` (cycle 0015): each node's //! typed knobs, which `Blueprint::param_space` aggregates into the sweep's flat, //! path-qualified param-space (C8/C23). Identity is positional (slot); the name is //! a non-load-bearing debug symbol. ``` - [ ] **Step 4: Repair the `Bare` test fixture literal** In the same file, the `Bare` fixture in `mod tests` (line ~99-101) constructs a `NodeSchema`. Add the field so it reads: ```rust fn schema(&self) -> NodeSchema { NodeSchema { inputs: vec![], output: vec![], params: vec![] } } ``` - [ ] **Step 5: Re-export `ParamSpec`** In `crates/aura-core/src/lib.rs:42`, the re-export line becomes: ```rust pub use node::{FieldSpec, Firing, InputSpec, Node, NodeSchema, ParamSpec}; ``` - [ ] **Step 6: Add a declaration test pinning the new field** In `crates/aura-core/src/node.rs` `mod tests`, add: ```rust #[test] fn schema_carries_declared_params() { let s = NodeSchema { inputs: vec![], output: vec![], params: vec![ParamSpec { name: "length".into(), kind: ScalarKind::I64 }], }; assert_eq!(s.params.len(), 1); assert_eq!(s.params[0].name, "length"); assert_eq!(s.params[0].kind, ScalarKind::I64); } ``` - [ ] **Step 7: Build + test `aura-core` (partial build gate)** Run: `cargo test -p aura-core` Expected: PASS — `aura-core` compiles (its one fixture repaired) and all its tests incl. `schema_carries_declared_params` pass. `aura-std`/`aura-engine` do **not** compile yet (their literals are repaired in Tasks 2-3); that is expected — this gate is scoped to `-p aura-core`. --- ## Task 2: `aura-std` — declare params in the 7 node schemas **Files:** - Modify: `crates/aura-std/src/sma.rs:6,24` - Modify: `crates/aura-std/src/exposure.rs:25` - Modify: `crates/aura-std/src/lincomb.rs:44` - Modify: `crates/aura-std/src/{sub.rs:29,add.rs:38,sim_broker.rs:61,recorder.rs:33}` - Test: `crates/aura-std/src/sma.rs` - [ ] **Step 1: `Sma` declares `length`** In `crates/aura-std/src/sma.rs`, add `ParamSpec` to the import (line 6): ```rust use aura_core::{Ctx, FieldSpec, Firing, InputSpec, Node, NodeSchema, ParamSpec, Scalar, ScalarKind}; ``` and the `schema()` literal (line 23-32) gains the field: ```rust fn schema(&self) -> NodeSchema { NodeSchema { inputs: vec![InputSpec { kind: ScalarKind::F64, lookback: self.length, firing: Firing::Any, }], output: vec![FieldSpec { name: "value", kind: ScalarKind::F64 }], params: vec![ParamSpec { name: "length".into(), kind: ScalarKind::I64 }], } } ``` - [ ] **Step 2: `Exposure` declares `scale`** In `crates/aura-std/src/exposure.rs`, add `ParamSpec` to the `aura_core` import, and the `schema()` literal (lines 24-27) gains: ```rust NodeSchema { inputs: vec![InputSpec { kind: ScalarKind::F64, lookback: 1, firing: Firing::Any }], output: vec![FieldSpec { name: "exposure", kind: ScalarKind::F64 }], params: vec![ParamSpec { name: "scale".into(), kind: ScalarKind::F64 }], } ``` - [ ] **Step 3: `LinComb` declares `weights[0..N]` (flat expansion)** In `crates/aura-std/src/lincomb.rs`, add `ParamSpec` to the `aura_core` import, and the `schema()` literal (lines 43-49) gains the mapped params: ```rust NodeSchema { inputs: self .weights .iter() .map(|_| InputSpec { kind: ScalarKind::F64, lookback: 1, firing: Firing::Any }) .collect(), output: vec![FieldSpec { name: "value", kind: ScalarKind::F64 }], params: (0..self.weights.len()) .map(|i| ParamSpec { name: format!("weights[{i}]"), kind: ScalarKind::F64 }) .collect(), } ``` - [ ] **Step 4: The four param-less nodes declare `params: vec![]`** Add `params: vec![]` as the final field of the `NodeSchema` literal in each of: - `crates/aura-std/src/sub.rs` (`Sub::schema`, ~line 29) - `crates/aura-std/src/add.rs` (`Add::schema`, ~line 38) - `crates/aura-std/src/sim_broker.rs` (`SimBroker::schema`, ~line 61 — `pip_size` is metadata, C10/C15, not a knob) - `crates/aura-std/src/recorder.rs` (`Recorder::schema`, ~line 33 — wiring, not a knob) No `ParamSpec` import is needed in these four (they use only `vec![]`). - [ ] **Step 5: Add the per-node declaration test** In `crates/aura-std/src/sma.rs` `mod tests` (it already imports the sibling nodes in `labels_carry_identifying_params`), add: ```rust #[test] fn nodes_declare_expected_params() { use crate::{Add, Exposure, LinComb, Recorder, SimBroker, Sub}; use aura_core::{Firing, ParamSpec, ScalarKind}; // single scalar knobs assert_eq!( Sma::new(3).schema().params, vec![ParamSpec { name: "length".into(), kind: ScalarKind::I64 }], ); assert_eq!( Exposure::new(0.5).schema().params, vec![ParamSpec { name: "scale".into(), kind: ScalarKind::F64 }], ); // vector knob expands flat to N indexed F64 entries let lc = LinComb::new(vec![1.0, -1.0]).schema().params; assert_eq!(lc.len(), 2); assert_eq!(lc[0].name, "weights[0]"); assert_eq!(lc[1].name, "weights[1]"); assert!(lc.iter().all(|p| p.kind == ScalarKind::F64)); // param-less nodes declare empty assert!(Sub::new().schema().params.is_empty()); assert!(Add::new().schema().params.is_empty()); assert!(SimBroker::new(0.0001).schema().params.is_empty()); let (tx, _rx) = std::sync::mpsc::channel(); assert!(Recorder::new(&[ScalarKind::F64], Firing::Any, tx).schema().params.is_empty()); } ``` - [ ] **Step 6: Build + test `aura-std` (partial build gate)** Run: `cargo test -p aura-std` Expected: PASS — `aura-std` compiles against the new `aura-core` and all tests incl. `nodes_declare_expected_params` pass. `aura-engine` still does not compile (Task 3). --- ## Task 3: `aura-engine` — repair `Composite::schema` + 10 test fixtures **Files:** - Modify: `crates/aura-engine/src/blueprint.rs:113` - Modify: `crates/aura-engine/src/blueprint.rs:{373,419,438,453}` - Modify: `crates/aura-engine/src/harness.rs:{358,384,406,436,474,498}` This task is pure compile-repair (mechanical) — every `NodeSchema` literal in `aura-engine` gains `params: vec![]` so the crate compiles again against the new field. No new behaviour, no new test. None of these are tunable-knob nodes. - [ ] **Step 1: `Composite::schema()` declares empty params** In `crates/aura-engine/src/blueprint.rs`, the `Composite::schema()` literal (line 112-113) becomes: ```rust let out_field = self.nodes[self.output.node].schema().output[self.output.field]; NodeSchema { inputs, output: vec![out_field], params: vec![] } ``` A composite is an authoring boundary, not a node; its interior params surface through `param_space()` (Task 4), not its derived schema. - [ ] **Step 2: Repair the 4 `blueprint.rs` test fixtures** In `crates/aura-engine/src/blueprint.rs` `mod tests`, append `params: vec![]` as the final field of the `NodeSchema { .. }` literal in each fixture: `Join2` (~line 373), `Pass1` (~419), `SinkF64` (~438), `SinkI64` (~453). - [ ] **Step 3: Repair the 6 `harness.rs` test fixtures** In `crates/aura-engine/src/harness.rs` `mod tests`, append `params: vec![]` as the final field of the `NodeSchema { .. }` literal in each fixture: `AsOfSum` (~line 358), `BarrierSum` (~384), `MixedSum` (~406), `Ohlcv` (~436), `TwoField` (~474), `TapForward` (~498). - [ ] **Step 4: Build `aura-engine` incl. tests (compile-repair gate)** Run: `cargo build -p aura-engine --all-targets` Expected: PASS — `aura-engine` lib + test targets compile (every literal repaired). If the build names any remaining `NodeSchema` literal missing `params`, add `params: vec![]` to it and re-run; the build error enumerates each one verbatim. - [ ] **Step 5: Existing `aura-engine` tests stay green** Run: `cargo test -p aura-engine` Expected: PASS — all pre-existing tests (incl. the bit-identical `composite_sma_cross_runs_bit_identical_to_hand_wired` and the golden render tests) stay green: the flat graph is unchanged, only schema literals gained an empty field. --- ## Task 4: `aura-engine` — `Blueprint::param_space()` aggregation + tests **Files:** - Modify: `crates/aura-engine/src/blueprint.rs:140-158` (Blueprint impl) + module scope (helper) - Modify: `crates/aura-engine/src/lib.rs:44` - Test: `crates/aura-engine/src/blueprint.rs` - [ ] **Step 1: Add the `param_space()` accessor** In `crates/aura-engine/src/blueprint.rs`, inside `impl Blueprint` (after `edges()`, which ends at line 158), add: ```rust /// The aggregated, flat, path-qualified param-space (C12): every node's declared /// params, concatenated in the deterministic depth-first item order `lower_items` /// uses, so a param's slot here matches the later flat-node order (#31 binds /// slot-by-slot). Read-only graph-as-data (C9); does not compile. Names are /// non-load-bearing: a composite's `name()` is prefixed at each level, but /// same-type siblings in one composite share a name — uniqueness is at the slot. pub fn param_space(&self) -> Vec { let mut out = Vec::new(); collect_params(&self.nodes, "", &mut out); out } ``` - [ ] **Step 2: Add the `collect_params` helper at module scope** In the same file, at module scope (next to `lower_items`, e.g. after the `Blueprint` impl block), add: ```rust /// Recursive read-only walk for `Blueprint::param_space`: a leaf contributes its /// declared params under the running path prefix; a composite pushes its `name()` /// onto the path and recurses. Order mirrors `lower_items` (items in declared order, /// composites depth-first) so a param's slot matches the later flat-node order. fn collect_params(items: &[BlueprintNode], prefix: &str, out: &mut Vec) { for item in items { match item { BlueprintNode::Leaf(node) => { for p in node.schema().params { let name = if prefix.is_empty() { p.name } else { format!("{prefix}.{}", p.name) }; out.push(ParamSpec { 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); } } } } ``` - [ ] **Step 3: Import `ParamSpec` into `blueprint.rs`** In `crates/aura-engine/src/blueprint.rs`, the `aura_core` import (line 14) gains `ParamSpec`: ```rust use aura_core::{Node, NodeSchema, ParamSpec, ScalarKind}; ``` - [ ] **Step 4: Re-export `ParamSpec` from `aura-engine`** In `crates/aura-engine/src/lib.rs:44`, add `ParamSpec` to the `aura_core` re-export (consumer of `param_space()` needs one import surface, per the #29 tidy precedent). The line is currently: ```rust pub use aura_core::{Firing, Scalar, ScalarKind, Timestamp}; ``` and becomes: ```rust pub use aura_core::{Firing, ParamSpec, Scalar, ScalarKind, Timestamp}; ``` - [ ] **Step 5: Add the headline nested-aggregation test** In `crates/aura-engine/src/blueprint.rs` `mod tests`, add (the test imports the sibling `aura_std` nodes, already a dev-dependency): ```rust #[test] fn param_space_is_flat_path_qualified_and_slot_disambiguated() { use aura_std::{LinComb, Sma, Sub}; // inner composite "fast_slow": two SMAs (same type → same param name) + a Sub let fast_slow = Composite::new( "fast_slow", vec![Sma::new(2).into(), Sma::new(4).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 }, ); // outer composite "strategy": the inner composite + a LinComb([1,-1]) let strategy = Composite::new( "strategy", vec![BlueprintNode::Composite(fast_slow), LinComb::new(vec![1.0, -1.0]).into()], vec![], vec![vec![Target { node: 0, slot: 0 }]], OutPort { node: 0, field: 0 }, ); let bp = Blueprint::new(vec![BlueprintNode::Composite(strategy)], vec![], vec![]); let space = bp.param_space(); let names: Vec<&str> = space.iter().map(|p| p.name.as_str()).collect(); assert_eq!( names, [ "strategy.fast_slow.length", // slot 0 — Sma(2) "strategy.fast_slow.length", // slot 1 — Sma(4): same name, distinct slot "strategy.weights[0]", // slot 2 — LinComb weight 0 "strategy.weights[1]", // slot 3 — LinComb weight 1 ] ); assert_eq!(space[0].kind, ScalarKind::I64); assert_eq!(space[2].kind, ScalarKind::F64); } ``` - [ ] **Step 6: Add top-level-unqualified, determinism, and empty tests** In the same `mod tests`, add: ```rust #[test] fn top_level_leaf_params_are_unqualified() { use aura_std::Sma; let bp = Blueprint::new(vec![Sma::new(3).into()], vec![], vec![]); let space = bp.param_space(); assert_eq!(space.len(), 1); assert_eq!(space[0].name, "length"); // no path prefix at the top level } #[test] fn param_space_is_deterministic() { use aura_std::{LinComb, Sma}; let bp = Blueprint::new( vec![Sma::new(2).into(), LinComb::new(vec![1.0, -1.0]).into()], vec![], vec![], ); assert_eq!(bp.param_space(), bp.param_space()); // pure structural function (C1) } #[test] fn param_space_empty_for_paramless_and_empty_blueprints() { use aura_std::{Add, Sub}; let only_paramless = Blueprint::new(vec![Sub::new().into(), Add::new().into()], vec![], vec![]); assert!(only_paramless.param_space().is_empty()); let empty = Blueprint::new(vec![], vec![], vec![]); assert!(empty.param_space().is_empty()); } ``` - [ ] **Step 7: Test `aura-engine` + full workspace build** Run: `cargo test -p aura-engine` Expected: PASS — the four new tests pass; all existing tests stay green. Run: `cargo build --workspace && cargo test --workspace` Expected: PASS — every crate compiles (aura-cli/aura-ingest unchanged, zero `NodeSchema` literals) and the whole suite is green. - [ ] **Step 8: Clippy gate** Run: `cargo clippy --workspace --all-targets -- -D warnings` Expected: PASS — no warnings (the `format!`/`collect` idioms in `collect_params` and `LinComb::schema` are clippy-clean). --- ## Notes for the implementer - **Do not touch** `compile`, `inline_composite`, `lower_items`, or any edge/wiring logic. `param_space()` is a *parallel* read-only projection that mirrors the inliner's traversal order; it must not share or alter it. The spec's correctness rests on the flat graph staying bit-identical (every existing golden / bit-identical test stays green by construction). - **fieldtests/ are out of scope** — they are excluded crates (own `Cargo.toml`), not in `--workspace`, and are frozen cycle-archive snapshots. They construct the old 2-field `NodeSchema` but never compile in this build, so they do not break the gate and are deliberately left unchanged. - Param identity is **positional** — name collisions (two same-type siblings sharing a path-qualified name) are the expected, correct case, never an error.