# Suite27: memory-conditioned native gradient boosting

This is the finalized research design approved for implementation. It defines a unified predictor with direct tree-to-memory-to-tree feedback during growth and hard routing during scoring. It makes no claim of theoretical perfection or a guaranteed AP increase. The learner optimizes a weighted logistic surrogate, while architecture selection uses earlier-origin faculty macro average precision; those are different objectives.

## What the Suite26 evidence establishes

Read `evidence/production_analysis.md` and its complete faculty tables for the verified experiment analysis. Latest MINT holdout faculty-fold macro AP is 0.33825776585066836, below Suite25 blend (0.369525592643798) and Suite22 safe blend (0.36915925013953516). Saved student-cluster intervals support those two gaps on these fitted historical checkpoints. MINT's smaller gap to Committee is uncertain under the same bootstrap. These are reused historical origins, not untouched prospective holdouts.

The aggregate conceals an important reversal. MINT improved substantially over its retrained tree-only branch on F6 and fell behind it on F7. F6's target no-history rate was about 0.79%, whereas F7's was about 27.70%; F7 also had a higher failure prevalence. Memory sensitivity reversed across these folds. The fitted F7 `no_memory` intervention raised AP by about 0.01661, yet still did not reach the separately retrained tree-only branch. This shows a brittle fitted dependency, not proof that legitimate history is intrinsically harmful. History was correlated with outcomes in both folds, which likewise does not prove useful incremental performance.

All MINT and memory models retained their feature-selector argmax choices throughout training. Thresholds could move, and parameters had gradients, but a nonzero gradient did not establish learned feature topology. Tree-only F1 changed one of 4,032 choices; that exception does not rescue the general feature-learning concern. Hard routing sensitivity was small, so merely swapping routing at inference is not a sufficient response.

Selection quality was also compromised by cohort composition. F3's 985 validation rows were 984 Business plus one English row, leaving twelve faculties absent. Other last-semester validation cohorts were similarly sparse. Such selection can favor a model that is inappropriate for the intended all-faculty target population. Suite27 replaces that policy with independent, supported same-term forecasting origins. This changes the selection protocol and must be acknowledged when comparing old results.

The ability branch's distinct gain was not established: MINT minus memory AP was approximately +0.003805 with an interval spanning zero. Suite27 consequently omits a latent ability/requirement branch. Stronger causal or semantic assumptions should be introduced only after a supported observation model and a matched capacity comparison justify them.

## Predictor and component roles

For permissible current information `x`, target course `c`, and the student's observed earlier events `H(t)`,

\[
F(x,c,H)=b+\eta\sum_{k=1}^{K}f_k(x,c,H;\theta),\qquad p=\sigma(F).
\]

`b` is the logit of clipped, faculty-weighted training prevalence. Every `f_k` is a newly grown hard tree; its leaves contain Newton logit increments. No Committee score, old-model probability, auxiliary reader-head prediction, residual blending head or posthoc calibrator contributes to this primary score. Optional multiple-seed runs average whole-model probabilities and are explicitly a seed ensemble.

| Component | Assigned responsibility | Evidence required |
|---|---|---|
| Chronological bank | Supply permissible student evidence | Strict semester/identity checks, retained/full counts |
| Course representation | Express relevance between target and historical courses | Known/unknown course strata and reader parameter changes |
| Memory reader | Summarize supported observed history | Attention, effective support, missing grades, empty state |
| Completed tree path | Describe the current partition before a new split | Comparable ancestor predicates and enabled context counts |
| Native grower | Induce feature, threshold and topology from logistic derivatives | Actual memory split usage, gains, Hessian/row support |
| Leaf ensemble | Produce the entire final score | Exact hard-score reconstruction and checkpoint reload |

The information boundary is deliberate. Course keys use course IDs and metadata; the candidate event's explicit observed failure and grade tensors are values rather than key inputs. Metadata itself includes permissible earlier course-outcome aggregates, whose upstream availability remains a cache assumption. The query uses target course identity/metadata and completed raw ancestor agreement, without an unrestricted neural classifier over all current student features. Student IDs select history but are not learned embeddings. Auxiliary heads supervise relevance learning and are absent from primary inference.

