feat(longitudinal): keep unit means out of within-unit change

ARCHITECTURE.md

@@ -61,6 +61,7 @@ boundaries above remain the target modular MSA architecture.
 | `tepp_simulation` | known-truth temporal/event data generation |
 | `validation_core` | RMSE, bias, coverage, graph, and Monte Carlo metrics |
 | `tepp_api` | versioned DTO, schema, and export contracts |
+| `longitudinal_core` | active-PR: within/between decomposition; refuse between-as-within; component RMSE |
 | `topic_lineage` | global topic identity across active/dormant/reactivated states |
 | `network_analysis` | compositional cluster-pair gates; raw simplex is not Euclidean |
 | `interpretation_gateway` | evidence-bounded LLM interpretations; not estimators or observed facts |

CHANGELOG.md

@@ -6,6 +6,7 @@ All notable changes to TEPP are documented here. The format follows Keep a Chang
 
 ### Added
 
+- `longitudinal_core` within/between decomposition: unit means stay between-unit components, occasion residuals stay within-unit change, and recovered components match known truth with lower computed RMSE than a grand-mean pooled collapse.
 - `topic_lineage` global P0 topic identity: activity may become dormant or reactivated without minting a new identity, and recovered identities match known truth at a higher computed rate than mint-on-reactivate replacements.
 - `interpretation_gateway` evidence-bounded LLM interpretations: proposals must cite at least one evidence span, remain hypothetical, cannot become estimator results or observed facts, and a cited interpreter records a lower computed unsupported-claim rate than uncited promotion.
 - `model_selection` candidate-`K` gates: statistical candidates require `K >= 2` and finite held-out log-likelihood/complexity, a Pareto front excludes dominated alternatives, LLM votes cannot define the numerical optimum, and selected `K` recovers known truth with computed RMSE.

Cargo.toml

