Aura/docs/specs/0030-named-param-binding.md

# Named param binding — fluent `.with()` / `.axis()` over `param_space()` — Design Spec

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

## Goal

Let an author bind a blueprint's open knobs **by name** instead of by a
positional `Vec<Scalar>` in `param_space()` order. Today a single run and a
sweep both supply their point positionally with each value `Scalar`-wrapped —
which is **order-fragile** (two swapped same-kind values still compile, a silent
correctness hazard) and **noisy** (`Scalar::I64(2)`, `Scalar::F64(0.5)`). A
fluent builder addresses both: `bp.with("sma_cross.fast", 2).with("sma_cross.slow",
4).with("scale", 0.5).bootstrap()` for a single run, `bp.axis("sma_cross.fast", [2,
3]).axis("sma_cross.slow", [4, 5]).axis("scale", [0.5]).sweep(run)` for a grid.
The bound name is the **exact** string `param_space()` emits (see §Architecture) —
path-qualified for a knob inside a composite (`sma_cross.fast`), bare for a
root-level knob (`scale`).

This is a pure **authoring layer** over the existing `bootstrap_with_params` /
`GridSpace` / `sweep` primitives. The engine core is untouched: no change to
determinism (C1), the param-space ground truth (C12/C19), the alias overlay
(C23), or the edge-time kind check (C7). Out of scope: structural blueprint
constants (a value removed from `param_space` entirely) — that is the opposite
operation and lives in #55.

## Architecture

Three layers, top to bottom:

1. **Fluent builders** (`Composite::with` / `Composite::axis`) accumulate named
   bindings as plain data, then resolve at the terminal call.
2. **A shared name-resolution core** maps each declared `param_space()` slot to
   its binding by name, in slot order, producing the positional structure the
   engine wants — and the name-level errors (`UnknownKnob`, `DuplicateBinding`,
   `AmbiguousKnob`).
3. **The existing engine primitives** (`bootstrap_with_params`,
   `GridSpace::new` + `sweep`) consume the resolved positional structure
   unchanged.

`param_space()` is the single ground truth: it carries each slot's **name**
(alias-aware, C23) and its **`ScalarKind`**. That is enough to map a name to a
position *and* to kind-check the bound value — so the named layer needs no new
metadata on the engine side.

**The match key is the exact `param_space()` name.** A bound name matches a slot
iff it equals the string `param_space()` emits for that slot — no unqualification,
no last-segment matching, no fuzzy resolution. Those strings are
**path-qualified**: a knob inside a composite surfaces as `<composite>.<name>`
(e.g. `sma_cross.fast`, via `collect_params` prefixing the composite name onto the
C23 alias), while a knob on a root-level leaf surfaces bare (e.g. `scale`, the
root `Exposure`'s param). This makes the match key both **grounded** (it is
literally what `param_space()` returns, pinned by
`param_space_is_flat_path_qualified_and_slot_disambiguated`) and **structurally
unambiguous**: two distinct knobs that would otherwise collide on a short name are
already disambiguated by their composite path. An author who wants to bind a knob
by a short bare name promotes it to a root-level leaf (as `scale` already is) — a
blueprint-authoring choice, not a job of this layer. `AmbiguousKnob` therefore
fires only when two slots emit the **identical** exact name (e.g. two unaliased
leaves whose factory param names collide, or two duplicate C23 aliases); the
author resolves it with a distinguishing `ParamAlias` (C23).

**Type lowering.** A bound value is `impl Into<Scalar>`; the Rust literal fixes
the variant. Because `From<i64>`/`From<f64>`/`From<bool>` exist for `Scalar` but
**no `From<i32>`**, a bare integer literal `2` infers as `i64` (the only integer
type satisfying the bound), and `0.5` as `f64`. So `.with("sma_cross.fast", 2)`
and `.with("scale", 0.5)` compile with raw literals, no suffix. The kind-check
against the slot's `ScalarKind` is then **pure equality** (C7-consistent): there
is **no coercion** — a `2` (lowered to `I64`) bound to an `F64` slot is a
`KindMismatch`, and the author writes `2.0`.

**Naming.** The value-supplying method is `.with()`, deliberately **not**
`.bind()` — `bind` is reserved for #55's structural-constant overlay (which
*removes* a knob from `param_space`). `.with()` is the opposite: it supplies a
value for an **open** knob that stays in `param_space`.

## Concrete code shapes

### User-facing — the worked author examples (the acceptance evidence)

Single run, before → after (the existing CLI sample at
`crates/aura-cli/src/main.rs:520`):

