Aura/docs/plans/0008-sum-combinators.md

Sum Combinators (Add + LinComb) — Implementation Plan

Parent spec: docs/specs/0008-sum-combinators.md

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

Goal: Ship two new aura-std leaf nodes — Add (two-input f64 sum) and LinComb { weights } (N-input weighted sum) — so the north-star "combine signals" move (C10) is expressible from shipped blocks.

Architecture: Two additive leaf nodes, one file each, mirroring the existing sub.rs / sma.rs pattern (struct + Node impl + co-located hand-driven #[cfg(test)] tests). Add mirrors sub.rs modulo the + operator; LinComb carries a Vec<f64> weight param (assert-non-empty at construction, like Sma::new) and builds a variadic input schema from weights.len(). Both withhold output until every input is present (no implicit cold-leg 0.0). Each node is module-declared and re-exported in lib.rs. No aura-core change, no new dependency.

Tech Stack: aura-core Node/Ctx/NodeSchema/Scalar contract; crates/aura-std/.

---

Files this plan creates or modifies:

• Create: crates/aura-std/src/add.rs — Add leaf node + tests.
• Create: crates/aura-std/src/lincomb.rs — LinComb leaf node + tests.
• Modify: crates/aura-std/src/lib.rs:18-25 — module declarations + pub use exports for both nodes (alphabetical order).
• Test: crates/aura-std/src/add.rs (#[cfg(test)] mod tests) — sum-once-both-present.
• Test: crates/aura-std/src/lincomb.rs (#[cfg(test)] mod tests) — weighted sum, unit-weights-equal-Add identity, three-input warm-up, empty-weights panic.

Mirror templates (read-only, do not edit): crates/aura-std/src/sub.rs:1-70, crates/aura-std/src/sma.rs:16-19 (the assert! precedent). The aura_core import set (Ctx, FieldSpec, Firing, InputSpec, Node, NodeSchema, Scalar, ScalarKind, plus test-only AnyColumn, Timestamp) is re-exported from the aura_core crate root (crates/aura-core/src/lib.rs:38-43). crates/aura-std/ Cargo.toml already depends on aura-core — no manifest change.

---

Task 1: Add — two-input f64 sum

Files:

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

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

• Test: crates/aura-std/src/add.rs

• Step 1: Write the failing test + declare the module

Create crates/aura-std/src/add.rs with the top-level import set and the test module only (no Add struct yet — that is what makes the test fail):

//! `Add` — two-input f64 sum (input 0 plus input 1), the companion to `Sub`.
//! Combines two signal streams into one — the most basic combinator for the
//! north-star "combine one signal with another" research move (C10).

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

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

    #[test]
    fn add_is_sum_once_both_inputs_present() {
        let mut add = Add::new();
        let mut inputs = vec![
            AnyColumn::with_capacity(ScalarKind::F64, 1),
            AnyColumn::with_capacity(ScalarKind::F64, 1),
        ];

        // only input 0 present -> None
        inputs[0].push(Scalar::F64(10.0)).unwrap();
        assert_eq!(add.eval(Ctx::new(&inputs, Timestamp(0))), None);

        // both present -> a + b
        inputs[1].push(Scalar::F64(4.0)).unwrap();
        assert_eq!(add.eval(Ctx::new(&inputs, Timestamp(0))), Some([Scalar::F64(14.0)].as_slice()));
    }
}

Then declare the module in crates/aura-std/src/lib.rs — insert mod add; as the first line of the mod block (before mod exposure; at line 18):

mod add;
mod exposure;

• Step 2: Run test to verify it fails

Run: cargo test -p aura-std add_is_sum_once_both_inputs_present Expected: FAIL — compile error E0433/E0422 "failed to resolve" / "cannot find function, struct, or type Add in this scope" (the test references Add::new(), which does not exist yet).

• Step 3: Write the Add node + export it

Insert the struct and impls into crates/aura-std/src/add.rs between the top-level use line and the #[cfg(test)] line:

/// Two-input f64 sum: input 0 plus input 1. Emits `None` until both inputs
/// have a value.
pub struct Add {
    out: [Scalar; 1],
}

impl Add {
    /// Build an `Add` node.
    pub fn new() -> Self {
        Self { out: [Scalar::F64(0.0)] }
    }
}

impl Default for Add {
    fn default() -> Self {
        Self::new()
    }
}

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

    fn eval(&mut self, ctx: Ctx<'_>) -> Option<&[Scalar]> {
        let a = ctx.f64_in(0);
        let b = ctx.f64_in(1);
        if a.is_empty() || b.is_empty() {
            return None;
        }
        self.out[0] = Scalar::F64(a[0] + b[0]);
        Some(&self.out)
    }
}

Then export it from crates/aura-std/src/lib.rs — insert pub use add::Add; as the first line of the pub use block (before pub use exposure::Exposure; at line 22):

pub use add::Add;
pub use exposure::Exposure;

• Step 4: Run test to verify it passes

Run: cargo test -p aura-std add_is_sum_once_both_inputs_present Expected: PASS — test add::tests::add_is_sum_once_both_inputs_present ... ok.

---

Task 2: LinComb — N-input weighted sum

Files:

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

• Modify: crates/aura-std/src/lib.rs:19,23

• Test: crates/aura-std/src/lincomb.rs

• Step 1: Write the failing tests + declare the module

Create crates/aura-std/src/lincomb.rs with the top-level import set and the test module only (no LinComb struct yet):

//! `LinComb` — weighted sum of `N` f64 inputs (`Σ weights[i] · input[i]`), the
//! general combinator for the north-star "combine signals with weights" move
//! (C10). `LinComb([1.0, 1.0])` is `Add`; `LinComb([1.0, -1.0])` is `Sub`. The
//! weights are the node's tunable parameters (C8/C12) and fix its arity.

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

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

    #[test]
    fn lincomb_weighted_sum_once_all_present() {
        let mut lc = LinComb::new(vec![0.5, 2.0]);
        let mut inputs = vec![
            AnyColumn::with_capacity(ScalarKind::F64, 1),
            AnyColumn::with_capacity(ScalarKind::F64, 1),
        ];

        // only input 0 present -> None
        inputs[0].push(Scalar::F64(10.0)).unwrap();
        assert_eq!(lc.eval(Ctx::new(&inputs, Timestamp(0))), None);

        // both present -> 0.5*10 + 2.0*3 = 11.0
        inputs[1].push(Scalar::F64(3.0)).unwrap();
        assert_eq!(lc.eval(Ctx::new(&inputs, Timestamp(0))), Some([Scalar::F64(11.0)].as_slice()));
    }

    #[test]
    fn lincomb_unit_weights_equal_add() {
        let mut lc = LinComb::new(vec![1.0, 1.0]);
        let mut inputs = vec![
            AnyColumn::with_capacity(ScalarKind::F64, 1),
            AnyColumn::with_capacity(ScalarKind::F64, 1),
        ];
        inputs[0].push(Scalar::F64(7.0)).unwrap();
        inputs[1].push(Scalar::F64(5.0)).unwrap();
        // unit weights reproduce Add: 7 + 5
        assert_eq!(lc.eval(Ctx::new(&inputs, Timestamp(0))), Some([Scalar::F64(12.0)].as_slice()));
    }

    #[test]
    fn lincomb_three_inputs_warm_up() {
        let mut lc = LinComb::new(vec![1.0, 1.0, 1.0]);
        let mut inputs = vec![
            AnyColumn::with_capacity(ScalarKind::F64, 1),
            AnyColumn::with_capacity(ScalarKind::F64, 1),
            AnyColumn::with_capacity(ScalarKind::F64, 1),
        ];
        inputs[0].push(Scalar::F64(1.0)).unwrap();
        inputs[1].push(Scalar::F64(2.0)).unwrap();
        // third leg still cold -> None (withheld until every leg is present)
        assert_eq!(lc.eval(Ctx::new(&inputs, Timestamp(0))), None);

        inputs[2].push(Scalar::F64(3.0)).unwrap();
        // all warm -> 1 + 2 + 3
        assert_eq!(lc.eval(Ctx::new(&inputs, Timestamp(0))), Some([Scalar::F64(6.0)].as_slice()));
    }

    #[test]
    #[should_panic(expected = "LinComb needs at least one weight")]
    fn lincomb_empty_weights_panics() {
        let _ = LinComb::new(vec![]);
    }
}

