Aura/fieldtests/cycle-0088-construction-op-script/FINDINGS.md

# Fieldtest — cycle 0088 (construction op-script service, #157) — 2026-06-29

**Status:** Triaged 2026-06-29 — filed to the forward queue (see Triage outcome)
**Author:** fieldtester (dispatched by fieldtest skill); triaged by orchestrator

> **Corpus refreshed 2026-06-30 (#163)** to replay against the current binary.
> Two drifts had accumulated since this run recorded the fixtures: `add`'s
> naming key was renamed `as` -> `name` (commit `3c4b667`; `expose` keeps `as`),
> and the dataflow-cycle bug below was fixed (`1652042`, closes #161). The `.json`
> inputs now use `name` for `add`; `c0088_3m_two_cycle` is a rejection fixture
> (`c0088_3m.err` carries the cycle-rejection message; the gap-era cyclic-blueprint
> golden was removed). The findings below are preserved as written at fieldtest time.

## Scope
Cycle 0088 shipped the **construction op-script service** (#157, C24): two CLI
subcommands over a declarative JSON op-list. `aura graph build` reads an op-list
from stdin, replays it op-by-op through the `aura-std` node vocabulary, and on
success prints a `format_version:1` #155 blueprint to stdout; on the first failing
op it prints `op N (kind): cause` (or `finalize: cause`) to stderr and exits
non-zero. `aura graph introspect --vocabulary | --node <T> | --unwired` answers,
build-free: the node-type roster, one type's input ports / output fields / param
paths, and (reading a partial op-list) the still-open interior slots. This field
test exercised the surface purely as a downstream consumer authoring topology as
data — public interface only (the C24/C17/C19/C23 ledger + the CLI's own output);
no implementation source read. Binary under test: freshly built `target/debug/aura`
(`cargo build --workspace`, nothing to recompile at HEAD).

## Examples
### fieldtests/cycle-0088-construction-op-script/c0088_1_sma_crossover.json — discover-then-author an SMA-crossover bias
- Used `introspect --vocabulary` (22 types) then `introspect --node SMA|Sub|Bias`
  to learn ports/kinds, then hand-wrote a 10-op script: one `price` source → two
  SMAs (lengths 2/4) → `Sub` → `Bias`, expose `bias.bias`.
- Fits scope: exercises `source`, `add`+`bind`, `feed` (fan-out into two slots),
  `connect`, `expose` — the full op vocabulary in one realistic signal graph.
- Outcome: **built, ran, matched expected.** Emitted a `format_version:1` blueprint
  with the expected 4 nodes / 3 edges / 1 input_role / 1 output
  (`c0088_1_blueprint.out.json`). First try, no diagnostics.

### fieldtests/cycle-0088-construction-op-script/c0088_2_partial.json (+ _completed.json) — author with the --unwired helper
- Wrote a deliberately partial doc (left `sub.rhs` and `bias` unconnected), ran
  `introspect --unwired`, finished wiring per its report, built.
- Fits scope: the cycle's headline build-free authoring aid.
- Outcome: **worked.** `--unwired` reported `sub.rhs:F64` / `bias.signal:F64`
  by-identifier with kinds; the completed doc built to a #155 blueprint;
  `--unwired` on the completed doc returned empty (exit 0) — a reliable
  "am I done?" check.

### fieldtests/cycle-0088-construction-op-script/c0088_3*.json — error ergonomics (15 fixtures)
- Provoked the realistic hand-author mistakes: bad node type, wrong-kind connect,
  wrong output field, unknown node id, double-wired slot, duplicate id, bad bind
  kind, bad expose field, unknown role, bad feed port, left-open slot, dataflow
  cycle (self-loop + explicit 2-cycle), unfed role, no-expose, naive/untyped bind,
  lowercase kind.
- Fits scope: judges whether `op N (kind): cause` tells you *where* and *what*.
- Outcome: **eager per-op messages are excellent** (by-identifier, right op index);
  three message-quality friction points and one acceptance gap surfaced (below).

### Round-trip sense-check (Task 4)
- Piped `c0088_1_blueprint.out.json` into `aura graph`; compared to bare `aura graph`.
- Outcome: byte-**identical** — `aura graph` ignores stdin and renders a hard-wired
  sample. No CLI subcommand consumes an emitted #155 blueprint (see G2).

## Findings

### [working] Discover-then-author round-trips cleanly through the CLI
- Examples: c0088_1, all `introspect` runs.
- `introspect --vocabulary` lists 22 node types; `introspect --node SMA` prints
  `in series:F64 / out value:F64 / param length:I64` — the exact dotted-port names
  (`fast.series`, `fast.value`) and capitalized kinds the op-script consumes. An
  author can go vocabulary → ports → op-script → `format_version:1` blueprint with
  no source reading. This is the core promise of C24's data-authoring surface and
  it holds.
- Recommended action: carry-on.

### [working] `--unwired` is a precise, by-identifier authoring aid
- Examples: c0088_2_partial / _completed.
- Reports open interior slots as `node.port:Kind` (`sub.rhs:F64`,
  `bias.signal:F64`) and returns empty on a fully-wired doc. Exactly the
  finish-the-wiring loop a hand-author wants; the kinds double as a connect hint.
- Recommended action: carry-on.

### [working] Eager per-op diagnostics name the op and the identifier
- Examples: c0088_3a–h, 3j, 3k.
- Verbatim wins: `op 1 (add): unknown node type "Smaa"`; `op 4 (connect): kind
  mismatch g.value -> fast.series (producer Bool, consumer F64)`; `op 4 (connect):
  node "fast" has no output field "output"`; `op 4 (connect): unknown node
  identifier "fst"`; `op 6 (connect): slot sub.lhs already wired`; `op 2 (add):
  duplicate identifier "fast"`; `op 2 (feed): unknown role "pryce"`; `op 2 (feed):
  node "fast" has no input port "serie"`. Every one names the op index and speaks
  by-identifier — you can fix without counting. Lowercase `kind:"f64"` even
  self-documents: `unknown variant 'f64', expected one of 'I64','F64','Bool',
  'Timestamp'`.
- Recommended action: carry-on.

### [bug] `graph build` accepts a dataflow cycle and reports success
- Examples: c0088_3i_unfed_role (self-loop), c0088_3m_two_cycle.
- `aura graph build < c0088_3m_two_cycle.json` → **exit 0**, emits a blueprint
  whose edges are `{from:0,to:1,slot:0},{from:1,to:0,slot:0}` — a combinational
  2-cycle. A self-loop (`fast.value → fast.series`, edge `{from:0,to:0}`) is
  likewise accepted. C9 / domain-invariant 5: "The graph is a DAG; the only
  feedback path is an explicit delay/state node." The construction service's gate
  set (kind, interior-slot totality, param-namespace injectivity, root-role
  boundness) omits acyclicity, so it green-lights a non-runnable blueprint and
  calls it a success. Caveat (cadence, unverifiable as a CLI consumer): acyclicity
  may be intended as a bootstrap-time (compile-to-`FlatGraph`) gate — but the CLI
  exposes no compile/run path for an emitted blueprint (see G2), so a CLI consumer
  gets no signal at all that the graph is not a DAG.
- Repro: `aura graph build < fieldtests/cycle-0088-construction-op-script/c0088_3m_two_cycle.json; echo $?` → `0`.
- Recommended action: debug.

### [friction] The holistic `finalize` error speaks raw indices, breaking the by-identifier surface
- Examples: c0088_2_partial.
- `aura graph build < c0088_2_partial.json` → `aura: finalize: UnconnectedPort
  { node: 2, slot: 1 }`. The whole op-script is authored by-identifier, and the
  sibling `introspect --unwired` reports the *same* open slot as `sub.rhs:F64` —
  so the identifier mapping demonstrably exists. The build finalize path drops to
  raw `node`/`slot` indices (and Debug-struct form), forcing the author to count
  nodes (0=fast,1=slow,2=sub) and slots to decode it.
- Why friction: task completed (the error is non-zero and correct) but the surface
  forced an index-counting dance the by-identifier design implies should be gone.
- Recommended action: plan — route finalize faults through the same by-identifier
  formatter `--unwired` already uses.

### [friction] Bind-kind-mismatch leaks the Debug struct, inconsistent with the connect message
- Examples: c0088_3g_bad_bind_kind.
- `op 1 (add): bad param on fast: KindMismatch { param: "length", expected: I64,
  got: F64 }` — the `KindMismatch { … }` is raw `#[derive(Debug)]`, whereas the
  parallel connect mismatch is hand-phrased prose (`producer Bool, consumer F64`).
  Two kind-mismatch errors, two registers.
- Recommended action: plan — phrase the bind mismatch like the connect one.

### [friction] The typed-Scalar bind form is not discoverable from introspection
- Examples: c0088_3n_naive_bind.
- `introspect --node SMA` shows `param length:I64` but never that a bind *value*
  must be wrapped `{"I64": 2}`. The natural first guess `"bind":{"length":2}`
  fails with a generic serde error: `invalid op-list: invalid type: integer 2,
  expected string or map at line 4 column 2` — correct location, no domain hint
  about the `{"I64": 2}` shape. (Capitalized `kind` *is* discoverable — both from
  `introspect --node` output and the self-documenting lowercase-kind error.)
- Recommended action: plan/doc — show the bind-value form in `introspect --node`
  (e.g. `param length:I64  (bind {"I64": <v>})`) or hint it in the serde error.

### [spec_gap] The construction surface is undiscoverable from the CLI
- Examples: bare `aura`, `aura --help`, `aura graph build --help`.
- Neither `aura` (no args, exit 2), `aura --help`, nor any public doc (glossary,
  project-layout) mentions `aura graph build` or `aura graph introspect`. The
  top-level usage string lists only the bare `aura graph` (HTML-render) arm. The
  subcommands appear *only* in the C24 ledger Status prose. `aura graph build
  --help` and `aura graph introspect --help` both print the giant top-level usage
  at exit 0 (the `--help` token is swallowed); there is no per-subcommand help and
  no statement anywhere of the op-list document shape. A genuine new user has no
  in-CLI route to learn the surface exists or how a document is shaped.
- Why spec_gap: the surface shipped without a discovery path; the ledger is silent
  on whether the CLI usage should advertise it. I read the surface only because the
  carrier named the subcommands.
- Recommended action: tighten the design ledger / plan — add `graph build` /
  `graph introspect` to the usage string and a `build --help` documenting the
  op-list shape (the op kinds, the typed-Scalar bind, capitalized kind).

### [spec_gap] No CLI consumer for the emitted #155 blueprint — the round-trip dead-ends
- Examples: Task 4 (pipe c0088_1_blueprint into `aura graph`).
- `graph build` emits a blueprint to stdout, but no subcommand reads one back:
  `aura graph` ignores stdin and renders a hard-wired sample (verified
  byte-identical with and without a piped blueprint), and no `aura run` /
  `graph render` accepts a blueprint file. C24 promises topology is a value
  "constructed, generated, mutated, serialized for reproduction, and (optionally)
  rendered"; the load path is realised only at the library level
  (`blueprint_from_json`, cycle 0087). A pure-CLI consumer can author and build
  topology-as-data but cannot run, render, or reload-validate it through the CLI —
  which is also why the cycle bug (above) is undiscoverable. Equally plausible
  reading: `build` is intentionally an emit-only producer feeding a library/World
  consumer — hence spec_gap, not bug.
- Recommended action: ratify the emit-only scope, or planner — add a CLI edge that
  consumes a #155 blueprint (render/run/validate). C24 Status already tracks #159
  (retire hard-wired harnesses); note the missing build→consume edge there.

### [spec_gap] The validity floor of `graph build` is unstated
- Examples: c0088_3i_unfed_role, c0088_3l_no_expose.
- Beyond the cycle (bug above), build accepts at exit 0: an unfed `source` role
  (emitted as `"targets":[]` — a dead role kept in the blueprint) and a graph with
  no `expose`/output at all (no `output` key emitted). The ledger names the gates
  build *does* enforce (kind, interior-slot totality, injectivity, root-role
  boundness) but not the minimal well-formedness it *guarantees* — so a consumer
  can't tell whether a dead role / output-less graph is intended-valid or a
  silently-accepted slip.
- Recommended action: ratify (state the validity floor — what `build` does/does not
  promise) or tighten.

## Recommendation summary
| Finding | Class | Action |
|---|---|---|
| Discover-then-author round-trips cleanly | working | carry-on |
| `--unwired` precise by-identifier aid | working | carry-on |
| Eager per-op diagnostics name op + identifier | working | carry-on |
| `graph build` accepts a dataflow cycle | bug | debug |
| `finalize` error speaks raw indices | friction | plan |
| Bind-kind-mismatch leaks Debug struct | friction | plan |
| Typed-Scalar bind form not discoverable | friction | plan / doc |
| Construction surface undiscoverable from CLI | spec_gap | tighten ledger / plan |
| No CLI consumer for emitted blueprint | spec_gap | ratify / plan |
| Validity floor of `graph build` unstated | spec_gap | ratify / tighten |

## Triage outcome (orchestrator, 2026-06-29)

The cycle bug was reproduced directly before filing. Findings routed to the forward queue:

| Finding | Disposition |
|---|---|
| `graph build` accepts a dataflow cycle (+ validity-floor: unfed role, no-`expose`) | filed **#161** (`bug`) — reject cyclic graphs, DAG invariant 5; validity floor decided alongside. RED-first via debug. |
| `finalize` raw indices + bind-mismatch Debug leak + typed-Scalar bind undiscoverable | filed **#162** (polish) — three message-quality defects on the by-identifier surface. |
| Construction surface undiscoverable from the CLI | commented on **#159** (CLI usage/help rework) — advertise the subcommands + per-subcommand `--help`. |
| No CLI consumer for the emitted #155 blueprint (round-trip dead-end) | commented on **#28** (render a consumer's OWN graph) — the build→consume CLI edge. |
| Three `working` findings | carry-on — the happy path, `--unwired`, and eager per-op diagnostics hold. |