Aura/docs/plans/0007-signal-quality-loop.md

Signal-quality loop — exposure stream + sim-optimal broker — Implementation Plan

Parent spec: docs/specs/0007-signal-quality-loop.md

For agentic workers: REQUIRED SUB-SKILL: use the implement skill to run this plan. Steps use - [ ] checkboxes for tracking.

Goal: Ship the signal-quality loop — two aura-std nodes (Exposure, SimBroker) and an end-to-end harness that backtests a moving-average-cross signal's quality as a synthetic pip-equity curve.

Architecture: Exposure { scale } clamps a raw signal score into a bounded exposure ∈ [-1,+1]; SimBroker { pip_size } integrates the return earned by the exposure held into each cycle (decided at t-1, no look-ahead) into cumulative pips. Both are plain structs in aura-std; the engine (aura-core/aura-engine) is untouched — the end-to-end tests live in the existing aura-engine harness test module, which already dev-depends on aura-std.

Tech Stack: aura-std (new node modules + re-exports), aura-engine harness test module (new end-to-end tests), aura-core Node/Ctx contract (used verbatim).

---

Files this plan creates or modifies:

• Create: crates/aura-std/src/exposure.rs — the Exposure node + unit tests.
• Create: crates/aura-std/src/sim_broker.rs — the SimBroker node + unit tests.
• Modify: crates/aura-std/src/lib.rs:18-21 — declare + re-export the two modules.
• Modify: crates/aura-engine/src/harness.rs — two end-to-end tests in the existing #[cfg(test)] mod tests (before its closing brace), and extend the use aura_std::{Sma, Sub}; import (test-module line ~340).
• Test: crates/aura-std/src/exposure.rs — clamp band + warm-up filter.
• Test: crates/aura-std/src/sim_broker.rs — lagged integration, no-look-ahead, flat-during-warmup, first-cycle.
• Test: crates/aura-engine/src/harness.rs — signal-quality loop records pip equity; loop is deterministic.

Note: the spec's worked example calls a helper named price_stream; the real helper in the harness test module is f64_stream (harness.rs:344). The end-to-end tests below use f64_stream — the spec name was illustrative.

---

Task 1: Exposure node (aura-std)

Files:

• Create: crates/aura-std/src/exposure.rs

• Modify: crates/aura-std/src/lib.rs:18-21

• Step 1: Write the Exposure node

Create crates/aura-std/src/exposure.rs:

//! `Exposure` — shapes a raw signal score into a bounded exposure (intent).
//! The decision/sizing node of C10's chain `signals -> decision/sizing node ->
//! exposure stream`: one f64 input, one f64 output `clamp(signal / scale, -1, +1)`.
//! `scale` sets which signal magnitude maps to full exposure (sizing lives here).

use aura_core::{Ctx, FieldSpec, Firing, InputSpec, Node, NodeSchema, Scalar, ScalarKind};

/// Bounded exposure from a raw signal score: `clamp(signal / scale, -1.0, +1.0)`.
/// Emits `None` until its input is present (warm-up filter, C8).
pub struct Exposure {
    scale: f64,
    out: [Scalar; 1],
}

impl Exposure {
    /// Build an exposure node with saturation magnitude `scale` (must be > 0).
    pub fn new(scale: f64) -> Self {
        assert!(scale > 0.0, "Exposure scale must be > 0");
        Self { scale, out: [Scalar::F64(0.0)] }
    }
}

impl Node for Exposure {
    fn schema(&self) -> NodeSchema {
        NodeSchema {
            inputs: vec![InputSpec { kind: ScalarKind::F64, lookback: 1, firing: Firing::Any }],
            output: vec![FieldSpec { name: "exposure", kind: ScalarKind::F64 }],
        }
    }

    fn eval(&mut self, ctx: Ctx<'_>) -> Option<&[Scalar]> {
        let w = ctx.f64_in(0);
        if w.is_empty() {
            return None; // not yet warmed up (C8 filter)
        }
        self.out[0] = Scalar::F64((w[0] / self.scale).clamp(-1.0, 1.0));
        Some(&self.out)
    }
}

• Step 2: Append the unit tests

Append to crates/aura-std/src/exposure.rs:

#[cfg(test)]
mod tests {
    use super::*;
    use aura_core::{AnyColumn, Timestamp};

    #[test]
    fn exposure_clamps_to_unit_band() {
        let mut e = Exposure::new(0.5);
        let mut inputs = vec![AnyColumn::with_capacity(ScalarKind::F64, 1)];
        // (raw signal, expected clamped exposure) for scale 0.5
        let cases = [
            (0.1_f64, 0.2_f64), // within band
            (0.5, 1.0),         // at the high edge
            (1.0, 1.0),         // saturates high
            (-0.1, -0.2),       // within band, negative
            (-1.0, -1.0),       // saturates low
        ];
        for (sig, want) in cases {
            inputs[0].push(Scalar::F64(sig)).unwrap();
            assert_eq!(
                e.eval(Ctx::new(&inputs, Timestamp(0))),
                Some([Scalar::F64(want)].as_slice())
            );
        }
    }

