# Suite28 — Dynamic Readiness–Requirement Model (DRRM)

Frozen research implementation, based primarily on the user's **Suite28_research_and_design(1).md**, 7 October 2026. This package does not claim a new state of the art or prospective validation.

## Decision after reviewing the proposed design

**Accepted as the scientific primary:** proposed candidate B, *Dynamic Readiness–Requirement Model*. Its components are designed to be identifiable enough to falsify, not promised to be optimal.

**Essential modifications implemented:**

1. Preserve a single shared student/faculty readiness state across concurrent target courses. Only student–semester invariant whitelisted predictors enter the state forecast. Other raw fields do not silently make the state course-dependent.
2. Estimate all five historic course statistics (`hist_count`, `hist_mean`, `hist_std`, `hist_fail_rate`, `hist_pass_rate`) strictly from earlier-semester training outcomes. Cached historical course aggregates are not trusted as-is. Course identity residuals have support shrinkage and unknown-ID fallback.
3. Replace the incorrect Suite26 failure/ability sign: increasing readiness for a fixed course always reduces conditional failure probability.
4. Avoid a redundant separate difficulty scalar in the nonlinear bottleneck decoder. Course requirements **are** effective thresholds; dimensions have fixed equal bottleneck weights. In the MIRT comparator, course discrimination and a *single* scalar difficulty replace requirements.
5. Use **one ordinal likelihood** for grades and failure. The first grade bin is exactly `P(fail)`; a missing numeric grade with known failure status uses the binary marginal, not an additional independent BCE.
6. Use a full 4×4 Gaussian readiness covariance, one fixed damped Fisher update per semester, and fixed deterministic antithetic integration samples. Update all grades in a semester **after** predicting all course rows in that semester; never impose an invented within-semester order.
7. Include an independently refitted contextual-only B (identical decoder, update disabled), an independently trained compensatory MIRT A, and a full-common-feature HGB current-state control with faculty one-hot inputs. The HGB control is not inside DRRM.
8. Select only the epoch count on development **origins F4/F5**. F6/F7 do not determine epochs, dimension, temperature, course smoothing, decoder or any fusion weight. F6/F7 have previously informed this research program and are **historical reused holdouts**, not fresh prospective confirmation.
9. The model never receives Committee or earlier-suite predictions. Earlier models appear only as references, with strict coverage tables. No blending, tree head, MoE, graph, or retriever hides inside the primary.

## Exact model

For student `s`, faculty block `f` and semester `t` before outcomes:

`q^-(theta)=N(mu^-, Sigma^-)`, `theta∈R^K`, default `K=4`.

Current invariant student/semester covariates supply `u(x)` and positive definite `V(x)`. Forecast from the last released semester:

`mu^- = rho_Delta mu_previous^+ + (1-rho_Delta) u(x)`

`Sigma^- = rho_Delta^2 Sigma_previous^+ + (1-rho_Delta^2) V(x) + Delta Q`

where the retention is bounded and decreases with elapsed semesters, and `Q` is positive diagonal.

Course metadata = **12 static descriptors** plus **5 prior-only aggregates** and a log support count. With a faculty-scoped course ID `c`, `r_c = encoder(metadata) + count/(count+12) * ID_residual(c)`. Unknown IDs map to the identity-zero slot. Each faculty has a course-parameter block and ordinal threshold increments, while the basic network architecture and encoders are shared globally.

For a fixed `theta` and target course `c`, bottleneck deficit:

`D(theta,c) = tau * (logsumexp((r_c-theta)/tau)-log(K))`.

Success utility `u_sc = -D(theta,c)` and failure probability `sigmoid(-u_sc)`; default `tau=.65` and fixed decoder slope 1. Coordinates satisfy `∂P(fail|theta,c)/∂theta_k <= 0`.

One **coherent ordinal** six-bin likelihood uses boundaries `<5`, `5–6`, `6–7`, `7–8`, `8–9`, `9–10`. For grade boundary k, `P(G<k|theta)=sigmoid(kappa_k-u_sc)`; `kappa_5=0`, remaining four thresholds are cumulative positive increments, scoped to faculty. The cumulative differences are nonnegative and sum to one (up to floating-point). The first bin is **exactly** failure probability.

For semester observations with released outcomes `E_{s,t}`, evaluate analytic log-likelihood gradients `g_i` and expected Fisher information `F_i` at the pre-semester mean. Compute

`Prec_plus = inv(Sigma_minus) + discount * sum(F_i)`

`mu_plus = mu_minus + damping * solve(Prec_plus, discount * sum(g_i))`, `Sigma_plus = inv(Prec_plus)`.

All sums are over an **unordered set of same-semester outcomes**. Stable Cholesky solves are used. This is an **approximate Gaussian filter**, neither conjugate Bayesian inference nor a mathematically exact posterior. The update is differentiable and gradient flows to earlier courses for subsequent-semester forecasts. Training also applies a small (0.0005) zero-location anchor to batch-mean readiness coordinates; it discourages global translation without claiming complete factor identification. The conditional independence approximation may overstate precision when multiple grades share semester-level shocks.