Then declare the module in crates/aura-std/src/lib.rs — insert mod lincomb; between mod exposure; and mod sim_broker;:

mod exposure;
mod lincomb;
mod sim_broker;

• Step 2: Run tests to verify they fail

Run: cargo test -p aura-std lincomb Expected: FAIL — compile error E0433/E0422 "cannot find function, struct, or type LinComb in this scope" (the tests reference LinComb::new, which does not exist yet).

• Step 3: Write the LinComb node + export it

Insert the struct and impls into crates/aura-std/src/lincomb.rs between the top-level use line and the #[cfg(test)] line:

/// Weighted sum of `N` f64 inputs: `Σ weights[i] · input[i]`. The `weights`
/// are the node's tunable parameters and fix its arity (`weights.len()` inputs,
/// in slot order). Emits `None` until *all* inputs have a value.
pub struct LinComb {
    weights: Vec<f64>,
    out: [Scalar; 1],
}

impl LinComb {
    /// Build a `LinComb` with one weight per input (at least one required).
    ///
    /// # Panics
    /// Panics if `weights` is empty.
    pub fn new(weights: Vec<f64>) -> Self {
        assert!(!weights.is_empty(), "LinComb needs at least one weight");
        Self { weights, out: [Scalar::F64(0.0)] }
    }
}

