Aura/fieldtests/milestone-topology-as-data/FINDINGS.md

# Fieldtest — milestone: Topology-as-data (C24) — 2026-06-30

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

## Scope

The milestone-close gate for **C24 — the blueprint is a serializable,
World-owned data value**. The milestone promises a downstream researcher can run
the whole topology-as-data story end to end: author a param-generic graph with
the Rust builder, **serialize** it to a canonical versioned data value,
**load** it back (data → blueprint → runnable), **construct** the same topology
declaratively through the CLI op-script (`aura graph build`), **introspect** the
closed node vocabulary without a build (`aura graph introspect`), and
**reproduce** a run bit-identically (C1). Spanning cycles 0087 (#155 serde
first-cut), 0088 (#157 construction service), 0089 (#161/#162 diagnostics +
acyclicity), 0090 (#156 forward-compat two-tier).

Run entirely from the public interface: the C24 ledger entry, `cargo doc`
doc-comments, `aura graph introspect`'s own output, and the existing op-script
fixture *shape*. No `crates/*/src` was read. Artefact under test:
`target/debug/aura` + the engine path-dep crates, both rebuilt from HEAD
(`cargo build --workspace`) before the run.

## Examples

All fixtures under `fieldtests/milestone-topology-as-data/`.

### mt_1_roundtrip.rs — Rust round-trip + run identity (tasks 1)
- Authors an SMA(2)/SMA(4)-cross bias signal with `GraphBuilder`
  (`source_role` → `Sma::builder().named().bind()` → `Sub` → `Bias` → `expose`),
  serializes with `blueprint_to_json`, loads with `blueprint_from_json` +
  `aura_std::std_vocabulary`, re-serializes, and runs both the original and the
  reloaded twin through an identical Recorder harness.
- Fits scope: the headline C24 acceptance (serialize → load → reproduce).
- Outcome: **built, ran, matched.** (a) canonical JSON round-trips
  byte-identically (647 bytes, serialize→load→re-serialize equal). (b) 9
  recorded bias rows value-for-value identical between original and reload (C1).

### mt_2_sma_cross.ops.json + mt_2_blueprint.cli.json — declarative construction + cross-surface identity (task 2)
- The same topology as a CLI op-script; `aura graph build < ops.json` emits the
  #155 blueprint. Compared against `mt_1_rust_blueprint.json` (the library
  emit).
- Fits scope: C1 identity across authoring surfaces (Rust builder vs op-script).
- Outcome: **built, ran, matched (modulo one byte).** The two blueprints are
  **character-for-character identical** except the CLI appends a trailing `\n`
  (648 vs 647 bytes). See spec_gap below.

### mt_3_*.out + mt_3_partial.ops.json — build-free introspection (task 3)
- `introspect --vocabulary` (22 closed types), `--node SMA|Sub|Bias|EMA|RollingMax`
  (ports, kinds, bind form), and `--unwired` on a partial op-list.
- Fits scope: discover the vocabulary / a node's ports / unwired slots without a
  build.
- Outcome: **ran, matched.** `--unwired` on a partial doc reports `sub.rhs:F64`
  (the one open slot, by identifier, no build). `--node LinComb`/`Recorder`
  correctly refuse (`unknown node type`, exit 2) — they are outside the
  round-trippable set, as the ledger states.

### mt_4_forward_compat.rs — forward-compat Tier-1/Tier-2 + cross-surface interop (tasks 4)
- Loads the **CLI-emitted** blueprint via the **library** loader (cross-surface
  interop); injects unknown optional fields at envelope and node level (Tier-1);
  bumps `format_version` to 999 and swaps a node type to `FOO` (Tier-2).
- Fits scope: the #156 two-tier discipline from the loader's seat.
- Outcome: **built, ran, matched.** CLI blueprint loaded + ran identically
  (trailing newline tolerated). Tier-1 unknown fields tolerated, dropped on
  re-emit (back to canonical), ran bit-identical. Tier-2 refused **by name** —
  `UnsupportedVersion { found: 999, supported: 1 }` and `UnknownNodeType("FOO")`
  — no panic, no silent wrong graph.

### mt_5{a,b,c}_*.ops.json + .err/.exit — fail-fast CLI diagnostics (task 5)
- Three malformed op-lists fed to `aura graph build`: unknown node type, a
  connect that closes a cycle, an unconnected input slot.
