fieldtest: cycle-0010 — 3 examples, 6 findings
Public-interface-only field test of the walking-skeleton closing seam (#8): the `aura run` CLI and the reusable aura-std::Recorder sink. A standalone consumer crate (path-deps on the three engine crates, as a C16 project would) drives the real binary as a subprocess and wires Recorder via the raw Harness::bootstrap API. Examples (all built from HEAD and ran green): - c0010_1: drive `aura run` as a downstream CLI/jq consumer — single-line JSON report, byte-identical across two runs (C1), bad-args → exit 2 + exact usage on stderr with empty stdout. - c0010_2: wire Recorder onto Sma(3) via raw bootstrap, drain the mpsc::Receiver — rows match the rustdoc warm-up model exactly. - c0010_3: Recorder over [I64, Bool, Timestamp] — the four-kind claim (never exercised by the CLI's f64-only path) holds, verified from rustdoc alone. Findings: 0 bugs, 4 working, 1 spec_gap, 1 friction. - [spec_gap] `aura run <trailing-arg>` is accepted (exit 0), not rejected — the arg parse keys only on the first token being `run` and ignores the rest. The cycle_scope's "any other or missing subcommand -> exit 2" does not unambiguously cover `run <junk>`; the binary chose the lenient reading. Tracked for a ratify-or-tighten decision. - [friction] verifying the documented {manifest, metrics} JSON nesting needs a hand-rolled string walker — the zero-dep consumer has only to_json() and no typed read-path. Low-priority tidy. Both non-bug findings filed to the forward queue; neither blocks the cycle.
This commit is contained in:
+30
@@ -0,0 +1,30 @@
|
||||
# This file is automatically @generated by Cargo.
|
||||
# It is not intended for manual editing.
|
||||
version = 4
|
||||
|
||||
[[package]]
|
||||
name = "aura-core"
|
||||
version = "0.1.0"
|
||||
|
||||
[[package]]
|
||||
name = "aura-engine"
|
||||
version = "0.1.0"
|
||||
dependencies = [
|
||||
"aura-core",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "aura-std"
|
||||
version = "0.1.0"
|
||||
dependencies = [
|
||||
"aura-core",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "c0010-fieldtest"
|
||||
version = "0.0.0"
|
||||
dependencies = [
|
||||
"aura-core",
|
||||
"aura-engine",
|
||||
"aura-std",
|
||||
]
|
||||
@@ -0,0 +1,33 @@
|
||||
# Standalone downstream-consumer crate for the cycle-0010 fieldtest
|
||||
# (aura-std::Recorder + the `aura run` CLI).
|
||||
#
|
||||
# Like the cycle-0007/0008/0009 fixtures, this is NOT a member of the aura
|
||||
# workspace — it path-depends on the engine crates exactly as a real research
|
||||
# project (C16) would, and is built/run via
|
||||
# `cargo run --manifest-path fieldtests/cycle-0010-aura-run/Cargo.toml --bin <name>`
|
||||
# so HEAD source is always what runs.
|
||||
# Empty [workspace] table: marks this fixture crate as its OWN workspace root.
|
||||
[workspace]
|
||||
|
||||
[package]
|
||||
name = "c0010-fieldtest"
|
||||
version = "0.0.0"
|
||||
edition = "2024"
|
||||
publish = false
|
||||
|
||||
[dependencies]
|
||||
aura-core = { path = "../../crates/aura-core" }
|
||||
aura-engine = { path = "../../crates/aura-engine" }
|
||||
aura-std = { path = "../../crates/aura-std" }
|
||||
|
||||
[[bin]]
|
||||
name = "c0010_1_cli_report"
|
||||
path = "c0010_1_cli_report.rs"
|
||||
|
||||
[[bin]]
|
||||
name = "c0010_2_recorder_sink"
|
||||
path = "c0010_2_recorder_sink.rs"
|
||||
|
||||
[[bin]]
|
||||
name = "c0010_3_recorder_four_kind"
|
||||
path = "c0010_3_recorder_four_kind.rs"
|
||||
@@ -0,0 +1,112 @@
|
||||
//! Fieldtest c0010 #1 — `aura run` as a downstream CLI consumer (axis a).
|
||||
//!
|
||||
//! Question under test: invoking the REAL `aura` binary the way the deferred
|
||||
//! C18 registry or a shell/jq pipeline would — capture stdout, treat it as the
|
||||
//! single-line canonical JSON report (manifest + metrics) — does the documented
|
||||
//! C14 machine-readable face hold? Specifically:
|
||||
//! - `aura run` -> exit 0, one line of JSON on stdout, nothing on stderr;
|
||||
//! - the JSON parses as an object with {manifest, metrics} nesting (rustdoc:
|
||||
//! "prints the run's metrics + manifest as canonical JSON to stdout");
|
||||
//! - two runs are byte-identical (C1 determinism, pinned on the surface);
|
||||
//! - missing / unknown subcommand -> exit 2 + `aura: usage: aura run` on
|
||||
//! stderr, NOTHING on stdout (cycle_scope bad-args contract).
|
||||
//!
|
||||
//! This consumer does NOT read crates/*/src. It only runs the binary and
|
||||
//! inspects observable behaviour. The binary path comes from $AURA_BIN (a CI
|
||||
//! consumer would point this at the built artefact); we default to the
|
||||
//! sibling workspace target/debug/aura so `cargo run` works out of the box.
|
||||
|
||||
use std::process::Command;
|
||||
|
||||
fn aura_bin() -> String {
|
||||
if let Ok(p) = std::env::var("AURA_BIN") {
|
||||
return p;
|
||||
}
|
||||
// Default: the workspace debug artefact, two levels up from this crate.
|
||||
let here = env!("CARGO_MANIFEST_DIR");
|
||||
format!("{here}/../../target/debug/aura")
|
||||
}
|
||||
|
||||
/// A bare-bones JSON value walker — enough for a consumer to confirm the
|
||||
/// documented {manifest, metrics} shape WITHOUT a serde dependency (the
|
||||
/// workspace is deliberately zero-external-dependency; a downstream consumer
|
||||
/// would reach for serde_json or jq, but here we only assert structural facts
|
||||
/// the rustdoc promises). Returns the substring value following `"key":`.
|
||||
fn raw_value_after<'a>(json: &'a str, key: &str) -> Option<&'a str> {
|
||||
let needle = format!("\"{key}\":");
|
||||
let idx = json.find(&needle)? + needle.len();
|
||||
Some(&json[idx..])
|
||||
}
|
||||
|
||||
fn run_capture(args: &[&str]) -> (String, String, i32) {
|
||||
let out = Command::new(aura_bin())
|
||||
.args(args)
|
||||
.output()
|
||||
.unwrap_or_else(|e| panic!("failed to spawn {}: {e}", aura_bin()));
|
||||
(
|
||||
String::from_utf8_lossy(&out.stdout).to_string(),
|
||||
String::from_utf8_lossy(&out.stderr).to_string(),
|
||||
out.status.code().unwrap_or(-1),
|
||||
)
|
||||
}
|
||||
|
||||
fn main() {
|
||||
println!("using binary: {}", aura_bin());
|
||||
|
||||
// --- `aura run`: exit 0, one JSON line on stdout, clean stderr ---
|
||||
let (stdout, stderr, code) = run_capture(&["run"]);
|
||||
println!("`aura run` exit={code}");
|
||||
println!("`aura run` stdout = {stdout:?}");
|
||||
assert_eq!(code, 0, "aura run must exit 0");
|
||||
assert!(stderr.is_empty(), "aura run must not write stderr, got {stderr:?}");
|
||||
|
||||
let line = stdout.trim_end_matches('\n');
|
||||
assert!(!line.contains('\n'), "report must be a single line of JSON");
|
||||
assert!(line.starts_with('{') && line.ends_with('}'), "report is a JSON object");
|
||||
|
||||
// Documented nesting: a `manifest` object and a `metrics` object.
|
||||
assert!(raw_value_after(line, "manifest").is_some(), "manifest key present");
|
||||
assert!(raw_value_after(line, "metrics").is_some(), "metrics key present");
|
||||
// Documented manifest fields (RunManifest rustdoc: commit/params/window/seed/broker).
|
||||
for k in ["commit", "params", "window", "seed", "broker"] {
|
||||
assert!(raw_value_after(line, k).is_some(), "manifest.{k} key present");
|
||||
}
|
||||
// Documented metrics fields (RunMetrics rustdoc).
|
||||
for k in ["total_pips", "max_drawdown", "exposure_sign_flips"] {
|
||||
assert!(raw_value_after(line, k).is_some(), "metrics.{k} key present");
|
||||
}
|
||||
|
||||
// --- determinism: two runs byte-identical (C1) ---
|
||||
let (stdout2, _, _) = run_capture(&["run"]);
|
||||
assert_eq!(stdout, stdout2, "two runs must be byte-identical (C1)");
|
||||
println!("determinism: two runs byte-identical OK");
|
||||
|
||||
// --- bad-args contract: missing subcommand ---
|
||||
let (out, err, code) = run_capture(&[]);
|
||||
println!("`aura` (no args) exit={code} stderr={err:?}");
|
||||
assert_eq!(code, 2, "no subcommand must exit 2");
|
||||
assert!(out.is_empty(), "no subcommand must print nothing on stdout, got {out:?}");
|
||||
assert_eq!(err.trim_end(), "aura: usage: aura run", "exact usage line on stderr");
|
||||
|
||||
// --- bad-args contract: unknown subcommand ---
|
||||
let (out, err, code) = run_capture(&["play"]);
|
||||
println!("`aura play` exit={code} stderr={err:?}");
|
||||
assert_eq!(code, 2, "unknown subcommand must exit 2");
|
||||
assert!(out.is_empty(), "unknown subcommand must print nothing on stdout");
|
||||
assert_eq!(err.trim_end(), "aura: usage: aura run", "exact usage line on stderr");
|
||||
|
||||
// --- probe: trailing junk after `run`. The cycle_scope says "Any other or
|
||||
// missing subcommand prints usage and exits 2"; `run extra` is neither a
|
||||
// clean `run` nor a different subcommand. What does the binary do? ---
|
||||
let (out, err, code) = run_capture(&["run", "extra-garbage"]);
|
||||
println!("`aura run extra-garbage` exit={code} stdout_len={} stderr={err:?}", out.len());
|
||||
// We RECORD the behaviour; the reading we assert is the lenient one the
|
||||
// binary actually exhibits, and flag the spec ambiguity in the report.
|
||||
if code == 0 {
|
||||
println!("NOTE: `aura run <extra>` was ACCEPTED (exit 0) — trailing args ignored.");
|
||||
} else {
|
||||
println!("NOTE: `aura run <extra>` was REJECTED (exit {code}).");
|
||||
}
|
||||
|
||||
println!("c0010_1 OK: aura run -> JSON report; determinism + bad-args contract observed");
|
||||
}
|
||||
@@ -0,0 +1,84 @@
|
||||
//! Fieldtest c0010 #2 — `aura_std::Recorder` as a reusable sink block (axis b).
|
||||
//!
|
||||
//! Question under test: a downstream project (C16) wires the SHIPPED
|
||||
//! `aura_std::Recorder` onto a node's output via the raw `Harness::bootstrap`
|
||||
//! API, runs the harness, drains the `mpsc::Receiver`, and the recorded
|
||||
//! `(Timestamp, Vec<Scalar>)` rows match what the public rustdoc led us to
|
||||
//! expect. The rustdoc says (struct.Recorder):
|
||||
//! - `Recorder::new(kinds, firing, tx)` — one input column per `kinds` entry;
|
||||
//! - "Each fired cycle it reads the newest value of every column and sends the
|
||||
//! row to tx; it returns None during warm-up until all columns have a value."
|
||||
//!
|
||||
//! Topology (single f64 source -> SMA(3) -> Recorder[F64]):
|
||||
//!
|
||||
//! price --> SMA(3) --> Recorder(tx) (Recorder is a pure consumer, C8)
|
||||
//!
|
||||
//! Public-surface facts used (rustdoc only):
|
||||
//! - aura_std::Sma::new(length): SMA over the last `length` f64 values, None
|
||||
//! until warm (warms once `length` values have arrived).
|
||||
//! - aura_std::Recorder::new(&[ScalarKind::F64], Firing::Any, tx).
|
||||
//! - aura_engine::{Harness, Edge, SourceSpec, Target}.
|
||||
|
||||
use std::sync::mpsc;
|
||||
|
||||
use aura_core::{Firing, Scalar, ScalarKind, Timestamp};
|
||||
use aura_engine::{Edge, Harness, SourceSpec, Target};
|
||||
use aura_std::{Recorder, Sma};
|
||||
|
||||
fn f64_stream(pairs: &[(i64, f64)]) -> Vec<(Timestamp, Scalar)> {
|
||||
pairs.iter().map(|&(t, v)| (Timestamp(t), Scalar::F64(v))).collect()
|
||||
}
|
||||
|
||||
fn main() {
|
||||
let (tx, rx) = mpsc::channel::<(Timestamp, Vec<Scalar>)>();
|
||||
|
||||
// nodes: 0 = SMA(3), 1 = Recorder over one F64 column.
|
||||
let mut h = Harness::bootstrap(
|
||||
vec![
|
||||
Box::new(Sma::new(3)),
|
||||
Box::new(Recorder::new(&[ScalarKind::F64], Firing::Any, tx)),
|
||||
],
|
||||
vec![SourceSpec {
|
||||
kind: ScalarKind::F64,
|
||||
targets: vec![Target { node: 0, slot: 0 }], // price -> SMA
|
||||
}],
|
||||
vec![
|
||||
Edge { from: 0, to: 1, slot: 0, from_field: 0 }, // SMA -> Recorder.in0
|
||||
],
|
||||
)
|
||||
.expect("valid SMA -> Recorder DAG");
|
||||
|
||||
// 5 ticks. SMA(3) warms at the 3rd tick; the Recorder then records once per
|
||||
// SMA-fired cycle (Firing::Any over one column already warm).
|
||||
let prices: &[(i64, f64)] = &[(1, 10.0), (2, 20.0), (3, 30.0), (4, 40.0), (5, 50.0)];
|
||||
h.run(vec![f64_stream(prices)]);
|
||||
|
||||
let rows: Vec<(Timestamp, Vec<Scalar>)> = rx.try_iter().collect();
|
||||
println!("recorded rows = {rows:?}");
|
||||
|
||||
// Hand model from rustdoc alone:
|
||||
// SMA(3) emits None for t=1,2 (warm-up), then:
|
||||
// t=3 -> mean(10,20,30) = 20.0
|
||||
// t=4 -> mean(20,30,40) = 30.0
|
||||
// t=5 -> mean(30,40,50) = 40.0
|
||||
// The Recorder records one row per fired (warm) cycle, tagged ctx.now(),
|
||||
// each row a single-element Vec<Scalar> with the F64 column's newest value.
|
||||
let expected: Vec<(Timestamp, Vec<Scalar>)> = vec![
|
||||
(Timestamp(3), vec![Scalar::F64(20.0)]),
|
||||
(Timestamp(4), vec![Scalar::F64(30.0)]),
|
||||
(Timestamp(5), vec![Scalar::F64(40.0)]),
|
||||
];
|
||||
assert_eq!(rows.len(), expected.len(), "one row per warm SMA cycle (no warm-up rows)");
|
||||
for (got, want) in rows.iter().zip(expected.iter()) {
|
||||
assert_eq!(got.0, want.0, "row timestamp = ctx.now()");
|
||||
assert_eq!(got.1.len(), 1, "single F64 column => one-element row");
|
||||
match (got.1[0], want.1[0]) {
|
||||
(Scalar::F64(g), Scalar::F64(w)) => {
|
||||
assert!((g - w).abs() < 1e-9, "recorded f64 {g} ~= {w}");
|
||||
}
|
||||
other => panic!("expected F64 scalar, got {other:?}"),
|
||||
}
|
||||
}
|
||||
|
||||
println!("c0010_2 OK: Recorder[F64] drained from mpsc matches the rustdoc model");
|
||||
}
|
||||
@@ -0,0 +1,123 @@
|
||||
//! Fieldtest c0010 #3 — Recorder four-kind support (axis c).
|
||||
//!
|
||||
//! The `aura run` CLI only ever uses the f64 Recorder path, so the rustdoc
|
||||
//! claim that the Recorder supports all four base scalar kinds (F64/I64/Bool/
|
||||
//! Timestamp -> Scalar::F64/I64/Bool/Ts in the recorded row) is verified here
|
||||
//! from the public surface alone, on a NON-f64 column set.
|
||||
//!
|
||||
//! There is no shipped aura-std producer of i64/bool/timestamp columns, so we
|
||||
//! author a tiny custom producer node in Rust (C17 — a downstream project
|
||||
//! authors its own nodes), emitting a 3-field record (i64, bool, timestamp)
|
||||
//! each cycle. A multi-column Recorder over [I64, Bool, Timestamp] records it.
|
||||
//!
|
||||
//! Topology (single source ticks the clock; the producer emits its own record;
|
||||
//! three edges bind producer field 0/1/2 into the recorder's slot 0/1/2):
|
||||
//!
|
||||
//! clock --> Counter ==(3 fields)==> Recorder[I64, Bool, Timestamp]
|
||||
//!
|
||||
//! Public-surface facts used (rustdoc only):
|
||||
//! - aura_core::{Node, NodeSchema, InputSpec, FieldSpec, Ctx, Scalar, ScalarKind,
|
||||
//! Firing, Timestamp}: the C8 node contract; a producer's eval returns a
|
||||
//! borrowed row matching schema().output.len().
|
||||
//! - aura_std::Recorder::new(&[I64, Bool, Timestamp], Firing::Any, tx): records
|
||||
//! the newest value of every column once all columns are warm.
|
||||
|
||||
use std::sync::mpsc;
|
||||
|
||||
use aura_core::{Ctx, FieldSpec, Firing, InputSpec, Node, NodeSchema, Scalar, ScalarKind, Timestamp};
|
||||
use aura_engine::{Edge, Harness, SourceSpec, Target};
|
||||
use aura_std::Recorder;
|
||||
|
||||
/// A 3-field producer: one f64 clock input (to tick it), emits
|
||||
/// (i64 counter, bool even?, timestamp ctx.now()) each cycle.
|
||||
struct Counter {
|
||||
n: i64,
|
||||
row: Vec<Scalar>,
|
||||
}
|
||||
impl Counter {
|
||||
fn new() -> Self {
|
||||
Counter { n: 0, row: Vec::new() }
|
||||
}
|
||||
}
|
||||
impl Node for Counter {
|
||||
fn schema(&self) -> NodeSchema {
|
||||
NodeSchema {
|
||||
// one f64 clock input so the engine fires this node each price cycle
|
||||
inputs: vec![InputSpec { kind: ScalarKind::F64, lookback: 1, firing: Firing::Any }],
|
||||
// a 3-column record: i64 / bool / timestamp
|
||||
output: vec![
|
||||
FieldSpec { name: "counter", kind: ScalarKind::I64 },
|
||||
FieldSpec { name: "is_even", kind: ScalarKind::Bool },
|
||||
FieldSpec { name: "stamp", kind: ScalarKind::Timestamp },
|
||||
],
|
||||
}
|
||||
}
|
||||
fn eval(&mut self, ctx: Ctx<'_>) -> Option<&[Scalar]> {
|
||||
if ctx.f64_in(0).is_empty() {
|
||||
return None;
|
||||
}
|
||||
self.n += 1;
|
||||
self.row = vec![
|
||||
Scalar::I64(self.n),
|
||||
Scalar::Bool(self.n % 2 == 0),
|
||||
Scalar::Ts(ctx.now()),
|
||||
];
|
||||
Some(&self.row)
|
||||
}
|
||||
}
|
||||
|
||||
fn f64_stream(pairs: &[(i64, f64)]) -> Vec<(Timestamp, Scalar)> {
|
||||
pairs.iter().map(|&(t, v)| (Timestamp(t), Scalar::F64(v))).collect()
|
||||
}
|
||||
|
||||
fn main() {
|
||||
let (tx, rx) = mpsc::channel::<(Timestamp, Vec<Scalar>)>();
|
||||
|
||||
// nodes: 0 = Counter (3-field producer), 1 = Recorder over [I64, Bool, Timestamp].
|
||||
let mut h = Harness::bootstrap(
|
||||
vec![
|
||||
Box::new(Counter::new()),
|
||||
Box::new(Recorder::new(
|
||||
&[ScalarKind::I64, ScalarKind::Bool, ScalarKind::Timestamp],
|
||||
Firing::Any,
|
||||
tx,
|
||||
)),
|
||||
],
|
||||
vec![SourceSpec {
|
||||
kind: ScalarKind::F64,
|
||||
targets: vec![Target { node: 0, slot: 0 }], // clock -> Counter
|
||||
}],
|
||||
vec![
|
||||
// bind each of the producer's three fields into the recorder's three slots
|
||||
Edge { from: 0, to: 1, slot: 0, from_field: 0 }, // i64 counter
|
||||
Edge { from: 0, to: 1, slot: 1, from_field: 1 }, // bool is_even
|
||||
Edge { from: 0, to: 1, slot: 2, from_field: 2 }, // timestamp stamp
|
||||
],
|
||||
)
|
||||
.expect("valid Counter -> Recorder[I64,Bool,Timestamp] DAG");
|
||||
|
||||
let clock: &[(i64, f64)] = &[(100, 0.0), (200, 0.0), (300, 0.0)];
|
||||
h.run(vec![f64_stream(clock)]);
|
||||
|
||||
let rows: Vec<(Timestamp, Vec<Scalar>)> = rx.try_iter().collect();
|
||||
println!("recorded rows = {rows:?}");
|
||||
|
||||
// Hand model from rustdoc alone: the Counter fires each clock cycle, all
|
||||
// three recorder columns are warm from the first cycle, so the Recorder
|
||||
// records 3 rows, each (ctx.now(), [I64(n), Bool(n even), Ts(now)]).
|
||||
let expected: Vec<(Timestamp, Vec<Scalar>)> = vec![
|
||||
(Timestamp(100), vec![Scalar::I64(1), Scalar::Bool(false), Scalar::Ts(Timestamp(100))]),
|
||||
(Timestamp(200), vec![Scalar::I64(2), Scalar::Bool(true), Scalar::Ts(Timestamp(200))]),
|
||||
(Timestamp(300), vec![Scalar::I64(3), Scalar::Bool(false), Scalar::Ts(Timestamp(300))]),
|
||||
];
|
||||
assert_eq!(rows.len(), expected.len(), "one row per clock cycle");
|
||||
assert_eq!(rows, expected, "i64/bool/timestamp columns recorded as I64/Bool/Ts scalars");
|
||||
|
||||
// Spot-check kinds explicitly (the four-kind claim is about the Scalar variant).
|
||||
let (_, first) = &rows[0];
|
||||
assert!(matches!(first[0], Scalar::I64(_)), "col0 is Scalar::I64");
|
||||
assert!(matches!(first[1], Scalar::Bool(_)), "col1 is Scalar::Bool");
|
||||
assert!(matches!(first[2], Scalar::Ts(_)), "col2 is Scalar::Ts");
|
||||
|
||||
println!("c0010_3 OK: Recorder records I64/Bool/Timestamp columns per the four-kind claim");
|
||||
}
|
||||
Reference in New Issue
Block a user