## Direct interaction at a node

At a node, take only the raw predicates that have already been chosen by ancestors. For each retained history event, evaluate the same transformed raw feature against each ancestor threshold and branch direction. The compatibility bias is

\[
B_h=\rho\,\frac{1}{|A|}\sum_{a\in A}(2\,\mathbf1[\text{event agrees with ancestor }a]-1).
\]

`rho` is selected from the fixed development grid, which includes zero. Missingness predicates are comparable because historical and current inputs share the same schema. Faculty onehot predicates are excluded. Memory-variable predicates are excluded: the historical event does not possess the query's node-dependent retrieved value. No free node-ID embedding or untrained path network is used. Root bias is zero. This restricted feedback does not encode every ancestor relationship; it is a concrete, auditable first implementation.

The memory query is fixed before evaluating this node's candidate split grid. Course attention plus compatibility produces fourteen evidence values for each row reaching the node. Raw variables and evidence values compete by native split gain. A raw split adds a reusable predicate to child queries; a memory split changes the row partition but contributes no fabricated raw ancestor. Consequently memory can change feature choices, thresholds, partitions and the shape of subsequent subtrees. This is internal learning rather than calibration of a frozen tree.

Enabled path context is not the same as attention changing, and attention changing is not the same as score improvement. Diagnostics distinguish context opportunities from postfit `no_path` score changes; development comparisons test whether the resulting trained architecture improves AP. A selected strength of zero is an honest negative finding about this feedback rule.

## Native split induction

Faculty weights are mean-one inverse row counts, `N/(F*n_faculty)`. There is no class balancing. For each boosting iteration,

\[
g_i=w_i(p_i-y_i),\qquad h_i=w_i p_i(1-p_i).
\]

For evaluated left/right candidate partitions,

\[
\operatorname{Gain}=\tfrac12\left(\frac{G_L^2}{H_L+\lambda}+\frac{G_R^2}{H_R+\lambda}-\frac{G^2}{H+\lambda}\right)-\gamma,
\quad v_{leaf}=\operatorname{clip}\left(-\frac{G}{H+\lambda},-v_{max},v_{max}\right).
\]