- Fits scope: invalid construction must fail fast, by identifier, non-zero exit.
- Outcome: **ran, matched.** Each reported by identifier with empty stdout and
  exit 2 (verbatim below).

## Findings

### [working] The C24 round-trip is real and bit-exact, both surfaces
- Examples: mt_1, mt_2, mt_4.
- What happened: a builder-authored signal serialized → loaded → re-serialized
  byte-identically (647 bytes) and the reload ran value-for-value identical to
  its twin (9 bias rows). The CLI op-script emitted a blueprint whose **content
  is character-identical** to the library emit, and that CLI blueprint loaded
  through the library loader and ran identically.
- Why working: the milestone's central promise (author → serialize → load →
  reproduce, identical across the Rust and CLI authoring surfaces) holds on
  first try from the public surface alone.
- Recommended action: carry-on. These are the C24 acceptance pins, empirically
  confirmed downstream.

### [working] Build-free introspection answers the three discovery questions
- Examples: mt_3.
- What happened: `--vocabulary` listed the closed 22-type set; `--node`
  surfaced ports/kinds **and** the exact bind form (`param length:I64 (bind
  {"I64": <v>})`); `--unwired` named the single open slot `sub.rhs:F64` with no
  build. Out-of-vocabulary `--node LinComb`/`Recorder` refused cleanly (exit 2).