Prediction is the marginal `E_{theta~q^-}[P(failure|theta,c)]`, estimated with **8 fixed antithetic draws** during training and **32** during evaluation. The training likelihood uses `-log(E_theta[p(observed outcome|theta,c)])`, *not* `E_theta[-log p]`.

## Causal/prequential information boundaries

- Historical bank for an origin contains only canonical **covered** history rows before that origin. Structured caches must have exactly matching `train_row_index`; mismatches abort.
- Course prior statistics use `source_semester < query_semester`; **same-semester outcomes are excluded**.
- At target evaluation, `label` is forced to **0** and `grade` forced to **NaN** in the model input. Target truth remains outside inference and is used only to compute metrics.
- A student's history is indexed by `(faculty, global_student_id)`. No trainable student-ID embedding exists.
- The current raw-feature generator remains external: the package can *check* student-semester invariance and as-of course aggregates, but cannot certify every upstream engineered feature. The log and manifest explicitly state this limitation.
- Numeric prior-semester grades are assumed released by the next semester because no grade-release timestamp is available. This is a source-data assumption, not something tested by the model.

## Models and hypotheses

| Output | Nature | Core question |
|---|---|---|
| `suite28_context_only` | Retained state forecast + bottleneck decoder, **no outcome assimilation**; independently refit | Is filtering the transcript better than valid current covariates? |
| `suite28_mirt` | Compensatory positive discrimination + one scalar difficulty, full filter | Is a bottleneck actually better than compensatory readiness? |
| **`suite28_drrm`** | **Primary**, nonlinear bottleneck + coherent grade likelihood + Gaussian filtering | Are multidimensional course deficits useful and temporally transferable? |
| `suite28_fulltab_hgb` | A single common-features HGB, no DRRM or Committee input | Did the constrained context ownership discard predictive tabular information? |
| `committee`, `suite22`, `suite25`, … | Saved earlier predictions only | How competitive is the primary relative to the strongest available previous systems? |
| Optional `suite28_k1` | Bottleneck K=1 | Do the data identify more than general readiness? |
| Optional `suite28_binary_only` | Same full filter, binary supervision instead of graded ordinal supervision | Does within-pass grade information help? |

A gain of `B - contextual-only` specifically supports filtered course-conditioned history; `B - MIRT` tests noncompensatory requirements. A model can beat both and still lose to strong GBDT/Committee references. An AP increase of about **0.02 over the best Suite22/Suite25 blend** would be a meaningful *target*, not an expected result.

## Development selection and fairness

- Select model epochs on independent historical **F4/F5 development origins**, each model fitted on that origin's earlier records and evaluated against the origin's same student-course rows.
- Development support: by default each faculty needs >=30 rows, >=3 positives, >=20 negatives, with 100% faculty coverage. Fail loudly if unsupported; options allow **explicit** changes with their use recorded in the manifest.
- Select epoch by macro AP over the two origins, F2@20 as tie breaker, then fewer epochs. One declared seed. Fixed `K=4`, `tau=.65`, `discount=.7`, `damping=.65`, optimizer AdamW.
- Final historic folds F1–F7 each independently refit permitted history to frozen selected epochs. **F6/F7 never select anything**. Differences between F4/F5 development selection and past suite-specific selection must be acknowledged.
- Operational thresholds are a separate, frozen **F1–F5** policy, transferred to F6/F7. Labels there cannot affect thresholds.
- Because former suites used these historical holdouts in research design, only a later unseen semester can provide a newly untouched prospective test.

## Mechanism diagnostics

1. Context-ownership audit, canonical/structured alignment, grade/label consistency, duplicate coarse ID checks, prior course support and unseen-course counts.
2. Faculty/fold AP, AUC, Brier, ECE, log-likelihood grade check, precision/recall/F2 by budget, fixed/drift operational confusion counts.
3. Filter retention, posterior covariance trace and eigenvalues, course projected predictive variance, history-support strata and no-history interventions.
4. Course-requirement centered effective rank, within-course dimension spread, known/rare/unseen course ID support and parameter scales.
5. Graded vs binary-only assimilation postfit, no-history, no-course-ID, same-faculty/same-semester historical outcome shuffling, mean-only uncertainty integration; independent **retrained** contextual/MIRT and optional K1/binary controls.
6. Paired faculty/fold comparison, student-cluster bootstrap, historical Council 13-fac overlap clearly labeled **not row-aligned**, and reference coverage errors explicit.
7. Runtime, model size, immutable code/config/source manifests, reproducible checkpoint weights and training-only processing artifacts.

This first experiment has no guarantee of identifying human-interpretable knowledge factors. Coordinates may be rotationally or permutationally unidentified and not linked across faculties. A bottleneck's gradient monotonicity is structural, **not causal**. No intervention recommendations should be inferred from latent factors alone.
