# Suite24 — Target-Conditioned Structural Residual Network (TCSR)

Suite24 is the evidence-driven successor to Suite23. It intentionally **does not** make the graph larger. Suite23 showed that correct student-history identity and direct course/prerequisite structure mattered, while global graph propagation, time modules, curriculum groups, faculty graph edges, and the course-cohort branch were weak or harmful. Suite24 therefore keeps only the supported mechanisms and redesigns fusion from a post-hoc faculty blend into a single bounded residual architecture.

## Frozen scientific questions

1. **A — History residual:** can target-conditioned student-history evidence improve the Committee when used as a bounded correction rather than as a full replacement predictor?
2. **B — Structural residual:** do direct prerequisite/course-structure paths add further gain?
3. **C — Evidence-conditioned residual (PRIMARY):** can row-wise evidence authority outperform fixed correction authority and avoid the faculty-level failures seen in Suite23?
4. **Standalone head:** how much can the same relational representation solve without Committee? This is deliberately reported so future work can move toward a fully independent architecture if Committee dependence remains necessary.
5. **Safe-scale and post-hoc blend:** these are diagnostics/deployment ablations only. They are not the primary scientific model.

## Architecture

```text
Student profile ───────────────────────────────┐
                                               │
Target course profile ──► target query ────────┼─────────────────────┐
                                               │                     │
Student's historical courses                   │                     │
  + grade/pass/credits                         │                     │
  + recency                                    │                     │
  + exact relation to target course ──────────► target-conditioned   │
                                                history attention    │
                                                                      ├─► standalone relational head
Direct prerequisite/structural course neighbors │                    │
  + direction/type ───────────────────────────► target-conditioned   │
                                                structural attention │
                                                                      │
Committee probability ─► logit anchor ────────────────────────────────┤
                                                                      │
History correction:    bounded ΔH × evidence gate aH ─────────────────┤
Structural correction: bounded ΔS × evidence gate aS ─────────────────┤
                                                                      ▼
                     z_final = z_committee + aH·ΔH + aS·ΔS
                                      │
                                      ▼
                               P(target grade < 5)
```

### What was deliberately removed from Suite23

- global heterogeneous message passing;
- course-cohort/student-similarity branch;
- curriculum group nodes;
- faculty graph nodes;
- learned temporal module;
- faculty-specific fusion coefficients.

Relative recency is retained only as an attribute of a historical course event. Chronology is enforced by construction and audited; it is not modeled with an RNN/Transformer.

## Important safety properties

- Every historical interaction must satisfy `edge_semester < query_semester`; any violation aborts the run.
- History correction is exactly zero when no history exists.
- Structural correction is exactly zero when no structural neighbor exists.
- Each correction is bounded by `±0.75` logits by default.
- With both corrections ablated, Suite24 becomes **exactly the Committee logit**.
- Evidence gates are deliberately tiny monotone functions of support/relevance rather than a high-capacity router.
- F6/F7 never select architecture, epoch, calibration, residual scale, or post-hoc blend.

## Training protocol

The protocol stays aligned with the pre-Suite19 experiments:

```text
history before target fold
    ├── older temporal blocks -> training
    └── latest 3 historical blocks -> validation
          ├── earlier validation portion -> calibration
          └── latest validation portion -> policy/scale/blend diagnostics

select epoch -> reinitialize -> refit permitted history -> target fold
F1-F5 = development
F6-F7 = untouched holdout
```

Training is faculty-balanced while preserving natural class prevalence inside a faculty. Objective:

`BCE(final) + 0.15 ranking(final) + 0.25*[BCE(standalone)+0.05 ranking(standalone)] + 0.01 residual² + 0.002 gate penalty`

No contrastive learning, no neural OOF reconstruction, no class-balanced positive oversampling.

## Outputs to examine first

The final log prints:

- all-fold and F6/F7 macro summaries;
- per-faculty comparison against Committee, Suites17/18/21/22/23, Council where available;
- F6/F7 operational fixed/drift policies and IT confusion matrices;
- A→B→C component uplift;
- paired bootstrap AP intervals;
- history/structural zero and shuffled-identity perturbations;
- correction ablations and fixed-gate ablation;
- per-faculty gate/correction magnitudes;
- support-stratified performance and support-vs-gain correlations;
- cold/new-course regimes;
- Committee false-negative rescue / false-alarm correction diagnostics;
- predeclared premise and Council-success audit.

The output directory also contains aligned per-faculty score CSVs for later analysis.

## Run

```bash
cd /root/disk_3tb/earlywarning/30072026
unzip suite24_target_conditioned_structural_residual.zip
cd suite24_target_conditioned_structural_residual
chmod +x run_suite24.sh
./run_suite24.sh
```

Default output:

`/root/disk_3tb/earlywarning/30072026/results/suite24_target_conditioned_structural_residual`

Default log:

`/root/disk_3tb/earlywarning/30072026/log/suite24_target_conditioned_structural_residual.log`