- Why working: a consumer can discover the entire authorable surface (what nodes
  exist, each node's ports, what a partial doc still needs) without compiling
  anything — exactly the #157 introspection promise.
- Recommended action: carry-on.

### [working] Forward-compat + fail-fast diagnostics are by-name / by-identifier
- Examples: mt_4, mt_5.
- What happened: Tier-1 unknown fields tolerated and dropped on re-emit; Tier-2
  refused by name with values (`found: 999, supported: 1`; `"FOO"`). The three
  build failures each named the cause at the offending site:
  `op 1 (add): unknown node type "FOO"`;
  `op 5 (connect): connecting b.value -> a.rhs would close a cycle`;
  `finalize: slot sub.rhs is unconnected` — all exit 2, all with empty stdout
  (no half-emitted blueprint).
- Why working: every refusal is actionable and points at an identifier, never a
  raw index or a panic — the #161/#162 polish landed and holds downstream.
- Recommended action: carry-on.

### [friction] The construction surface is undiscoverable from the CLI's own help
- Examples: observed probing `aura --help`, `aura graph --help`, `aura graph`.
- What happened: top-level usage lists only `aura graph` (no `build` /
  `introspect`). `aura graph --help` reprints the same top-level usage. `aura
  graph` with no subcommand silently streams a ~1.4 MB HTML viewer to stdout and
  exits 0. The only way I learned `build`/`introspect` existed was the C24
  ledger; the only way I learned the introspect flags was triggering its usage
  line by passing a bad arg.
- Why friction: the task completed, but a consumer with only the binary cannot
  find the milestone's headline CLI surface. (Known/filed as #159.)
- Recommended action: plan — add a `graph` subcommand help listing
  `build | introspect` and their flags; make bare `aura graph` print usage
  rather than dump HTML to a TTY.

### [friction] The op-script JSON schema is documented nowhere durable; the only example is stale
- Examples: mt_2 (and the failed build of `fieldtests/cycle-0088-…/c0088_1`).
- What happened: no durable public doc (ledger, glossary, README) states the
  op-list grammar — the verbs (`source`/`add`/`feed`/`connect`/`expose`) or
  their keys. `aura graph build --help` does not exist (empty input just prints a
  JSON parse error). The only worked example is the cycle-0088 fixture corpus,
  which still uses the **retired `as` key** for `add`; replaying it verbatim
  fails with `op 2 (add): duplicate identifier "sma"` because `add`'s naming key
  was renamed `as → name` (commit `feat: construction add names a node via name`).
  A consumer copying the visible example hits this immediately.
- Why friction: I had to reconstruct the correct schema (`"name"` not `"as"` for
  `add`; `"as"` retained only for `expose`) by cross-reading the commit log — a
  downstream consumer reading docs + the example corpus would be misled.
- Recommended action: plan / docwriter — document the op-script grammar in a
  durable doc (or `aura graph build --help`), and either refresh or clearly
  date-stamp the cycle-0088 corpus as pre-rename.

### [friction] Closing the loop to a *run* drops out of the data surface into hand-wired Rust
- Examples: mt_1, mt_4 (the Recorder wrapper).
- What happened: the serializable unit is the sink-less signal composite (a
  Recorder captures an `mpsc::Sender`, deliberately outside the round-trippable
  set). To *observe* a reloaded blueprint actually running, I had to drop to
  Rust, hand-author a wrapper `Composite` by raw index, attach a `Recorder`, and
  bootstrap. There is no `aura graph run <blueprint.json>` (cf. #28): the CLI can
  author and emit topology but cannot run an emitted blueprint or show its
  trace.
- Why friction: the milestone's "data → blueprint → **runnable**" is
  library-complete but, from the CLI alone, dead-ends at the emitted JSON; the
  reproduce step requires writing Rust and re-introducing a non-serializable
  sink. (Intended per the ledger, but a real seam a consumer feels.)
- Recommended action: plan — track under the #28/#159 build→consume edge (a CLI
  consumer that loads a blueprint, attaches a sink/tap, and runs).

### [spec_gap] "Canonical" form: CLI `graph build` appends a trailing newline the library emit omits
- Examples: mt_2 (`mt_2_blueprint.cli.json` 648 B vs `mt_1_rust_blueprint.json`
  647 B; last bytes `5d 7d 7d 0a` vs `7d 5d 7d 7d`).
- What happened: both paths emit the documented "canonical, versioned" blueprint,
  byte-identical in content, but the CLI frames it with a trailing `\n` and the
  library `blueprint_to_json` does not. The ledger calls the format canonical and
  lists **content-addressed topology identity in the manifest (#158)** as
  remaining — yet a content hash of the same blueprint differs by which surface
  emitted it.
- Why spec_gap: the ledger does not constrain whether the canonical artifact
  includes a trailing newline; I picked the reading "the JSON content is
  canonical, the CLI's newline is incidental framing," but the reading "the CLI's
  stdout *is* the canonical on-disk artifact" is equally plausible, and the two
  disagree by one byte — load-bearing once #158 content-addresses topology.
- Repro: `diff <(aura graph build < mt_2_sma_cross.ops.json)
  mt_1_rust_blueprint.json` → differs only by the final newline.
- Recommended action: ratify / tighten the ledger — state whether canonical
  includes a trailing newline and make the two emit paths byte-identical before
  #158 lands.

### [spec_gap] `Composite` (the loaded value) has no `Debug` / `PartialEq`
- Examples: mt_4 (a `match` had to avoid `{:?}`-ing the `Ok(Composite)` arm; a
  direct `assert_eq!` on two loaded composites is impossible).
- What happened: `blueprint_from_json` returns `Result<Composite, LoadError>`,
  but `Composite` derives neither `Debug` nor `PartialEq`, so `unwrap_err()`,
  `{:?}`, and composite-level equality assertions don't compile. A consumer must
  route every identity/round-trip assertion through `blueprint_to_json` (string
  compare), which is what I did.
- Why spec_gap: the ledger frames the blueprint as a first-class data **value**
  the World "owns, stores, mutates, structurally searches" — value-like
  ergonomics (compare, debug-print) are implied but unspecified, and the type as
  shipped supports neither.
- Recommended action: ratify / tighten — decide whether the public `Composite`
  value should carry `Debug`/`PartialEq` (string-via-JSON is the current
  contract); document the intended equality surface.

## Recommendation summary

| Finding | Class | Action |
|---|---|---|
| C24 round-trip bit-exact, both surfaces | working | carry-on |
| Build-free introspection (vocab/node/unwired) | working | carry-on |
| By-name / by-identifier forward-compat + fail-fast | working | carry-on |
| Construction surface undiscoverable from CLI help | friction | plan (#159) |
| Op-script schema undocumented; example stale on `as`→`name` | friction | plan / docwriter |
| Run-the-loop requires hand-wired Rust sink (no `graph run`) | friction | plan (#28/#159) |
| Trailing-newline divergence vs "canonical" / #158 | spec_gap | ratify / tighten |
| `Composite` value lacks `Debug`/`PartialEq` | spec_gap | ratify / tighten |