# Suite34 — Information-Preserving Multi-View Conditional Learning (IP-MVCL)

**Document type:** Complete Research and Engineering Implementation Specification  
**Project:** AQ Academic Early-Warning Prediction  
**Status:** Finalized implementation specification; not yet implemented or tested  
**Date:** 21 October 2026  
**Priority:** High  
**Next planned research direction:** Suite35/36 — Self-Supervised Learning from Historical Academic Sequences

---

# 1. Executive Summary

Implement Suite34 as a complete, independently runnable research experiment testing whether **explicit conditional interactions between student preparation, target-course characteristics, and academic trajectory improve course-failure prediction beyond an information-matched neural baseline**.

The main contribution is an architecture-controlled test of semantic multi-view representation learning.

Do not simply construct a bigger Transformer, Mixture of Experts, router, or ensemble.

The distinguishing principles are:

1. Preserve the entire existing input information path.
2. Partition selected input features into semantically meaningful views.
3. Compare additive view fusion against explicit multiplicative interactions.
4. Use an information-matched randomized-view placebo.
5. Train one end-to-end model producing one failure logit.
6. Preserve the canonical faculty-level chronological evaluation.
7. Report complete results and mechanism diagnostics in one consolidated log.

The implementation must reuse the existing AQ project caches rather than require a new database export.

**Deliverable:** A self-contained ZIP containing all executable Python code, scripts, configuration, tests, documentation, and experiment protocol.

The resulting package must work on the user's existing Linux research server without modifying earlier experiment results or source caches.

---

# 2. Research Motivation

## 2.1 Task definition

For student \(s\), target course \(c\), and semester \(t\), predict:

\[
y_{s,c,t}=\mathbb{1}[\mathrm{grade}_{s,c,t}<5].
\]

Predictions must use information admissible at the intended semester-origin prediction horizon.

The prediction unit is one canonical eligible student–course–semester registration.

The primary evaluation metric is unweighted macro average precision:

\[
\mathrm{mAP}_{\mathcal G}
=
\frac{1}{|\mathcal G|}
\sum_{g\in\mathcal G}\mathrm{AP}_g,
\]

where \(g\) denotes a faculty–fold evaluation cell.

Do not replace this with pooled AP over all registrations.

Folds F1–F5 constitute development evidence. F6–F7 are repeatedly inspected retrospective periods, not untouched prospective holdouts.

## 2.2 Relevant experimental history

Previous AQ experiments investigated:

- Neural classifiers, HGB, Random Forests, ExtraTrees, stacking, Committee and Council.
- Faculty-shared and faculty-private encoders.
- Multiple experts, residual correction, gating, routing and competence prediction.
- TabM, ModernNCA and representation learning.
- Temporal Transformers and student-history representations.
- Feature graphs and target-conditioned historical context.
- Retrieval and historical memory.
- Concurrent course-set and joint portfolio learning.
- External tabular pretraining.
- Cross-faculty selective borrowing.
- Reconstructed classmates' prior GPA and offering context.

Suite33's selected model achieved retrospective macro AP approximately **0.343516**, compared with its S0 baseline at **0.346168**.

The strongest broadly comparable historical composites remain approximately:

| Historical model | Retrospective macro AP |
|---|---:|
| Suite25 Committee blend | 0.369526 |
| Suite22 safe blend | 0.369159 |
| Committee | 0.350152 |
| Suite33 S0 / Suite32 local common HGB | 0.346168 |

These are historical reference results, not proof of exact model-family equivalence. Comparisons must identify differences in coverage, data contracts and training recipes.

## 2.3 Scientific hypothesis

The primary hypothesis is:

> Explicitly modeling how student preparation and historical trajectory interact with target-course requirements produces a more useful chronological failure-ranking representation than independently encoding these views and concatenating them.

This is not a hypothesis that multiple views are statistically independent.

It is not a claim that previous multi-expert or relational experiments were entirely unrelated.

The implementation must test the incremental value of the interaction mechanism directly.

## 2.4 Primary falsification criterion

If explicit semantic cross-view interactions fail to improve against an equally informed additive-view model and a full-input neural baseline, Suite34's principal hypothesis is unsupported.

A gain over a restricted student-only model is insufficient.

Improved training loss or activated interaction channels are also insufficient.

---

# 3. Project Environment and Input Data

## 3.1 Existing project root

Default root:

```text
/root/disk_3tb/earlywarning/30072026
```

Allow overriding this location through `AQ_ROOT` or `--root`.

Existing canonical caches:

```text
results/cross_faculty_residual_moe/cache/
    <faculty>_fold_<n>.joblib
```

Structured course-feature sidecars:

```text
results/suite12_structured_cache/
    <faculty>_fold_<n>.joblib
```

The implementation must discover faculties from actual canonical cache filenames and verify that all seven folds are present.

Expected full evaluation: 14 faculties × 7 folds.

Do not silently substitute another data directory or a different feature pipeline.

## 3.2 Canonical cache contract

Earlier experiment documentation identifies the following expected canonical keys:

```python
Xtr
Xte
ytr
yte
train_frame
test_frame
feature_names
cf_covered_mask
cf_probabilities
```

The agent must inspect representative real cache files and the existing Suite25/29/30/33 loaders before finalizing the adapter.

Unknown serialization structure must not be guessed.

Expected information:

