diff --git a/docs/plans/0008-sum-combinators.md b/docs/plans/0008-sum-combinators.md new file mode 100644 index 0000000..6a2f5c4 --- /dev/null +++ b/docs/plans/0008-sum-combinators.md @@ -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` 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, + 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) -> 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.