    #[test]
    fn exposure_is_none_until_input_present() {
        let mut e = Exposure::new(0.5);
        let inputs = vec![AnyColumn::with_capacity(ScalarKind::F64, 1)];
        assert_eq!(e.eval(Ctx::new(&inputs, Timestamp(0))), None);
    }
}

• Step 3: Register the exposure module in lib.rs

In crates/aura-std/src/lib.rs, replace lines 18-21:

mod sma;
mod sub;
pub use sma::Sma;
pub use sub::Sub;

with:

mod exposure;
mod sma;
mod sub;
pub use exposure::Exposure;
pub use sma::Sma;
pub use sub::Sub;

(Only exposure is registered here — Task 2 adds the sim_broker line once that file exists. Registering mod sim_broker; now, before sim_broker.rs exists, would fail the Step 4 compile/test gate: a filtered cargo test still compiles the whole crate.)

• Step 4: Run the Exposure tests

Run: cargo test -p aura-std --lib exposure:: Expected: PASS — test result: ok. 2 passed (exposure::tests::exposure_clamps_to_unit_band, exposure::tests::exposure_is_none_until_input_present).

---

Task 2: SimBroker node (aura-std)

Files:

• Create: crates/aura-std/src/sim_broker.rs

• Step 1: Write the SimBroker node

Create crates/aura-std/src/sim_broker.rs:

//! `SimBroker` — the sim-optimal broker (class (a) of C10): deterministic,
//! frictionless, perfect-fill. Consumes an exposure stream (slot 0) + a price
//! stream (slot 1) and integrates the return earned by the exposure held INTO
//! each cycle (decided at t-1) into a cumulative synthetic pip-equity output.
//! Measures signal quality, not execution-modelled P&L.

use aura_core::{Ctx, FieldSpec, Firing, InputSpec, Node, NodeSchema, Scalar, ScalarKind};

/// Integrates `exposure * price-return` into cumulative pips. `pip_size` is
/// per-instrument reference metadata (beside the hot path, C7/C15), held here,
/// never streamed.
pub struct SimBroker {
    pip_size: f64,
    prev_price: Option<f64>,
    prev_exposure: f64, // exposure held into this cycle (decided at t-1); 0.0 = flat
    cum: f64,           // cumulative pips
    out: [Scalar; 1],
}

impl SimBroker {
    /// Build a sim-optimal broker for an instrument whose pip is `pip_size`
    /// (price units per pip; must be > 0).
    pub fn new(pip_size: f64) -> Self {
        assert!(pip_size > 0.0, "SimBroker pip_size must be > 0");
        Self {
            pip_size,
            prev_price: None,
            prev_exposure: 0.0,
            cum: 0.0,
            out: [Scalar::F64(0.0)],
        }
    }
}

impl Node for SimBroker {
    fn schema(&self) -> NodeSchema {
        NodeSchema {
            inputs: vec![
                InputSpec { kind: ScalarKind::F64, lookback: 1, firing: Firing::Any }, // 0 exposure
                InputSpec { kind: ScalarKind::F64, lookback: 1, firing: Firing::Any }, // 1 price
            ],
            output: vec![FieldSpec { name: "equity", kind: ScalarKind::F64 }],
        }
    }

    fn eval(&mut self, ctx: Ctx<'_>) -> Option<&[Scalar]> {
        let price = ctx.f64_in(1);
        if price.is_empty() {
            return None; // no price yet — nothing to mark
        }
        let price = price[0];
        let expo = ctx.f64_in(0).first().copied().unwrap_or(0.0); // flat until exposure warms up
        if let Some(pp) = self.prev_price {
            self.cum += self.prev_exposure * (price - pp) / self.pip_size;
        }
        self.prev_price = Some(price);
        self.prev_exposure = expo; // update AFTER taking PnL — no look-ahead (C2)
        self.out[0] = Scalar::F64(self.cum);
        Some(&self.out)
    }
}

• Step 2: Append the unit tests

Append to crates/aura-std/src/sim_broker.rs:

#[cfg(test)]
mod tests {
    use super::*;
    use aura_core::{AnyColumn, Timestamp};

    fn two_f64_inputs() -> Vec<AnyColumn> {
        vec![
            AnyColumn::with_capacity(ScalarKind::F64, 1),
            AnyColumn::with_capacity(ScalarKind::F64, 1),
        ]
    }

