# Suite29 v2 — Code and experimental-contract audit

## Architectural components and exact wiring

1. Group rows by `(faculty_idx, student ID, target_NHHK)`. Never concatenate courses from different students, different semesters, or different faculties. Row indices are retained for reconstruction of the original prediction order.
2. Load the same per-row common raw schema and 17 previously engineered target-course features used by Suite25; keep row-specific features rather than treating the common schema as a shared student state.
3. Fit mean/std and calendar-semester normalization using the permitted historical train portion only; store those transformations in the final checkpoint.
4. Encode each course row with a **single shared** MLP, learned faculty embedding, and normalized semester feature.
5. Project each course token into multi-head queries, keys, and values. Append a globally learned null key and value. Use key padding masks so padded slots never influence a valid query. A course itself is an allowed key.
6. `set` allows all valid concurrent course keys; `self_only` restricts allowed course keys to self, plus the same null key. The models have equal parameter counts. The no-peer inference ablation uses the *fitted set weights* and simply changes the mask.
7. Apply residual attention output, residual feed-forward network, then a shared per-course sigmoid-logit head. Average registration-level BCE across valid course rows. No committee/probability ensemble is used in the trainable framework.
8. Select an epoch using only historical blocks **with one global semester cutoff across faculties**. Refit from scratch on permissible history. Score the target group in a single pass and write probabilities back to original per-course registration row order.

## Fixed issues relative to Suite29 v1

- **Temporal cross-faculty contamination**: replaced per-faculty latest-block selection with a global calendar-semester cutoff; refuse outer-target overlap.
- **Historical group truncation not visible**: audit counts partially observed historical student–semester groups caused by CF-covered row masks; optional strict failure.
- **Insufficient diagnostics**: added individual faculty+set-size+outcome attention reports, group-size predictive summaries, faculty-specific per-epoch selection curves, a paired results table, and coverage manifest.
- **Checkpoint not re-runnable**: save fit preprocessing statistics, faculty order, feature names, architecture hyperparameters, seed/fold/epochs; added independent replay verifier.
- **Large accumulated group diagnostics**: append per-fold/per-seed group report to CSV to avoid retaining millions of group-record dictionaries in memory.
- **Misleading reference subset scores**: suppress an entire faculty-cell metric if reference scores are missing for some of its rows, and report completion coverage.

## Known limitations and necessary real-data checks

- The structural source archives do not certify prediction-time availability of every upstream engineered feature. This is an upstream lineage issue, not cured by attention masking.
- Historical OOF-row coverage can make earlier enrollment sets incomplete. The audit reports the proportion. A large discrepancy from test-set coverage may require a different history data source or an explicitly matched target-coverage experiment.
- Grouping occurs **within faculties**. Complete simultaneous registrations across all other faculties may not be in the cache.
- Single-head prediction per course is a discriminative marginal outcome model; it does not provide a calibrated **joint** distribution over the vector of all grades. The displayed `1-prod(1-p)` any-failure probability uses a conditional independence approximation.
- The self-only control is matched in parameter count and training settings, not guaranteed to have the same effective optimization difficulty.
- The Set block has one multi-head attention layer; it is not the full original Set Transformer induced-attention architecture. This is an intentional minimal scientific ablation of peer-course interactions.
- Attention mass is not a causal explanation. The separately trained control and peer-intervention are the stronger mechanism tests.
- Cross-faculty global calendar cutoffs can reduce validation coverage for faculties with non-overlapping date ranges. The selection coverage of each faculty must be reviewed.
- Repeated past use of F6/F7 invalidates claims of an untouched historical holdout. Preregister a future confirmation period.
- Large real-data memory usage, runtime, exact cache path compatibility and end-to-end historical preprocessing provenance have not been verified locally.

## Test result

Unit tests and synthetic integration/independent checkpoint replay were successful on the local tool runtime. This verifies basic execution and row reconstruction, not the validity of the university's original raw tables.
