Aura/docs/specs/fieldtest-0031-node-naming.md

# Fieldtest — cycle-0031 — 2026-06-11

**Status:** Draft — awaiting orchestrator triage
**Author:** fieldtester (dispatched by fieldtest skill)

## Scope

Cycle 0031 (node-instance naming, #56) gives every blueprint node a name. A
primitive builder gains an optional instance name (`Sma::builder().named("fast")`);
omitted, it defaults to the node's type label ASCII-lowercased verbatim
(`"SMA"`→`"sma"`, no snake_case). `param_space()` is now uniformly
`<node>.<param>` at every level including the root (`sma_cross.fast.length`,
`exposure.scale`). Fan-in distinguishability (C9) and `signature_of` re-key onto
the node name: two same-type siblings both defaulting to `"sma"` collide and
`IndistinguishableFanIn` fires; naming them `"fast"`/`"slow"` fixes both the
naming collision and the fan-in check in one act. The index-addressed
`ParamAlias` overlay (and `Composite::new`'s 5th argument) was retired.

Tested from the public interface only: the design ledger (C9/C23 amendments),
spec 0031, and `cargo doc --workspace` rustdoc; never `crates/*/src`. Build
exercised: `cargo build --workspace` (green from HEAD `0e411f1`), then each
fixture via `cargo run --manifest-path
fieldtests/cycle-0031-node-naming/Cargo.toml --bin <name>` so HEAD source is
always what runs. The fixture crate is a standalone non-member crate
path-depending on `aura-core/-engine/-std`, as a C16 research project would.

## Per-task roll-up

| Task | Axis | Built? | Ran? | Matched expected? |
|---|---|---|---|---|
| 1 named single-run | a | yes | yes | yes — `sma_cross.fast.length` etc., bound & ran, deterministic |
| 2 forcing function | b | yes | yes | partially — fan-in is rejected, but **not via the diagnostic the spec headlines** (see F4) |
| 3 default names | c | yes | yes | yes — `sma.length`/`exposure.scale`, verbatim lowercase, paramless legal |

## Examples

### fieldtests/cycle-0031-node-naming/c0031_1_named_single_run.rs — the named single-run authoring path (axis a)
- Builds the canonical harness `source → sma_cross{ Sma("fast"), Sma("slow"),
  Sub } → Exposure → SimBroker → Recorder`, inspects `param_space()`, binds
  `sma_cross.fast.length` / `sma_cross.slow.length` / `exposure.scale` by name
  (no `ParamAlias`, no index counting), runs, and re-runs disjoint for C1.
- Why it fits: this is exactly the friction the 0030 milestone fixture (`mw_1`)
  had to work around with two hand-counted `ParamAlias` overlays — acceptance
  #1/#2/#4 of the spec.
- Outcome: built and ran first try. `param_space()` = `[sma_cross.fast.length:I64,
  sma_cross.slow.length:I64, exposure.scale:F64]`; named bind bootstrapped and
  recorded 12 exposure rows; two disjoint runs bit-identical.

### fieldtests/cycle-0031-node-naming/c0031_2_forcing_function.rs — the forcing function (axis b)
- Authors the SAME 2-SMA cross WITHOUT names, then tries to bind/bootstrap it
  the way a downstream author naturally would (`.with(...).bootstrap()`), then
  isolates the compile wall via `compile_with_params`, then recovers by naming
  the legs and runs.
- Why it fits: acceptance #3 — the deliberate forcing function, and the carrier's
  explicit question "is the diagnostic discoverable/helpful from the public
  surface alone?"
- Outcome: built and ran. The un-named cross IS rejected (good), but the
  diagnostic an author reaches depends entirely on the path (see F4/F5). Naming
  the legs resolves it and the named cross runs (12 rows).

### fieldtests/cycle-0031-node-naming/c0031_3_default_names.rs — default names + paramless-legal (axis c)
- A single un-named `Sma` at root → `sma.length`; un-named `Exposure` →
  `exposure.scale`; checks no `sim_broker`-style snake_case leaks; binds the
  default names and runs; then a two-`Add` paramless same-name fan-in compiles
  (stays legal).
- Why it fits: the spec's "Default name" and "Paramless interchangeable stays
  legal" clauses, plus the carrier's optional 3rd axis.
- Outcome: built and ran. `sma.length` / `exposure.scale` emitted at root and
  bindable; paramless same-name fan-in compiled (`ok: true`).

## Findings

### [working] Named single-run path: `.named()` → uniform `<node>.<param>` → bind by name → run, deterministic
- Example: c0031_1.
- What happened: `Sma::builder().named("fast")` made `param_space()` emit
  `sma_cross.fast.length` / `sma_cross.slow.length`, and the root `Exposure`
  emitted `exposure.scale` — exactly the spec's uniform shape. Binding all three
  by name with `.with(...).bootstrap()` succeeded with no `ParamAlias` and no
  index counting; the run recorded a populated 12-row trace; a disjoint second
  run was bit-identical (C1).
- Why working: the headline acceptance (#1/#2/#4) is reachable, correct, and
  unambiguous from rustdoc + ledger alone. The exact pain the 0030 milestone
  fixture documented (`mw_1`'s two hand-counted overlays) is gone.
- Recommended action: carry-on.

### [working] Naming the colliding legs is the single recovering act; the named cross runs
- Example: c0031_2 (block [2]).
- What happened: the same un-named topology that is rejected becomes legal the
  moment both SMAs are `.named("fast")`/`.named("slow")` — one act clears both
  the param-path collision and the fan-in check, and the harness runs (12 rows).
- Why working: confirms the spec's central claim that one author act fixes both
  walls.
- Recommended action: carry-on.

### [working] Default names = verbatim-lowercased type label, root-level qualified, paramless fan-in stays legal
- Example: c0031_3.
- What happened: an un-named `Sma` at root emitted `sma.length` (root segment now
  present, as the spec inverts the old bare-root rule); un-named `Exposure` →
  `exposure.scale`; no `sim_broker` snake_case appeared; both default names bound
  and ran. Two un-named **paramless** same-type (`Add`) legs under a fan-in
  compiled cleanly — the spec's "paramless interchangeable stays legal" clause
  holds.
- Why working: the default-name mechanism and the param-bearing-vs-paramless
  distinction behave exactly as specified.
- Note (not a defect): `SimBroker` exposes **no** tunable knob (its spread is a
  constructor value), so the `"simbroker"` vs `"sim_broker"` verbatim-lowercase
  rule could not be exercised on an actually-emitted knob; `sma`/`exposure`
  confirm the no-snake-case rule on real knobs.
- Recommended action: carry-on.

### [spec_gap] The headline `IndistinguishableFanIn` diagnostic is unreachable from the canonical by-name authoring flow
- Example: c0031_2 (blocks [0], [1], [1a], [1b]).
- What happened: the spec headlines `IndistinguishableFanIn { node }` as the
  forcing-function diagnostic that tells the author "name the colliding legs"
  (acceptance #3, ledger C9 amendment). But a downstream author using the
  **canonical single-run flow** (`.with(...).bootstrap()`, the spec-0030 surface
  this cycle builds on) never sees it:
  - guessing the old collision name `sma_cross.length` →
    `UnknownKnob("sma_cross.length")`;
  - binding the name `param_space()` **actually** emits — `sma_cross.sma.length`
    — → `AmbiguousKnob("sma_cross.sma.length")`;
  - `IndistinguishableFanIn { node: 2 }` only appears via the **positional**
    `compile_with_params(&[...])`, which a by-name author has no reason to call.
- Why spec_gap: acceptance #3 says "an unnamed same-type param-bearing fan-in is
  rejected with `IndistinguishableFanIn`, and the rejection names the node;
  naming the legs resolves it." It IS rejected — correctly — but through
  `.bootstrap()` the rejection is a **binder** error (`UnknownKnob` /
  `AmbiguousKnob`) that points at a knob *name*, not at "give your nodes distinct
  names." The author whose mental model is "I bound a name that doesn't resolve"
  is led to fiddle with the bind string, not to `.named()` the legs — the exact
  recovery the cycle is built to teach. Two readings are equally plausible from
  the surface: (i) "`IndistinguishableFanIn` is the contract; the binder errors
  are an incidental earlier wall" vs (ii) "the by-name flow should surface the
  fan-in/naming guidance too." I asserted neither in the fixture — I recorded
  both walls verbatim.
- Recommended action: ratify-or-tighten. Either (a) document on
  `param_space()` / `Composite::with` that a duplicate-named (default-collision)
  knob is the *symptom* and node-naming is the *cure* — i.e. make `AmbiguousKnob`
  / `UnknownKnob` text (or rustdoc) point at `.named()`; or (b) have the
  by-name `.bootstrap()` path surface `IndistinguishableFanIn` (or fold its
  guidance into the binder error) so the canonical flow reaches the diagnostic
  the spec promises. No engine behaviour is wrong; the guidance is mis-routed.

### [friction] `param_space()` advertises a literal duplicate knob name for an un-named same-type fan-in
- Example: c0031_2 (block [0]).
- What happened: the un-named cross's `param_space()` emits
  `sma_cross.sma.length` **twice** — two `ParamSpec` entries with byte-identical
  names, neither individually bindable (`AmbiguousKnob`). A value-empty blueprint
  (C11) thus publicly advertises two knobs the consumer cannot address.
- Why friction: the task (bind the cross) still completes once the author names
  the legs, but the public `param_space()` projection contains an un-actionable
  duplicate — a consumer enumerating it (e.g. to build a sweep grid or a UI) sees
  a degenerate entry with no surface signal that the cure is `.named()`. The old
  pre-0031 collision was `sma_cross.length` (×2); 0031 changes the string but not
  the duplicate-ness in the default case.
- Recommended action: plan (tidy) — consider whether `param_space()` should
  de-dup, error, or annotate a collision-named entry, so the flat projection is
  never silently degenerate. At minimum a rustdoc note on `param_space()` that a
  duplicate entry signals an un-named same-type sibling.

### [friction] `FlatGraph` / `Harness` lack `Debug`, so a `compile`/`bootstrap` `Result` cannot be `{:?}`-printed
- Example: c0031_2, c0031_3 (compile-time, worked around).
- What happened: `compile_with_params` returns `Result<FlatGraph, CompileError>`
  and `bootstrap` returns `Result<Harness, CompileError>`; printing either with
  `{:?}` fails to compile (`FlatGraph`/`Harness` don't implement `Debug`). A
  consumer probing diagnostics must `.err()`/`.is_ok()` the Result rather than
  print it whole.
- Why friction: not new to 0031 and not wrong, but it surfaced immediately when
  field-testing the very errors this cycle re-keys — the natural first reflex
  (`println!("{:?}", result)`) does not compile, forcing a `.err()` dance.
- Recommended action: carry-on (or plan, low priority) — deriving `Debug` on the
  success types would let consumers print a compile/bootstrap result directly;
  orthogonal to 0031's contract.

## Recommendation summary

| Finding | Class | Action |
|---|---|---|
| Named single-run path uniform `<node>.<param>`, bind, run, deterministic | working | carry-on |
| Naming the colliding legs is the single recovering act | working | carry-on |
| Default names verbatim-lowercase, root-qualified, paramless legal | working | carry-on |
| `IndistinguishableFanIn` unreachable from the canonical by-name flow | spec_gap | ratify / tighten (route the naming guidance into the binder error or rustdoc) |
| `param_space()` advertises a literal duplicate knob in the default case | friction | plan (tidy) |
| `FlatGraph`/`Harness` not `Debug` → can't print a compile/bootstrap Result | friction | carry-on / plan (low) |

## Verdict

Cycle 0031 delivers its core promise cleanly — `.named()`, uniform
`<node>.<param>` paths, and the one-act fan-in/param-path fix all work first try
from the public surface; the only real gap is that the spec's headline
`IndistinguishableFanIn` diagnostic never reaches an author using the canonical
`.with(...).bootstrap()` flow (they hit `UnknownKnob`/`AmbiguousKnob` instead),
so the cure (`.named()`) is under-signposted exactly where the cycle most wants
to teach it.