Aura/docs/specs/fieldtest-milestone-construction-layer.md

Fieldtest — milestone "Construction layer" — 2026-06-05

Status: Draft — awaiting orchestrator triage Author: fieldtester (dispatched by fieldtest skill, milestone-scope variant) Scope mode: MILESTONE (closing functional gate), not per-cycle.

Scope

The "Construction layer" milestone (cycles 0012 composites + 0013 render) promises that a downstream researcher can build a graph fractally from a Rust builder — author leaf nodes and reusable named composites (a sub-graph exposing one output), nest them arbitrarily, and compile() / bootstrap() the param-generic Blueprint down to the flat, deterministic runnable instance (C9/C19/C23). They can introspect the built graph as data and render it as an ASCII DAG (aura graph clustered authored view, aura graph --compiled flat inlined view) so the structure — and any mis-wiring — is visible (C14/C22, #13). The composite boundary dissolves at inline (C23); a composite-authored graph runs bit-identical to the hand-wired flat equivalent (C1).

This fieldtest derives four end-to-end scenarios top-down from that promise, one per carrier axis (a–d), and drives them from the public interface only: the design ledger (docs/design/INDEX.md), the crate doc-comments (rendered via cargo doc --no-deps), the public re-export lists, and the aura CLI. No crates/*/src was read. The construction-layer API was discovered entirely from the ledger + rustdoc. The artefact under test was built from HEAD (cargo build --workspace; the consumer crate compiled against the current path-dep'd engine crates; the CLI driven via cargo run -p aura-cli, so HEAD is always what ran).

Examples

fieldtests/milestone-construction-layer/mc_1_composite_build_run.rs — author + compile + run a named composite

• A standalone consumer crate (own [workspace], path-deps on the engine crates — the shape a C16 project takes) authors an SMA(2)/SMA(4)-cross as a reusable named Composite (sma_cross, one price role fanning into both SMAs, Sub's output as the exposed port), wires it into a harness Blueprint (source → composite → Exposure(0.5) → SimBroker(1e-4) → Recorder), bootstrap()s, and run()s it over a synthetic price ramp.
• Fits the milestone: this is the headline authoring story — build a graph fractally from a Rust builder via a named composite, then compile/bootstrap/run it.
• Outcome: built? yes, first try. ran? yes. matched expected? yes — 12 recorded equity rows, non-degenerate (equity_pips ramps 0 → 11.5 → −6.5), the composite-authored harness produces a populated trace.

fieldtests/milestone-construction-layer/mc_2_miswire_render.rs — a fast/slow swap is observable in graph-as-data + labels

• Builds the sma_cross composite twice — correct (fast→Sub.slot0, slow→Sub.slot1) and swapped — and asserts the per-node label()s carry the disambiguating params (SMA(2) / SMA(4)) and that the interior edge table differs between the two. The property under test is the one the render relies on: if a swap produced identical graph-as-data, no renderer could surface it.
• Fits the milestone: the headline promise is "the render visibly surfaces the mistake." This verifies the consumer-side substrate of that promise (labels + edge table), complementing the aura graph CLI render exercised below.
• Outcome: built? yes. ran? yes. matched expected? yes — labels read ["SMA(2)", "SMA(4)", "Sub"]; correct edges [{0→2.s0},{1→2.s1}] vs swapped [{1→2.s0},{0→2.s1}] — observably different.

fieldtests/milestone-construction-layer/mc_3_nested_composite.rs — composite-inside-composite inlines, runs

• Nests the sma_cross composite inside an outer strategy composite (which maps it through Exposure(0.5)), wires strategy → SimBroker → Recorder, bootstrap()s and run()s.
• Fits the milestone: "nest composites arbitrarily" + "the compiled/flat view handles nesting." This verifies the recursive-inline run-path from the consumer side (the known sharp edge #26 is about the clustered render, not the run path — see findings).
• Outcome: built? yes. ran? yes. matched expected? yes — the nested composite recursively inlined to a flat runnable instance; 12 recorded rows.

fieldtests/milestone-construction-layer/mc_4_introspect_graph.rs — walk the graph-as-data via read-only accessors

• Builds a Blueprint (composite + Exposure) and walks it purely through the public accessors: Blueprint::nodes()/sources()/edges() and Composite::name()/nodes()/edges()/input_roles()/output(), plus label() on each boxed leaf, recursing into the composite interior.
• Fits the milestone: "introspect the built graph as data" (C9/C14) — can a consumer walk it without engine internals?
• Outcome: built? yes (after one import fix — see finding). ran? yes. matched expected? yes — the full interior (3 items, 1 role fanning to 2 targets, Sub's output port, 2 interior edges) is reachable through the public accessors alone.

Render artefacts (CLI, built-in sample) — render_clustered.txt / render_compiled.txt

• aura graph and aura graph --compiled run live (via cargo run -p aura-cli), captured as artefacts. Both render the engine's built-in sample blueprint (the same SMA-cross harness). Byte-identical across two runs (C1 for the render).

Findings

[working] The full composite authoring → compile → bootstrap → run thread is authorable from the public interface

• Examples: mc_1, mc_3.
• What happened: the entire construction-layer authoring story — Composite::new(name, nodes, edges, input_roles, output), BlueprintNode::from(node) / BlueprintNode::Composite(..), Blueprint::new(..).bootstrap(), Harness::run — compiled on the first attempt from rustdoc signatures + the ledger (C9/C19/C23) alone, for both a single composite and a composite-in-composite. Both produced populated, non-degenerate recorded traces.
• Why working: the milestone's central promise — build a graph fractally from a Rust builder and compile/bootstrap/run it — is delivered, and the public surface (ledger + rustdoc) is self-sufficient for a downstream author. The recursive inline of a nested composite works end to end on the run path.
• Recommended action: carry-on.

[working] The graph-as-data accessors let a consumer walk the built graph (incl. composite interiors) with no engine internals

• Example: mc_4.
• What happened: Blueprint::{nodes,sources,edges} and Composite::{name,nodes,edges,input_roles,output} together expose the whole graph as read-only data; a recursive walk reaches every leaf label, every role fan-out, the output port, and every interior edge. node.label() dispatches off the boxed leaf without importing the Node trait.
• Why working: C9 "the built graph is introspectable runtime data" and the #13 graph-as-data promise hold from the consumer side.
• Recommended action: carry-on.

[working] Per-node labels disambiguate identical node types, and a mis-wire changes the graph-as-data

• Examples: mc_2, render_clustered.txt.
• What happened: label() overrides carry params (SMA(2) vs SMA(4)), so the two SMAs are distinguishable; a fast/slow swap changes the interior edge table. The aura graph clustered render shows both SMAs feeding Sub with the labels present, so a reader can trace which leg goes where. Render is byte-identical across runs (C1).
• Why working: the C8-refinement label mechanism does exactly what the milestone needs — it makes a swap readable. This is the substrate of the headline "render surfaces a mis-wiring" promise.
• Recommended action: carry-on.

[friction] aura graph renders ONLY the built-in sample — a consumer cannot render the graph they authored

• Examples: mc_1/mc_2/mc_3 (authored blueprints) vs the CLI render artefacts.
• What happened: aura graph and aura graph --compiled are hard-wired to one built-in sample blueprint. Any extra argument is silently ignored: aura graph --bogus, aura graph mc_1_composite_build_run.rs, and even aura graph --help all render the same built-in sample and exit 0. There is no path (flag, file, stdin) to point the renderer at a consumer's own Blueprint.
• Why friction: the milestone's headline payoff — "render the structure so any mis-wiring is visible before/around a run" — is, at the CLI level, only available for the engine's own sample. A downstream researcher who authored mc_2's swapped cross (the literal mis-wire the feature exists to catch) cannot feed it to aura graph; they fall back to introspecting the graph-as-data by hand (mc_2/mc_4) or writing their own ascii-dag adapter (which lives only in aura-cli, not a reusable surface). The render-as-a-library affordance that would let a consumer render their own graph is absent. Task completed (the render exists and is correct), but the consumer is forced into a hand-rolled workaround to apply it to their own work.
• Recommended action: plan — expose a render entry point a consumer can call on their own Blueprint (a library render(&Blueprint) -> String in a face crate, or aura graph accepting a project/blueprint selector). Pairs naturally with the deferred aura new / experiment-builder surface.

[friction] The construction surface (aura-engine) does not re-export the core scalar vocabulary a graph-builder needs

• Example: mc_4 (initial use aura_engine::{… ScalarKind …} failed to compile: "no ScalarKind in the root … consider importing aura_core::ScalarKind").
• What happened: building a Blueprint/SourceSpec/Recorder requires ScalarKind (and, for sources/recorders, Scalar / Firing / Timestamp), but aura-engine — the crate that owns Blueprint, Composite, Edge, Target, SourceSpec — re-exports none of them. SourceSpec { kind: ScalarKind, .. } is an aura-engine struct whose own field type must be imported from a different crate (aura-core). A downstream author must know to reach across crate boundaries for the vocabulary the engine's own public types demand.
• Why friction: it is a paper cut, not a blocker — the compiler error names the right import — but it makes the "build a graph from a Rust builder" surface more than one use aura_engine::*. The construction API and the scalar vocabulary it consumes live in two crates with no convenience re-export.
• Recommended action: plan (tidy) — re-export the core scalar vocabulary (Scalar, ScalarKind, Firing, Timestamp) from aura-engine (or a prelude) so a graph-builder has a single import surface. Low priority.

[spec_gap] aura graph --help / unknown args → render the sample, exit 0 (no help, args silently swallowed)

• Examples: render probes — aura graph --help and aura graph --bogus both print the clustered sample and exit 0.
• What happened: the graph subcommand keys only on the presence of the exact --compiled token; every other argument (including --help) falls through to the clustered view. No usage/help text, no rejection of unknown flags.
• Why spec_gap: the milestone/CLI contract does not pin how aura graph handles unknown or --help arguments; the binary chose the lenient "ignore and render the default view" reading. An equally plausible reading rejects unknown flags (exit 2) and prints help on --help. This re-confirms, on the new graph subcommand, the same lenient-arg gap the walking-skeleton fieldtest recorded for aura run <junk> and aura --help.
• Recommended action: ratify-or-tighten — decide a single CLI arg policy (reject unknown flags + --help→stdout/exit 0) across both run and graph, rather than per-subcommand. Low priority; carried/expanded from the walking-skeleton finding.

[spec_gap] The known nested-composite render panic (#26) is unreachable from the public CLI today — its consumer impact is latent, not live

• Example: mc_3 (authored a nested composite; could not feed it to aura graph).
• What happened: the carrier flags #26 — the clustered blueprint view has an unimplemented! on nested composites — as a sharp edge to classify. As a downstream consumer I could not reach it: aura graph renders only the built-in single-level sample (see the friction above), so there is no public surface that feeds a nested blueprint into the clustered renderer. The panic is real in the code but structurally unreachable from the shipped CLI; the run-path nesting (mc_3) works fine.
• Why spec_gap: the milestone promise says the render makes nesting visible, but the only render entry point is the fixed sample, so "render a nested composite" is not actually exercisable by a consumer — the gap and the latent panic are two faces of the missing "render my own graph" affordance. Severity of #26 as a consumer-facing bug is currently low/latent (no public trigger), but it becomes live the moment the render is made parameterizable (the friction above) — at which point a consumer rendering a nested clustered view would panic.
• Recommended action: tighten the design ledger / sequence #26 — record that the "render my own graph" affordance (the friction above) and the #26 clustered nesting fix are coupled: shipping the former without the latter exposes the panic to consumers. The audit's own note ("resolve #26 before the next render-touching cycle") already points this way; this fieldtest confirms the coupling empirically. Classify #26 as the blocker for the parameterizable-render cycle, not for this milestone (which ships only the sample render).

Recommendation summary

Finding	Class	Action
Composite authoring → compile → bootstrap → run thread authorable, populated	working	carry-on
Graph-as-data accessors walk the built graph (incl. interiors)	working	carry-on
Labels disambiguate; a swap changes graph-as-data; render deterministic	working	carry-on
aura graph renders only the built-in sample (no render-my-own-graph)	friction	plan
aura-engine doesn't re-export the core scalar vocabulary	friction	plan (tidy)
aura graph --help / unknown args → render sample, exit 0	spec_gap	ratify-or-tighten (unify CLI arg policy)
#26 nested-render panic unreachable from CLI today (latent, coupled to render-my-own-graph)	spec_gap	tighten ledger / sequence #26 with the parameterizable-render cycle

Milestone roll-up

The "Construction layer" milestone DELIVERS its core promise. A downstream researcher can author leaf nodes and reusable named composites, nest them arbitrarily, and compile()/bootstrap()/run() the param-generic Blueprint down to a flat, deterministic, populated-trace instance (C9/C19/C23) — all from the public interface, first try, including a composite-in-composite. The graph-as-data accessors let a consumer walk the built graph without engine internals, and the C8-refinement labels make a mis-wire readable in both the graph-as-data and the aura graph render.

The gap is in the render's reach, not its correctness: aura graph is hard-wired to one built-in sample, so the headline "render any mis-wiring before a run" payoff is, at the CLI level, only demonstrated on the engine's own example — a consumer cannot point it at the graph they authored, which is exactly where a mis-wire would live. That single missing affordance ("render my own graph") subsumes both the friction and the latent reachability of the #26 nested-render panic: making the render parameterizable is the next step, and #26 must land with it. No bugs found (the #26 panic is real in code but structurally unreachable from the public surface today). Three working, two friction, two spec_gap — none blocking the milestone gate.