impl Node for LinComb {
    fn schema(&self) -> NodeSchema {
        NodeSchema {
            inputs: self
                .weights
                .iter()
                .map(|_| InputSpec { kind: ScalarKind::F64, lookback: 1, firing: Firing::Any })
                .collect(),
            output: vec![FieldSpec { name: "value", kind: ScalarKind::F64 }],
        }
    }

    fn eval(&mut self, ctx: Ctx<'_>) -> Option<&[Scalar]> {
        let mut acc = 0.0;
        for (i, &w) in self.weights.iter().enumerate() {
            let w_in = ctx.f64_in(i);
            if w_in.is_empty() {
                return None; // not yet warmed up — withhold until every leg is present
            }
            acc += w * w_in[0];
        }
        self.out[0] = Scalar::F64(acc);
        Some(&self.out)
    }
}

Then export it from crates/aura-std/src/lib.rs — insert pub use lincomb::LinComb; between pub use exposure::Exposure; and pub use sim_broker::SimBroker;:

pub use exposure::Exposure;
pub use lincomb::LinComb;
pub use sim_broker::SimBroker;

• Step 4: Run tests to verify they pass

Run: cargo test -p aura-std lincomb Expected: PASS — all four lincomb::tests::* tests ... ok (lincomb_weighted_sum_once_all_present, lincomb_unit_weights_equal_add, lincomb_three_inputs_warm_up, lincomb_empty_weights_panics).

---

Task 3: Crate-wide gates

Files: none (verification only).

• Step 1: Full test suite

Run: cargo test -p aura-std Expected: PASS — all existing aura-std tests plus the five new ones (add::tests::add_is_sum_once_both_inputs_present and the four lincomb::tests::*); 0 failed.

• Step 2: Clippy, warnings denied

Run: cargo clippy -p aura-std --all-targets -- -D warnings Expected: PASS — no warnings. (Add has a Default impl so clippy::new_without_default does not fire; LinComb::new takes an argument so the lint does not apply.)

• Step 3: Doc build, warnings denied

Run: RUSTDOCFLAGS="-D warnings" cargo doc -p aura-std --no-deps Expected: PASS — clean; the new intra-doc references (Sub, Add) resolve.