- `Xtr`: historical registration feature matrix.
- `Xte`: target registration feature matrix.
- `ytr`: historical binary labels.
- `yte`: target binary labels.
- `train_frame`: historical registration identity and semester information.
- `test_frame`: target registration identity and semester information.
- `feature_names`: ordered feature identifiers.
- `cf_covered_mask`: historical cross-fitting coverage.
- `cf_probabilities`: historical cross-fitted reference scores or associated coverage information.

The exact interpretation of each cache key must be verified against the source implementation.

## 3.3 Structured sidecar contract

Previous suites use an additional 17 target-course features, ordinarily exposed through `course_target` arrays for training and target partitions.

The sidecar training rows are associated with `train_row_index`.

**Mandatory assertion:**

The sidecar historical row indices must match the exact canonical historical rows retained after applying the documented cross-fitting coverage conditions.

Do not assume matching row counts establish matching row identities.

If the sidecar indexes the canonical covered rows, assert:

```python
np.array_equal(
    sidecar_train_row_index,
    np.flatnonzero(canonical_covered_mask)
)
```

Adapt this assertion only after verifying the precise indexing convention in the existing source loader.

The final assembled matrix should ordinarily contain:

- 136 shared raw features.
- 17 structured course features.
- 153 original feature channels.

The actual dimensions must be validated and printed, not hardcoded as an unconditional truth.

## 3.4 Faculty-common raw schema

Construct a deterministic feature intersection across the intended full fourteen-faculty population.

Preserve original ordering consistently across every faculty and fold.

Compute the global schema once before fitting.

Do not recompute a different common schema for a single-faculty smoke test; this would make smoke-test input dimensions and learned view definitions incomparable with the full run.

Feature mismatches must trigger a clear error explaining which faculty and fold are inconsistent.

## 3.5 Dataset invariants

For each faculty and fold:

1. Historical feature rows align with historical labels.
2. Target feature rows align with target labels.
3. Historical target semesters precede the current fold's target semester.
4. The structured sidecar matches the expected rows and order.
5. No target label is used in feature construction or preprocessing.
6. No rows are silently dropped during neural preprocessing.
7. Every experimental arm uses exactly the same historical and target registration support.
8. Target predictions preserve original target-row ordering.
9. Every target has exactly one binary label.
10. Original registration identifiers remain available for prediction-level alignment and audits.

Fail loudly when these invariants are violated.

## 3.6 Important provenance limitation

The original engineered features and historical grade-entry semantics are not independently certified as semester-origin available.

Suite34 must inherit this uncertainty explicitly rather than claim certified origin-time prediction.

Do not use Suite33's reconstructed enrollment rosters or present-day peer context.

Do not introduce new raw database variables in the main Suite34 experiment.

---

# 4. Semantic Multi-View Construction

## 4.1 Three primary views

Define three conceptually distinct views.

### View S — Student preparation

Possible content:

- Historical cumulative academic performance.
- Previously failed credits.
- Previously attempted credits.
- Accumulated achievement.
- Existing student-level academic support measurements.

### View C — Target-course context

Possible content:

- Historical course difficulty.
- Course grade statistics.
- Historical course-failure rates.
- Course-support quantities.
- The 17 verified structured `course_target` channels.

### View H — Academic trajectory

Possible content:

- Previous-semester GPA.
- Performance improvement or deterioration.
- Recent historical outcomes.
- Previous attempts and course history.
- Temporal history availability and recency.

These are semantic categories, not a license to invent features.

## 4.2 View manifest

Create:

```text
config/feature_views.json
```

It must explicitly record:

```json
{
  "schema_version": 1,
  "input_feature_names": [],
  "student": [],
  "course": [],
  "history": [],
  "full_path_only": [],
  "semantic_review_status": "REVIEWED",
  "provenance_notes": {}
}
```

The agent must inspect the real feature names before populating the arrays.

Never ship guessed column names as though verified.

A feature may remain in `full_path_only` if its semantics are uncertain.

For the primary experiment, each selected original feature should belong to exactly one semantic view. This simplifies architecture interpretation and placebo matching.

All original feature channels, including those assigned to no specialized view, still pass through the full-input network.

Do not silently infer the final view partition at every training run.

Any initial heuristic feature classification must be reviewed, persisted, and hashed before experimentation.

## 4.3 Missingness

Preserve observed missingness where available.

Fit imputation statistics on permissible training data only.

Suggested preprocessing for numeric features:

1. Replace positive/negative infinity with missing values.
2. Compute training-only median.
3. Impute with that median.
4. Apply training-only scale estimation.
5. Clip extreme transformed magnitudes using a fixed documented bound.
6. Include corresponding missingness indicators consistently for all arms.

If the original cached matrices have already replaced missing values with zeros, do not claim to recover unavailable original missingness.

If categorical variables exist, inspect their semantics and use training-fitted encodings.

All arms must receive identical preprocessing information.

Store the mapping from original features to transformed feature indices so view slices include the corresponding missingness indicators.

---

# 5. Neural Architecture

## 5.1 Backbone choice

Use a compact PyTorch residual MLP.

TabM is not required.

The immediate objective is to isolate the effect of input-view structure and explicit conditional interactions.

Default suggestions:

```yaml
backbone_width: 128
backbone_residual_blocks: 2
view_embedding_dim: 32
interaction_rank: 24
dropout: 0.10
activation: GELU
normalization: LayerNorm
```

These are implementation defaults, not experimentally established optimal settings.

## 5.2 Full-information pathway

For preprocessed input \(x\in\mathbb R^D\):

\[
h_f=E_f(x).
\]

Use:

```text
Linear(D,128)
LayerNorm(128)
GELU
ResidualBlock(128)
ResidualBlock(128)
```

