feat(psychometric): recover Eq. 5 of 2017-era commented discreteTRAITVAR on main

CHANGELOG.md

@@ -38,6 +38,7 @@ All notable changes to TEPP are documented here. The format follows Keep a Chang
 
 ## [Unreleased]
 
+- `psychometric_core` recovers Equation 5 of 2017-era commented `discreteTRAITVAR` as `λ² (1 − e^{a Δt})² (trait / a²) + θ` on current main (Driver, Oud, & Voelkle, 2017, Eq. 5, p. 5; Eq. 3, p. 5; Table 2, p. 12; §4.3, p. 9; p. 16; 2017-era ctsem `summary.ctsemFit.R`; JSS PDF re-opened 2026-08-31T05:20Z from https://www.jstatsoft.org/index.php/jss/article/download/v077i05/1104). cran/ctsem 2.5.0 `summary.ctsemFit.R` comments `discreteTRAITVAR <- (I − expm(DRIFT * Δt)) %*% asymTRAITVAR %*% t(...)` with `asymTRAITVAR <- solve(DRIFT) %*% TRAITVAR %*% t(solve(DRIFT))`. Those names are not in the active `outlist`. Form `e^{a Δt}` via the exact scalar lag, form `1 − e^{a Δt}` then square, form `1 / a` first then square then multiply by `trait`, multiply, then `λ²` plus `θ`. Do not form `λ²` first. Do not export the unstandardised discrete trait. Do not import unpublished `#330` / `#343` / `#347` helpers. A zero loading is exactly `θ`. A zero trait is exactly `θ` even if `a ≥ 0`. `a ≥ 0` with a nonzero trait fails closed. Numeric: `a = −0.5`, `Δt = 1`, `trait = 1`, `λ = 2`, `θ = 0.3` recovers 2.7770899479388076, distinct from unstandardised discrete trait 0.619..., from untransformed `TRAITVAR` 1, from `TRAITVARstd` 1, and from `MANIFESTVAR` 0.3. A non-event clock fails closed. Meredith (1993) remains unread (Unpaywall 2026-08-31T05:10Z: `is_oa: false`; Springer `content/pdf` is an HTML stub; escholarship hits are citations). Mislevy (1991, *Psychometrika, 56*, 177–196, DOI 10.1007/bf02294457) remains unread on the same terms. Still not a Kalman filter, not a matrix `expm`, not ESEM estimation, not DSEM, and not ctsem estimation.
 - Removed the repository-local hourly PR-maintenance caller now covered by the central required scheduler, retired stale workflow registrations, narrowed documentation triggers, keyed PR concurrency by fixed workflow name, repository, and pull-request number without cancelling non-PR runs, and combined line/branch coverage on one sequential runner while preserving both 100% gates and diagnostics.
 
 - `event_core` adds bounded Allen interval-consistency classification, atomic path-consistency closure, contradiction/resource refusals, and an explicit dependency-error fallback without claiming unrestricted global satisfiability.

crates/psychometric_core/src/error.rs

@@ -710,6 +710,28 @@ pub enum PsychometricError {
     /// `MANIFESTVARstd`. `λ² Var(η) + θ` is `Var(y)`, not the
     /// correlation form of `Θ`.
     ObservedVarianceIsNotStandardisedManifestVariance,
+    /// Eq. 5 of 2017-era commented `discreteTRAITVAR` was requested
+    /// for a non-stable drift. That map is
+    /// `λ² (1 − e^{a Δt})² (trait / a²) + θ` and requires `a < 0`
+    /// when the trait is nonzero. A zero trait is exactly `θ` even
+    /// if `a ≥ 0`.
+    DiscreteTraitObservedVarianceRequiresStableDrift,
+    /// Unstandardised 2017-era commented `discreteTRAITVAR`
+    /// `(1 − e^{a Δt})² (trait / a²)` was treated as Eq. 5 of that
+    /// map. The latent discrete trait is not `Var(y)`.
+    UnstandardisedDiscreteTraitVarianceIsNotDiscreteTraitObservedVariance,
+    /// Untransformed `TRAITVAR` was treated as Eq. 5 of 2017-era
+    /// commented `discreteTRAITVAR`. `trait` is not
+    /// `λ² (1 − e^{a Δt})² (trait / a²) + θ`.
+    UnstandardisedTraitVarianceIsNotDiscreteTraitObservedVariance,
+    /// Driver Table 2 `MANIFESTVAR` `θ` was treated as Eq. 5 of
+    /// 2017-era commented `discreteTRAITVAR`. Measurement error is
+    /// not `Var(y)` when the loading and discrete trait are nonzero.
+    MeasurementErrorIsNotDiscreteTraitObservedVariance,
+    /// Driver p. 16 `TRAITVARstd` was treated as Eq. 5 of 2017-era
+    /// commented `discreteTRAITVAR`. `trait / trait = 1` is not
+    /// `λ² (1 − e^{a Δt})² (trait / a²) + θ`.
+    StandardisedTraitVarianceIsNotDiscreteTraitObservedVariance,
 }
 
 impl fmt::Display for PsychometricError {
@@ -1235,6 +1257,21 @@ impl fmt::Display for PsychometricError {
             Self::ObservedVarianceIsNotStandardisedManifestVariance => {
                 "observed-indicator variance is not standardised measurement-error variance"
             }
+            Self::DiscreteTraitObservedVarianceRequiresStableDrift => {
+                "discrete-trait observed variance requires a stable negative drift"
+            }
+            Self::UnstandardisedDiscreteTraitVarianceIsNotDiscreteTraitObservedVariance => {
+                "unstandardised discrete trait variance is not discrete-trait observed variance"
+            }
+            Self::UnstandardisedTraitVarianceIsNotDiscreteTraitObservedVariance => {
+                "unstandardised trait variance is not discrete-trait observed variance"
+            }
+            Self::MeasurementErrorIsNotDiscreteTraitObservedVariance => {
+                "measurement error is not discrete-trait observed variance"
+            }
+            Self::StandardisedTraitVarianceIsNotDiscreteTraitObservedVariance => {
+                "standardised trait variance is not discrete-trait observed variance"
+            }
         };
         formatter.write_str(message)
     }
@@ -2073,4 +2110,31 @@ mod tests {
             "measurement error is not standardised manifest-trait variance"
         );
     }
+
+    #[test]
+    fn discrete_trait_observed_variance_boundary_messages_are_stable() {
+        assert_eq!(
+            PsychometricError::DiscreteTraitObservedVarianceRequiresStableDrift.to_string(),
+            "discrete-trait observed variance requires a stable negative drift"
+        );
+        assert_eq!(
+            PsychometricError::UnstandardisedDiscreteTraitVarianceIsNotDiscreteTraitObservedVariance
+                .to_string(),
+            "unstandardised discrete trait variance is not discrete-trait observed variance"
+        );
+        assert_eq!(
+            PsychometricError::UnstandardisedTraitVarianceIsNotDiscreteTraitObservedVariance
+                .to_string(),
+            "unstandardised trait variance is not discrete-trait observed variance"
+        );
+        assert_eq!(
+            PsychometricError::MeasurementErrorIsNotDiscreteTraitObservedVariance.to_string(),
+            "measurement error is not discrete-trait observed variance"
+        );
+        assert_eq!(
+            PsychometricError::StandardisedTraitVarianceIsNotDiscreteTraitObservedVariance
+                .to_string(),
+            "standardised trait variance is not discrete-trait observed variance"
+        );
+    }
 }