```rust
// before — positional, order-fragile, Scalar-wrapped:
let mut h = bp
    .bootstrap_with_params(vec![Scalar::I64(2), Scalar::I64(4), Scalar::F64(0.5)])
    .expect("sample blueprint compiles under a valid point");

// after — named (exact param_space() names), order-free, raw literals:
let mut h = bp
    .with("sma_cross.fast", 2)   // knob inside the `sma_cross` composite → path-qualified
    .with("sma_cross.slow", 4)
    .with("scale", 0.5)          // root-level Exposure knob → bare
    .bootstrap()
    .expect("sample blueprint compiles under a valid point");
```

The mixed forms are deliberate and honest: the sample's two SMA lengths live
inside the `sma_cross` composite (so `param_space()` emits `sma_cross.fast` /
`sma_cross.slow`), while `scale` is a root-level knob (bare). The example shows
exactly how each is addressed under the exact-name match key — no fixture change.

Sweep, before → after (the existing CLI grid at
`crates/aura-cli/src/main.rs:228-238`):

```rust
// before — positional axes in param_space() order:
let space = sample_blueprint_with_sinks().0.param_space();
let grid = GridSpace::new(
    &space,
    vec![
        vec![Scalar::I64(2), Scalar::I64(3)],
        vec![Scalar::I64(4), Scalar::I64(5)],
        vec![Scalar::F64(0.5)],
    ],
)
.expect("the built-in grid matches the sample param-space");
let family = sweep(&grid, |point| { /* run one */ });

// after — named axes (exact param_space() names), same vocabulary as the single run:
let family = sample_blueprint_with_sinks().0
    .axis("sma_cross.fast", [2, 3])
    .axis("sma_cross.slow", [4, 5])
    .axis("scale", [0.5])
    .sweep(|point| { /* run one */ });
```

### Implementation shapes — secondary

```rust
// the value-binding builder (single run)
impl Composite {
    pub fn with(self, name: &str, v: impl Into<Scalar>) -> Binder {
        Binder { bp: self, bound: vec![(name.to_string(), v.into())] }
    }
}
pub struct Binder { bp: Composite, bound: Vec<(String, Scalar)> }
impl Binder {
    pub fn with(mut self, name: &str, v: impl Into<Scalar>) -> Binder {
        self.bound.push((name.to_string(), v.into()));
        self
    }
    pub fn bootstrap(self) -> Result<Harness, BindError> {
        let space = self.bp.param_space();
        let point = resolve(&space, &self.bound)?;        // shared core
        self.bp.bootstrap_with_params(point).map_err(BindError::Compile)
    }
}

// the axis builder (sweep) — same shape, a Vec<Scalar> per knob
impl Composite {
    pub fn axis(self, name: &str, vals: impl IntoIterator<Item = impl Into<Scalar>>) -> SweepBinder {
        let axis = vals.into_iter().map(Into::into).collect();
        SweepBinder { bp: self, axes: vec![(name.to_string(), axis)] }
    }
}
pub struct SweepBinder { bp: Composite, axes: Vec<(String, Vec<Scalar>)> }
impl SweepBinder {
    pub fn axis(mut self, name: &str, vals: impl IntoIterator<Item = impl Into<Scalar>>) -> SweepBinder {
        self.axes.push((name.to_string(), vals.into_iter().map(Into::into).collect()));
        self
    }
    pub fn sweep<F>(self, run_one: F) -> Result<SweepFamily, BindError>
    where F: Fn(&[Scalar]) -> RunReport + Sync {
        let space = self.bp.param_space();
        let ordered = resolve_axes(&space, &self.axes)?;  // Vec<Vec<Scalar>> in slot order
        let grid = GridSpace::new(&space, ordered)         // pre-validated, cannot fail
            .expect("named layer pre-validates arity/kind/non-empty");
        Ok(sweep(&grid, run_one))
    }
}

// the authoring-layer error vocabulary (name-qualified)
#[derive(Debug, PartialEq)]
pub enum BindError {
    UnknownKnob(String),                                   // name matches no slot
    MissingKnob(String),                                   // a slot left unbound
    KindMismatch { knob: String, expected: ScalarKind, got: ScalarKind },
    DuplicateBinding(String),                              // same name twice
    AmbiguousKnob(String),                                 // name matches >1 slot
    EmptyAxis(String),                                     // sweep only: axis with no values
    Compile(CompileError),                                 // single run: downstream bootstrap fault
}

// the shared single-run core
fn resolve(space: &[ParamSpec], bound: &[(String, Scalar)]) -> Result<Vec<Scalar>, BindError>;
fn resolve_axes(space: &[ParamSpec], axes: &[(String, Vec<Scalar>)]) -> Result<Vec<Vec<Scalar>>, BindError>;
```

## Components