The Newton/gain formulation follows the second-order tree-boosting framework of [Chen and Guestrin (2016)](https://arxiv.org/abs/1603.02754). Suite27 implements its own node-local grower; it is not an XGBoost or LightGBM modification. Histogram candidates are training-only. Raw bins are cached as uint8. Memory thresholds use root-evidence training quantiles for the frozen cycle, and node-specific evidence is assigned to those thresholds. Values outside that root range remain routable, although root grids can miss useful node-local thresholds. This approximation is explicit and can be reconsidered using diagnostics.

Greedy depth-limited growth requires minimum leaf rows, minimum Hessian mass and positive gain after regularization. Ties follow fixed feature/bin order. Defaults are depth grid 3/4, 63 bins, minimum 40 rows, Hessian mass 1, L2 5, learning rate .05 and leaf increment clip 2. Tree budgets are 32/64/96/128. There is no global optimality claim: histogram search, greedy induction, clipping and logistic-vs-AP mismatch all matter. A memory-conditioned tree is not globally axis aligned in the original feature space, even though every decision is hard and locally interpretable.

## Evidence representation

Keep up to 32 latest strictly earlier same-student events, selected using semester and stable sample key only. Log full eligible counts and retained counts separately. Course-ID embeddings and a shared normalized metadata encoder form relevance keys/queries. Unknown ID zero has a neutral padding embedding; metadata remains usable. Attention combines bounded course similarity, nonnegative age decay and bounded same-course bonus, then adds the path bias. Empty-history attention is explicitly zero.

The interface is compact and named:

| Evidence | Meaning |
|---|---|
| failure_supported / performance_supported | Attention means shrunk toward earlier faculty priors |
| performance_sd | Weighted performance dispersion |
| failure_relevance_contrast | Attention failure mean minus retained uniform mean |
| effective_support_log | log(1 + effective sample size) |
| retained_history_log / full_history_log | log support counts |
| recency_log | Attention mean log(1 + semester distance) |
| same_course_mass | Attention mass on matching course |
| observed_grade_mass | Attention mass with observed historical grades |
| attention_entropy | Entropy normalized by retained support |
| history_present | Explicit nonempty flag |
| prior_failure / prior_performance | Strictly earlier faculty cumulative priors |

Effective sample size is `1/sum(alpha²)` for nonempty history, and zero for empty history. Support shrinkage is `ESS/(ESS+4)`. Performance uses observed grade/10, falling back to `1-y` where historical grade is missing; grade availability remains explicit. Priors are computed separately for every query using only bank semesters strictly earlier than the query minus the configured embargo. A global full-training prevalence is never substituted as a feature for an early training query. With no earlier faculty observations, priors default to .1 failure/.65 performance. These defaults are assumptions, not calibrated institutional facts.

Support shrinkage is a feature operation; it never blends final model probabilities. Cold students can still follow ordinary raw splits, but they are not guaranteed to receive the same score as an independently trained current-only model. Trees can learn to misuse prior/support variables, which is why cold-history strata and matched current-only controls are mandatory.

## Reader training and consistency

1. **Origin-local pretraining.** Fit on chronological queries within that origin's earlier training table. Default three epochs, at most 120,000 randomly sampled training queries per epoch, batch 512, AdamW learning rate .001. Weighted failure BCE plus .15 observed-grade MSE and .002 attention-concentration penalty supervise the reader through evidence-only auxiliary heads. The query's own label/grade is a target, never a history input. Log retrieval parameter gradients and changes separately from auxiliary heads.
2. **Freeze and grow.** Compute frozen course bases/root logits and grow the hard forest from the prevalence intercept. Cached arrays are fingerprinted against retrieval parameters. Auxiliary-head-only changes do not affect primary evidence; all retrieval changes invalidate the pair.
3. **Optional co-adaptation proposal.** Select at most eight fitted trees containing attention-sensitive memory splits. Hold the full hard reference logits, selected hard contributions, split structures, thresholds and leaves fixed. Optimize `reference - selected_hard + eta*selected_soft` using sigmoid routing over the selected subforest. The main BCE is anchored by .2 auxiliary loss; defaults one epoch, at most 10,000 queries, batch 128, learning rate .0002. Raw and memory predicates use saved node scales. Log the main-loss retrieval gradient separately. This is a partial soft surrogate and an alternating proposal, not exact differentiation through hard split search.
4. **Discard and regrow.** After an update, discard the entire previous forest and cached evidence. Freeze the new reader and regrow every tree from the intercept. Intermediate proposal forests always use the fixed maximum 128-tree budget in both selection and final refit; the final scoring forest uses the selected tree count. This prevents a shorter selected score budget from silently changing the adaptation trajectory.
5. **Select the pair.** Compare cycle zero and cycle one only on supported earlier origins. A proposal may be rejected. With no attention-sensitive splits, explicitly skip it. No monotone improvement or convergence theorem is claimed. A selected cycle zero means co-adaptation has not earned inclusion.

## Comparison ladder and selection

| Variant | Comparison purpose |
|---|---|
| stock | Current-only scikit-learn histogram GBDT foundation |
| native | Matched custom current-only grower; isolates backend cost |
| deterministic | Same custom grower plus fixed recency history evidence |
| global | Learned target-course relevance, no ancestor feedback |
| path | Frozen learned reader with development-selected ancestor strength |
| mcgb | Path reader with development-selected cycle zero/one |

All use the same canonical common features, raw missing flags, faculty indicators and faculty weighting. Here current-only means the permissible canonical row features without the new event-memory reader; those canonical features can already include earlier-history aggregates. Stock is independently selected within the same depth/tree grids with automatic early stopping disabled. Its class probabilities are mapped through `classes_`, including single-class training. The custom backbone can underperform stock; that is a first-class failure finding, not a reason to hide the reference. Simpler variants may win. MCGB is the prespecified research primary, not an assertion that it will win.

Choose the latest two eligible single-semester origins earlier than each target, with matching term type (`ordinal % 3`). Every origin gets its own preprocessing, vocabulary, history bank, reader and forest. Default minimums are 2,000 total validation-semester rows, 30 validation rows and 30 earlier training rows per faculty, five positive and twenty negative validation rows per faculty, and 5,000 total earlier training rows. Default faculty coverage is one: every requested faculty must qualify. The implementation's support thresholds and audit are authoritative; inspect `--help` before changing them. Print every candidate semester/faculty, support and rejection reason, even when none qualify. Zero supported origins stops with a saved full audit; it never silently falls back to an off-cycle or one-faculty validation cohort.

If fewer than two origins qualify, report the actual count and selection uncertainty. An explicit coverage relaxation is supported and logged; candidates still share exactly the same eligible cells. AP is averaged over faculty-origin-seed cells, with ties preferring no adaptation, fewer trees, shallower depth and lower path strength. Full refit uses all strictly earlier history with the selected recipe. Target labels are used only for reports. Defaults one seed; optional paired seeds report training variation separately from student bootstrap uncertainty.

## Temporal assumptions and limitations

Canonical raw features and Suite12 metadata are external caches. Suite27 verifies mapping, shared feature schemas, IDs, event chronology, course-stat reconstruction for uncovered rows, train-only normalization/vocab/bins, and all file hashes. It cannot reconstruct or certify how every cached raw feature was originally produced. Feature availability must already be correct in those caches. Previous-semester grades are assumed released by the next semester because release timestamps are absent. `--history-embargo` excludes immediate prior semesters from memory and cumulative priors; it does not regenerate external current features/course metadata under that embargo.

Training priors and memory are chronological per query, but a shared reader and forest are supervised on the whole training origin. They are statistical learners, not an online causally identified model. Independent origin fitting prevents later-origin model supervision from reaching validation. Historical F6/F7 have already informed research choices; this package treats them as descriptive benchmarks. An unseen future origin is still needed for prospective confirmation.

## Reporting and mechanism inspection

The runner prints and saves all faculty/fold metrics and supports, full faculty macro AP/AUC, Brier, 10-bin ECE, warning-budget precision/recall/F2 at 10/15/20/25%, paired aligned comparisons, prior-reference coverage, and student-cluster intervals with invalid replicate counts. Operational F2 thresholds are selected per faculty/model using configured earlier development folds only; report every target confusion matrix, realized flag rate and unique-student workload. This policy is separate from architecture selection and is not a new probability calibrator. Seed variation, origin variation, and bootstrap variation answer different questions.

Per fitted model save node/leaf support, split gains/variables, actual memory split fraction, comparable ancestor opportunities, enabled feedback counts, root memory evidence/support/entropy, known-course flags, history regimes, and timed/resource/model-size records. Sensitivity interventions remove memory, both explicit outcomes, path feedback, attention relevance, shorten history or shuffle valid histories. Save score-change fractions/magnitudes and per-faculty AP changes. These are postfit sensitivity probes, not the gain of retraining an ablation. `no_outcomes` masks both grade and failure values but retains permissible metadata/priors; `no_memory` uses the explicit empty state. `uniform_attention` also removes path bias. Names and remaining channels are documented to avoid Suite26's intervention confounding.

Source/configuration/runtime/input fingerprints prevent mixing experiments. Completed folds alone are resumable; incomplete folds rerun. Trusted local checkpoints save reader/preprocessor/forest/policy context together, with no huge duplicated bank. Reload uses the same verified original inputs and reproduces hard scores under the same runtime/device. CPU/GPU floating-point boundaries can differ. Every error and traceback reaches the append-only unbuffered log via the bash wrapper's pipefail/tee pipeline.

Success requires evidence: a competent native backbone, legitimate memory benefit, positive learned-relevance/path/coadapt increments across supported origins/faculties/seeds, acceptable cold-history behavior and practical cost. Software tests prove contracts, not substantial academic improvement. If the simpler history GBDT wins, retain it and treat failed increments as research results.
