# Bound params in the graph model + viewer signature — Design Spec **Date:** 2026-06-13 **Status:** Draft — awaiting user spec review **Authors:** orchestrator + Claude ## Goal A node built with `.bind(slot, value)` fixes one declared param to a structural constant: the slot leaves the *tunable* surface (`params()` / the aggregated `param_space` / the sweep axes) — correct, and the point of `bind`. But it also vanishes from the *rendered node signature*, because the graph-model serializer (`prim_record`) emits only `schema.params`, which no longer holds the bound slot. The observable defect (cycle 0036 showcase): the `signals` composite's `blend` node is a `LinComb(3)` with three input ports (`term[0..2]`) whose third weight is `bind`-bound to `0.5`. The viewer renders ``` blend: LinComb[weights[0], weights[1]] ``` — a 2-arity signature over a box that shows 3 input ports, with the fixed `0.5` **invisible**. The signature misrepresents the node. This cycle separates the two concerns `bind` conflates: - **Tunable surface** (`param_space`, sweep axes, C12/C19): `bind` *removes* the slot. Unchanged — correct. - **Node signature** (the render): `bind` should *annotate*, not erase. Show all slots; mark the bound one with its fixed value. Target render (the settled notation — see *Settled design decisions*): ``` blend: LinComb[weights[0], weights[1], weights[2]=0.5] ``` all three slots, the bound `weights[2]=0.5` visually dimmed. This is consistent with the value-empty blueprint convention: a *free* param renders as a name (value deferred to sweep/bootstrap, e.g. `SMA[length]`); a *bound* param has its value fixed at blueprint time, so it renders `name=value`. Showing the bound value is showing a **structural fact**, not a tuning value. The change is structurally identical to cycle 0035 (commit `0ae8320`, the node instance-name surface): a conditional field threaded `engine → model → viewer` plus goldens and a headless render guard. Like the instance name, the bound annotation is a **render/model-only debug symbol**, dropped at lowering (C23), and the model stays deterministic (C14). ## Settled design decisions The issue (#63) flagged **one** open design decision — the render notation — "settle BEFORE implementing (with the user)". It was settled with the user in this `/boss` session (reconciliation comment posted on #63, 2026-06-13): - **Notation = Option A.** Keep the square-bracket `TYPE[...]` convention (as `SMA[length]`); render the bound slot as `name=value` (`weights[2]=0.5`), visually dimmed (reuse the 0035 `:` separator's muted grey `#9399b2`). Rejected alternatives: positional value-only (`...,0.5`, drops the slot name); parens (`LinComb(...)`, a global notation change beyond this issue's scope). Two further decisions are realizations of the settled notation, not open forks (they do not change the cycle's observable acceptance — the showcase bind is of the *trailing* slot, where every option renders identically): - **Slot-order faithfulness — record the original slot position.** The issue's stated goal is "merge the free params and the bound params back into **slot order**". For a *trailing* bind (the showcase) "append bound after free" and "true slot order" coincide; for a *non-trailing* bind they diverge. Honouring the issue's own "slot order" goal for **any** bind pattern requires the bound record to carry the slot's original position. This is the value-empty-blueprint convention applied faithfully (a slot's *position* is a structural fact, like its name). The issue's illustrative triple `["weights[2]","f64","0.5"]` (an `e.g.`) therefore gains a leading position: `[2,"weights[2]","f64","0.5"]`. Chosen on substance (what the design permits — correct rendering of mid-slot binds — and compositional clarity), not effort. - **Deterministic value rendering (C14).** The bound `Scalar` value formats to a canonical string via a new `scalar_str` helper, mirroring the existing `kind_str`: `i64`/`bool`/`timestamp` by their integer/`true`/`false`/epoch-ns form, `f64` by Rust's shortest round-trippable debug form (`{:?}`), which keeps a decimal point for whole values (`1.0`, not `1`) so a bound `f64` never reads as an `i64` in the head. `0.5` renders `0.5` under either Display or Debug; the Debug choice only disambiguates whole-number floats. ## Architecture Three layers, mirroring the 0035 thread, plus goldens and a guard: 1. **aura-core** (`node.rs`, `PrimitiveBuilder`): `bind` additionally records a `bound: Vec` entry — the bound slot's original position, name, kind, and value — alongside the existing closure capture (which is unchanged). A `bound_params()` accessor exposes it, the twin of `instance_name()`. 2. **aura-engine** (`graph_model.rs`, `prim_record`): emit a conditional `"bound"` field — present only when non-empty (mirrors the conditional `"name"` field) — each entry serialized `[pos,"name","kind","value"]` via a new `scalar_str` value helper. Deterministic (C14). 3. **graph-viewer.js** (`adaptNodes`, `genDot` leaf-emit, `cellLabel`): carry `bound`; `cellLabel` merges the free params and the bound params back into slot order by position and renders a bound slot as `weights[2]=0.5`, dimmed. 4. **Goldens + tests**: re-capture the `sample-model.json` fixture (the `blend` node gains a `"bound"` field); the engine's own inline `model_golden` (`sample_root`, which uses no `bind`) stays byte-unchanged. Add a `prim_record` unit test (bound field present only when bound) and a headless viewer render guard (bound slot renders `name=value`, dimmed; free slots unchanged; slot order correct for a non-trailing bind). ## Concrete code shapes ### User-facing program (the acceptance evidence) The authoring is **already shipped** (cycle 0036, `aura-cli/src/main.rs` `signals()`); this cycle fixes only what it *renders*: ```rust // crates/aura-cli/src/main.rs — signals(), UNCHANGED authoring LinComb::builder(3) .named("blend") .bind("weights[2]", Scalar::F64(0.5)) // a fixed signal-line weight .into() ``` `aura graph` viewer box head, **before** this cycle (the defect): ``` blend: LinComb[weights[0], weights[1]] # 2 slots, but the box shows 3 ports ``` **after** this cycle (the fix — `weights[2]=0.5` dimmed): ``` blend: LinComb[weights[0], weights[1], weights[2]=0.5] ``` A trader/researcher who fixes a weight with `.bind()` and opens the graph now reads the true signature: all three slots, the constant `0.5` shown as a fixed value rather than silently dropped. This is the criterion's evidence — the feature measurably removes a misrepresentation (signature arity now matches the port count) and reintroduces no failure class (render-only; C23/C14 intact). ### aura-core — `node.rs` (`PrimitiveBuilder`) A small record type and a field on the builder: ```rust /// One param bound to a structural constant by `bind` (render/debug only, C23). /// `pos` is the slot's position in the node's ORIGINAL (pre-bind) param list, so /// the renderer can place it back into slot order regardless of bind sequence. #[derive(Clone, Debug, PartialEq)] pub struct BoundParam { pub pos: usize, pub name: String, pub kind: ScalarKind, pub value: Scalar, } ``` before — the builder fields: ```rust pub struct PrimitiveBuilder { name: &'static str, instance_name: Option, schema: NodeSchema, #[allow(clippy::type_complexity)] build: Box Box>, } ``` after — add `bound` (and initialize it `Vec::new()` in `new`): ```rust pub struct PrimitiveBuilder { name: &'static str, instance_name: Option, schema: NodeSchema, bound: Vec, #[allow(clippy::type_complexity)] build: Box Box>, } ``` before — `bind` (the closure mechanics, unchanged) records nothing visible: ```rust pub fn bind(mut self, slot: &str, value: Scalar) -> Self { // ... matches/pos resolution + kind assert (unchanged) ... self.schema.params.remove(pos); // [param_space side] let inner = self.build; // [value side] self.build = Box::new(move |open: &[Scalar]| { let mut full = open.to_vec(); full.insert(pos, value); inner(&full) }); self } ``` after — record a `BoundParam` with the slot's ORIGINAL position before removal. `pos` is the index in the already-shrunk array; map it to the original index by adding back every earlier-bound slot at an original position `<= ` it: ```rust pub fn bind(mut self, slot: &str, value: Scalar) -> Self { // ... matches/pos resolution + kind assert (unchanged) ... let removed = &self.schema.params[pos]; // capture name+kind before removal // map the compressed index `pos` to the original full-arity position: let mut orig = pos; let mut prior: Vec = self.bound.iter().map(|b| b.pos).collect(); prior.sort_unstable(); for p in prior { if p <= orig { orig += 1; } } self.bound.push(BoundParam { pos: orig, name: removed.name.clone(), kind: removed.kind, value, }); self.schema.params.remove(pos); // [param_space side] — unchanged let inner = self.build; // [value side] — unchanged self.build = Box::new(move |open: &[Scalar]| { let mut full = open.to_vec(); full.insert(pos, value); inner(&full) }); self } ``` new accessor — the twin of `instance_name()`: ```rust /// The params bound to structural constants by `bind`, in bind-call order, each /// carrying its ORIGINAL slot position. The render-surface twin of the value /// captured in the build closure (unreachable to the model serializer, which /// never builds). Empty for a node with no binds. pub fn bound_params(&self) -> &[BoundParam] { &self.bound } ``` ### aura-engine — `graph_model.rs` (`prim_record` + a value helper) new value helper, mirroring `kind_str`: ```rust /// A scalar VALUE as a canonical, deterministic string for the model (C14). /// `f64` uses the shortest round-trippable debug form (keeps a decimal point on /// whole values, so a bound f64 is not mistaken for an i64 in the render). fn scalar_str(s: aura_core::Scalar) -> String { use aura_core::Scalar; match s { Scalar::I64(n) => n.to_string(), Scalar::F64(f) => format!("{f:?}"), Scalar::Bool(b) => b.to_string(), Scalar::Ts(t) => t.0.to_string(), } } ``` before — `prim_record` emits `{name?}type/role/params/ins/outs`: ```rust fn prim_record(b: &aura_core::PrimitiveBuilder) -> String { let s = b.schema(); let role = if s.output.is_empty() { "sink" } else { "node" }; let params = join(s.params.iter().map(|p| named_kind(&p.name, p.kind))); let ins = join(s.inputs.iter().map(port_json)); let outs = join(s.output.iter().map(|f| named_kind(f.name, f.kind))); let name = match b.instance_name() { Some(n) => format!(r#""name":{},"#, json_str(n)), None => String::new(), }; format!( r#"{{"prim":{{{name}"type":{},"role":{},"params":[{params}],"ins":[{ins}],"outs":[{outs}]}}}}"#, json_str(&b.label()), json_str(role), ) } ``` after — a conditional `"bound"` field, placed right after `"params"` (the tunable surface and its bound annotation grouped). Present only when non-empty, exactly like `"name"`, so an unbound node's bytes are unchanged: ```rust fn prim_record(b: &aura_core::PrimitiveBuilder) -> String { let s = b.schema(); let role = if s.output.is_empty() { "sink" } else { "node" }; let params = join(s.params.iter().map(|p| named_kind(&p.name, p.kind))); let ins = join(s.inputs.iter().map(port_json)); let outs = join(s.output.iter().map(|f| named_kind(f.name, f.kind))); let name = match b.instance_name() { Some(n) => format!(r#""name":{},"#, json_str(n)), None => String::new(), }; // bound params: present only when the node has binds (mirrors "name"). // each entry: [pos,"name","kind","value"]. let bound = if b.bound_params().is_empty() { String::new() } else { let items = join(b.bound_params().iter().map(|bp| { format!( "[{},{},{},{}]", bp.pos, json_str(&bp.name), json_str(kind_str(bp.kind)), json_str(&scalar_str(bp.value)), ) })); format!(r#","bound":[{items}]"#) }; format!( r#"{{"prim":{{{name}"type":{},"role":{},"params":[{params}]{bound},"ins":[{ins}],"outs":[{outs}]}}}}"#, json_str(&b.label()), json_str(role), ) } ``` The `blend` node in the re-captured `sample-model.json` then reads (abridged): ```json {"prim":{"name":"blend","type":"LinComb","role":"node", "params":[["weights[0]","f64"],["weights[1]","f64"]], "bound":[[2,"weights[2]","f64","0.5"]], "ins":[["f64","any","term[0]"],["f64","any","term[1]"],["f64","any","term[2]"]], "outs":[["value","f64"]]}} ``` ### graph-viewer.js (`adaptNodes`, `genDot` leaf-emit, `cellLabel`) before — `adaptNodes` carries `name` but not `bound`: ```js out[key] = { prim: { name: p.name, type: p.type, role: p.role, params: p.params, ins: adaptIns(p.ins), outs: p.outs } }; ``` after — carry `bound` (default `[]` when absent): ```js out[key] = { prim: { name: p.name, type: p.type, role: p.role, params: p.params, bound: p.bound || [], ins: adaptIns(p.ins), outs: p.outs } }; ``` before — `genDot` leaf-emit forwards the prim fields to `cellLabel`: ```js block += `${cid} [label=${cellLabel(cid, { name: s.name, type: s.type, params: s.params, ins: s.ins, outs: s.outs, bodyBg: bodyBgFor(s.role), composite: false }, showTypes)}];\n`; ``` after — forward `bound`: ```js block += `${cid} [label=${cellLabel(cid, { name: s.name, type: s.type, params: s.params, bound: s.bound, ins: s.ins, outs: s.outs, bodyBg: bodyBgFor(s.role), composite: false }, showTypes)}];\n`; ``` before — `cellLabel` builds the signature from free params only: ```js const sp = o.params.map(([n, k]) => `${showTypes && k ? `${n}:${k}` : n}`); const sig = o.params.length ? `[${sp.join(', ')}]` : ""; ``` after — merge free params and bound params into slot order by position; render a bound slot as `name=value` in the dimmed separator grey (`#9399b2`); the bracket test keys on the *total* slot count so an all-bound node still shows `[...]`: ```js const bound = o.bound || []; const total = o.params.length + bound.length; const byPos = new Map(bound.map(([pos, n, k, v]) => [pos, [n, k, v]])); const slots = []; let fi = 0; for (let pos = 0; pos < total; pos++) { if (byPos.has(pos)) { const [n, , v] = byPos.get(pos); // bound: dimmed name=value slots.push(`${n}=${v}`); } else { const [n, k] = o.params[fi++]; // free: type-coloured name slots.push(`${showTypes && k ? `${n}:${k}` : n}`); } } const sig = total ? `[${slots.join(', ')}]` : ""; ``` `addInfo` (the tooltip) is left unchanged: it shows the *tunable* params (the knob view); the bound constant is a signature fact shown in the head, not a knob. ## Components | Component | File | Change | |-----------|------|--------| | `BoundParam` + `PrimitiveBuilder.bound` + `bind` record + `bound_params()` | `crates/aura-core/src/node.rs` | new struct, field, ~6 lines in `bind`, accessor | | `scalar_str` + conditional `"bound"` in `prim_record` | `crates/aura-engine/src/graph_model.rs` | new helper, ~8 lines in `prim_record` | | `bound` carried + merged-slot render | `crates/aura-cli/assets/graph-viewer.js` | `adaptNodes`, `genDot`, `cellLabel` | | sample fixture re-capture | `crates/aura-cli/tests/fixtures/sample-model.json` | `blend` gains `"bound"` | | `prim_record` bound unit test | `crates/aura-engine/src/graph_model.rs` (tests) | new test | | `bind` records position unit test | `crates/aura-core/src/node.rs` (tests) | new test | | headless render guard (`.mjs` + `.rs`) | `crates/aura-cli/tests/viewer_bound_param.{mjs,rs}` | new guard pair | ## Data flow ``` author: LinComb::builder(3).bind("weights[2]", F64(0.5)) → PrimitiveBuilder { schema.params: [w0,w1], bound: [{pos:2,"weights[2]",F64,0.5}] } → prim_record: "params":[[w0],[w1]], "bound":[[2,"weights[2]","f64","0.5"]] → render_html: window.AURA_MODEL = { ... blend ... } → adaptNodes: { ..., bound: [[2,"weights[2]","f64","0.5"]] } → cellLabel merge by pos: [ w0(free), w1(free), weights[2]=0.5(bound, dimmed) ] → "blend: LinComb[weights[0], weights[1], weights[2]=0.5]" ``` At lowering (bootstrap/compile) nothing changes: `bind` still resolves the name to a fixed position and re-splices the value in the build closure; `bound` is a render/debug surface only, never read by bootstrap or the run loop (C23). ## Error handling - `bind`'s existing preconditions are unchanged: panic on zero / ambiguous slot matches and on a value-kind mismatch (its should-panic tests stay green). - The original-position computation is total and panic-free (a sort + a counted increment over already-recorded positions); no new failure mode. - `scalar_str` is total over all four `Scalar` variants — no `unreachable!`. - The model JSON stays well-formed for any bind count (zero → no `"bound"` key; N → an N-element array). `json_str` escaping is reused for name/kind/value. ## Testing strategy - **`bind` records the original position (aura-core unit).** Bind a non-trailing slot and a chained reverse-order pair (mirroring `chained_bind_…`); assert `bound_params()` carries the correct ORIGINAL positions (e.g. binding the middle of three → `pos == 1`; reverse-binding `weights[1]` then `weights[0]` on `LinComb(2)` → positions `{0,1}`). This is the test that justifies carrying the position rather than appending. - **`prim_record` emits `"bound"` only when bound (aura-engine unit).** A bound builder's record contains `"bound":[[…]]` with the canonical value string; an unbound builder's record contains no `"bound"` substring (twin of `prim_record_emits_name_for_explicit_only`). - **Model determinism + goldens.** `model_is_deterministic` and the inline `model_golden` (`sample_root`, no binds) stay byte-unchanged — proves the conditional field does not perturb unbound nodes. The `sample-model.json` fixture is re-captured; the two fixture consumers (`viewer_dot_ids.mjs`, `viewer_nested_depth.mjs`) keep passing (they assert DOT-id grammar / nesting depth, not params), confirming the new field flows through `adaptNodes`/`genDot` without breaking id generation. - **Headless render guard (`viewer_bound_param.mjs` + `.rs`).** Mirror `viewer_name_prefix`. Drive the real `genDot` over two minimal models: (a) a LinComb-like leaf with free `weights[0]`/`weights[1]` and `bound:[[2,"weights[2]","f64","0.5"]]` → assert the head contains the dimmed `weights[2]=0.5` and the two free slots in their type colour, in order `weights[0], weights[1], weights[2]=0.5`; (b) a 3-param leaf binding the MIDDLE slot (`pos 1`) → assert the rendered order is `a, b=, c` (the bound slot between the free ones), which fails under an append-only design and so pins slot-order faithfulness. `node` is REQUIRED (a skipped guard is not a guard). - **Sweep / `param_space` unaffected.** The `cli_run` E2E params pin (eight free params, `weights[2]` correctly absent) and the in-crate sweep pins stay green — `bind` still removes the slot from the tunable surface. ## Acceptance criteria 1. A node built with `.bind(slot, value)` renders all its declared slots in the `aura graph` viewer; the bound slot shows `name=value`, visually dimmed, in true slot order. The cycle-0036 `blend` renders `blend: LinComb[weights[0], weights[1], weights[2]=0.5]`. 2. The graph model carries a conditional `"bound"` field (`[pos,"name","kind","value"]`), present only for nodes with binds; deterministic (C14). Unbound nodes' model bytes are unchanged. 3. The bound slot remains absent from the tunable surface (`params()` / `param_space` / sweep axes) — `bind`'s tuning-side behaviour is unchanged (C12/C19), and the compilat is unchanged (C23: render/debug symbol only). 4. New unit tests pin the recorded original position and the conditional model field; a headless guard pins the dimmed `name=value` render and slot-order faithfulness (including a non-trailing bind). All existing goldens, viewer guards, and sweep pins stay green; `cargo build`/`test`/`clippy` clean.