Aura/docs/specs/fieldtest-0006-substrate.md

Fieldtest — cycle-0006 (sink recording) — 2026-06-04

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

Scope

Cycle 0006 settled "a sink is a role, not a type": recording is done by an ordinary node in its eval, pushing a record to a destination it holds as a field (channel / buffer / chart handle) — an out-of-graph side effect. Three substrate changes shipped: (1) Ctx::now() -> Timestamp (a Copy accessor so a recording node can causally stamp each record with the cycle timestamp); (2) the old single observe: usize recording affordance was removed — Harness::bootstrap dropped its 4th parameter and Harness::run returns () (retention is owned by whoever holds the recording node's destination's read end); (3) the run loop is otherwise an unchanged topological router. No Sink type, no SinkHandler trait, no engine sink registry. The fieldtest exercised this from a standalone downstream consumer crate (fieldtests/cycle-0006-substrate/) that path-depends on the engine crates and uses only the public surface (rustdoc + specs + ledger).

Examples

fieldtests/cycle-0006-substrate/c0006_1_custom_node_now.rs — custom recording node via the Node contract

• Authors a Recorder node from scratch: schema() declares one f64 input + output: vec![] (pure consumer); eval reads the typed window, calls ctx.now(), sends (now, value) out of graph, returns None. Wired as source -> SMA(2) -> Recorder.
• Fits the "author a custom node incl. Ctx::now()" axis.
• Outcome: built, ran, matched expected [(20,11.0),(30,13.0),(40,15.0)] on first try.

fieldtests/cycle-0006-substrate/c0006_2_fanout_dag.rs — multi-stage fan-out / fan-in DAG, bootstrapped + run

• source -> {SMA(2), SMA(4)} -> Sub(fast-slow) -> Recorder. Uses the post-0006 3-arg bootstrap (no observe) and run() -> (); retention via the channel.
• Fits the "fan-out/fan-in DAG" and "bootstrap arity / run returns ()" axes.
• Outcome: built, ran, matched [(4,2.0),(5,2.0),(6,2.0)] on first try.

fieldtests/cycle-0006-substrate/c0006_3_multi_sink_record.rs — many interior streams, one run (headline)