A residual block can be:

\[
h'=h+\mathrm{Dropout}
\left[
W_2\,\mathrm{GELU}
\left(W_1\mathrm{LayerNorm}(h)\right)
\right].
\]

The full-input pathway must be present in every arm.

It must never be replaced by only the specialized views.

## 5.3 View encoders

For \(v\in\{S,C,H\}\):

\[
z_v=E_v(x_v), \qquad z_v\in\mathbb R^{32}.
\]

Suggested encoder:

```text
Linear(view_input_dim, 32)
LayerNorm(32)
GELU
Dropout(0.10)
Linear(32,32)
LayerNorm(32)
GELU
```

Use independent encoder parameters per view.

The network receives all available input views for both training and inference.

No separate test-time multi-sample acquisition is required.

## 5.4 Interaction projections

Define:

\[
s=W_s z_S,\qquad c_s=W_{c,s}z_C,
\]

\[
h=W_h z_H,\qquad c_h=W_{c,h}z_C.
\]

Each projection has output dimension \(r=24\).

### Additive interactions

\[
a_{SC}=\frac{s+c_s}{2},
\]

\[
a_{HC}=\frac{h+c_h}{2}.
\]

### Multiplicative interactions

\[
m_{SC}=s\odot c_s,
\]

\[
m_{HC}=h\odot c_h.
\]

The additive and multiplicative arms must use the same projection dimensions and parameterized layers.

Their fusion vector dimensions and head architecture must be identical.

This provides an architecture-controlled contrast.

Do not introduce a larger prediction head exclusively for the multiplicative arm.

## 5.5 Fusion

The main interaction model uses:

\[
u =
[h_f,z_S,z_C,z_H,m_{SC},m_{HC}].
\]

With width 128, view dimension 32 and rank 24:

\[
\dim(u)=128+3(32)+2(24)=272.
\]

For the additive arm, substitute \(a_{SC}\) and \(a_{HC}\), retaining the same dimension.

The fusion head is:

```text
LayerNorm(272)
Linear(272,128)
GELU
Dropout(0.10)
ResidualBlock(128)
Linear(128,1)
```

Return one raw logit per registration.

Use `BCEWithLogitsLoss` or an equivalent numerically stable formulation.

Probability is:

\[
p=\sigma(\ell).
\]

No separately trained expert outputs are averaged.

No routing decision is required at inference.

---

# 6. Experimental Arms

## A0 — Full-input residual MLP

Receives the entire preprocessed feature vector.

No semantic view encoders or cross-view interactions.

This is the main plain-neural control.

## A0M — Parameter-matched full-input MLP

Recommended additional control.

Increase the width or depth of the A0 architecture so its trainable parameter count is within approximately 5% of A2.

This tests whether A2's gains arise merely from additional parameters.

Report the exact parameter count.

## A1 — Additive multi-view fusion

Receives the full-input representation and three semantic-view representations.

Uses the additive projection terms.

## A2 — Multiplicative IP-MVCL

**Primary research model.**

Uses the same full-input and semantic-view encoders as A1, with multiplicative student–course and history–course interactions.

A1 and A2 must have exactly matching trainable parameter counts unless a documented technical restriction prevents that.

## P1 — Randomized feature-view assignment

Uses the identical A2 architecture and full-input information.

Randomize only which eligible feature channels are assigned to the specialized student, course and history view encoders.

Preserve the number of channels assigned to each view.

Preserve the entire full-input pathway unchanged.

Use a deterministic, recorded partition seed.

The random partition must be created without consulting outcome labels.

The same partition should remain fixed across comparable faculty/fold fits for that seed.

Do not permute feature values across students: that would create a different, more destructive placebo.

The purpose is to test whether semantic view structure contributes beyond arbitrary grouped feature transformations.

## A3 — Auxiliary view supervision

Conditional research extension.

Architecture identical to A2 except for three lightweight view-specific training heads:

\[
\ell_S=g_S(z_S),\quad
\ell_C=g_C(z_C),\quad
\ell_H=g_H(z_H).
\]

The final deployed prediction remains the joint A2 logit.

Example objective:

\[
L_{\mathrm{A3}}=
L_{\mathrm{main}}
+
\lambda_{\mathrm{aux}}
\frac{L_S+L_C+L_H}{3}.
\]

Initial fixed \(\lambda_{\mathrm{aux}}=0.05\).

Do not use auxiliary heads for final prediction averaging.

Report whether auxiliary supervision improves or harms the principal head.

A3 must not be used to rescue a failed A2 hypothesis without clearly labeling the change in research question.

---

# 7. Parameter and Information Matching

For each arm print:

```text
arm
input_dimension
full_input_dimension
view_dimensions
trainable_parameters
optimizer_parameters
feature_schema_hash
training_row_count
validation_row_count
target_row_count
```

Comparisons A1 versus A2 must hold fixed:

- Raw features.
- Preprocessing.
- View partition.
- Parameter count.
- Historical training rows.
- Validation rows.
- Optimizer.
- Learning rate.
- Weight decay.
- Batch size.
- Maximum epochs.
- Early stopping.
- Random seed.

A0M must be capacity-matched as closely as practical.

All arms must preserve exactly the same final target rows.

---

# 8. Chronological Training Protocol

## 8.1 Outer folds

Run:

```text
F1, F2, F3, F4, F5, F6, F7
```

For each faculty and fold, use only historical labels permitted by that fold's chronological information contract.

Do not concatenate overlapping expanding-window training caches as independent observations.