    // Drive one broker cycle by hand: optionally push an exposure into slot 0
    // (None models a cycle where the exposure chain has not warmed up — slot 0
    // stays empty) and a price into slot 1, then eval and return the equity.
    fn step(b: &mut SimBroker, inputs: &mut [AnyColumn], expo: Option<f64>, price: f64) -> f64 {
        if let Some(e) = expo {
            inputs[0].push(Scalar::F64(e)).unwrap();
        }
        inputs[1].push(Scalar::F64(price)).unwrap();
        match b.eval(Ctx::new(inputs, Timestamp(0))) {
            Some([Scalar::F64(v)]) => *v,
            other => panic!("expected Some([F64]), got {other:?}"),
        }
    }

    #[test]
    fn sim_broker_integrates_lagged_exposure_times_return() {
        let mut b = SimBroker::new(1.0);
        let mut inputs = two_f64_inputs();
        assert_eq!(step(&mut b, &mut inputs, Some(0.5), 100.0), 0.0); // no prev price
        assert_eq!(step(&mut b, &mut inputs, Some(0.5), 110.0), 5.0); // 0.5*(110-100)
        assert_eq!(step(&mut b, &mut inputs, Some(-1.0), 108.0), 4.0); // +0.5*(108-110) = -1
        assert_eq!(step(&mut b, &mut inputs, Some(-1.0), 100.0), 12.0); // +(-1)*(100-108) = +8
    }

    #[test]
    fn sim_broker_no_lookahead() {
        let mut b = SimBroker::new(1.0);
        let mut inputs = two_f64_inputs();
        step(&mut b, &mut inputs, Some(1.0), 100.0);
        // exposure flips to 0.0 THIS cycle, but the PnL must use the 1.0 held
        // into it: 1.0*(110-100) = 10. Using the fresh 0.0 would give 0.
        assert_eq!(step(&mut b, &mut inputs, Some(0.0), 110.0), 10.0);
    }

    #[test]
    fn sim_broker_is_flat_during_warmup() {
        let mut b = SimBroker::new(1.0);
        let mut inputs = two_f64_inputs();
        // exposure never pushed (slot 0 empty) -> treated as flat; equity stays 0
        assert_eq!(step(&mut b, &mut inputs, None, 100.0), 0.0);
        assert_eq!(step(&mut b, &mut inputs, None, 110.0), 0.0);
        assert_eq!(step(&mut b, &mut inputs, None, 90.0), 0.0);
    }

    #[test]
    fn sim_broker_first_cycle_has_no_pnl() {
        let mut b = SimBroker::new(1.0);
        let mut inputs = two_f64_inputs();
        assert_eq!(step(&mut b, &mut inputs, Some(1.0), 100.0), 0.0); // no prev price to mark
    }
}

• Step 3: Register the sim_broker module in lib.rs

In crates/aura-std/src/lib.rs, replace the post-Task-1 module block:

mod exposure;
mod sma;
mod sub;
pub use exposure::Exposure;
pub use sma::Sma;
pub use sub::Sub;

with:

mod exposure;
mod sim_broker;
mod sma;
mod sub;
pub use exposure::Exposure;
pub use sim_broker::SimBroker;
pub use sma::Sma;
pub use sub::Sub;

• Step 4: Run the SimBroker tests

Run: cargo test -p aura-std --lib sim_broker:: Expected: PASS — test result: ok. 4 passed (sim_broker_integrates_lagged_exposure_times_return, sim_broker_no_lookahead, sim_broker_is_flat_during_warmup, sim_broker_first_cycle_has_no_pnl).

---

Task 3: End-to-end signal-quality tests (aura-engine)

Files:

