A leaf primitive built with `.named("fast")` now renders its `aura graph` viewer
box head as `fast: SMA[length]` — the instance name as a `:` declaration prefix.
An unnamed leaf keeps the bare `SMA[length]`.
Engine half: a new raw `PrimitiveBuilder::instance_name() -> Option<&str>` (the
explicit name, default not resolved) feeds a conditional leading `"name"` field
in prim_record, present only for an explicitly-named node; both golden twins
(inline model_golden + sample-model.json) re-captured. Viewer half: adaptNodes
carries `name`, the genDot leaf-emit forwards it, and cellLabel prepends the
`name: ` prefix when present (composites stay bare). `named()`'s non-empty
debug_assert is unchanged, its doc re-grounded to the now load-bearing Some/None
invariant (knob-address segment + prefix switch).
The name is a render/model-only debug symbol — dropped at lowering (C23), and the
model stays deterministic (C14). Parameter ganging (one knob, several nodes) was
considered and spun off as an explicit composite-shared-param idea (#61), not via
name collision (param_space is injective, C12/C19).
closes#58
Architect drift review over 065cf1d..HEAD. Code + contracts hold; the only drift
was documentation cross-references made stale by retiring RunReport's hand-rolled
to_json.
Contracts (all hold):
- C14: to_json still emits canonical, flat, deterministic JSON — now serde-produced.
model_to_json (the graph-model JSON) stays hand-rolled and was correctly untouched.
- C16: serde_json dev-dep → normal-dep in aura-engine is squarely sanctioned by the
amended per-case policy (INDEX.md:576-583) — a vetted standard crate used where it
does the job (incl. the frozen bot), removing a hand-rolled writer. No gap.
- C1: report types have no HashMap; serde is declaration-order/deterministic; the
r1.to_json()==r2.to_json() asserts and the new to_json_equals_serde_disk_shape pin
stay green.
Regression: none configured (profile regression: []) — no-op; architect is the gate.
Resolution — fix (3 prose cross-refs, fixed inline this commit):
- graph_model.rs:5 (module doc) — claimed the model JSON is in the "RunReport::to_json
house style (no serde)"; to_json is serde now. Reframed: the model JSON is hand-rolled
(no serde), and is the engine's last hand-rolled JSON writer since 0033.
- graph_model.rs:30 (json_str doc) — cross-referenced RunReport::json_str, deleted this
cycle. Reworded to describe the escape set directly (graph_model's own json_str stays).
- docs/design/INDEX.md:729 — "golden-tested like RunReport::to_json" framed the hand-rolled
model JSON by a now-serde to_json. Reframed to name model_to_json as the surviving
hand-rolled writer.
Cycle 0033 drift-clean after this tidy. Not a milestone close (the param-sweep milestone
fieldtest is a separate deliberate act). Gates: clippy --workspace --all-targets -D
warnings clean (doc-only edits, compile-inert).
refs #54
Every blueprint node now carries a name. A primitive builder gains an optional
instance name (Sma::builder().named("fast")); when omitted it defaults to the
node's type label, ASCII-lowercased verbatim ("SMA"->"sma", "SimBroker"->
"simbroker"). 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, so
one act -- naming the legs "fast"/"slow" -- fixes both the naming collision and
the fan-in check. The index-addressed ParamAlias overlay, Composite.params, the
Composite::new 5th argument, aliases_on, and check_alias_indices are removed
(Role.name and OutField.name untouched). Ledger C9 and C23 amended.
This is why the change is correct, not merely convenient: blueprints are
value-empty (C11), so the thing that would otherwise distinguish two SMAs --
their length -- is not present at construction; identity must come from a name,
not a deferred value. Closes the #56 friction surfaced by the param-space &
sweep milestone fieldtest (a freshly-authored 2-SMA cross was unbindable and
would not bootstrap without two hand-counted ParamAlias overlays).
Two plan defects were corrected during implementation and verified:
- the three new fan-in/path tests authored sma_cross at root level, which would
qualify to "fast.length" (root prefix is empty) and is not the nested case the
fan-in check inspects; nesting sma_cross under a root (a shared
sma_cross_under_root helper) restores the asserted "sma_cross.fast.length" and
IndistinguishableFanIn{node:2};
- three cycle-0030 named-binder tests bound the real harness by the old names
(sma_cross.fast / scale) and were migrated to the new path strings, surfaced by
the workspace test gate.
Verified by the orchestrator: cargo build/test --workspace green (198 tests,
0 red), clippy --all-targets -D warnings clean. model_to_json emits the type
label + factory param names (node-name-independent), so sample-model.json and the
graph_model golden are byte-identical (untouched). NodeSchema gained a Default
derive (the builder default-name test constructs an empty schema). fieldtests/
are frozen non-workspace records, not migrated.
closes#56
PortSpec gains a non-load-bearing `name: String`, so an input port is named just
as FieldSpec.name (output) and ParamSpec.name (param) already are — input ports
were the lone unnamed member of the node signature. Identity stays positional by
slot (C23); the name is render/debug only, never read by bootstrap or the run
loop. PortSpec drops Copy (String is not Copy), exactly as ParamSpec already does.
- Every aura-std node names its input slots: SMA/EMA "series", Sub/Add "lhs"/"rhs",
Exposure "signal", SimBroker "exposure"/"price" (the slots become
self-documenting), LinComb "term[i]" and Recorder "col[i]" generated in their
build loops (mirroring LinComb's existing weights[i] param loop).
- derive_signature carries a composite's Role.name into the derived input port
(it was dropped before — the output side already carried FieldSpec.name), so the
graph model is homogeneously named at both levels.
- model_to_json (port_json + the composite-header inputs in scope_json) emits the
name as a third tuple element: ["f64","any","exposure"]. The byte golden was
re-captured (machine bytes) and its substring twins updated; the model is now
fully named across inputs/outputs/params.
- All 16 PortSpec construction sites threaded in one compile-gate change; test
fixtures carry fixture names. C8 realization note added to the design ledger.
Why name-only, no validation: the name is a pure debug symbol. Wire-by-name was
rejected (it would be a C23 contract change). Bootstrap slot-wiring validation
(which would close#21's same-kind swap footgun) is deferred to its own cycle —
a name alone does not catch the swap; it makes the slots self-documenting and
gives a future validation something to check against.
Verified: cargo test --workspace 168 green; clippy --all-targets -D warnings
clean; cargo build --workspace clean. Read-only render path (C9), no serde (C14),
scalar kinds unchanged (C4).
closes#50
refs #21
refs #51
Iteration 1 of the graph render redesign: a read-only model_to_json(&Composite)
that serializes the harness root + every distinct composite type into the
canonical, deterministic JSON model the browser viewer will consume. New
crates/aura-engine/src/graph_model.rs; lib.rs re-exports model_to_json.
- House style: hand-rolled JSON like RunReport::to_json, NO serde (C14).
- Model shape (faithful to the types, resolving the spec's prototype-flavoured
example): node keys are indices (C23, the blueprint has no unique names);
input ports carry kind+firing only, no name (PortSpec has none — acceptance
criterion 3); a vec![] output is the C8 sink; bound root source-roles are
minted as synthetic src_<role> source nodes; composite boundaries use @role
(input) and #N (output) endpoints; distinct composites collected once.
- Improvement over the plan: a composite's input kind is read from the actually
fed interior slot (matching blueprint::derive_signature) rather than a hardcoded
f64 — invents nothing.
- Read-only (C9): &Composite -> String, no eval/compile/bootstrap on the path.
- 10 new tests green: byte golden on the sample harness, determinism, structural
mis-wire differs (param swaps are invisible to the pre-compile model — the
property is carried by a structural re-target), read-only witness, sink /
two-input / distinct-once structural assertions. Workspace green, clippy clean.
aura graph still renders via ascii-dag (untouched); iteration 2 ports the viewer
JS, vendors the WASM-Graphviz asset, emits the self-contained HTML, and retires
ascii-dag.
Brummel