feat(psychometric): recover Driver later-occasion variance of predetermined T0VAR on main

CHANGELOG.md

@@ -38,6 +38,8 @@ All notable changes to TEPP are documented here. The format follows Keep a Chang
 
 ## [Unreleased]
 
+- `psychometric_core` recovers the Driver, Oud, and Voelkle (2017, §4.3, pp. 9–10; Eq. 3–4, pp. 4–5; Table 2, p. 12; p. 16; §7.2, pp. 20–21; JSS PDF re-opened 2026-08-31T09:29Z from https://www.jstatsoft.org/index.php/jss/article/download/v077i05/1104) scalar later-occasion variance of §4.3 predetermined `T0VAR` on current main after `0ce16e8` dropped the pre-consolidation code while research notes already named the map (register item 45). Section 4.3 treats the first time point as predetermined when no assumptions are made about the process prior to the initial time point. Free `T0VAR` `p_0` is then estimated. The process gradually transitions from the variances of the initial parameters toward those of the parameters when the model is stationary. Equation 3 writes `η(t) = exp(A Δt) η(t0) + … +` the stochastic integral. Equation 4 writes that the integral exhibits covariance `Q_Δt`. The law of total variance on the within-subject state is `e^{2 a Δt} p_0 + Q_Δt`. Trait variance and `addedTIPREDVAR` are time-invariant between-subject and do not enter that process-noise integral. The later-occasion composition is `trait + e^{2 a Δt} p_0 + Q_Δt + (B / a)² v`. Form the evolved free first-occasion variance first, then include the trait, then include the TI extra variance, then add. Setting `p_0 = −q / (2 a)` recovers the stationary later-occasion map. Stationary later-occasion variance uses `−q / (2 a)` in place of `p_0` and is not this map when `p_0` is free. Evolving `trait + p_0 + (B / a)² v` as if it were all state is not this map. Free `T0VAR` `p_0` is not this map. As `Δt → ∞` with stable `a < 0` the composition approaches contemporaneous stationary `T0VAR`. As `Δt → 0+` the composition approaches `trait + p_0 + (B / a)² v`. Nonzero diffusion with `a ≥ 0` is a growing process and is kept. `a ≥ 0` with a nonzero TI contribution fails closed. A non-event clock, a non-positive interval, and an overflowing product or sum fail closed. Meredith (1993) remains unread (Unpaywall historically `is_oa: false`; title *Measurement Invariance, Factor Analysis and Factorial Invariance*). Mislevy (1991, *Psychometrika, 56*, 177–196) remains unread on the same terms. Still not a Kalman filter, not a matrix `expm`, not ESEM estimation, not DSEM, and not ctsem estimation.
+
 - `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.
 
 - `psychometric_core` recovers the Driver, Oud, and Voelkle (2017, Table 2, p. 12 `MANIFESTTRAITVAR`; §7.1, p. 19; p. 16 `MANIFESTTRAITVARstd`; footnote 4; 2017-era ctsem `summary.ctsemFit.R`; JSS PDF re-opened 2026-08-27T14:20Z from https://www.jstatsoft.org/index.php/jss/article/download/v077i05/1104) scalar standardised manifest-trait variance on current main after `0ce16e8` dropped the pre-consolidation code while research notes already named the map (register items 83–84). Table 2 names `MANIFESTTRAITVAR` `Ψ_τ` the additional time-invariant variance-covariance on the measurement level and sets it `NULL` when there is no manifest trait. Equation 5 writes `Γ ~ N(τ, Ψ)` and names that covariance the manifest traits. Section 7.1 names manifest traits stable individual differences in indicator levels, distinct from process-level `TRAITVAR` `φ_ξ`. Page 16 prints standardised matrices with the suffix `std` when appropriate. The printed example on p. 16 is `discreteDRIFTstd`, not `MANIFESTTRAITVARstd`. Footnote 4 standardises using only the relevant variance, not the total. The relevant variance for that named indicator-level correlation is `MANIFESTTRAITVAR`, not process-level `TRAITVAR` and not residual `MANIFESTVAR` `θ`. The 2017-era source forms `MANIFESTTRAITVARstd` only when `MANIFESTTRAITVAR != 0`, as `solve(sqrt(diag(MANIFESTTRAITVAR) + ridging)) %&% MANIFESTTRAITVAR` when `verbose = TRUE`. OpenMx `%&%` is `t(A) %*% B %*% A`. Unlike `TRAITVARstd`, that formation adds `diag(c(ridging), n.manifest)`. The default `ridging = FALSE` adds 0, not `0.0001`; that ridge is a numerical hack and is not this exact map. The scalar correlation is `ψ / ψ = 1` after strictly positive `MANIFESTTRAITVAR`. Form strictly positive `ψ` first, then `1 / √ψ`, then `(1 / √ψ) ψ (1 / √ψ)`. Unstandardised `MANIFESTTRAITVAR` is defined for a zero trait; standardised `MANIFESTTRAITVAR` is not. Zero `MANIFESTTRAITVAR` skips forming `MANIFESTTRAITVARstd` in the 2017-era source and fails closed here. Indicator-level trait variance is an event-time structural quantity, so a non-event clock fails closed. `MANIFESTTRAITVAR` does not require stable `a < 0`. Distinct positive `ψ` recover the same 1. `trait / trait = 1` is `TRAITVARstd` and recovers the same number and remains a distinct named quantity. `θ` is `MANIFESTVAR` and is measurement error, not this correlation. Meredith (1993) remains unread (web search 2026-08-27T14:20Z: Springer/Cambridge Core paywalled; Unpaywall historically `is_oa: false`; Springer `content/pdf` is an HTML stub). Mislevy (1991, *Psychometrika, 56*, 177–196) remains unread on the same terms (DOI `10.1007/bf02294457`). Still not a Kalman filter, not a matrix `expm`, not ESEM estimation, not DSEM, and not ctsem estimation.

crates/psychometric_core/src/error.rs

@@ -504,6 +504,18 @@ pub enum PsychometricError {
     /// later-occasion stationary observed variance. Lagged covariance
     /// omits `Q_Δt` and `θ`.
     StationaryLaggedObservedCovarianceIsNotStationaryLaterObservedVariance,
+    /// Driver §4.3 later-occasion predetermined variance was treated
+    /// as later-occasion stationary variance. Free `T0VAR` `p_0` is
+    /// not `−q / (2 a)` when the first occasion is predetermined.
+    PredeterminedLaterLatentVarianceIsNotStationaryLaterVariance,
+    /// Driver §4.3 later-occasion predetermined variance was treated
+    /// as the free discrete evolution of `trait + p_0 + (B / a)² v`.
+    /// Trait variance and `addedTIPREDVAR` do not enter `Q_Δt`.
+    PredeterminedLaterLatentVarianceIsNotDiscreteVariance,
+    /// Driver §4.3 later-occasion predetermined variance was treated
+    /// as free first-occasion `T0VAR`. `p_0` is the start, not
+    /// `trait + e^{2 a Δt} p_0 + Q_Δt + (B / a)² v`.
+    PredeterminedLaterLatentVarianceIsNotInitialVariance,
     /// Driver p. 16 `CINTstd` was requested without a strictly positive
     /// `asymDIFFUSION`. Footnote 4 standardises using only the
     /// relevant variance; zero `q` has no positive process SD.
@@ -1105,6 +1117,15 @@ impl fmt::Display for PsychometricError {
             Self::StationaryLaggedObservedCovarianceIsNotStationaryLaterObservedVariance => {
                 "stationary lagged observed covariance is not the stationary later-occasion observed variance"
             }
+            Self::PredeterminedLaterLatentVarianceIsNotStationaryLaterVariance => {
+                "predetermined later-occasion latent variance is not the stationary later-occasion latent variance"
+            }
+            Self::PredeterminedLaterLatentVarianceIsNotDiscreteVariance => {
+                "predetermined later-occasion latent variance is not the free discrete latent variance"
+            }
+            Self::PredeterminedLaterLatentVarianceIsNotInitialVariance => {
+                "predetermined later-occasion latent variance is not the free first-occasion latent variance"
+            }
             Self::StandardisedContinuousInterceptRequiresPositiveStationaryVariance => {
                 "standardised continuous intercept requires strictly positive stationary within-subject variance"
             }
@@ -1852,6 +1873,23 @@ mod tests {
         );
     }
 
+    #[test]
+    fn predetermined_later_variance_boundary_messages_are_stable() {
+        assert_eq!(
+            PsychometricError::PredeterminedLaterLatentVarianceIsNotStationaryLaterVariance
+                .to_string(),
+            "predetermined later-occasion latent variance is not the stationary later-occasion latent variance"
+        );
+        assert_eq!(
+            PsychometricError::PredeterminedLaterLatentVarianceIsNotDiscreteVariance.to_string(),
+            "predetermined later-occasion latent variance is not the free discrete latent variance"
+        );
+        assert_eq!(
+            PsychometricError::PredeterminedLaterLatentVarianceIsNotInitialVariance.to_string(),
+            "predetermined later-occasion latent variance is not the free first-occasion latent variance"
+        );
+    }
+
     #[test]
     fn standardised_continuous_intercept_boundary_messages_are_stable() {
         assert_eq!(