feat(recovery): nested mixedmirt random-effect RMSE evidence

.github/workflows/R-CMD-check.yaml

@@ -36,25 +36,42 @@ jobs:
 
       - uses: r-lib/actions/setup-pandoc@d3c5be51b12e724e68f33216ca3c148b66d5f0b6 # v2
 
-      - uses: r-lib/actions/setup-r@6f6e5bc62fba3a704f74e7ad7ef7676c5c6a2590 # v2
+      - uses: r-lib/actions/setup-r@d3c5be51b12e724e68f33216ca3c148b66d5f0b6 # v2
         with:
           r-version: ${{ matrix.config.r }}
           http-user-agent: ${{ matrix.config.http-user-agent }}
           use-public-rspm: true
 
-      - uses: r-lib/actions/setup-r-dependencies@6f6e5bc62fba3a704f74e7ad7ef7676c5c6a2590 # v2
+      # Build stringfish before dependency setup because packages built during
+      # resolution can load it and fail on a prebuilt oneTBB ABI mismatch.
+      - name: Source-build stringfish before dependency resolution
+        run: >-
+          Rscript -e 'install.packages(c("RcppParallel", "stringfish"), type = "source",
+          repos = "https://cloud.r-project.org")'
+
+      - uses: r-lib/actions/setup-r-dependencies@d3c5be51b12e724e68f33216ca3c148b66d5f0b6 # v2
         with:
+          # Refresh the dependency cache after the macOS qs2/RcppParallel TBB ABI mismatch.
+          cache-version: '2'
           extra-packages: |
             any::rcmdcheck
             any::testthat
           needs: check
 
+      # Rebuild every installed package that links to RcppParallel against the
+      # same local oneTBB ABI before loading kaefa or its test dependencies.
+      - name: Rebuild RcppParallel-linked packages from source
+        run: >-
+          Rscript -e 'r <- "https://cloud.r-project.org"; install.packages("RcppParallel", type = "source", repos = r);
+          linked <- tools::dependsOnPkgs("RcppParallel", dependencies = "LinkingTo");
+          if (length(linked)) install.packages(linked, type = "source", repos = r)'
+
       - name: Run Zh formula regression tests
         run: |
           Rscript -e 'install.packages(".", repos = NULL, type = "source")'
           Rscript -e 'library(kaefa); testthat::test_file("tests/testthat/test-zh-misfit-decision-rule.R")'
 
-      - uses: r-lib/actions/check-r-package@6f6e5bc62fba3a704f74e7ad7ef7676c5c6a2590 # v2
+      - uses: r-lib/actions/check-r-package@d3c5be51b12e724e68f33216ca3c148b66d5f0b6 # v2
         with:
           error-on: '"error"'
           upload-snapshots: true

.github/workflows/test-fast.yaml

@@ -16,15 +16,30 @@ jobs:
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
-      - uses: r-lib/actions/setup-r@6f6e5bc62fba3a704f74e7ad7ef7676c5c6a2590 # v2
+      - uses: r-lib/actions/setup-r@d3c5be51b12e724e68f33216ca3c148b66d5f0b6 # v2
         with:
           use-public-rspm: true
 
-      - uses: r-lib/actions/setup-r-dependencies@6f6e5bc62fba3a704f74e7ad7ef7676c5c6a2590 # v2
+      # Build stringfish before dependency setup because packages built during
+      # resolution can load it and fail on a prebuilt oneTBB ABI mismatch.
+      - name: Source-build stringfish before dependency resolution
+        run: >-
+          Rscript -e 'install.packages(c("RcppParallel", "stringfish"), type = "source",
+          repos = "https://cloud.r-project.org")'
+
+      - uses: r-lib/actions/setup-r-dependencies@d3c5be51b12e724e68f33216ca3c148b66d5f0b6 # v2
         with:
           extra-packages: any::testthat
           needs: check
 
+      # Rebuild every installed package that links to RcppParallel against the
+      # same local oneTBB ABI before loading kaefa or its test dependencies.
+      - name: Rebuild RcppParallel-linked packages from source
+        run: >-
+          Rscript -e 'r <- "https://cloud.r-project.org"; install.packages("RcppParallel", type = "source", repos = r);
+          linked <- tools::dependsOnPkgs("RcppParallel", dependencies = "LinkingTo");
+          if (length(linked)) install.packages(linked, type = "source", repos = r)'
+
       - name: Install kaefa package for fast tests
         run: R CMD INSTALL .
 
@@ -38,4 +53,8 @@ jobs:
                               reporter = reporter)
           testthat::test_file("tests/testthat/test-core-api-contract.R",
                               reporter = reporter)
+          testthat::test_file("tests/testthat/test-aefa-parameter-recovery.R",
+                              reporter = reporter)
+          testthat::test_file("tests/testthat/test-mixedmirt-parameter-recovery.R",
+                              reporter = reporter)
           RSCRIPT

.github/workflows/test-suite.yaml

@@ -1,7 +1,8 @@
 name: test-suite
 
-# Runs the complete testthat suite (26 files), which the previous CI setup
-# skipped: R-CMD-check runs with --no-tests and test-fast runs only 3 files.
+# Runs the complete testthat suite, which the previous CI setup skipped:
+# R-CMD-check runs with --no-tests and test-fast runs a small productization
+# subset.
 # On push/PR the suite's own CI guards (.skip_expensive_ci_calls, skip_on_ci)
 # keep expensive AEFA estimations out. The weekly scheduled run and manual
 # dispatch set RUN_FULL_AEFA_TESTS=1, which unlocks the estimations guarded