• Modify: crates/aura-engine/src/harness.rs (test module use aura_std import + two new tests before the module's closing brace)

• Step 1: Extend the test-module aura_std import

In crates/aura-engine/src/harness.rs, inside #[cfg(test)] mod tests, replace:

    use aura_std::{Sma, Sub};

with:

    use aura_std::{Exposure, Sma, SimBroker, Sub};

• Step 2: Add the pip-equity recording test

Add inside #[cfg(test)] mod tests (before its closing brace) in crates/aura-engine/src/harness.rs:

    #[test]
    fn signal_quality_loop_records_pip_equity() {
        let (tx_eq, rx_eq) = mpsc::channel();
        let mut h = Harness::bootstrap(
            vec![
                Box::new(Sma::new(2)),                              // 0 fast
                Box::new(Sma::new(4)),                              // 1 slow
                Box::new(Sub::new()),                               // 2 raw signal
                Box::new(Exposure::new(0.5)),                       // 3 exposure
                Box::new(SimBroker::new(0.0001)),                   // 4 pip equity
                Box::new(Recorder::new(&[ScalarKind::F64], Firing::Any, tx_eq)), // 5 sink
            ],
            vec![SourceSpec {
                kind: ScalarKind::F64,
                targets: vec![
                    Target { node: 0, slot: 0 }, // price -> SMA fast
                    Target { node: 1, slot: 0 }, // price -> SMA slow
                    Target { node: 4, slot: 1 }, // price -> broker price input
                ],
            }],
            vec![
                Edge { from: 0, to: 2, slot: 0, from_field: 0 }, // fast     -> Sub.0
                Edge { from: 1, to: 2, slot: 1, from_field: 0 }, // slow     -> Sub.1
                Edge { from: 2, to: 3, slot: 0, from_field: 0 }, // signal   -> Exposure
                Edge { from: 3, to: 4, slot: 0, from_field: 0 }, // exposure -> broker.0
                Edge { from: 4, to: 5, slot: 0, from_field: 0 }, // equity   -> recorder
            ],
        )
        .expect("valid signal-quality harness");

        h.run(vec![f64_stream(&[
            (1, 1.0000),
            (2, 1.0010),
            (3, 1.0025),
            (4, 1.0020),
            (5, 1.0040),
        ])]);

        let equity: Vec<(Timestamp, Vec<Scalar>)> = rx_eq.try_iter().collect();
        // broker fires every cycle (price fresh each tick): five records, ts 1..=5
        assert_eq!(equity.len(), 5);
        assert_eq!(
            equity.iter().map(|(t, _)| t.0).collect::<Vec<_>>(),
            vec![1, 2, 3, 4, 5]
        );
        // flat until SMA(4) warms (cycle 4) and the held exposure meets the next
        // price move (cycle 5): the first four equities are exactly 0.
        for (_, row) in &equity[0..4] {
            assert_eq!(row, &vec![Scalar::F64(0.0)]);
        }
        // cycle 5: prev_exposure 0.00175 * (1.0040 - 1.0020) / 0.0001 = 0.035 pips
        let Scalar::F64(last) = equity[4].1[0] else {
            panic!("equity is f64");
        };
        assert!((last - 0.035).abs() < 1e-9, "final equity = {last}, want ~0.035");
    }

• Step 3: Add the determinism test

Add inside #[cfg(test)] mod tests (before its closing brace) in crates/aura-engine/src/harness.rs:

    #[test]
    fn signal_quality_loop_is_deterministic() {
        let build = || {
            let (tx, rx) = mpsc::channel();
            let mut h = Harness::bootstrap(
                vec![
                    Box::new(Sma::new(2)),
                    Box::new(Sma::new(4)),
                    Box::new(Sub::new()),
                    Box::new(Exposure::new(0.5)),
                    Box::new(SimBroker::new(0.0001)),
                    Box::new(Recorder::new(&[ScalarKind::F64], Firing::Any, tx)),
                ],
                vec![SourceSpec {
                    kind: ScalarKind::F64,
                    targets: vec![
                        Target { node: 0, slot: 0 },
                        Target { node: 1, slot: 0 },
                        Target { node: 4, slot: 1 },
                    ],
                }],
                vec![
                    Edge { from: 0, to: 2, slot: 0, from_field: 0 },
                    Edge { from: 1, to: 2, slot: 1, from_field: 0 },
                    Edge { from: 2, to: 3, slot: 0, from_field: 0 },
                    Edge { from: 3, to: 4, slot: 0, from_field: 0 },
                    Edge { from: 4, to: 5, slot: 0, from_field: 0 },
                ],
            )
            .expect("valid harness");
            h.run(vec![f64_stream(&[
                (1, 1.0000),
                (2, 1.0010),
                (3, 1.0025),
                (4, 1.0020),
                (5, 1.0040),
            ])]);
            rx.try_iter().collect::<Vec<(Timestamp, Vec<Scalar>)>>()
        };
        assert_eq!(build(), build());
    }

• Step 4: Run the end-to-end tests

Run: cargo test -p aura-engine --lib signal_quality Expected: PASS — test result: ok. 2 passed (signal_quality_loop_records_pip_equity, signal_quality_loop_is_deterministic).

---

Task 4: Full workspace gates

Files: none (verification only)

• Step 1: Full test suite

Run: cargo test --workspace Expected: PASS — all crates green, including the 6 new tests (2 exposure, 4 sim_broker) and 2 new engine end-to-end tests; no prior test regressed.

• Step 2: Clippy, warnings-as-errors

Run: cargo clippy --workspace --all-targets -- -D warnings Expected: clean — no warnings, exit 0.

• Step 3: Engine surface-purity grep

Run: git grep -nE 'dyn Any|Rc<|RefCell<' -- 'crates/aura-engine/src/*.rs' 'crates/aura-core/src/*.rs' Expected: no matches (exit 1) — the new nodes are plain structs in aura-std; aura-engine/aura-core source carries no interior mutability. (SimBroker/Exposure are defined in aura-std, referenced only from the engine's test module — the engine non-test surface stays domain-free.)