- `Composite::with` / `Binder` (new, `aura-engine`): single-run value binding.
- `Composite::axis` / `SweepBinder` (new, `aura-engine`): sweep-axis binding.
- `resolve` / `resolve_axes` (new, `aura-engine`): the name-resolution core,
  the load-bearing shared logic both scopes call. `resolve_axes` reuses the
  same name→slot mapping as `resolve`, differing only in per-slot fill (one
  `Scalar` vs a `Vec<Scalar>` axis), the `EmptyAxis` check, and a **per-element**
  kind check over each axis. Its validation is a **superset** of what
  `GridSpace::new` checks (arity, non-empty, per-element kind), so the
  `GridSpace::new` call it feeds is infallible by construction.
- `BindError` (new, `aura-engine`): the authoring-layer error vocabulary.
- The CLI sample single-run and sweep (`aura-cli`): converted to the new form
  as living acceptance evidence.

Engine primitives consumed unchanged: `param_space()`, `bootstrap_with_params`,
`GridSpace::new`, `sweep`, `CompileError`, `SweepError`.

## Data flow

Single run: `.with(name, v)*` accumulate `(String, Scalar)` → terminal
`.bootstrap()` calls `param_space()` → `resolve` runs the two phases (validate
bindings against the slot names, then walk slots in order kind-checking), emits
`Vec<Scalar>` → existing `bootstrap_with_params` → `Harness`.

Sweep: `.axis(name, vals)*` accumulate `(String, Vec<Scalar>)` → terminal
`.sweep(run)` calls `param_space()` → `resolve_axes` produces `Vec<Vec<Scalar>>`
in slot order → existing `GridSpace::new` (pre-validated) → existing `sweep` →
`SweepFamily`.

## Error handling

`BindError` is the **single authoring-layer error type** for both scopes,
name-qualified so a message names the offending knob rather than a slot index.
The named layer validates fully *before* handing off, so the downstream
`GridSpace::new` is given an already-valid grid (its positional `SweepError`
stays the engine-level error for direct `GridSpace::new` callers and is not
re-exposed through the named surface).

| Variant | Trigger | Scope | Decision |
|---|---|---|---|
| `UnknownKnob(name)` | a bound name equals no slot's exact `param_space()` name | both | error — almost certainly a typo or a missing composite prefix |
| `MissingKnob(name)` | a slot is left unbound | both | error — **completeness enforced**; a single run needs a full vector, and every sweep knob needs an axis |
| `KindMismatch{knob,expected,got}` | value kind ≠ slot kind | both | error — **no coercion**; `2` for an `F64` slot fails, author writes `2.0` |
| `DuplicateBinding(name)` | the same name bound twice | both | error — **not last-wins**; a second `.with("fast", …)` is almost certainly accidental |
| `AmbiguousKnob(name)` | a name equals the exact `param_space()` name of >1 slot (colliding unaliased factory names, or duplicate C23 aliases) | both | error — author disambiguates via `ParamAlias` (C23) |
| `EmptyAxis(name)` | a sweep axis has zero values | sweep | error — nothing to sweep on that knob; the name-qualified counterpart of the engine's `SweepError::EmptyAxis` |
| `Compile(CompileError)` | downstream bootstrap fault on the single-run path | single run | forwarded — the named layer pre-validates the point, but `bootstrap_with_params` may still surface an unrelated construction fault |

**Precisification flagged for review:** the ratified narrative listed five
name-level variants; this spec adds `EmptyAxis` (a necessary completeness check
for the ratified sweep scope — an axis with no values has nothing to enumerate)
and `Compile` (forwarding the existing downstream `CompileError` on the
single-run terminal, since `.bootstrap()` ultimately calls
`bootstrap_with_params`). Neither is a new design decision; both are
consequences of wrapping the existing primitives. Surfaced here, not buried.

**Resolution timing and error precedence.** Lazy — at the terminal
(`.bootstrap()` / `.sweep()`), never per `.with()`/`.axis()`. The builder
accumulates plain data; resolution against `param_space()` happens once. The
**first** failing check in the **total order** below wins (error-collection is a
later additive concern). The order is total — every co-occurrence of errors has a
single defined winner — so the surfaced `BindError` is a pure function of the
inputs:

**Phase 1 — per binding, in `.with()`/`.axis()` chain order (left to right);
for each binding apply checks a–d in this fixed sub-order before moving to the
next binding:**

- **a.** the name resolves to **zero** `param_space()` slots → `UnknownKnob(name)`.
- **b.** the name resolves to **more than one** slot (identical exact names) →
  `AmbiguousKnob(name)`.
- **c.** *(sweep path only)* the axis has **zero** values → `EmptyAxis(name)`.
- **d.** the (now unique) resolved slot was **already claimed** by an earlier
  binding → `DuplicateBinding(name)`; otherwise the binding claims its slot.

**Phase 2 — only if Phase 1 fully succeeds, walk `param_space()` slots in slot
order; for each slot apply e–f:**