@@ -32,15 +33,30 @@ jobs:
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
-      - uses: r-lib/actions/setup-r@6f6e5bc62fba3a704f74e7ad7ef7676c5c6a2590 # v2
+      - uses: r-lib/actions/setup-r@d3c5be51b12e724e68f33216ca3c148b66d5f0b6 # v2
         with:
           use-public-rspm: true
 
-      - uses: r-lib/actions/setup-r-dependencies@6f6e5bc62fba3a704f74e7ad7ef7676c5c6a2590 # v2
+      # Build stringfish before dependency setup because packages built during
+      # resolution can load it and fail on a prebuilt oneTBB ABI mismatch.
+      - name: Source-build stringfish before dependency resolution
+        run: >-
+          Rscript -e 'install.packages(c("RcppParallel", "stringfish"), type = "source",
+          repos = "https://cloud.r-project.org")'
+
+      - uses: r-lib/actions/setup-r-dependencies@d3c5be51b12e724e68f33216ca3c148b66d5f0b6 # v2
         with:
           extra-packages: any::testthat
           needs: check
 
+      # Rebuild every installed package that links to RcppParallel against the
+      # same local oneTBB ABI before loading kaefa or its test dependencies.
+      - name: Rebuild RcppParallel-linked packages from source
+        run: >-
+          Rscript -e 'r <- "https://cloud.r-project.org"; install.packages("RcppParallel", type = "source", repos = r);
+          linked <- tools::dependsOnPkgs("RcppParallel", dependencies = "LinkingTo");
+          if (length(linked)) install.packages(linked, type = "source", repos = r)'
+
       - name: Install kaefa package
         run: R CMD INSTALL .
 

AGENTS.md

@@ -11,6 +11,7 @@ Use this file as the local operating guide when modifying `kaefa`.
 - Core orchestration: `R/kaefa.R`
 - Estimation engine: `R/newEngine.R`
 - Shared helpers: `R/utils.R`
+- Recovery protocol: `R/recovery.R`
 - Shiny app: `inst/shiny-app/app.R`
 - Tests: `tests/testthat/`
 - Local CI workflow definitions: `.github/workflows/`

ARCHITECTURE.md

@@ -1,6 +1,6 @@
 # kaefa Architecture
 
-Last updated: 2026-02-14
+Last updated: 2026-08-17
 
 ## Purpose
 
@@ -32,7 +32,11 @@ explicitly requires vendored source integration.
 
 - `R/kaefa.R`: public orchestration entry points and exported runtime behavior.
 - `R/newEngine.R`: candidate-model estimation engine used by the AEFA loop.
-- `R/utils.R`: helper routines and shared utilities.
+- `R/utils.R`: helper routines and shared utilities. `.mirt()` and
+  `.mixedmirt()` treat a missing (`NA`) second-order test as
+  non-convergence when `leniency` is false.
+- `R/recovery.R`: internal true-parameter RMSE helpers used by the AEFA
+  and nested mixedmirt recovery protocols. Not a public API.
 - `inst/shiny-app/app.R`: bundled Shiny interface logic.
 - `inst/shiny-app/README.md`: Shiny usage and minimal UI configuration guide.
 - `tests/testthat/*.R`: functional, regression, and integration tests.
@@ -58,6 +62,13 @@ explicitly requires vendored source integration.
 
 - PR merge requires review approval and resolved conversations.
 - Required checks include R-CMD-check matrix and dependency review.
+- Buyer-facing recovery evidence is the five-repeat RMSE protocol in
+  `tests/testthat/test-aefa-parameter-recovery.R` and the nested mixedmirt
+  contracts in `tests/testthat/test-mixedmirt-parameter-recovery.R`. The
+  formula, alignment, and coverage-exclusion contracts run in `test-fast`.
+  Live `aefa()` and five-seed `.mixedmirt` recovery are gated by
+  `RUN_FULL_AEFA_TESTS=1`. One-seed `.mirt` and `.mixedmirt` recovery fits
+  run in the full suite.
 - If code scanning is enabled later, alerts can be tracked via GitHub code
   scanning APIs.
 

CLAUDE.md

@@ -57,6 +57,10 @@ testthat::test_file("tests/testthat/test-shiny-product-surface.R",
                     reporter = reporter)
 testthat::test_file("tests/testthat/test-core-api-contract.R",
                     reporter = reporter)
+testthat::test_file("tests/testthat/test-aefa-parameter-recovery.R",
+                    reporter = reporter)
+testthat::test_file("tests/testthat/test-mixedmirt-parameter-recovery.R",
+                    reporter = reporter)
 RSCRIPT
 
 # R CMD check as CI runs it (note: tests are skipped here)
@@ -124,6 +128,8 @@ psychometrics (see AGENTS.md).
 - `R/newEngine.R` — `engineAEFA()`: the candidate-model estimation engine used
   by the aefa loop (MCMC/estimation controls such as NCYCLES, BURNIN,
   SEMCYCLES, rotation choices, etc.).
+- `R/recovery.R` — internal true-parameter RMSE helpers for the AEFA and
+  nested mixedmirt recovery protocols (not exported).
 - `R/utils.R` — shared internals (`.mirt`/`.mixedmirt` wrappers around mirt,
   `.covdataClassifieder`, `.covdataFixedEffectComb`, `.exportParmsEME`) and the
   theta-prior utilities `fitThetaPrior()`, `testThetaPriorCalibration()`,