• Two independent Recorder nodes tap SMA(2) and SMA(4) in one harness, draining to two channels into Vec<(Timestamp, Vec<Scalar>)> (the spec's stated drain shape). Asserts both streams correct AND of different length (sparse, timestamped, no shared cycle index).
• Fits the "record multiple distinct interior streams of one run" axis (the cycle headline; impossible before 0006).
• Outcome: built, ran, both streams matched (4 vs 2 records) on first try.

fieldtests/cycle-0006-substrate/c0006_4_determinism.rs — byte-identical recorded output across two runs

• Two fresh harnesses, identical input through {SMA(2),SMA(4)} -> Sub -> Recorder; compares recorded f64::to_bits() and timestamps for true byte-identity.
• Fits the "verify determinism (C1)" axis.
• Outcome: built, ran, byte-identical on first try.

fieldtests/cycle-0006-substrate/c0006_5_reject_mismatch.rs — mis-wired recording edge rejected

• An i64 producer field bound into a recorder's f64 slot; asserts bootstrap returns BootstrapError::KindMismatch { producer: I64, consumer: F64 } before any data flows. Correct behaviour here is rejection.
• Fits the recording axis from the failure side (recording adds no new wiring hole).
• Outcome: built, ran, rejected with the documented error on first try.

Findings

[working] Custom recording node + Ctx::now() is natural and correct

• Examples: c0006_1, c0006_3, c0006_5.
• What happened: implementing Node for a user type, declaring output: vec![], reading ctx.f64_in(0), calling ctx.now(), performing an mpsc side effect, and returning None all worked verbatim from the rustdoc signatures and the 0006 spec's worked example. Ctx::now() returned the present cycle's timestamp on every fired cycle; recorded streams were sparse + timestamped exactly as documented.
• Why working: the new surface was reached for, used as designed, and correct on the first run with no surprises.
• Recommended action: carry-on.

[working] The cycle headline — many interior streams from one run

• Example: c0006_3.
• What happened: two recorders tapped two different-rate indicators in one harness; drained streams were individually correct and independently lengthed (4 vs 2). The thing the cycle exists to enable (more than one recorded stream per run) works.
• Why working: this is the acceptance evidence the spec promised, reproduced empirically by a downstream consumer.
• Recommended action: carry-on.

[working] Post-0006 Harness API (3-arg bootstrap, run() -> ()) + determinism + rejection

• Examples: c0006_2 (3-arg bootstrap, run returns ()), c0006_4 (byte-identical re-run), c0006_5 (KindMismatch rejection).
• What happened: the shrunk surface is exactly as the rustdoc/ledger state; a consumer holding the channel's read end owns retention with no engine help. Determinism held bit-exactly; a mis-wired recorder edge was rejected at bootstrap.
• Why working: the substrate shrink introduced no regression and no forbidden failure class (C1/C7 hold from the consumer's vantage).
• Recommended action: carry-on.

[friction] Standalone consumer crate fights the workspace resolver

• Example: all (the fixture crate's Cargo.toml).
• What happened, verbatim: error: current package believes it's in a workspace when it's not: ... this may be fixable by adding ... Alternatively, to keep it out of the workspace, add ... an empty [workspace] table to the package's manifest.
• Resolution taken: added an empty [workspace] table to the fixture manifest (the keep-it-out option Cargo itself lists; no edit to the engine root manifest). After that, all five binaries built and ran.
• Why friction: a real downstream research project (C16: "a project is always a Rust crate" depending on aura) created inside or beside this repo hits the same wall. The task completed, but only after a non-obvious one-liner. This is the resolver-fight the carrier explicitly asked be recorded.
• Recommended action: plan — note in onboarding/docs (or the future aura new scaffolder, an open ledger thread) that a project crate needs its own [workspace] root when nested under the engine repo.

[friction] Recorder boilerplate is hand-rewritten per author

• Examples: all five (each redeclares a near-identical Recorder: a tx field, a schema with output: vec![], an eval that reads inputs by kind, sends, returns None).
• What happened: the cycle deliberately ships no Recorder/sink library type (C9 — no speculative surface; the spec calls Recorder "this cycle's test-local fixture, not a shipped type"). So every consumer writes the channel-sink dance, including the per-kind match to pull the newest value of each input.
• Why friction: it is redundant across authors and the 0006 spec implies a real author writes "their ChartSink, their RegistrySink" each from scratch. The cycle's scope intentionally excludes a library sink, so this is expected friction, not a bug — but it is the natural candidate for the next tidy.
• Recommended action: plan — consider an aura-std channel/buffer recording block (or a small Recorder helper) once a second consumer confirms the shape, so the boilerplate is written once. Not urgent; C9 correctly kept it out of this cycle.

[spec_gap] No public statement of the canonical sink declaration / Some-with-empty-output

• Examples: c0006_1, c0006_3, c0006_5 (all declare output: vec![]).
• What happened: I needed the canonical way to declare a no-output (pure consumer) node. The public surface (rustdoc for NodeSchema/Node; the 0006 spec) shows output: vec![] only implicitly inside the worked example's prose ("a node with output: vec![]"); neither the rustdoc nor the ledger C8 entry states outright that an empty output vec is the sink declaration, nor what the engine does if a node with output: vec![] nonetheless returns Some(row) (ignored? debug-asserts on a width mismatch? UB?). I picked output: vec![] + return None — it matched the worked example and ran correctly — but the "what if a sink returns Some" corner is unconstrained by the public surface, and I did not probe it (probing the engine's reaction would require reading implementation source, which ends the test).
• Why spec_gap: the design surface is silent on a corner a downstream author can hit by mistake; the natural reading worked but another (a sink that records and forwards via output: vec![] + Some) is left undefined publicly.
• Recommended action: tighten the design ledger / rustdoc — state explicitly that output: vec![] is the pure-consumer declaration and define the contract for a Some return paired with an empty output (reject at bootstrap, debug-assert, or documented-ignore). The C8 "both" case is documented for a node with a real output port; the empty-output-plus-Some mistake is not.

Recommendation summary

Finding	Action
[working] custom node + Ctx::now()	carry-on
[working] many interior streams, one run (headline)	carry-on
[working] 3-arg bootstrap / run()->() / determinism / rejection	carry-on
[friction] consumer crate fights workspace resolver	plan
[friction] recorder boilerplate rewritten per author	plan
[spec_gap] canonical sink declaration / Some-with-empty-output undefined	tighten the design ledger