Cycle B of milestone "The World — parameter-space & sweep". A blueprint's tunable
values are injected at bootstrap rather than baked into the builder: a leaf becomes
a param-generic recipe (LeafFactory: params -> sized node), and a new build-then-
wire compile path binds a positional Scalar vector slot-by-slot against
param_space(), building each node through its own constructor.
Ratified design (brainstorm): value-empty B over mutate-in-place and over the
default-bearing variant. The value lives only in the injected vector (no baked
default), so the blueprint stays a pure param-generic recipe (C19); injected
values flow through the single new() sizing/validation gate; and because
compile_with_params consumes the vector in the same depth-first order param_space()
reports, the two share one traversal — subsuming #34's dual-traversal drift hazard.
Scope: one vector -> one instance; LeafFactory in aura-core; bootstrap_with_params/
compile_with_params; CompileError::{ParamKindMismatch, ParamArity}; Scalar::as_i64/
as_f64 accessors; fixtures/CLI/bit-identity re-expressed against the vector.
Deferred: sweep enumeration (#32), domain validation (#32/C20), single-run
authoring convenience (#35).
Gates: grounding-check PASS (8 current-behaviour assumptions ratified against green
tests; the sole BLOCK — a missing Scalar value accessor — resolved by adding it as
in-scope surface). Parse gate a no-op (profile declares no spec_validation).
refs #31
The cycle-0015 E2E guard param_space_mirrors_compiled_flat_node_param_order
pins the load-bearing C23/#31 invariant — Blueprint::param_space() slot order
mirrors compile()'s flat-node param order kind-by-slot — but only on the
single-level composite_sma_cross_harness. collect_params (blueprint.rs:217)
duplicates lower_items' depth-first traversal rather than sharing it (kept a
parallel read-only projection so compile/inline_composite stay untouched and
the compilat bit-identical, C9/C23), so the two orders must stay in lockstep
forever. No mirror test ever compiled a composite-inside-a-composite: a future
inliner reorder that desynced the projections only under nesting could pass the
single-level mirror and the isolated nested param_space order test, yet break
the slot-by-slot premise #31's binding rests on.
Adds param_space_mirrors_compiled_flat_node_param_order_under_nesting: compiles
a strategy -> { fast_slow -> [Sma, Sma, Sub], LinComb } nest and asserts
param_space() equals the compiled flat-node param order kind-by-slot, pinning
the concrete [I64, I64, F64, F64] shape. Green immediately — coverage-hardening,
no desync in the current tree. Test-only; collect_params/lower_items/compile
untouched.
Verified: cargo test -p aura-engine green (55 tests), clippy --all-targets -D
warnings clean.
closes#34
Architect drift review of the #30 cycle (561482c..931109d) against the design
ledger. Code holds: param_space() is a read-only C9 projection, compile/inline
untouched, compilat bit-identical, positional identity (C23) and topology-fixed
vector arity (C19) implemented and well-covered. Two ledger drifts + one debt item.
ledger (fixed here):
- C23 'Status' parenthetical said the sweep pass 'presupposes per-node param
declarations (C8 — deliberately not in the schema yet)' — now stale, the
declarations landed this cycle. Reworded to 'landed in cycle 0015 as name+kind;
swept range still pending #32/C20'.
- C8 guarantee promises params 'typed, with ranges' but cycle 0015 shipped name+
kind only. Added a 'Realization (cycle 0015)' note (the established per-cycle
pattern, as C8 already carries for 0005/0006) recording what landed and the
load-bearing refinement from the design discussion: the SEARCH-RANGE is the run's,
not the node's (#32/C20) — the node declares the knob's existence and type, never
its search interval; identity is positional (slot), the path-qualified name a
non-load-bearing debug symbol.
debt (filed, carry-on):
- collect_params (blueprint.rs:217) duplicates lower_items' traversal order rather
than sharing it (deliberate — keeps param_space a parallel projection so the
compilat stays bit-identical). The E2E mirror guard is shape-specific (no nested-
composite compile case). Filed as #34 to harden before #31 binds atop the
invariant. Not active drift — the guard exists, only the shape coverage is partial.
regression: profile declares no regression scripts and no architect_sweeps — the
architect review is the sole gate. No baseline to update.
Cycle A is drift-clean after these amendments. NOT a milestone close — that needs
the end-to-end milestone fieldtest, deferred until the sweep root (#31-#33) lands.
Cycle A of milestone 'The World — parameter-space & sweep'. A node now declares
its tunable parameters in its C8 schema, and a blueprint aggregates them into one
flat, inspectable param-space — the root that unlocks the C12 orchestration axes
(#31 bind, #32 sweep), filling the gap C8/C23 name 'deliberately not in the schema
yet'.
- aura-core: ParamSpec { name: String, kind: ScalarKind } as a third schema-
declaration type; NodeSchema gains a third field 'params'. name is String (not
&'static like FieldSpec) because a vector knob carries a runtime index and
aggregation prefixes the composite path.
- aura-std: Sma declares [length:I64], Exposure [scale:F64], LinComb expands to N
flat [weights[i]:F64] (N = its input arity, topology-fixed per C19); Sub/Add/
SimBroker/Recorder declare none (pip_size is metadata, C10/C15; Recorder is
wiring).
- aura-engine: Blueprint::param_space() walks the graph-as-data depth-first in
lower_items order, path-qualifying via the already-public Composite::name() — a
read-only projection (C9). compile/inline_composite/lower_items are untouched, so
the compilat stays bit-identical (composite_sma_cross_runs_bit_identical_to_hand_wired
and the golden render tests stay green).
Design: param identity is positional (slot after the deterministic inline order,
C23 'by index not name'); the path-qualified name is a non-load-bearing debug
symbol — same-type siblings in one composite share a name, uniqueness is at the
slot. Flat over a structured arity-bearing ParamSpec because flattening is
unavoidable (a sweep enumerates a flat point-space) and structure-in-the-runtime
is the nested-composite reading C23 rejects (see spec 0015 for the full rationale).
Scope is declaration + aggregation + inspection only; binding (#31), sweep
enumeration (#32), search-range, validity-constraint, and default-range/slider are
deferred. An E2E test pins the load-bearing C23/#31 invariant: param_space() slot
order mirrors compile()'s flat-node param order, kind-by-slot, on the SMA-cross
harness. fieldtests/ (excluded crates) left as frozen snapshots.
Verified: cargo build/test --workspace green (64 tests), clippy --all-targets -D
warnings clean; compile/inline diff empty.
closes#30
Four bite-sized tasks, sequenced by crate-compile boundary (the non-Default
params field breaks every NodeSchema literal until repaired): aura-core type +
field, aura-std declarations, aura-engine fixture compile-repair, then the
param_space() aggregation + tests.
refs #30
Cycle A of milestone 'The World — parameter-space & sweep'. A node declares
its tunable parameters in its C8 schema (ParamSpec { name, kind }, a third
NodeSchema field); Blueprint::param_space() aggregates them into one flat,
path-qualified param-space as a read-only projection of the graph-as-data.
Param identity is positional (slot after the deterministic inline order),
the name a non-load-bearing path-qualified debug symbol (C23). Vector knobs
(LinComb.weights) expand to N flat indexed entries; N is topology-fixed (C19).
compile/inline_composite are untouched — the compilat stays bit-identical.
Scope is declaration + aggregation + inspection only; binding (#31), sweep
enumeration (#32), search-range, constraint, and default-range are deferred.
refs #30
Two behaviour-preserving tidies from the post-0013 fieldtest/backlog.
#29: aura-engine re-exports Firing/Scalar/ScalarKind/Timestamp at the crate
root. A Blueprint builder needs ScalarKind for SourceSpec.kind and Scalar/
Firing/Timestamp for sources & Recorder columns, but aura-engine previously
re-exported only the wiring types — forcing a second aura-core import for the
vocabulary its own public structs (SourceSpec.kind, ...) demand. The fieldtest
flagged this paper cut (mc_4). One import surface now. Guarded by a new
reexport_tests module.
#14: the two near-identical #[cfg(test)] Recorder fixtures in report.rs and
harness.rs are deleted in favour of the shipped aura-std::Recorder (already a
dev-dependency). Constructor signature, schema, and try_iter() drain are
identical, so no call site changed — only the struct/impl deletion plus adding
Recorder to each file's existing aura_std import. report.rs additionally drops
four imports (Ctx/InputSpec/Node/NodeSchema) that only the deleted fixture
used. The separate TapForward fixture in harness.rs is untouched.
Verified: cargo build/test/clippy --workspace all green (49 aura-engine lib
tests incl. the new one); bit-identical, golden-snapshot, SMA-disambiguation,
and mixed-kind recording tests all stay green — behaviour preserved.
closes#29closes#14
Post-cycle tidy iteration (audit fix-path: planner + implement). Covers two
pure-tidy issues:
- #29: aura-engine re-exports the core scalar vocabulary (Firing/Scalar/
ScalarKind/Timestamp) so a Blueprint builder needs one import surface.
- #14: delete the two near-identical #[cfg(test)] Recorder fixtures in
report.rs/harness.rs in favour of the shipped aura-std::Recorder (identical
constructor + try_iter drain, so call sites stay byte-identical).
#27 (cross-crate sma_cross dedup) was the third tidy candidate but is excluded:
after the bit-identical-test protection (hand_wired pole must stay independent)
and the aura-run-out-of-scope rule, its only remaining content is deduping a
concrete sma_cross composite across aura-cli (non-test) and aura-engine
(#[cfg(test)]). No C9-clean home exists for that (a feature-gated pub fn would
make a concrete trading signal an engine pub API, which C9 forbids). Narrowed
per orchestrator decision; refs #27.
End-to-end milestone fieldtest (closing gate) for the "Construction layer"
milestone (#12 composites + #13 aura graph render). Four real downstream tasks
authored against the PUBLIC interface only (ledger + doc-comments + re-exports
+ the aura CLI), under fieldtests/milestone-construction-layer/:
mc_1 — author a named sma_cross composite, build a Blueprint, compile +
bootstrap + run (12 populated equity rows);
mc_2 — correct vs fast/slow-swapped cross: labels + graph-as-data differ
observably (the headline mis-wire-visible property);
mc_3 — composite-nested-in-composite inlines and runs;
mc_4 — walk the built graph via the read-only accessors, no engine internals.
Roll-up: friction_found, NO bugs. The milestone delivers its core promise —
fractal authoring -> compile -> bootstrap -> run, introspection as graph-as-data,
and param-carrying labels that make a mis-wire readable. None of the findings
block the gate.
Findings filed to the forward queue (not fixed here):
- #28 (feature) — the headline friction: `aura graph` renders only the built-in
sample and the render adapter is CLI-private, so a consumer can't render their
OWN graph. Subsumes the reachability of #26 (the nested-render panic is
structurally unreachable until the render is parameterizable). Likely next
(consumer-project / World) milestone.
- #29 (idea) — aura-engine doesn't re-export the scalar vocabulary (ScalarKind
etc.) a graph-builder needs; one-crate ergonomics tidy.
- #16 (comment) — `aura graph` arg policy (help / unknown-arg) should unify with
the still-open `aura run` strictness question.
The fieldtester read no implementation source; all artefacts are the consumer
crate + the two live render captures (render_clustered.txt / render_compiled.txt,
byte-identical across runs).
Architect drift review over 9fbc16a..0a855c3 (aura graph ASCII-DAG render,
#13): no contract violation. Regression gate is a no-op (commands.regression
empty); architect is the sole gate.
Contracts verified against the diff (by fact, not claim):
- C8/C1: `Node::label()` is genuinely non-load-bearing — called only in the
renderer (aura-cli/src/graph.rs) and test assertions, never in the run loop
(harness.rs) nor the compile path (blueprint.rs). Wiring stays index-based;
determinism untouched. The C8 Refinement note (INDEX.md) matches what shipped.
- C16: no engine-crate manifest changed (aura-core/std/engine/ingest Cargo.toml
all clean); ascii-dag v0.9.1 appears only in aura-cli/Cargo.toml + the matching
Cargo.lock delta. The zero-external-dependency engine firewall is intact.
- C9/C23: `Composite.name` dissolves at inline — `inline_composite` destructures
`name: _` (blueprint.rs), the name never reaches the flat compilat. The
compiled view emits no cluster (golden asserts `!contains("sma_cross")`); the
blueprint view draws composites as clusters. Boundary dissolution holds.
Drift status: drift_found = technical debt only (no fix iteration; contracts
hold). Filed to the forward queue rather than fixed in-cycle:
- #26 (feature) — the blueprint (clustered) view panics `unimplemented!` on
nested composites while the compiled view handles nesting; the two views
diverge in capability. Built-in sample is single-level so it is unreachable
today. Bundles the low-severity source-label gap (sources render `source:{kind}`
because SourceSpec has no name — latent C20 gap).
- #27 (idea) — the SMA-cross sample wiring is now triplicated (aura run flat
harness, aura graph composite blueprint, engine bit-identical fixture);
distinct from #14's Recorder-fixture dedup.
No baseline update (no regression script). Next-iteration direction (architect):
resolve#26 before the next render-touching cycle so the two views stop diverging.
Make a wired graph introspectable so a mis-wiring becomes visible. Two
selectable views, both authored from one built-in sample blueprint:
aura graph clustered blueprint view — composites drawn as named
ascii-dag cluster boxes (pre-inline, C9)
aura graph --compiled flat compilat view — composite boundaries dissolved
(C23); the graph the run loop actually runs
The payoff is intrinsic, param-carrying node labels: two SMAs read SMA(2) /
SMA(4), so a swapped fast/slow input reads back differently. This is realized
by a `label()` default method on the core Node trait — a non-load-bearing
render symbol the run loop never reads (wiring is by index), the symbol C23
already reserves citing #13. Recorded as a C8 refinement in the ledger.
Rejected the alternatives in brainstorm: a separate Describe trait (forces a
combined trait-object dance for a label the ledger calls non-load-bearing) and
extrinsic parallel labels (decoupled from the node, so an author can label the
slow SMA "fast" and mask the very bug the render exists to surface).
Mechanism:
- aura-core: Node::label() default method (additive, object-safe, single-line).
- aura-std: per-node overrides — SMA(n)/Exposure(s)/SimBroker(p) carry params;
Sub/Add/LinComb/Recorder are bare (their identity is not a mis-wiring axis).
- aura-engine: Composite gains an authored `name` (cluster title; dissolves at
inline) + read-only graph-as-data accessors on Blueprint/Composite. No
external dependency — the engine stays dependency-pure (C16); ascii-dag lives
only in aura-cli. The label-free index-wired compilat (C23) is unchanged.
- aura-cli: ascii-dag v0.9.1 + a graph.rs adapter (Vertical mode; labels
materialized into an owned Vec<String> that outlives the borrow-based Graph).
`aura run` is untouched (the sample duplication is dedup idea #14).
Tests: a concern-defining test (swapped sample renders != correct), structure
pins (cluster present in blueprint view, absent in compiled view), per-node
label disambiguation, and two frozen byte-goldens of the deterministic render.
The cycle-0012 bit-identical and run-sample non-regression tests stay green.
Verified by the orchestrator (not the agent report): cargo build --workspace
clean; cargo test --workspace all green; cargo clippy --workspace --all-targets
-D warnings clean; both views run live and render as expected.
closes#13
Render a wired graph as an ASCII DAG via an `aura graph` subcommand so a
mis-wiring becomes visible (the concern of #13). Two selectable views: a
blueprint view (composites as cluster boxes, pre-inline) and a `--compiled`
view (the flat compilat, boundaries dissolved per C23).
Settled in brainstorm: render labels come from a non-load-bearing `label()`
default method on the core `Node` trait (a C8 refinement aligned with C23,
which already reserves render names citing #13), overridden per node to carry
params (SMA(2) vs SMA(4)) so a swap reads back differently. Composites gain an
authored name; the engine exposes read-only graph-as-data accessors and stays
dependency-free (C16) — ascii-dag lives only in aura-cli. `aura run` is left
untouched this cycle.
Gates: self-review clean; parse gate a no-op (no spec_validation in profile);
grounding-check PASS.
refs #13
Architect drift review over fef09d4..a4fb5d7 (blueprint construction layer /
composite inlining, #12): drift-clean, carry-on. Regression gate is a no-op
(commands.regression empty); architect is the sole gate and found nothing
actionable.
What holds against the ledger (verified by fact, not claim):
- C1/C16: `git diff --stat` shows only blueprint.rs (new) + lib.rs (+2 lines).
harness.rs (run loop, bootstrap), node.rs (Node trait), and
Edge/Target/SourceSpec are byte-untouched, so determinism is preserved — the
compilat is the same flat topology a hand-wiring produces. aura-engine's
Cargo.toml adds no external dependency (aura-std is [dev-dependencies] only),
so the zero-external-dependency engine workspace invariant holds.
- C9/C23: `Composite` is not a `Node` (no `impl Node for Composite`, never
`eval`'d); `compile()` inlines to a flat (nodes, sources, edges) wired by raw
index; names survive only as non-load-bearing debug symbols. The
bit-identical demonstrator proves the compilat equals the hand-wired flat
graph for the SMA-cross. No runtime sub-engine reached the run loop.
- C19: binding is a compilation; typed CompileError validation delegates the
lowered-compilat check to the unchanged bootstrap kind/Kahn check (no
re-implementation).
Acknowledged debt (low, named — not silent drift), filed to the forward queue:
- #24 — Composite::schema() panics on malformed indices where compile() returns
a typed CompileError (two validity surfaces, divergent failure modes;
doc-acknowledged).
- #25 — compile() re-calls dyn Node::schema() (fresh Vec alloc) at each resolve
site, duplicating bootstrap's kind-derivation; compile-time only, no hot-path
cost.
Neither debt item blocks the deferred C23 optimisation passes, the natural
next direction.
Add the construction layer (C9/C19/C23): a named, param-generic graph-as-data
(`Blueprint`) that *compiles* to the flat, type-erased instance the run loop
already runs. The unit of reuse is the `Composite` — a nestable sub-graph
fragment exposing one output port (C8) and named input roles — which
`Blueprint::compile()` **inlines** by raw-index lowering into the flat
`(nodes, sources, edges)` the unchanged `Harness::bootstrap` consumes.
Design (settled in spec 0012, ledger C9/C19/C23): a composite is an
authoring-level node, NOT a runtime `Box<dyn Node>` sub-engine. The chosen
inlining approach keeps the sacrosanct deterministic run loop untouched and
leaves the composite interior fully inspectable for the deferred cross-graph
optimiser; the rejected "runtime sub-engine" reading would have put throwaway
complexity into the run loop and kept the interior opaque. The compilat is
wired by raw index, not by name; names survive only as non-load-bearing debug
symbols (as `FieldSpec.name` already is).
Lowering is recursive index rewriting: interior items append at an offset,
interior edges rewrite by that offset, an edge into a composite fans through
its input roles (one blueprint edge -> several flat edges), an edge out
resolves to the interior output port, and nesting recurses inside-out.
Construction-phase faults are caught as a typed `CompileError`
(BadInteriorIndex / RoleKindMismatch / OutputPortOutOfRange); the lowered flat
compilat is validated by bootstrap's existing kind- and Kahn-cycle-check
(wrapped as `CompileError::Bootstrap`), with no re-implementation.
Non-goals (deferred per C23/C16): no optimisation pass (CSE/DCE,
sweep-invariant hoisting), no external optimisation crate, no named-handle
ergonomic wiring, no `aura graph` render (#13).
Verification: 48 engine tests green (8 blueprint: derived-schema, single +
nested composite inlining, the three CompileError paths, bootstrap-error wrap,
and the headline `composite_sma_cross_runs_bit_identical_to_hand_wired` C1
demonstrator — the SMA-cross composite lowers to a flat graph byte-identical to
the hand-wired sample harness, producing bit-for-bit identical equity +
exposure traces); `cargo clippy --workspace --all-targets -D warnings` clean.
`Node`, `Harness::bootstrap`, the run loop, and `Edge`/`Target`/`SourceSpec`
are unchanged.
closes#12
Bite-sized plan for the construction layer: Blueprint/Composite types +
derived schema (Task 1), the recursive compile() inliner with typed
CompileError validation (Task 2), and the SMA-cross bit-identical
demonstrator (Task 3). Lowers to the unchanged Harness::bootstrap;
optimisation passes deferred (C23).
refs #12
The Construction-layer milestone's anchor spec: a Blueprint graph-as-data that
compiles (inlines composites) to the flat (nodes, sources, edges) the unchanged
Harness::bootstrap consumes (C9/C19/C23). The SMA-cross composite runs
bit-identical to the hand-wired sample_harness (C1). Non-goals: optimisation
passes, external deps, named-handle ergonomics, aura graph.
Grounding-check PASS (13/13 current-behaviour assumptions ratified by green tests).
refs #12
Settle the Construction-layer milestone's design fork before any spec is written:
a composite is a blueprint fragment compiled away by inlining, not a runtime
sub-engine Node.
- C23 (new): the bootstrap is a compilation -- a param-generic, named blueprint
is lowered to a flat, type-erased compilat wired by raw index; composites
inline (C9). The compilat is the target of behaviour-preserving optimisation
(C1 is the correctness invariant) on two levels: intra-compilat (CSE/DCE) and
across the sweep family (loop-invariant prefix hoisting -- the sweep-invariant
sub-graph computed once and shared via C11/C12). Passes are deferred follow-on;
this milestone builds the representation only.
- C9 refined: "a composite is itself a Node" is an authoring-level identity; the
nested Box<dyn Node> sub-engine reading is explicitly rejected (it keeps the
interior opaque to the cross-graph optimiser and adds a runtime sub-loop the
flat model does not need).
- C19 refined: the blueprint->instance binding is a compilation; "no recompile"
means no Rust/cdylib rebuild -- re-deriving an instance per param-set is a
cheap graph re-compilation, not a code recompile.
- Names are non-load-bearing debug symbols (as FieldSpec.name already is); the
wiring resolves by raw index, names survive only for tracing/rendering.
- CLAUDE.md domain-invariant 11 pulled coherent with the compilat reading.
refs #12
`aura run` keyed only on the first token being `run`, so `aura run
extra-garbage` printed the full report and exited 0 -- a typo'd
`aura run --sweep` silently ran instead of hinting. #16 ratified the
strict reading over the lenient one (the lenient reading buys no real
forward-compat: future args would be parsed explicitly anyway, while the
silent-swallow actively hides typos and clashes with the exit-2 hygiene
the unknown-subcommand path already enforces).
Add a match guard so only a bare `run` reaches the JSON happy path:
Some("run") if args.next().is_none() => println!(...)
A trailing token fails the guard and falls through to the existing
`_ =>` usage-error arm (stderr usage, exit 2) -- no literal duplication,
the error path is reused. Bare `aura run` is unchanged, pinned by the
positive-preservation assertion and the two sibling run-tests. Verified:
cargo test -p aura-cli green (6), clippy --all-targets -D warnings clean.
closes#16
`aura run extra-garbage` keys only on the first token being `run` and
ignores the rest, so it prints the full report and exits 0 -- a typo'd
`aura run --sweep` masquerades as a successful run instead of getting a
hint. The 0010 cycle_scope ("any other or missing subcommand -> usage +
exit 2") did not unambiguously cover `run <token>`; #16 ratifies the
strict reading.
This RED pins it: a trailing unexpected token takes the error path
(usage on stderr, empty stdout, exit 2), mirroring the no-args sibling;
bare `aura run` is held to its current happy path (JSON on stdout, exit
0) by a positive-preservation assertion so the strict guard cannot
regress it.
refs #16
RunManifest.commit read option_env!("AURA_COMMIT").unwrap_or("unknown"),
so a normal build's manifest identity field was a bare placeholder --
C8's audit trail (this run = this commit) had nothing to point back at
once runs are archived (C18 registry).
Add crates/aura-cli/build.rs: at compile time it shells out to the `git`
already in PATH -- `rev-parse HEAD`, plus a `-dirty` suffix when
`status --porcelain` is non-empty -- and emits
`cargo:rustc-env=AURA_COMMIT=<sha>`. The existing option_env! read is
untouched and now picks it up. Chose shelling to git over a libgit crate
to keep the zero-external-dependency commitment (C14/C18); the firewall
crate is aura-ingest, and a build-time process call adds no runtime dep.
No-git case (packaged source tree, no .git): build.rs returns early and
swallows git errors, leaving AURA_COMMIT unset so "unknown" still holds.
Staleness guard: build.rs emits rerun-if-changed on .git/HEAD and
.git/logs/HEAD (logs/HEAD grows on every HEAD move incl. branch switch),
so the captured sha is rebuilt when HEAD moves rather than going stale.
Determinism (C1) is intact: AURA_COMMIT is fixed at compile time, so two
runs of one build still produce byte-identical manifests.
Two tests that pinned the old "unknown" placeholder are relaxed to the
new structural contract (not scope creep -- they were the old contract):
the cli_run.rs JSON-shape prefix no longer pins the commit value, and
the main.rs unit test asserts commit is non-empty and stable across runs
instead of equal to "unknown". The headline contract (manifest.commit
contains the real HEAD sha) is pinned by run_manifest_commit_carries_
real_git_head (4552d0c). Verified: cargo test -p aura-cli green (5),
clippy --all-targets -D warnings clean.
closes#15
RunManifest.commit comes from option_env!("AURA_COMMIT") defaulting to
"unknown", so the C18 manifest's identity field -- which code produced
this run -- is a bare placeholder in a normal build. C8's audit-trail
invariant (this run = this commit) needs the manifest to point back at
its source once runs are archived.
This RED pins the desired contract structurally: a normal `aura run`'s
manifest.commit CONTAINS the current git HEAD sha (obtained in-test via
`git rev-parse HEAD`) and is NOT the bare "unknown" literal. Structural
(contains, not equals) on purpose: the working tree may be dirty when
the test runs (this test file itself was uncommitted at author time), so
a build that appends a "-dirty" suffix must still pass. GREEN is a
build.rs in aura-cli capturing HEAD at compile time, "unknown" retained
only for the no-git case.
refs #15
`aura --help` and `aura -h` are a newcomer's reflex first command but
fell through to the catch-all unknown-subcommand arm: exit 2, empty
stdout, error text on stderr. The conventional help affordance returning
the error path is a C22 first-contact friction (milestone fieldtest).
Add a `Some("--help") | Some("-h")` arm before the catch-all that prints
the usage to stdout and returns normally (exit 0). The `_ =>` error path
is untouched, so an unknown subcommand still prints `aura: usage: aura
run` to stderr and exits 2 -- pinned by the negative-preservation
assertion in the RED test (07ba20a). Verified: cli_run.rs all green
(help/no-args/run), clippy --all-targets -D warnings clean.
Minimal slice per the tdd handoff: the stdout help literal ("usage: aura
run") and the stderr error literal ("aura: usage: aura run") are left as
two distinct user-facing strings rather than factored into a shared
usage constant -- a single usage source is a deliberate non-goal here,
left for a future cycle if one wants it.
closes#20
`aura --help` and `aura -h` are a newcomer's reflex first command, but
today they hit the unknown-subcommand error path: exit 2, empty stdout,
one-line `aura: usage: aura run` on stderr. For a C22 "newcomer sees a
populated trace" milestone the conventional help affordance returning
the error path is a first-contact friction.
This compile-clean RED pins the desired success-path contract: `--help`
and `-h` print non-empty usage to stdout and exit 0, and the usage names
the `run` subcommand. A negative-preservation assertion keeps an unknown
subcommand (`frobnicate`) on the exit-2 error path so the fix cannot
regress bad-args handling. Asserts structural facts only (exit code,
non-empty stdout, mentions `run`), not exact help prose.
refs #20
The rustdoc claimed 'None if the symbol has no data in [from_ms, to_ms]',
implying a bar-level None. Empirically (cycle-0011 fieldtest) None is
file-level: it propagates data-server's own None, returned only when no
archived file overlaps the window (far-future window or unknown symbol).
A window that overlaps a loaded file but holds zero bars returns
Some(M1Columns) with empty columns, not None.
Document the distinction precisely (chosen over collapsing in-coverage-
empty into None): None propagates data-server's one file-level meaning
unchanged -- 'no data source to read from' -- rather than overloading it
with a second aura-level 'source present but empty here' meaning. So
Some/None means 'data source present' vs 'nothing to read from', not
'has bars' vs 'has none'; a consumer testing for an empty window must
check cols.close.is_empty(). Doc-only, no behaviour change; ledger
untouched (the contract is not referenced there).
closes#18
load_m1_window took (from_ms: i64, to_ms: i64) and forwarded
Some(from_ms)/Some(to_ms) into stream_m1_windowed, throwing away the
underlying API's per-bound Option<i64> (None = unbounded). There was thus
no way to express an open upper bound, and the natural i64::MAX sentinel
overflowed chrono's from_timestamp_millis inside data-server's coarse
unix_ms_to_year_month file filter, panicking the whole ingest.
Thread Option<i64> through both bounds unchanged, so None = unbounded
matches the underlying contract and 'to the end of history' needs no
sentinel. Rejected the alternative of clamping a too-large bound to a
ceiling constant: a ceiling is not actually unbounded (it silently drops
any post-ceiling bar) and reintroduces a magic literal; restoring the
Option makes the open bound structurally expressible instead.
The committed RED test (2e38106) is now GREEN: it reads AAPL.US's latest
archived month with None as the upper bound and asserts bar-for-bar
equality with the finite sane bound. Verified: cargo test --workspace
green (unbounded_window and real_bars both ran the real /mnt/tickdata
path, not skipped); clippy --all-targets -D warnings clean.
Out of scope, left untouched: the None-vs-Some(empty) rustdoc semantics
(#18), and three out-of-workspace frozen fieldtest crates that still call
the old bare-i64 signature -- those are dated historical replay records
and are intentionally not rewritten.
closes#23
load_m1_window cannot express an open upper bound: it hardcodes
Some(from_ms)/Some(to_ms) into stream_m1_windowed, so callers reach for
the i64::MAX sentinel, which panics upstream in chrono's
from_timestamp_millis (data-server records.rs:28). This compile-RED pins
the desired Option<i64> contract (None = unbounded) and asserts an
unbounded read equals the finite sane bound bar-for-bar.
refs #23
Milestone-scope fieldtest (the functional leg of the Walking-skeleton
milestone-close gate), from the public interface only. Three end-to-end
scenarios, all green:
- the newcomer CLI path: `aura run` -> single-line {manifest,metrics} JSON,
exit 0, byte-identical twice (C1), non-degenerate trace (C22), bad-args ->
exit 2;
- the real-data thread: real AAPL.US 2006-08 M1 bars -> load_m1_window ->
close_stream -> SMA-cross -> Exposure -> SimBroker -> summarize -> RunReport,
deterministic AND populated;
- epoch-ns coherence: C3 normalization holds ingest -> run -> sink.
Roll-up: the milestone DELIVERS its promise end to end (ingest -> one signal ->
exposure -> sim-optimal broker -> pip-equity metric -> structured RunReport,
deterministic, populated) on BOTH the synthetic and real-data paths. 0 bugs.
Headline concern (verified by the orchestrator): issue #19's premise is WRONG at
the shipped SMA(2)/SMA(4) demo config — 21 AAPL.US bars warm the cross and
produce a populated trace (total_pips=-1.5, max_drawdown=65.5, 6 sign flips),
not all-zero. The degeneracy #19 saw was deep-SMA/param-dependent, not intrinsic
to the symbol. #19 to be re-scoped. Other findings: `aura run <junk>` exit 0
(already #16), `aura --help` lands on the exit-2 error path (friction), SimBroker
two-f64-slot order unchecked at bootstrap (documented footgun) — both filed.
Per-cycle fieldtest of the aura-ingest ingestion boundary (issue #7), from the
public interface only. 3 examples (transpose/normalize core; close_stream ->
deterministic harness run with epoch-ns end-to-end; load_m1_window over real
AAPL.US 2006-08 bars + None paths), all green. 0 bugs, 0 friction.
Two spec_gaps named for follow-up (neither a code defect; both filed to the
tracker):
- load_m1_window returns Some(empty M1Columns) — not None — for an in-coverage
but bar-empty window. The rustdoc's "None if no data in [from_ms,to_ms]" reads
bar-level but the realized boundary is file-level (it inherits data-server's
file-skip None). A consumer matching None == "no bars" is wrong for the
in-coverage-empty case. -> tighten the load_m1_window rustdoc (one line).
- AAPL.US (the carrier/integration-test symbol) has only ~21 M1 bars/month, so
the SMA-cross never warms and the end-to-end run yields all-zero (degenerate
but valid) metrics. The boundary is correct (C2 warm-up); the milestone's
shipped demo data is too thin to show a non-degenerate trace. -> weigh against
C22's "newcomer sees a populated trace" before the Walking-skeleton close
(document expected density or name a denser demo symbol/window).
Architect drift review (f68258b..HEAD) found no code drift — the firewall is
real at the dependency-graph level (aura-core/std/engine/cli carry no external
dep; the chrono/regex/zip tree is confined to aura-ingest), and C3/C7/C1 are
faithfully realized. Four ledger-level items, all resolved here:
- [ledger-drift] The zero-external-dependency commitment — the load-bearing
rationale for making aura-ingest a crate rather than a feature-gate — lived
only in spec 0011. Recorded in the ledger: C16 now states the engine workspace
is zero-external-dependency by commitment, names aura-ingest as the ingestion
edge / external-dependency firewall, and forbids an external dep in any engine
crate other than aura-ingest.
- [ledger-drift] C16's reuse taxonomy did not place aura-ingest. C16 now lists
the non-node engine crates (aura-engine, aura-cli, aura-ingest).
- [ledger-debt] C12's eager-materialization-now / Arc<[T]>-sharing-later choice
was only in the spec. C12 now carries a "Status (cycle 0011)" note recording
the deliberate gap.
- [debt] aura-engine/Cargo.toml carried a stale comment ("data-server enters
when the ingestion task starts") that contradicted the firewall it should
protect. Replaced with the dependency-pure / firewall-in-aura-ingest note.
The External components data-server bullet is updated to reality (pulled in by
aura-ingest; workspace now resolves from a populated cargo cache, not fully
offline).
Regression gate: no-op (commands.regression empty); architect is the sole gate.
Cycle 0011 is drift-clean. (Drift-clean, not a milestone close — the
Walking-skeleton milestone close additionally needs its end-to-end milestone
fieldtest, a separate deliberate act.)
aura's first real data source (closes#7, Walking-skeleton milestone). A new
aura-ingest workspace crate transposes data-server's AoS M1Parsed records into
SoA base columns (C7), normalizes Unix-ms to canonical epoch-ns at the one
ingestion boundary (C3), and feeds the existing k-way merge a real close-price
stream so a backtest runs over real bars, deterministically (C1).
Surface:
- unix_ms_to_epoch_ns(time_ms) -> Timestamp (= ms * 1_000_000), the single C3
unit normalization.
- M1Columns: the OHLCV bar as a bundle of base columns (open/high/low/close/
spread: f64, volume: i64, ts: epoch-ns) — SoA, C7.
- transpose_m1(&[M1Parsed]) -> M1Columns: pure AoS->SoA (C1).
- M1Columns::close_stream() -> Vec<(Timestamp, Scalar)>: the price input the
SMA-cross sample strategy consumes.
- load_m1_window(server, symbol, from_ms, to_ms): drains data-server's
chronological chunks, transposes once at the boundary.
Design (per spec 0011):
- Eager materialization, not a lazy/shared Source abstraction: C12's cross-sim
Arc<[T]> sharing has no consumer until the multi-sim orchestration cycle;
deferred, the transpose logic carries over.
- aura-ingest is the external-dependency firewall. data-server transitively
pulls chrono + regex + zip (+ their trees) into Cargo.lock; isolating it in
this one crate keeps aura-core/std/engine zero-external-dependency and the
frozen deploy artifact (C6 replays recorded streams, never re-ingests) clean.
cargo test --workspace now needs a populated cargo cache (one Gitea fetch,
done).
- Scope: boundary + tests only, no aura run CLI arg surface (M1 first; tick and
the CLI wiring are follow-ups).
Tests: 6 hermetic unit tests on hand-built M1Parsed (normalization, field-wise
transpose, purity, close_stream order, empty edges) + one gated integration
test (tests/real_bars.rs) that runs the cycle-0007 sample harness over real
AAPL.US 2006-08 close bars and asserts finite metrics + two-run bit-identical
JSON (C1); it skips cleanly where /mnt/tickdata is absent. On this machine it
ran the real path. Workspace gates green: test (86), clippy -D warnings, doc
-D warnings.
Minor: transient unused-import warnings in the new lib.rs across the additive
build steps resolved once load_m1_window consumed the imports; final -D warnings
gate clean.
Placeholder-free 6-task plan for spec 0011 (refs #7). T1 scaffolds the
aura-ingest crate + workspace member + unix_ms_to_epoch_ns (proves the
data-server git dep resolves); T2 M1Columns + transpose_m1; T3 close_stream;
T4 load_m1_window (data-server adapter, compile-gated against the real API);
T5 the gated real-bars integration test (cycle-0007 sample harness over real
AAPL.US close bars, finite + deterministic, skips where data absent);
T6 full-workspace gates. Mirrors report.rs build_two_sink_harness with the
shipped aura_std::Recorder. External data-server signatures verified against
its source in the spec commit.
First real data source (refs #7, Walking-skeleton milestone). A new
`aura-ingest` crate pulls data-server as a cargo git dependency, transposes
its AoS M1Parsed records into SoA base columns (C7), normalizes Unix-ms to
canonical epoch-ns at the one ingestion boundary (C3), and feeds the existing
k-way merge a real close-price stream so a backtest runs over real bars (C1).
Decisions captured:
- Eager materialization (not a lazy/shared Source abstraction): C12's cross-sim
Arc<[T]> sharing has no consumer until the multi-sim orchestration cycle, so
building it now would be speculative infra; deferred, transpose logic carries
over.
- aura-ingest is the external-dependency firewall: data-server transitively
pulls chrono+regex+zip; isolating it in its own crate keeps core/std/engine
zero-external-dep. cargo test --workspace now needs a populated cargo cache.
- Scope: boundary + tests only, no aura run CLI arg surface (would force the
unsettled #16 arg-parse decision); M1 first, tick deferred.
grounding-check returned BLOCK on the single load-bearing external assumption
(the data-server public API) — structurally unratifiable by an aura-side test
because data-server is brand-new this cycle; all 9 aura-internal assumptions
were ratified by named green tests. Overridden after verifying data-server's
API against its actual source (lib.rs DataServer::new/has_symbol/
stream_m1_windowed/next_chunk/DEFAULT_DATA_PATH; records.rs M1Parsed fields,
types, Copy), per the agent's documented override path. User-approved.
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.
Architect drift review over 7a8d209..559903a (aura run CLI, #8): drift-clean,
carry-on. Regression gate is a no-op (commands.regression empty); architect is
the sole gate and found nothing actionable.
What holds against the ledger:
- C22 closing seam genuinely delivered: `aura run` bootstraps a CLOSED harness
WITH two sinks and emits a populated, non-trivial trace (one exposure sign
flip, a real drawdown) — a newcomer sees a real trace, as C22 promises.
- C16 respected: Recorder ships in aura-std as a domain-free universal block
(parameterised over ScalarKind/Firing/Sender, no instrument/strategy concepts);
sample_harness lives in aura-cli, not aura-engine, so the engine stays
domain-free while wiring stays plain Rust (C17/C20 — raw Harness::bootstrap, no
DSL).
- C7 purity: mpsc::Sender out-of-graph handle, no Rc/RefCell. C8 sink contract:
output: vec![], eval returns None. C14 structured face: real binary → canonical
JSON on stdout, exit-code contract integration-tested. C1 determinism pinned.
Acknowledged, spec-deferred debt (tracked, not silent drift) — filed to the
forward queue:
- Three near-identical Recorder definitions now coexist: the shipped aura-std
block (the strict superset — four kinds) plus the two #[cfg(test)] engine
fixtures (f64-only) in report.rs / harness.rs. The spec explicitly defers
de-dup; flagged for a later tidy.
- manifest.commit is option_env!("AURA_COMMIT") → "unknown" — the C18 identity
field is a placeholder until build.rs git capture (named non-goal).
The one implementer deviation (a scoped #[allow(clippy::type_complexity)] on
sample_harness) is consistent with the identical allow on aura-engine's
build_two_sink_harness fixture — not drift.
The Walking-skeleton milestone's closing seam: a real `aura run` binary that
bootstraps a built-in sample harness, runs it deterministically, and prints the
cycle-0009 metrics+manifest report as canonical JSON to stdout — the headline
C14 "run a sim, emit structured metrics" move, end-to-end, from a binary for the
first time.
Two deliverables:
- aura-std::Recorder — a reusable recording sink node (the glossary *sink* role,
C8/C22): a pure consumer (output: vec![]) over kinds.len() input columns,
holding an mpsc::Sender<(Timestamp, Vec<Scalar>)> as its out-of-graph
destination. mpsc keeps the engine's purity invariant (C7): no Rc/RefCell.
Supports all four base scalar kinds; returns None until every column is warm.
Promotes the shape the #[cfg(test)] fixtures already proved into a shipped,
reusable block (the fixtures stay as historical snapshots; de-dup is a later
tidy).
- aura-cli `run` subcommand — synthetic_prices / sample_harness / run_sample /
main. The sample harness (synthetic source → SMA(2)/SMA(4) → Sub → Exposure →
SimBroker → two Recorder sinks) is authored in plain Rust over the raw
Harness::bootstrap(nodes, sources, edges) API (C17/C20) — the open
experiment-builder DSL thread is deliberately not committed this cycle. main
hand-parses one subcommand: `run` prints run_sample().to_json() (exit 0),
anything else prints a one-line usage to stderr (exit 2). aura-cli gains
aura-std + aura-core path deps; the workspace stays zero-(external-)dependency.
The built-in synthetic stream (7 ticks, rises then reverses) yields a non-trivial
demo trace: equity [0,0,0,0,-0.08,-0.17,-0.13] → total_pips -0.13, max_drawdown
0.17, exposure_sign_flips 1. The run_sample unit test pins the integer flip count
exactly and the two f64 metrics within 1e-9 (the real run's float dust is ~7e-15,
confirming the tolerance); determinism is pinned exactly (two runs → identical
JSON). tests/cli_run.rs drives the built binary for the observable exit/stdout
contract.
manifest.commit is filled from option_env!("AURA_COMMIT") (defaults to
"unknown"); real HEAD capture via build.rs is deferred. Non-goals untouched:
experiment-builder DSL, aura new, Aura.toml schema, the data-server source (#7).
One deviation from the plan's verbatim code: a scoped
#[allow(clippy::type_complexity)] on sample_harness (its (Harness, Receiver,
Receiver) return tuple trips the lint under -D warnings) — consistent with the
identical allow on the build_two_sink_harness fixture in aura-engine. Verified
myself: cargo test --workspace (61 green, 0 red), clippy --all-targets
-D warnings (clean), cargo doc -D warnings (clean), and both smoke runs.
closes#8
Placeholder-free, verbatim-code plan for cycle 0010 (#8). Two deliverables in
dependency order, four tasks:
1. aura-std::Recorder — a four-kind recording sink (pure consumer, output:
vec![], holds an mpsc::Sender), mirroring the existing #[cfg(test)] fixture;
wired into lib.rs alphabetically; two unit tests (f64 capture after warm-up,
None-until-all-columns-warm).
2. aura-cli run subcommand — synthetic_prices / sample_harness / run_sample /
main over the raw Harness::bootstrap API (no builder DSL), + aura-std/aura-core
path deps; a unit test pinning determinism and the hand-computed metrics.
3. tests/cli_run.rs — integration test driving the built binary (run -> exit 0 +
single-line JSON; no args -> exit 2 + usage stderr).
4. Workspace gates (test / clippy -D warnings / doc -D warnings).
The chosen synthetic stream (7 ticks, rises then reverses) is traced tick-by-tick
in the plan: equity [0,0,0,0,-0.08,-0.17,-0.13] -> total_pips -0.13, max_drawdown
0.17, exposure_sign_flips 1. The integer flip count is pinned exactly; the two
f64 metrics within 1e-9 (dust ~1e-15); determinism pinned exactly.
refs #8
Cycle 0010, the Walking-skeleton milestone's closing seam: an `aura run`
subcommand that bootstraps a built-in sample harness (synthetic source →
SMA-cross → Exposure → SimBroker → recording sinks), runs it
deterministically, and prints the cycle-0009 metrics+manifest report as
canonical JSON to stdout.
The crux the cycle resolves: no recording sink node ships today (recording
lives only as #[cfg(test)] fixtures), and Harness::run returns () with a sink
as the only data-out path. So this cycle first ships a reusable
aura-std::Recorder (a pure consumer holding an mpsc::Sender, purity-preserving
per C7), then wires the CLI on top.
Load-bearing decisions, user-approved at the brainstorm gate:
- Recorder ships in aura-std (universal block, C16), not engine or CLI-local.
- Sample harness is authored as a plain Rust constructor over the raw
Harness::bootstrap API (C17/C20) — the open experiment-builder DSL thread is
deliberately NOT committed this cycle.
- Zero-dependency CLI: hand-parsed args (no clap); manifest commit from
option_env!("AURA_COMMIT") defaulting to "unknown" (build.rs git capture
deferred).
Grounding-check PASS (all load-bearing codebase assumptions ratified by green
tests). Non-goals: experiment-builder DSL, aura new, Aura.toml schema, the
data-server source (#7), build.rs git capture.
refs #8
Resolves the two doc-level findings from the cycle-0009 fieldtest
(docs/specs/fieldtest-0009-run-metrics.md), both the same doc pass on
RunReport::to_json's rustdoc:
- spec_gap: the JSON key names and {manifest,metrics} nesting were not on the
public surface — a consumer parsing the JSON (the C18 registry, the deferred
aura run printer) could not author against it from rustdoc alone. Now stated:
keys mirror the struct field names in fixed order, window is a 2-element
[from,to] array, params is an insertion-order object, with a worked sample
object. Ratifies field-name-mirroring as the contract for the C14 face.
- friction: a whole-valued f64 renders without a fractional part (12.0 -> 12),
so one f64 field may appear as an integer or decimal token across runs. Now
documented, with the consumer guidance to parse as a number, never key off
token shape.
Doc-only change; no behaviour change. The sample is a `text` fence (not a
doctest). Verified: RUSTDOCFLAGS="-D warnings" cargo doc -p aura-engine clean;
clippy -p aura-engine --all-targets -D warnings clean; doctests 0.
refs #6
First fieldtest of the run-metrics + manifest report surface. A standalone
downstream-consumer crate (fieldtests/cycle-0009-run-metrics/) path-depends on
the engine crates and exercises the post-0009 surface from the public interface
only (rustdoc + ledger + glossary + project layout, never crates/*/src).
Primary axis empirically met: the north-star "a run emits metrics + manifest"
move is reachable from rustdoc alone — drain two recording sinks -> f64_field ->
summarize -> RunManifest -> to_json, metrics matching the hand model on the first
run, deterministic across reruns.
Findings: 0 bugs, 1 friction, 1 spec_gap, 4 working.
- working x4: north-star reachable from rustdoc; SimBroker firing/slot docs (a
resolved 0007 gap) now carry the example; summarize metric definitions exact
on six degenerate inputs (incl. negative-curve drawdown + flat-as-sign-0);
f64_field panics precise and well-located.
- spec_gap: to_json's JSON key names + {manifest,metrics} nesting are not on
the public surface — a consumer parsing the JSON (C18 registry, the deferred
aura run printer) cannot author against it from rustdoc alone.
- friction: to_json renders whole-valued f64 without a decimal point (3.0 ->
"3"), so one f64 field appears as integer or decimal token within one schema.
Both doc-level findings are the same doc pass and matter mainly for the deferred
aura run (#8) and the C18 registry that will parse this JSON. Spec feeds the next
plan as reference.
refs #6
Architect drift review over 521a16e..80d7bfb (run-metrics-and-manifest):
no drift, no debt. The shipped report surface matches the ledger:
- Pure-additive as claimed: lib.rs gains only `mod report;` + one re-export
line; harness.rs `run` signature is untouched (`-> ()`). No engine / Harness
/ node-contract change — the cycle-0006 sink mechanism (C8/C22) is consumed
read-only, not altered.
- C1/C12: summarize is a total, pure, value-only reduction; the e2e test
asserts bit-identical metrics + JSON across two runs.
- C18 sequencing: ships manifest + metrics "from day one", explicitly defers
the registry/index to its later milestone. C14 structured face delivered as
hand-rolled JSON; the zero-dependency stance is preserved (all four crates
path-only deps).
- params-as-honest-precursor wording matches the 0008 typed-param-space
deferral (node.rs); f64_field panic-as-wiring-bug matches the engine's
existing "checked at wiring" convention.
Forward note (not drift, no contract speaks to it, spec documents it as an
accepted assumption): to_json renders f64 via `{}` and is valid JSON only under
the finite-value invariant — a NaN/Inf would emit bare NaN/inf tokens. The
invariant holds today (SimBroker integrates finite returns, Exposure clamps),
so C14 "machine-readable" is not breached. Worth a debug-assert or named
constant only if a future broker can produce non-finite equity — flag it then.
Regression gate: profile commands.regression is empty — no-op; architect is the
sole gate and is green. carry-on.
Cycle 0009 (Walking skeleton milestone). A run's two C18 "from day one"
artefacts — a reproducible manifest and summary metrics — land as a new,
pure-additive `report` module in aura-engine:
- summarize(equity, exposure) -> RunMetrics: a post-run pure reduction over a
run's recorded pip-equity + exposure streams. total_pips (last cumulative
value), max_drawdown (worst running-peak-to-trough), exposure_sign_flips (a
turnover proxy: adjacent normalized-sign changes, flat distinct from
long/short via a three-way sign0). Total and pure: empty -> zeros, identical
inputs -> identical metrics (C1/C12).
- RunManifest: the reproducible descriptor (commit, params as name->value
pairs, data-window, seed, broker label). Caller-supplied — the engine cannot
introspect a git commit or seed. params is the honest precursor to the
deferred typed param-space (node.rs; 0008 audit).
- RunReport { manifest, metrics } + to_json(): canonical, hand-rolled JSON for
the structured C14 face.
- f64_field(rows, field): bridges a recording sink's Vec<Scalar> rows to
summarize; panics on a kind/width mismatch (a wiring bug), like the engine's
other "checked at wiring" violations.
Why post-run, not a node: a node emits one record per eval with no terminal
eval (C8), so an end-of-run reduction has no home as a node; the World drains
its cycle-0006 recording sinks after Harness::run and folds them here. Matches
C18's "store manifests + metrics, re-derive results on demand".
Why hand-rolled JSON, not serde: the workspace is deliberately zero-dependency
and the schema is tiny/closed/flat; serde is reconsidered when the run-registry
milestone grows the schema. (User-approved at spec review.)
Scope: the surface + a determinism end-to-end test reusing the cycle-0007
two-sink harness; the `aura run` subcommand that prints the report is #8. No
engine/Harness/node-contract change; workspace stays zero-dependency.
Verified: cargo test --workspace green (aura-engine 40, incl. 10 new report
tests); clippy --all-targets -D warnings clean; RUSTDOCFLAGS=-D warnings cargo
doc clean.
closes#6
Six-task plan for the cycle-0009 report surface (issue #6): module scaffold +
RunMetrics/RunManifest/RunReport types (Task 1), the pure summarize reduction
(Task 2, RED-first), the f64_field recorded-stream adapter (Task 3, RED-first),
RunReport::to_json canonical zero-dep JSON (Task 4, RED-first), an end-to-end
determinism test reusing the cycle-0007 two-sink harness (Task 5), and the full
workspace gates (Task 6). Pure-additive in a new aura-engine report module; the
re-export line grows per task so the crate compiles at every boundary.
refs #6
Cycle 0009 (Walking skeleton milestone, issue #6): a post-run pure-function
reduction over the recorded pip-equity + exposure streams into summary metrics
(total pips, peak-to-trough drawdown, exposure sign-flip count) plus a
caller-supplied RunManifest (commit, params, data-window, seed, broker), paired
as RunReport with canonical hand-rolled zero-dep JSON (C14). Lives in a new
aura-engine report module; no engine/Harness/node-contract change.
The reduction is post-run, not a node (C8 caps a node at one record per eval
with no end-of-run eval); matches C18's manifest+metrics-per-run-from-day-one.
The `aura run` subcommand that prints the report is deferred to #8.
Grounding-check PASS (all load-bearing assumptions ratified by green tests /
authoritative sources). Spec-validation parse pass is a documented no-op (no
parser configured for the profile).
refs #6
Resolves the two spec_gaps from the cycle-0008 fieldtest
(docs/specs/fieldtest-0008-sum-combinators.md), the same class the 0007 fieldtest
raised for SimBroker (and which e9f4352 patched there) — the combinators shipped
without the equivalent note:
- per-input firing policy: both Add and every LinComb leg are Firing::Any
(mode-A as-of join) — the node fires on every cycle in which any leg is
fresh, once all legs have a value, pairing the fresh leg with the held value
of the others; None until all present (no cold-leg-as-0.0). A consumer
combining different-rate sources (e.g. an M5 signal with a daily-bias leg)
needs this to predict whether the bias is held-and-combined every cycle
(mode A, what ships) or only on rare both-fresh cycles (mode B).
- multi-row-per-timestamp: a fired node emits one row per *cycle*, and two
sources sharing a timestamp are two distinct cycles (C4 tie-break by source
order), so a recorded combined stream may carry >1 row per timestamp. Correct
and forced by C4/C5; ratified here, now stated on the surface so "one row per
timestamp" is not silently assumed.
Doc-only change; no behaviour change. Verified: RUSTDOCFLAGS="-D warnings" cargo
doc -p aura-std clean (intra-doc links to aura_core::Firing::Any resolve); clippy
--all-targets -D warnings clean; cargo test -p aura-std 14 passed.
refs #11
First fieldtest of the sum combinators. A standalone downstream-consumer crate
(fieldtests/cycle-0008-sum-combinators/) path-depends on the engine crates and
exercises the post-0008 surface from the public interface only (rustdoc + ledger
+ glossary + project-layout, never crates/*/src).
Primary axis empirically met: the north-star two-signal combine move now uses the
shipped Add (Add::new() dropped in exactly where the 0007 fixture hand-authored
an Add2) — the 0007 boilerplate is retired, end to end through SimBroker to a
deterministic recorded pip curve.
Findings: 0 bugs, 1 friction, 2 spec_gaps, 3 working.
- working ×3: Add2 retired; LinComb weighted/variadic sums exact (<1e-12);
warm-up barrier + empty-weights panic as documented.
- spec_gap: Add/LinComb per-input firing policy (Firing::Any / mode-A as-of
join) absent from the public surface — same class as the 0007 SimBroker gap.
- spec_gap: a fired combinator emits one row per *cycle*, so a heterogeneous
same-timestamp multi-source trace can carry >1 row per timestamp (correct per
C4/C5, undocumented at this surface).
- friction: nested consumer crate still needs the empty [workspace] table
(carried from 0006/0007; #9 closed the docs half; folds into aura new).
Spec feeds the next plan as reference.
Architect drift review (fa2835e..HEAD) at cycle close. Regression gate is a
no-op (commands.regression empty); architect is the sole gate.
What holds (no drift): purely additive C16 extension, one node per file, no
engine/manifest change; C2/C8 warm-up discipline correct (None until every leg
present, no implicit cold-leg 0.0); C7 zero per-cycle alloc. Shipping the named
convenience nodes Add (and pre-existing Sub) beside the general LinComb is NOT
C9 adapter-zoo drift — they are distinct named producers, not coercion shims,
mirroring the already-shipped Sub.
Fixed [ledger-gap/high]: lincomb.rs rustdoc and the feat commit body called the
weights "the node's tunable parameters (C8/C12)", but aura_core/src/node.rs
states tunable params (C12/C19) are deliberately not part of the schema yet
(spec 0002 "Out of scope"). The weights are construction parameters that
configure the node and fix its arity (C11) — the natural home for combination
tuning params once the schema-level param surface lands, but not yet surfaced to
any optimizer. Rustdoc reworded to say exactly that. No ledger change: the C8
text vs node.rs tension pre-exists this cycle and is already documented in
node.rs; only the new rustdoc over-claimed.
Carry-on [drift/high]: the cycle-0007 fieldtest still imports Sub-only and keeps
its hand-authored Add2 (acceptance said the fieldtest *can* drop it). The 0007
fieldtest crate is a historical snapshot of what that run did; rewriting it
retroactively would falsify why Add2 existed. The structural drop-in feasibility
(the acceptance content) is confirmed by the architect (add.rs == sub.rs modulo
operator; LinComb([1,1]) == Add; Add2 byte-identical to Add). End-to-end
demonstration belongs to a cycle-0008 fieldtest (fresh example on the shipped
node), dispatched next — not a retroactive edit of the 0007 record.
Gates: cargo test -p aura-std 14 passed / 0 failed; clippy --all-targets
-D warnings clean; RUSTDOCFLAGS="-D warnings" cargo doc -p aura-std clean.
aura-std shipped Sma, Sub, Exposure, SimBroker but no sum, so the north-star
"combine one signal with another" research move (C10) could not be expressed
from shipped blocks — the cycle-0007 fieldtest had to hand-author a project-local
Add2. This adds the missing combinator(s):
- Add — two-input f64 sum (a + b), the parameterless companion to Sub. Mirrors
sub.rs modulo the operator.
- LinComb { weights } — N-input weighted sum (Σ wᵢ·xᵢ). The weights are the
node's tunable parameters (C8/C12) and fix its arity (weights.len() inputs);
this is the form the north-star "combine A and B *with weights*" reaches for.
LinComb([1,1]) is Add; LinComb([1,-1]) is Sub.
Both withhold output (None) until *all* inputs are present — consistent with Sub,
and causally clean: a cold input leg is never silently folded in as 0.0.
LinComb::new panics on empty weights (build-time param error, like Sma::new).
Both ship because each is independently reached-for: Add for readability symmetry
with Sub, LinComb for the weighted/tunable combination — mirroring the project's
already-shipped choice to keep Sub as a named node beside a general form.
Hand-driven unit tests in the established aura-std style (5 new): Add sum, the
Add == LinComb([1,1]) identity, the N>2 warm-up, and the empty-weights panic.
Verified: cargo test -p aura-std (14 passed), clippy --all-targets -D warnings
clean, RUSTDOCFLAGS="-D warnings" cargo doc -p aura-std --no-deps clean.
closes#11
Brummel