By-name bootstrap surfaces AmbiguousKnob, not the IndistinguishableFanIn 'name your nodes' cure, for un-named same-type siblings #59

New Issue

2026-06-11T12:18:49+02:00

Brummel commented

2026-06-11 12:18:49 +02:00

Surfaced + verified by the cycle 0031 per-cycle fieldtest
(docs/specs/fieldtest-0031-node-naming.md, fixture c0031_2_forcing_function).

The gap

Cycle 0031 made IndistinguishableFanIn the forcing function: an un-named
2-SMA cross should reject and tell the author to name the colliding legs. That
holds on the compile() / positional compile_with_params path. But on the
canonical authoring flow — bp.with(name, v).bootstrap() — the author never
sees it. Verified fixture output for an un-named cross:

param_space():
    sma_cross.sma.length : I64     <- literal DUPLICATE knob name
    sma_cross.sma.length : I64
    exposure.scale : F64
.with("sma_cross.fast.length", 2).bootstrap()  -> UnknownKnob("sma_cross.length")
.with("sma_cross.sma.length", 2).bootstrap()   -> AmbiguousKnob("sma_cross.sma.length")
compile_with_params(...)                        -> IndistinguishableFanIn { node: 2 }

The binder resolves names against param_space() before bootstrap runs the
compile fan-in check, so it short-circuits on the duplicate-name condition. The
author hits UnknownKnob / AmbiguousKnob — both point at the knob name, not
at the cure ("name your nodes with .named(...)"). The diagnostic the cycle
designed to guide them is on a path they do not take.

Two coupled symptoms:

Under-signposted cure (spec_gap). The canonical flow surfaces the wrong
error for the un-named-sibling case.
Duplicate knob in param_space() (friction). Two un-named same-type
siblings produce a literal duplicate name (sma_cross.sma.length x2). It is
harmless to correctness (such a blueprint cannot bootstrap — the fan-in check
rejects it either way), but param_space() advertising a duplicate is a smell.

Direction (not prescriptive)

Surface the node-naming cure on the path the author takes — e.g. have the binder
(or bootstrap) detect the duplicate-name / fan-in-indistinguishable condition
and raise (or chain) the IndistinguishableFanIn / "name your nodes" guidance
instead of a bare AmbiguousKnob, or have param_space() refuse to emit a
duplicate name and carry the cure in the error. Relates to #58 (node identity
not surfaced to the consumer). Not a correctness bug — no invalid blueprint runs.

Minor, separable: FlatGraph/Harness lack a Debug impl, so a compile/
bootstrap Result can't be {:?}-printed by a consumer (low friction).

Surfaced + verified by the cycle 0031 per-cycle fieldtest (docs/specs/fieldtest-0031-node-naming.md, fixture c0031_2_forcing_function). ## The gap Cycle 0031 made `IndistinguishableFanIn` the forcing function: an un-named 2-SMA cross should reject and tell the author to name the colliding legs. That holds on the `compile()` / positional `compile_with_params` path. But on the **canonical authoring flow** — `bp.with(name, v).bootstrap()` — the author never sees it. Verified fixture output for an un-named cross: ``` param_space(): sma_cross.sma.length : I64 <- literal DUPLICATE knob name sma_cross.sma.length : I64 exposure.scale : F64 .with("sma_cross.fast.length", 2).bootstrap() -> UnknownKnob("sma_cross.length") .with("sma_cross.sma.length", 2).bootstrap() -> AmbiguousKnob("sma_cross.sma.length") compile_with_params(...) -> IndistinguishableFanIn { node: 2 } ``` The binder resolves names against `param_space()` **before** `bootstrap` runs the compile fan-in check, so it short-circuits on the duplicate-name condition. The author hits `UnknownKnob` / `AmbiguousKnob` — both point at the *knob name*, not at the cure ("name your nodes with `.named(...)`"). The diagnostic the cycle designed to guide them is on a path they do not take. Two coupled symptoms: 1. **Under-signposted cure (spec_gap).** The canonical flow surfaces the wrong error for the un-named-sibling case. 2. **Duplicate knob in `param_space()` (friction).** Two un-named same-type siblings produce a literal duplicate name (`sma_cross.sma.length` x2). It is harmless to correctness (such a blueprint cannot bootstrap — the fan-in check rejects it either way), but `param_space()` advertising a duplicate is a smell. ## Direction (not prescriptive) Surface the node-naming cure on the path the author takes — e.g. have the binder (or `bootstrap`) detect the duplicate-name / fan-in-indistinguishable condition and raise (or chain) the `IndistinguishableFanIn` / "name your nodes" guidance instead of a bare `AmbiguousKnob`, or have `param_space()` refuse to emit a duplicate name and carry the cure in the error. Relates to #58 (node identity not surfaced to the consumer). Not a correctness bug — no invalid blueprint runs. Minor, separable: `FlatGraph`/`Harness` lack a `Debug` impl, so a `compile`/ `bootstrap` `Result` can't be `{:?}`-printed by a consumer (low friction).

Brummel added the idea label 2026-06-11 12:18:49 +02:00

Brummel referenced this issue from a commit

2026-06-11 18:45:44 +02:00

spec: 0032 param-namespace-injectivity (boss-signed)

Brummel referenced this issue from a commit

2026-06-11 18:45:44 +02:00

spec: 0032 correct test 5 fixture nesting (boss-signed)

Brummel referenced this issue from a commit

2026-06-11 18:45:44 +02:00

plan: 0032 param-namespace-injectivity

Brummel referenced this issue from a commit

2026-06-11 18:45:44 +02:00