Aura/docs/specs/fieldtest-0010-aura-run.md

Fieldtest — cycle-0010 — 2026-06-04

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

Scope

Cycle 0010 is the Walking-skeleton milestone's closing seam (#8). It shipped two public surfaces:

1. aura_std::Recorder — a reusable recording-sink node. A pure consumer (output: vec![]) over kinds.len() input columns, holding an mpsc::Sender<(Timestamp, Vec<Scalar>)> as its out-of-graph destination (C7/C8/C22). Constructor: Recorder::new(kinds: &[ScalarKind], firing: Firing, tx) -> Self. Each fired cycle it sends (ctx.now(), row) with the newest value of every column; returns None and records nothing until all columns are warm. Supports all four base scalar kinds.
2. The aura run CLI (crate aura-cli, bin aura) — bootstraps a built-in sample harness (synthetic source → SMA(2)/SMA(4) → Sub → Exposure → SimBroker → two Recorder sinks), runs it deterministically (C1), and prints the cycle-0009 RunReport as canonical single-line JSON to stdout (exit 0). Any other or missing subcommand prints aura: usage: aura run to stderr, exit 2.

Tested from the public interface only (rustdoc, design ledger, glossary, project layout, the observable behaviour of the aura binary) — never crates/*/src. The CLI's own functions are pub(crate), so axis (a) drove the real binary as a subprocess. The build exercised: workspace cargo build from HEAD (target/debug/aura) for the binary; cargo run --manifest-path fieldtests/cycle-0010-aura-run/Cargo.toml for the two library-consumer fixtures.

Examples

fieldtests/cycle-0010-aura-run/c0010_1_cli_report.rs — aura run as a downstream CLI consumer (axis a)

• Spawns the real aura binary as a subprocess (path via $AURA_BIN, default the sibling workspace target/debug/aura); captures stdout/stderr/exit for run, no-args, an unknown subcommand, and run with a trailing junk arg.
• Fits the cycle's headline C14 move: a shell/jq/registry consumer parses the single-line JSON report and relies on the exit-code + determinism contract.
• Outcome: built (from HEAD) and ran; exit 0 with {manifest:{commit,params, window,seed,broker}, metrics:{total_pips,max_drawdown,exposure_sign_flips}}, byte-identical across two runs, clean stderr; bad-args → exit 2 + exact usage. Matched expected. Surfaced one spec_gap (trailing-arg leniency) and one friction (no JSON parser in the consumer).

fieldtests/cycle-0010-aura-run/c0010_2_recorder_sink.rs — aura_std::Recorder as a reusable sink block (axis b)

• Wires the shipped Recorder onto an Sma(3) output via the raw Harness::bootstrap(nodes, sources, edges) API (exactly as a C16 project would), runs 5 ticks, drains the mpsc::Receiver, asserts the recorded (Timestamp, Vec<Scalar>) rows against the rustdoc warm-up model.
• Fits the cycle's first deliverable: Recorder used the way a downstream project consumes it, not the way the CLI's built-in harness does.
• Outcome: built and ran first try; rows [(3,[20.0]),(4,[30.0]),(5,[40.0])] exactly matched the hand model (no warm-up rows, one row per warm cycle, ts = ctx.now()). Matched expected.

fieldtests/cycle-0010-aura-run/c0010_3_recorder_four_kind.rs — Recorder four-kind support (axis c)

• Authors a tiny custom 3-field producer node (i64 counter / bool even? / timestamp now) in Rust (C17), wires a multi-column Recorder::new(&[I64, Bool, Timestamp], …) over it via three field-wise edges, runs, drains, asserts the recorded Scalars are I64/Bool/Ts.
• Fits the cycle's four-kind claim: the CLI only ever exercises the f64 path, so the non-f64 kinds are verifiable from the public rustdoc alone only this way.
• Outcome: built (after one trivial authoring fix — see working finding) and ran; rows matched [(100,[I64(1),Bool(false),Ts(100)]),(200,[I64(2),Bool(true), Ts(200)]),(300,[I64(3),Bool(false),Ts(300)])] exactly. Matched expected.

Findings

[working] aura run end-to-end: clean single-line JSON, deterministic, jq-parseable

• Example: c0010_1.
• What happened: aura run → exit 0, one line of JSON on stdout, empty stderr. The documented {manifest, metrics} nesting and all eight documented fields (commit, params, window, seed, broker; total_pips, max_drawdown, exposure_sign_flips) are present. Two runs are byte-identical (C1). Piped through jq, .metrics.total_pips is a number, .manifest.params | keys resolves — a downstream C18/shell consumer can author against it.
• Why working: the headline C14 "run a sim, emit structured metrics" move is reachable from a real binary, from rustdoc alone, on the first try, with the determinism and shape the ledger promises.
• Recommended action: carry-on.

[working] Bad-args contract exact and stdout-clean

• Example: c0010_1.
• What happened: aura (no args) and aura play (unknown) each → exit 2, stderr exactly aura: usage: aura run\n, stdout empty (0 bytes). A consumer keying off exit code never sees a half-report on stdout.
• Why working: matches the cycle_scope contract precisely; the stdout/stderr split is clean (errors never contaminate the machine-readable channel).
• Recommended action: carry-on.

[working] Recorder as a reusable sink: warm-up + row shape match rustdoc

• Example: c0010_2.
• What happened: a downstream wiring of Recorder over Sma(3) via raw Harness::bootstrap, drained from mpsc::Receiver, produced exactly the rows the rustdoc model predicts — no warm-up rows, one one-element Vec<Scalar> per warm cycle, each tagged ctx.now(). The constructor signature on the surface (&[ScalarKind], Firing, Sender) is enough to author against with no source reading.
• Why working: the cycle's primary deliverable is reachable and correct from the public interface as a standalone consumer block (not just inside the CLI).
• Recommended action: carry-on.

[working] Recorder four-kind claim holds on a non-f64 column set

• Example: c0010_3.
• What happened: a Recorder over [I64, Bool, Timestamp] recorded Scalar::I64 / Scalar::Bool / Scalar::Ts values verbatim, matching the rustdoc's four-kind claim — a path the CLI never exercises. The trivial authoring miss (FieldSpec.name is &'static str, I wrote .to_string()) was caught by the compiler with an exact fix-it; the public FieldSpec rustdoc states pub name: &'static str plainly. No source reading needed.
• Why working: the four-kind claim, otherwise unverifiable from the CLI, is empirically true; the supporting types (FieldSpec, Scalar, multi-edge field-wise binding) author cleanly from rustdoc.
• Recommended action: carry-on.

[spec_gap] aura run <trailing-arg> is accepted (exit 0), not rejected

• Example: c0010_1.
• What happened: aura run extra-garbage printed the full JSON report and exited 0 — trailing args after run are silently ignored. The cycle_scope states "Any other or missing subcommand prints aura: usage: aura run to stderr and exits 2."
• Why spec_gap: run <junk> is neither a clean run nor a different subcommand, so the contract does not unambiguously cover it. The binary picked the lenient reading (key only on the first arg being run, ignore the rest); the strict reading (any extra/unexpected token → usage + exit 2) is equally plausible and is what a user who typos aura run --sweep would expect (they'd get a silent full run instead of a hint). I asserted the lenient reading the binary exhibits and recorded the ambiguity rather than treating it as a bug.
• Recommended action: ratify (document the arg-parse contract as "first-arg-keyed, trailing args ignored") or tighten — decide whether unexpected trailing tokens should be a usage error. A one-line note on the intended arg contract in the aura crate rustdoc closes it.

[friction] Verifying the documented JSON nesting needs a hand-rolled walker

• Example: c0010_1.
• What happened: the consumer crate is zero-external-dependency by design (no serde/serde_json), and RunReport exposes only to_json() -> String with no typed accessor. To confirm the documented {manifest, metrics} nesting and field presence, the fixture hand-walks the string (find("\"key\":")) — a consumer authoring real assertions against the report shape either pulls in a JSON dep or writes this dance.
• Why friction: the task (confirm the structured-face shape) completed, but the surface offered no programmatic handle on the report's structure short of re-parsing the string the engine just serialized. The cycle's C14 framing ("machine-readable") implies a consumer can inspect the structure, not only re-stringify it.
• Recommended action: plan (tidy) — consider a minimal typed read-path (e.g. RunReport already round-trips its own fields; exposing the structured values, or shipping a tiny documented parse helper, would let consumers assert without a serde dep). Low priority; the JSON is correct and jq-parseable for shell consumers today.

Recommendation summary

Finding	Class	Action
aura run end-to-end JSON + determinism	working	carry-on
Bad-args contract exact + stdout-clean	working	carry-on
Recorder reusable sink matches rustdoc	working	carry-on
Recorder four-kind claim holds	working	carry-on
aura run <trailing-arg> accepted	spec_gap	ratify / tighten the design ledger
JSON nesting needs a hand-rolled walker	friction	plan (tidy)