@@ -11,6 +11,7 @@ members = [
     "crates/tepp_simulation",
     "crates/validation_core",
     "crates/tepp_api",
+    "crates/longitudinal_core",
     "crates/topic_lineage",
     "crates/network_analysis",
     "crates/interpretation_gateway",
@@ -28,6 +29,7 @@ default-members = [
     "crates/tepp_simulation",
     "crates/validation_core",
     "crates/tepp_api",
+    "crates/longitudinal_core",
     "crates/topic_lineage",
     "crates/network_analysis",
     "crates/interpretation_gateway",

README.md

@@ -6,6 +6,12 @@ implemented in Rust.
 
 ## Current implementation state
 
+This branch establishes the Rust workspace, quality-gate foundation, and the
+longitudinal within/between decomposition capability. The eleven bounded crates
+compile independently. `longitudinal_core` exposes within/between decomposition
+and component RMSE APIs; the remaining crates expose no placeholder production
+APIs, and domain behavior for them begins in Task 2 with immutable evidence
+identifiers and source records.
 This branch establishes the Task 1 Rust workspace and quality-gate foundation.
 The eleven bounded crates compile independently but intentionally expose no
 placeholder production APIs. Domain behavior begins in Task 2 with immutable
@@ -22,6 +28,7 @@ crates/corpus_split
 crates/tepp_simulation
 crates/validation_core
 crates/tepp_api
+crates/longitudinal_core
 crates/topic_lineage
 crates/network_analysis
 crates/interpretation_gateway

crates/longitudinal_core/Cargo.toml

@@ -0,0 +1,17 @@
+[package]
+name = "longitudinal_core"
+description = "Within/between decomposition gates and component RMSE."
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+authors.workspace = true
+repository.workspace = true
+homepage.workspace = true
+readme.workspace = true
+keywords.workspace = true
+categories.workspace = true
+publish = false
+
+[lints]
+workspace = true

crates/longitudinal_core/src/component.rs

@@ -0,0 +1,185 @@
+//! Known-truth RMSE for within/between components.
+
+use crate::{ComponentLevel, LongitudinalError};
+
+/// One unit-specific within or between component.
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub struct ComponentValue {
+    unit_index: u32,
+    occasion_index: u32,
+    level: ComponentLevel,
+    value: f64,
+}
+
+impl ComponentValue {
+    /// Construct a component record from its identity fields and raw value.
+    ///
+    /// The value is stored exactly as given, including non-finite values;
+    /// this constructor performs no validation.
+    #[must_use]
+    pub const fn new(
+        unit_index: u32,
+        occasion_index: u32,
+        level: ComponentLevel,
+        value: f64,
+    ) -> Self {
+        Self {
+            unit_index,
+            occasion_index,
+            level,
+            value,
+        }
+    }
+
+    /// Return the unit index.
+    #[must_use]
+    pub const fn unit_index(self) -> u32 {
+        self.unit_index
+    }
+
+    /// Return the occasion index.
+    #[must_use]
+    pub const fn occasion_index(self) -> u32 {
+        self.occasion_index
+    }
+
+    /// Return the component level.
+    #[must_use]
+    pub const fn level(self) -> ComponentLevel {
+        self.level
+    }
+
+    /// Return the component value.
+    #[must_use]
+    pub const fn value(self) -> f64 {
+        self.value
+    }
+}
+
+/// RMSE of recovered components against known-truth components.
+///
+/// The sum of squared residuals is accumulated with max-magnitude scaling so
+/// large finite residuals cannot overflow to infinity.
+///
+/// # Errors
+///
+/// Returns [`LongitudinalError::InvalidComponentPayload`] when either slice is
+/// empty, the lengths differ, a unit/occasion/level identity mismatches, a
+/// value or a computed residual is non-finite.
+pub fn component_root_mean_square_error(
+    truth: &[ComponentValue],
+    decided: &[ComponentValue],
+) -> Result<f64, LongitudinalError> {
+    if truth.is_empty() || truth.len() != decided.len() {
+        return Err(LongitudinalError::InvalidComponentPayload);
+    }
+    let mut scale = 0.0_f64;
+    let mut scaled_sum_squares = 0.0_f64;
+    for (truth_row, decided_row) in truth.iter().zip(decided) {
+        if truth_row.unit_index() != decided_row.unit_index()
+            || truth_row.occasion_index() != decided_row.occasion_index()
+            || truth_row.level() != decided_row.level()
+            || !truth_row.value().is_finite()
+            || !decided_row.value().is_finite()
+        {
+            return Err(LongitudinalError::InvalidComponentPayload);
+        }
+        let residual = decided_row.value() - truth_row.value();
+        if !residual.is_finite() {
+            return Err(LongitudinalError::InvalidComponentPayload);
+        }
+        let magnitude = residual.abs();
+        if magnitude > scale {
+            let ratio = scale / magnitude;
+            scaled_sum_squares = 1.0 + scaled_sum_squares * ratio * ratio;
+            scale = magnitude;
+        } else if scale > 0.0 {
+            let ratio = magnitude / scale;
+            scaled_sum_squares += ratio * ratio;
+        }
+    }
+    Ok(scale * (scaled_sum_squares / truth.len() as f64).sqrt())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{ComponentValue, component_root_mean_square_error};
+    use crate::{ComponentLevel, LongitudinalError};
+
+    #[test]
+    fn maximal_residuals_do_not_overflow() {
+        let truth = [
+            ComponentValue::new(0, 0, ComponentLevel::Between, 0.0),
+            ComponentValue::new(1, 0, ComponentLevel::Between, 0.0),
+        ];
+        let maxed = [
+            ComponentValue::new(0, 0, ComponentLevel::Between, f64::MAX),
+            ComponentValue::new(1, 0, ComponentLevel::Between, f64::MAX),
+        ];
+        assert_eq!(
+            component_root_mean_square_error(&truth, &maxed),
+            Ok(f64::MAX)
+        );
+        let partial_extreme = [
+            ComponentValue::new(0, 0, ComponentLevel::Between, f64::MAX),
+            ComponentValue::new(1, 0, ComponentLevel::Between, 0.0),
+        ];
+        let expected = f64::MAX / f64::sqrt(2.0);
+        let got = component_root_mean_square_error(&truth, &partial_extreme).expect("scaled rmse");
+        assert!((got - expected).abs() <= expected * 4.0 * f64::EPSILON);
+    }
+
+    #[test]
+    fn overflowing_residual_fails_closed() {
+        let truth = [ComponentValue::new(0, 0, ComponentLevel::Within, -f64::MAX)];
+        let decided = [ComponentValue::new(0, 0, ComponentLevel::Within, f64::MAX)];
+        assert_eq!(
+            component_root_mean_square_error(&truth, &decided),
+            Err(LongitudinalError::InvalidComponentPayload)
+        );
+    }
+
+    #[test]
+    fn mismatched_identity_and_nan_fail_closed() {
+        let truth = [ComponentValue::new(0, 0, ComponentLevel::Between, 0.5)];
+        let other_unit = [ComponentValue::new(1, 0, ComponentLevel::Between, 0.5)];
+        assert_eq!(
+            component_root_mean_square_error(&truth, &other_unit),
+            Err(LongitudinalError::InvalidComponentPayload)
+        );
+        let other_level = [ComponentValue::new(0, 0, ComponentLevel::Within, 0.5)];
+        assert_eq!(
+            component_root_mean_square_error(&truth, &other_level),
+            Err(LongitudinalError::InvalidComponentPayload)
+        );
+        let other_occasion = [ComponentValue::new(0, 1, ComponentLevel::Between, 0.5)];
+        assert_eq!(
+            component_root_mean_square_error(&truth, &other_occasion),
+            Err(LongitudinalError::InvalidComponentPayload)
+        );
+        let nan = [ComponentValue::new(0, 0, ComponentLevel::Between, f64::NAN)];
+        assert_eq!(
+            component_root_mean_square_error(&truth, &nan),
+            Err(LongitudinalError::InvalidComponentPayload)
+        );
+        let nan_truth = [ComponentValue::new(0, 0, ComponentLevel::Between, f64::NAN)];
+        assert_eq!(
+            component_root_mean_square_error(&nan_truth, &truth),
+            Err(LongitudinalError::InvalidComponentPayload)
+        );
+        assert_eq!(
+            component_root_mean_square_error(&truth, &[]),
+            Err(LongitudinalError::InvalidComponentPayload)
+        );
+        let valid = [ComponentValue::new(0, 0, ComponentLevel::Between, 0.5)];
+        assert_eq!(component_root_mean_square_error(&truth, &valid), Ok(0.0));
+        assert_eq!(
+            component_root_mean_square_error(&[], &valid),
+            Err(LongitudinalError::InvalidComponentPayload)
+        );
+        assert_eq!(
+            ComponentValue::new(2, 3, ComponentLevel::Within, 0.1).occasion_index(),
+            3
+        );
+    }
+}