From e9f4352640e42c4e4ccbb385ee90aeaae2b56e83 Mon Sep 17 00:00:00 2001 From: Brummel Date: Thu, 4 Jun 2026 17:31:20 +0200 Subject: [PATCH] docs(aura-std): document SimBroker input slots + firing/warm-up shape MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Resolves the two spec_gaps from the cycle-0007 fieldtest (docs/specs/fieldtest-0007-signal-quality.md): the consumer-facing SimBroker struct rustdoc stated only the integration formula, leaving two things a downstream author cannot infer from the public surface — - input slot order (slot 0 = exposure, slot 1 = price). Both slots are f64, so a swapped wiring is NOT caught at bootstrap (no kind mismatch) and silently yields a wrong-but-plausible equity curve. The order is now documented as load-bearing on the struct doc, with that hazard called out. - firing / warm-up emission shape: both inputs are Firing::Any, so the broker fires on every price-fresh cycle and reads a cold exposure leg as flat 0.0 — emitting equity rows (leading 0.0s) from the first price tick, one per price cycle, not one per exposure value. A consumer needs this to predict the recorded curve's length and leading values. Doc-only change; no behaviour change. Verified: RUSTDOCFLAGS="-D warnings" cargo doc -p aura-std clean (intra-doc links to crate::Exposure and aura_core::Firing resolve); clippy -p aura-std --all-targets -D warnings clean. refs #5 Co-Authored-By: Claude Opus 4.8 (1M context) --- crates/aura-std/src/sim_broker.rs | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/crates/aura-std/src/sim_broker.rs b/crates/aura-std/src/sim_broker.rs index 837e49d..422f8af 100644 --- a/crates/aura-std/src/sim_broker.rs +++ b/crates/aura-std/src/sim_broker.rs @@ -9,6 +9,30 @@ use aura_core::{Ctx, FieldSpec, Firing, InputSpec, Node, NodeSchema, Scalar, Sca /// Integrates `exposure * price-return` into cumulative pips. `pip_size` is /// per-instrument reference metadata (beside the hot path, C7/C15), held here, /// never streamed. +/// +/// # Input slots +/// +/// Two `f64` inputs, **order is load-bearing** (both are `f64`, so a swapped +/// wiring is *not* caught at bootstrap — it would silently produce a wrong +/// equity curve): +/// +/// - **slot 0 — exposure** ∈ [-1, +1] (the strategy's intent, e.g. from +/// [`Exposure`](crate::Exposure)). +/// - **slot 1 — price** (the instrument price the exposure is marked against). +/// +/// # Firing and warm-up +/// +/// Both inputs are [`Firing::Any`](aura_core::Firing::Any), so the broker fires +/// on **every price-fresh cycle** (price is typically the source tick). A +/// not-yet-warmed exposure leg is read as flat `0.0`, so the broker emits an +/// equity row from the **first** price tick, reading `0.0` until the exposure +/// leg produces its first value — the recorded curve therefore has one row per +/// price cycle, with leading `0.0`s during warm-up, not one row per exposure. +/// +/// # Output +/// +/// One `f64` column, the cumulative pip equity (a producer; tap it with a +/// recording sink to persist the curve). pub struct SimBroker { pip_size: f64, prev_price: Option,