- **e.** the slot is **unclaimed** by any binding → `MissingKnob(slot_name)`.
- **f.** a claimed value's kind **≠** the slot kind → `KindMismatch{knob, expected,
  got}`. **Single-run:** the one bound value. **Sweep:** **every** element of the
  bound axis is kind-checked, in axis order; `got` is the kind of the **first**
  offending element, so the surfaced error is deterministic. This per-element
  check is **total** — it is exactly the check `GridSpace::new` repeats — so once
  `resolve_axes` returns Ok, the grid it produces is fully arity-, non-empty-, and
  per-element-kind-valid, making the downstream `GridSpace::new(&space,
  ordered).expect(…)` in `SweepBinder::sweep` genuinely infallible: it can never
  panic on author input, because every `SweepError` `GridSpace::new` can raise has
  already been raised as the corresponding `BindError` in Phase 1/2.

`Compile(CompileError)` is downstream of a fully-successful resolve (the
single-run terminal forwarding a `bootstrap_with_params` fault). Because name
resolution (a/b) precedes the duplicate check (d) *within* a binding, a name that
is both unknown and repeated — `.with("typo", 1).with("typo", 2)` — surfaces
`UnknownKnob("typo")` at its first occurrence, never reaching the duplicate
check. The chain order, the a–f sub-order, and the slot order are all fixed, so
no two inputs share an undefined winner.

## Testing strategy

- **`resolve` round-trip:** a named binding resolves to a `Vec<Scalar>`
  bit-identical to the hand-written positional vector.
- **One RED assertion per `BindError` variant:** `UnknownKnob`, `MissingKnob`,
  `KindMismatch`, `DuplicateBinding`, `AmbiguousKnob` (single run);
  `EmptyAxis`, `MissingKnob` (sweep).
- **Match-key grounding:** binding the sample by its exact `param_space()` names
  (`sma_cross.fast`, `sma_cross.slow`, `scale`) resolves; binding the unqualified
  `fast` raises `UnknownKnob("fast")` — pinning that the match key is the exact
  emitted name, path-qualification included, not a short form.
- **Error precedence (cross-phase):** a call with both a Phase-1 and a Phase-2
  error (a typo'd name `.with("typo", 1)` alongside a kind-mismatched valid name)
  surfaces the Phase-1 error (`UnknownKnob("typo")`) — binding validation precedes
  the slot walk.
- **Error precedence (intra-binding):** `.with("typo", 1).with("typo", 2)` (a
  name that is both unknown and duplicated) surfaces `UnknownKnob("typo")` — the
  a–d sub-order resolves the name (check a) before the duplicate check (d), so the
  total order has a single defined winner.
- **Sweep mixed-kind axis (no panic):** `.axis("scale", [0.5, 1])` against the
  `F64` slot raises `KindMismatch` (the second element is `I64`) as a clean
  `BindError` — never reaching `GridSpace::new`, pinning that `resolve_axes`
  per-element kind-check is total and the downstream `.expect()` cannot panic.
- **Equivalence (C1):** the same point expressed named vs positional bootstraps
  to an instance that runs to a **bit-identical** result — the convenience
  changes nothing about the outcome.
- **Sweep parity:** named axes resolve to the **same `GridSpace`** (same
  enumerated points, same order) as the positional axes.
- **Living acceptance evidence:** the CLI sample single-run and sweep are
  converted to the `.with()` / `.axis()` form; their existing golden/behaviour
  tests stay green, proving the conversion is behaviour-preserving.

## Acceptance criteria

1. `bp.with("sma_cross.fast", 2).with("sma_cross.slow", 4).with("scale", 0.5).bootstrap()`
   compiles with raw literals and bootstraps the same instance as the positional
   vector — binding by each slot's exact `param_space()` name.
2. `bp.axis("sma_cross.fast", [2, 3]).axis("sma_cross.slow", [4, 5]).axis("scale", [0.5]).sweep(run)`
   enumerates the same family as the positional `GridSpace`.
3. Every `BindError` variant is reachable and has a covering RED test.
4. The C1 equivalence test passes (named ≡ positional, bit-identical run).
5. The CLI sample single-run and sweep use the new form; all existing tests
   stay green.
6. `cargo build/test --workspace` green, `cargo clippy --workspace --all-targets
   -- -D warnings` clean.

### Iteration cut

- **Iteration 1 — single run:** `resolve`, `Composite::with`/`Binder`,
  `BindError` (the single-run variants + `Compile`), the C1 equivalence test,
  and the CLI sample single-run conversion.
- **Iteration 2 — sweep axes:** `resolve_axes`, `Composite::axis`/`SweepBinder`,
  `EmptyAxis`, the sweep-parity test, and the CLI sweep conversion.