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

[seonghobae]

Summary

psychometric_core recovers the Driver, Oud, and Voelkle (2017, §4.3, pp. 9–10; Eq. 3–5, pp. 4–5; Table 2, p. 12; p. 16; 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.

This is an independent companion of still-unmerged PR #310 (discreteDRIFTstd), PR #357 (asymptotes=TRUE DIFFUSION rewrite), PR #355 / #352 (asymptotes=TRUE TIPREDEFFECT rewrite), and PR #349 (asymptotes=TRUE CINT rewrite). It branches from origin/main 1bc02f58, does not wait for those drafts, and is not stacked on them. Closed PR #181 recovered this map on a predecessor of #49 and was dropped from current main (0ce16e8); github search recover_predetermined on current main is zero hits. Stationary later-occasion variance is already on main as recover_stationary_later_latent_variance. Predetermined first-occasion T0VAR is free p_0 and is not this later-occasion map.

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 (default in ctsem). The process gradually transitions from the variances of the initial parameters toward those of the parameters when the model is stationary. Between-subject TRAITVAR / addedTIPREDVAR are inherently 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 (unlike the stationary later-occasion map, which fails closed on a ≥ 0).

Fail-closed EventTime-only clocks, non-positive Δt, and invalid numeric input. Three refuse helpers: refuse_predetermined_later_latent_variance_as_stationary_later_variance, refuse_predetermined_later_latent_variance_as_discrete_variance, refuse_predetermined_later_latent_variance_as_initial_variance.

Meredith (1993) remains unread (Unpaywall historically is_oa: false; Springer content/pdf is an HTML stub). 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.

Plan

Fail-closed scalar recover_predetermined_later_latent_variance(trait, p_0, q, B, v, a, Δt, clock) as trait + e^{2 a Δt} p_0 + Q_Δt + (B / a)² v on origin/main, with three refuse helpers, three error variants, CHANGELOG, ADR 0005 timestamp, CLAUDE.md, research notes item 45 timestamp, and crate/contract tests. Independent of #310, #357, #355, #352, and #349.

Verification

• cargo clippy -p psychometric_core --all-targets -- -D warnings (clean)
• cargo test -p psychometric_core --lib (190 passed)
• cargo test -p psychometric_core --test multilevel_event_time_recovery_contract -- --exact recover_predetermined_later_latent_variance_matches_driver_total_variance refuse_predetermined_later_latent_variance_named_quantities_stay_distinct (2 passed)
• cargo test -p psychometric_core --test scientific_claim_boundary_contract -- --exact predetermined_later_latent_variance_is_not_stationary_later_or_discrete_or_initial (1 passed)

Do not rustfmt lib.rs (reorders types after functions).

Opened by: Grok Build (xAI) on behalf of Seongho Bae.

Do not merge without independent non-author APPROVE + exact-head required-check success. Do not convert from draft. Do not self-approve. Do not request Copilot.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[seonghobae]

Restack on protected main (a243f18)

Non-force merge of origin/main (merge commit be23cc71); the only conflict was the CHANGELOG.md append, both entries kept. cargo fmt --all --check flagged pre-existing layout diffs in four psychometric_core files; rustfmt applied (formatting only).

Local evidence on the pushed head (toolchain 1.98.0): cargo test -p psychometric_core 369 passed / 0 failed, clippy -D warnings clean, cargo fmt --all --check clean, documentation/workspace/docstring contracts PASS, git diff --check clean.

🤖 Generated with Claude Code