Each outer fold has its own canonical historical training support.

## 8.2 Historical validation

Within each outer fold, select a chronological validation block from its historical training data.

Default proposal:

- Use the latest three eligible historical calendar semesters as validation.
- Use strictly earlier calendar semesters for model fitting.
- Apply one globally defined academic-semester ordering.
- Validate that all fitting semesters precede all validation semesters.

For faculty-local models, use the same calendar ordering and cutoff semantics across faculties.

If a faculty has insufficient positive support, use a documented earlier fallback rule or fail with a specific reason.

Do not silently use random validation splitting.

## 8.3 Training and refitting

For each faculty, fold, seed and arm:

1. Load the fold's canonical historical records.
2. Partition historical data chronologically into fitting and validation blocks.
3. Fit preprocessing on fitting data only.
4. Train for up to the configured maximum epochs.
5. Select the epoch on chronological validation macro AP (or that faculty's AP when independently fitted).
6. Record validation metrics and selected epoch.
7. Reinitialize the model using the same recorded seed.
8. Refit on the complete permissible historical support for the selected epoch count.
9. Fit refit preprocessing on that full permissible historical support.
10. Predict the unchanged target rows.
11. Save scores, model configuration, preprocessing and metrics.

No target-fold label may influence fitting, epoch selection, or prediction.

The final evaluation may use target labels only after predictions are frozen.

## 8.4 Seeds

Recommended seeds:

```text
29,129,229
```

Keep the same seeds across arms.

Log deterministic settings, PyTorch/CUDA versions and nondeterministic-operation warnings.

At minimum report:

- Mean across seeds.
- Standard deviation across seeds.
- Per-seed faculty/fold results.
- Paired A2−A1 differences using matched seeds.

Do not treat three seeds as three independent semesters.

## 8.5 Initial training configuration

Suggested defaults:

```yaml
max_epochs: 18
min_epochs: 3
early_stopping_patience: 5
batch_size: 1024
optimizer: AdamW
learning_rate: 0.0003
weight_decay: 0.001
dropout: 0.10
gradient_clip_norm: 1.0
validation_semester_blocks: 3
```

Use natural-prevalence mini-batches initially.

Do not add a class-balanced sampler, AP loss, contrastive loss or sophisticated scheduler to the primary architecture comparison without a separate control.

If imbalanced weighting is required, use a predeclared fixed rule applied equally across all arms and report it.

Preserve calibrated probability evaluation even if training uses class weights.

## 8.6 Resource management

The server environment may provide a V100-class GPU, but actual availability must be detected.

Implement:

- CUDA auto-detection.
- CPU fallback.
- Optional mixed precision on supported CUDA devices.
- Gradient clipping.
- Optional gradient accumulation.
- Checkpoint saving.
- Deterministic output naming.
- Resumability by completed faculty/fold/seed/arm key.

Do not repeatedly load all seven historical caches into GPU memory.

Train sequentially or using explicitly bounded concurrency.

Save models to CPU-portable checkpoints.

---

# 9. Predeclared Evaluation

## 9.1 Primary metric

For each faculty–fold cell compute average precision using the entire eligible target list.

Compute macro AP as the unweighted mean of faculty–fold AP values.

Do not pool all registrations before calculating AP.

If a cell has no positive labels, print its eligibility status and omit its undefined AP from the corresponding defined-cell average; do not assign AP zero.

## 9.2 Secondary metrics

Print for every cell and arm:

- AP.
- ROC-AUC, when defined.
- BCE/log loss.
- Brier score.
- ECE using ten bins.
- Failure prevalence.
- Precision and recall at 10%, 15%, 20%, 25% alert budgets.
- F1/F2 at fixed warning budgets.
- F1/F2 under development-selected probability thresholds.
- Number of true positives, false positives, true negatives and false negatives under each declared operating policy.
- Alert count and alert fraction.

For fixed top-k warning budgets, define deterministic tie breaking.

Do not confuse F2@20% with F2 at an optimized threshold.

## 9.3 Threshold selection

Thresholds must be selected only using earlier development predictions.

Recommended policy:

- F1 has no prior target-fold prediction history; report its threshold policy as unavailable.
- F2 uses eligible F1 development predictions.
- F3 uses F1–F2.
- F4 uses F1–F3.
- F5 uses F1–F4.
- F6/F7 use thresholds frozen from F1–F5.

Thresholds are model- and faculty-specific where supported.

For F7, do not retune the operating policy using F6 retrospective outcomes.

Print threshold, optimization objective, supporting rows, supporting positives, and resulting warning rates.

## 9.4 Retrospective evaluation

F6/F7 results must never be used to select the architecture, view partition, learning objective, or hyperparameters.

Evaluate all predeclared experimental arms on F6/F7 for complete retrospective mechanism analysis, but freeze the development selection decision before reading these outcomes.

Label all retrospective results accordingly.

---

# 10. Mechanism Diagnostics

The next experiment must be designed to explain how it behaves, not merely report one AP score.

## 10.1 Incremental architectural effects

Compute:

```text
A1 - A0
A1 - A0M
A2 - A1
A2 - A0
A2 - A0M
A2 - P1
A3 - A2, if A3 was run
```

Print:

- Mean AP difference.
- Median difference.
- Wins/losses/ties.
- Standard deviation.
- Largest positive difference.
- Largest negative difference.
- Faculty-level means.
- Fold-level means.
- Seed-level differences.

## 10.2 Training versus validation fit

For each epoch print:

```text
faculty
fold
seed
arm
epoch
train_loss
train_ap
validation_loss
validation_ap
validation_auc
validation_brier
learning_rate
elapsed_seconds
```

Record train–validation gaps.

Detect whether increasing model complexity simply improves in-sample learning while harming chronological validation.

## 10.3 Interaction ablation

For each trained A2 model, compute secondary predictions with:

1. Both interaction terms unchanged.
2. Student×course interaction tensor replaced with zero.
3. History×course interaction tensor replaced with zero.
4. Both interaction tensors replaced with zero.

Compute AP, AUC, BCE and prediction-change distributions for these interventions.

These interventions may move inputs outside the training distribution. Treat them as diagnostic sensitivity tests, not causal proof.

Compare their patterns against the independently trained A1 control.

## 10.4 View-level diagnostics

Record:

- Norms of view embeddings.
- Norms of interaction representations.
- Per-view observed feature counts.
- Missing-feature fractions.
- Fractions with unavailable historical evidence.
- Prediction variation under controlled view ablations.
- Correlation between original view variables and their encoded representations where interpretable.

Do not claim that large representation norms or nonzero activations demonstrate usefulness.

## 10.5 Error rescues and harms

Relative to A0 and A1, classify target rows into:

- Newly corrected predictions at specified fixed thresholds.
- Newly introduced errors.
- Previously missed failures moved upward in rank.
- Previously well-ranked failures moved downward.
- Negatives that enter the warning budget.
- Negatives removed from the warning budget.

Report support counts and faculty/fold distributions.

Use exact same-row predictions.

For AP-focused analysis, compare changes in the ranks of positive examples within the original faculty–fold target list.

## 10.6 History-availability strata

Using verified existing feature flags, report outcomes for:

- Strong previous academic history.
- Limited previous academic history.
- Missing specific recent-history fields.
- Existing previous course attempts.
- No observed prior attempt where applicable.

The grouping definitions must be frozen, transparent, and derived only from available original features.

Do not infer that every blank history field means the student is genuinely new.

## 10.7 Temporal stability

Report:

- F1–F5 development effects.
- F6 and F7 individually.
- Faculty-specific sign reversals.
- Seed-dependent sign reversals.
- Differences between earlier and later development origins.
- Cases where higher training AP coincides with worse future AP.

The purpose is to identify genuine chronological generalization rather than better in-sample fitting.

---

# 11. Historical Baselines

## 11.1 Strong same-run reference

Implement or reuse a matched standalone HGB control trained on the same historical rows and original feature contract.

Use a documented fixed configuration based on the source of Suite32/33 S0 where recoverable.

If the original configuration is unavailable, explicitly label this as a new matched HGB control rather than falsely claiming exact Suite33 replication.

## 11.2 Archived references

Include historical macro and faculty-level comparison references where available:

- Committee.
- Suite22 safe blend.
- Suite25 Committee blend.
- Suite31 full-history HGB.
- Suite32 local HGB.
- Suite33 S0.

Council requires separate 13-faculty and IT-only comparisons.

Never mix an IT-only AP with a fourteen-faculty mean.

## 11.3 Row-aligned Committee predictions

If the canonical caches or a verified reference file provide Committee predictions for the target registrations, calculate paired AP differences on matched row identities.

Validate:

```text
faculty
fold
student identity
course identity
target semester
row identity
binary target label
```

Report alignment coverage.

Equal array lengths are insufficient evidence of row alignment.

When paired scores are not verifiably available, fall back to clearly labeled historical metrics-only comparison.

---

# 12. Development Promotion Guard

The promotion rules must be frozen before retrospective evaluation.

Suggested research-stage requirements for promoting A2 to a primary candidate:

1. Mean development A2−A1 AP ≥ +0.010.
2. Mean development A2−A0 AP ≥ +0.010.
3. A2 outperforms A0M, establishing value beyond parameter count.
4. A2 meaningfully outperforms P1; suggested minimum +0.005 AP.
5. A2 improves over A1 on at least three of five development folds.
6. Positive A2−A1 faculty effects in at least eight of fourteen faculties.
7. Positive mean A2−A1 differences for at least two of three seeds.
8. No unacceptable large systematic faculty harm.
9. Operational F1/F2 and warning load remain within prespecified acceptable ranges.
10. All chronology and data-alignment checks pass.

These are suggested practical thresholds and should be finalized in `PROTOCOL.md` before executing the primary study.

Do not relax criteria after observing results.

Passing these gates means **development-stage research promotion**, not deployment certification.

A2 failing these criteria does not authorize automatic post-hoc selection of A3 or P1 as a replacement winner.

---

# 13. Complete Single-Log Reporting

The user's most important operational requirement is that the full experiment can be reviewed from a single log file.

Default path:

```text
/root/disk_3tb/earlywarning/30072026/log/suite34_ipmvcl.log
```

The log must be written without output truncation.

Use:

```bash
set -euo pipefail
python -u train_suite34.py "$@" 2>&1 | tee "$LOG"
```

The launcher must propagate Python failures correctly.

A full run should replace the previous active log, with optional archival backup before overwrite.

## 13.1 Required log sections

```text
[RUN_CONFIGURATION]
[ENVIRONMENT]
[DEPENDENCIES]
[DATA_DISCOVERY]
[FEATURE_SCHEMA]
[FEATURE_VIEW_MANIFEST]
[PREPROCESSING_AUDIT]
[CHRONOLOGY_AUDIT]
[CACHE_ALIGNMENT]
[MODEL_PARAMETER_COUNTS]
[TRAINING_START]
[EPOCH_METRICS]
[EARLY_STOPPING]
[REFIT]
[FACULTY_FOLD_RESULTS]
[DEVELOPMENT_MACRO_RESULTS]
[DEVELOPMENT_FOLD_MATRIX]
[DEVELOPMENT_FACULTY_MATRIX]
[DEVELOPMENT_PAIRED_CONTRASTS]
[DEVELOPMENT_DECISION]
[RETROSPECTIVE_RESULTS]
[RETROSPECTIVE_FOLD_MATRIX]
[RETROSPECTIVE_FACULTY_MATRIX]
[HISTORICAL_COMPARISONS]
[OPERATIONAL_THRESHOLDS]
[ALERT_BUDGET_RESULTS]
[INTERACTION_ABLATIONS]
[VIEW_DIAGNOSTICS]
[ERROR_RESCUES_AND_HARMS]
[HISTORY_AVAILABILITY]
[TEMPORAL_STABILITY]
[SEED_VARIABILITY]
[UNCERTAINTY]
[RESEARCH_CONCLUSIONS]
[RUN_STATUS]
```

## 13.2 Full result tables

Print the complete faculty × fold × arm × seed matrix.

No `head(20)` or default DataFrame truncation.

Recommended:

```python
print(df.to_string(
    index=False,
    max_rows=None,
    max_cols=None,
    line_width=10000
))
```

For every table print:

```text
table name
number of rows
number of columns
column definitions
complete table
```

## 13.3 Required summary matrices

At minimum:

- F1–F5 AP by arm.
- F6–F7 AP by arm.
- F1–F7 AP by fold and arm.
- AP by faculty and arm for development.
- AP by faculty and arm for retrospective.
- AUC/Brier/ECE by arm and stage.
- F1/F2 operating-policy results.
- Per-seed summary.
- Paired arm differences.
- Worst affected faculties and folds.
- Historical comparison on matched support.
- Training/validation generalization gaps.
- Model parameter counts and runtime.

## 13.4 Interpretation text

The final log must include automatically generated descriptive interpretations, such as:

```text
A2 versus A1:
  mean_delta_ap
  positive_faculties
  positive_folds
  positive_seeds
  worst_harm
  placebo_margin

Primary hypothesis:
  supported / unsupported / inconclusive

Chronological behavior:
  stable / unstable / mixed

Research promotion:
  pass / fail

Deployment status:
  not certified
```

The script must not assert a causal explanation from metric changes alone.

For example, if A2 beats A1 but P1 matches it, the log must explicitly state that semantic view partitioning was not validated.

If A2 substantially improves training AP but not target AP, report an apparent generalization failure.

---

# 14. Prediction Files and Checkpoints

The log is the primary review artifact, but retain machine-readable outputs for reproducibility.

Suggested output directory:

```text
results/suite34_ipmvcl/
```

Files:

```text
config.json
environment.json
feature_manifest.json
data_coverage.csv
training_curves.csv
all_metrics.csv
all_predictions.csv
paired_contrasts.csv
faculty_summary.csv
fold_summary.csv
development_selection.json
historical_comparisons.csv
threshold_policies.csv
operational_metrics.csv
interaction_ablations.csv
view_diagnostics.csv
history_strata.csv
uncertainty.csv
runtimes.csv
checkpoints/
```

Prediction rows must include:

```text
faculty
fold
seed
arm
row_index
student_id
course_id
target_semester
y
p
reference_prediction (if verified)
```

Preserve identifiable keys only in local research artifacts with appropriate access controls. Do not print personal identifiers in the aggregated console log.

Checkpoints must include:

- Model weights.
- Architecture configuration.
- Exact feature ordering.
- View manifest.
- Preprocessing statistics and mappings.
- Random seed.
- Selected epoch.
- Target fold.
- Faculty.
- Package/version information.
- Source-data hashes or reproducibility identifiers.

Checkpoint replay must reproduce saved probabilities within a documented numerical tolerance.

---

# 15. Required Package Structure

Create exactly one top-level package directory.

```text
suite34_ipmvcl/
├── run_suite34.sh
├── train_suite34.py
├── s34_data.py
├── s34_preprocessing.py
├── s34_views.py
├── s34_model.py
├── s34_training.py
├── s34_metrics.py
├── s34_diagnostics.py
├── s34_comparisons.py
├── s34_reporting.py
├── s34_checkpoint.py
├── s34_synthetic.py
├── check_environment.py
├── requirements.txt
├── README.md
├── PROTOCOL.md
├── config/
│   ├── default.json
│   └── feature_views.json
├── tests/
│   ├── test_data.py
│   ├── test_views.py
│   ├── test_model.py
│   ├── test_chronology.py
│   ├── test_training.py
│   ├── test_metrics.py
│   ├── test_reporting.py
│   ├── test_checkpoint.py
│   └── test_synthetic_e2e.py
└── examples/
    └── sample_report.txt
```

## 15.1 Module responsibilities

### `s34_data.py`

Canonical joblib discovery, loading, source identity, row validation, sidecar alignment and feature-matrix assembly.

### `s34_preprocessing.py`

Fitted numerical/categorical preprocessing, missingness preservation, transformed feature mapping and checkpoint serialization.

### `s34_views.py`

Feature-manifest loading, semantic partition validation, randomized-view placebo generation, feature-index mapping and manifest hashing.

### `s34_model.py`

Residual MLP, view encoders, additive fusion, multiplicative fusion and auxiliary heads.

### `s34_training.py`

Training loops, chronological selection, early stopping, refitting, seed management, optimizer configuration and checkpoint handling.

### `s34_metrics.py`

Canonical AP, AUC, BCE, Brier, ECE, F1/F2, alert-budget ranking, thresholds and confusion counts.

### `s34_diagnostics.py`

Interaction interventions, view effects, training-gap analysis, subgroup metrics and rescue/harm diagnostics.

### `s34_comparisons.py`

Within-run paired comparisons, history-reference alignment, bootstrap analyses and historical benchmark tables.

### `s34_reporting.py`

Full, untruncated results tables and descriptive interpretation text in the single consolidated log.

### `train_suite34.py`

Experiment orchestration and frozen selection protocol.

### `run_suite34.sh`

Environment validation, tests, execution and correct single-log capture.

---

# 16. CLI and User Workflow

Default full command:

```bash
cd /root/disk_3tb/earlywarning/30072026

unzip -o suite34_ipmvcl_complete.zip

cd suite34_ipmvcl

bash run_suite34.sh
```

The archive should contain the folder directly so this command works without additional file moves.

Allow:

```bash
AQ_ROOT=/custom/root bash run_suite34.sh
```

and:

```bash
PYTHON=/custom/python bash run_suite34.sh
```

Recommended CLI flags:

```text
--root
--cache-dir
--structured-dir
--output-dir
--faculties
--folds
--seeds
--arms
--epochs
--min-epochs
--patience
--batch-size
--learning-rate
--weight-decay
--device
--amp
--validation-blocks
--save-checkpoints
--resume
--smoke-test
--bootstrap
--feature-view-manifest
--print-feature-manifest
--strict-data-gate
```

Default arms:

```text
A0,A0M,A1,A2,P1
```

A3 remains optional or gated according to the frozen experimental plan.

Recommended real-cache smoke test:

```bash
bash run_suite34.sh \
    --folds 1 \
    --faculties all \
    --seeds 29 \
    --epochs 2 \
    --min-epochs 1 \
    --patience 1 \
    --smoke-test \
    --bootstrap 0
```

The smoke test is for compatibility only.

It must not be reported as research performance.

---

# 17. Automated Validation Tests

The implementation is incomplete until the following tests pass.

## 17.1 Source alignment tests

- Historical labels and features have matching lengths.
- Target labels and features have matching lengths.
- Incorrect sidecar row indices trigger failure.
- Identical sidecar row counts with shuffled row indices trigger failure.
- Missing feature names trigger failure.
- Unknown faculty/fold filenames trigger failure.
- Invalid cross-fit coverage triggers failure.
- Missing or duplicate target identities are handled according to a documented policy.

## 17.2 Chronology tests

- Historical validation never includes target labels.
- Training semesters strictly precede validation semesters.
- Model fitting never uses target semesters.
- F6/F7 scores cannot change development model selection.
- A later retrospective fold cannot change earlier frozen threshold policies.

## 17.3 Model tests

- A0 output shape equals batch size.
- A1/A2 output shape equals batch size.
- A1/A2 parameter counts are identical.
- P1 preserves the full-input pathway.
- All model arms backpropagate finite gradients.
- A2's interaction projections receive gradients.
- A3 auxiliary heads receive gradients when enabled.
- Inference returns one logit per registration.
- No NaN probabilities under normal finite preprocessed inputs.

## 17.4 Metric tests

Use small manually constructed examples to test:

- AP.
- Ranking ties.
- AUC.
- Precision and recall.
- F1/F2.
- Fixed top-k warning budgets.
- Confusion matrices.
- Macro cell averaging.
- Undefined-metric handling.

## 17.5 Reproducibility tests

- Same seed and same data reproduce predictions within tolerance.
- Feature schema hash matches saved checkpoint.
- Checkpoint replay matches saved predictions.
- Random-view partition is deterministic.
- Different placebo seeds produce appropriately different partitions.
- Resume does not duplicate completed cells.

## 17.6 Synthetic full-pipeline test

Generate synthetic data that replicates the essential AQ cache structures.

Run all seven folds for at least two synthetic faculties and all principal arms with a minimal training budget.

Verify:

- Successful completion.
- Output file integrity.
- Exact expected cell counts.
- Consistent row alignment.
- Complete log sections.
- Full result matrices.
- No retrospective selection leakage.
- Correct unsuccessful exit codes on deliberately corrupted inputs.

Synthetic predictive performance is not scientifically meaningful.

---

# 18. Real-Data Preflight

Before the first full experiment, perform a read-only preflight against the server's actual joblib files.

Print a table containing:

```text
faculty
fold
Xtr shape
Xte shape
ytr length
yte length
historical semester range
target semester
coverage fraction
sidecar train shape
sidecar target shape
sidecar row alignment
common raw feature count
structured feature count
total feature count
label prevalence
```

Also print:

- All discovered feature names.
- Semantic view assignments.
- Unassigned features.
- Nonfinite/missing-value counts.
- Categorical fields.
- Duplicate identity warnings.
- All source-data mismatches.

A full experiment must not begin if the data gate reports unresolved fatal errors.

The agent should inspect and reconcile actual sidecar dictionary structures rather than bypass them by guessing new keys.

---

# 19. Runtime and Efficiency

The expected complete experiment may involve more than one thousand neural fits when accounting for seven folds, fourteen faculties, several arms and three seeds.

Do not estimate total runtime from synthetic tests alone.

Required engineering features:

- A real-cache smoke mode.
- Bounded CPU/GPU memory.
- Checkpoint-based resume.
- Optional skip of expensive nonessential analyses until main fitting completes.
- Incremental prediction writing.
- No duplicate copies of large historical matrices in memory.
- Clear progress messages per faculty/fold/arm/seed.
- Independent timing for loading, preprocessing, selection, refitting, inference and reporting.

Do not change architecture size by faculty or fold without a frozen and explicitly documented rule.

If resource constraints require a smaller development pilot, keep it separate from the primary experiment and never compare its restricted macro score directly against full historical benchmarks.

---

# 20. Research Interpretation Requirements

The final analysis must answer the following questions explicitly.

### Q1. Does semantic view separation help?

Test A1 versus A0 and A0M.

### Q2. Do explicit interactions help?

Test A2 versus A1.

### Q3. Are gains due merely to model size?

Test A2 versus A0M.

### Q4. Does semantic view membership matter?

Test A2 versus P1.

### Q5. Are both interaction types useful?

Use separate student×course and history×course interventions.

### Q6. Does the framework generalize chronologically?

Inspect development folds, F6, F7 and training/validation gaps.

### Q7. Which faculties benefit?

Report all fourteen faculty-level AP changes and worst losses.

### Q8. Are failures with limited history handled better?

Use verified history-availability subgroups.

### Q9. Does the framework improve warning decisions?

Analyze fixed budgets and development-frozen F1/F2 thresholds.

### Q10. Does the framework outperform strong historical predictors?

Compare with matched HGB, Committee and archived Suite22/Suite25 references, respecting coverage and training-recipe differences.

### Q11. Does the model support the actual multi-view hypothesis?

A model may improve AP without validating semantic view interactions.

State this distinction.

### Q12. Should the direction continue?

Return one of:

```text
CONTINUE — credible mechanism and chronological improvement
REFINE — localized or inconclusive benefit requiring bounded investigation
CLOSE — insufficient evidence after meaningful controls
```

Include justification grounded in the observed results.

---

# 21. Explicit Exclusions

Do not introduce the following into the principal Suite34 run:

- Mixture-of-Experts routers.
- Council residual-correction authority mechanisms.
- Current-semester classmates' final outcomes.
- Reconstructed future-known enrollment context.
- Target-semester academic results.
- External foundation-model pretraining.
- Historical sequence self-supervised pretraining.
- Generic contrastive alignment between semantically different views.
- Uncontrolled feature additions.
- Post-hoc architecture selection using F6/F7.
- Committee blending as a substitute for demonstrating standalone value.

These exclusions keep the main scientific hypothesis identifiable.

Self-supervised sequence pretraining is reserved for the planned Suite35/36 research direction.

---

# 22. Final Acceptance Criteria for the Implementation Agent

The task is considered completed only when:

- [ ] The complete executable source tree exists.
- [ ] Every Python module is implemented.
- [ ] The launcher works from the documented project directory.
- [ ] The actual cache and sidecar contracts have been inspected.
- [ ] Feature-view assignments are saved and validated.
- [ ] The A0, A0M, A1, A2 and P1 controls run.
- [ ] The optional A3 implementation is included.
- [ ] All arms retain the full-input feature pathway.
- [ ] A1/A2 parameters and input information are matched.
- [ ] Chronological selection is leak-resistant under the documented proxy contract.
- [ ] Complete F1–F7 runs are supported.
- [ ] The development decision is frozen before retrospective evaluation.
- [ ] All result matrices are printed without truncation.
- [ ] Operational threshold metrics are included.
- [ ] Mechanism and view-ablation diagnostics are included.
- [ ] The single consolidated log is sufficient for subsequent research review.
- [ ] Predictions and model checkpoints are reproducible.
- [ ] Synthetic end-to-end tests pass.
- [ ] A real-cache integration smoke test passes on the user's server, or is explicitly marked as requiring execution there.
- [ ] The final ZIP has a stable top-level directory and passes archive-integrity validation.
- [ ] README documents exact installation, commands, dependencies, outputs and limitations.
- [ ] No real-data predictive improvement is claimed before an actual university-data experiment completes.

**Deliverable filename:**

```text
suite34_ipmvcl_complete.zip
```

**Expected consolidated log:**

```text
/root/disk_3tb/earlywarning/30072026/log/suite34_ipmvcl.log
```

**Expected results directory:**

```text
/root/disk_3tb/earlywarning/30072026/results/suite34_ipmvcl/
```

---

# 23. Instructions to the Implementing Agent

Implement the entire package directly rather than only drafting a design.

Do not ask the researcher to manually prepare additional data if the required information already exists in the canonical joblib caches and sidecars.

Where cache keys or feature names are uncertain, inspect the original files and previous Suite25/29/30/33 loader code instead of inventing compatibility assumptions.

Preserve the experimental definition above and avoid introducing unrelated architecture changes.

Prioritize correctness, reproducibility, scientific validity and informative reporting over adding further neural-network complexity.

Before delivery:

1. Validate Python syntax and imports.
2. Run unit tests.
3. Run synthetic end-to-end tests.
4. Check all final log sections.
5. Verify checkpoint and prediction replay.
6. Verify ZIP integrity.
7. Clearly distinguish successful synthetic validation from real-data execution.

The researcher wants **one complete runnable archive** and, after execution, **one comprehensive log file** that can be uploaded for an in-depth scientific review.

The purpose of Suite34 is not to demonstrate that deep learning can fit AQ data. It is to determine whether structured semantic multi-view interactions offer a genuine, stable advantage over strong, information-matched predictors.

**End of Suite34 implementation specification.**
