plan: 0008 sum combinators (Add + LinComb)

Bite-sized RED-first plan for the two new aura-std nodes. Task 1 ships Add (mirrors sub.rs modulo operator), Task 2 ships LinComb (Vec<f64> weights param, variadic schema, empty-weights panic), Task 3 the crate-wide test/clippy/doc gates. No engine change. refs #11
2026-06-04 18:05:56 +02:00
parent 288e75e7fd
commit 23e4cdae14
1 changed files with 356 additions and 0 deletions
@@ -0,0 +1,356 @@
+# 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):
+
+```rust
+//! `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):
+
+```rust
+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:
+
+```rust
+/// 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):
+
+```rust
+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):
+
+```rust
+//! `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;`:
+
+```rust
+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:
+
+```rust
+/// 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;`:
+
+```rust
+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.