# Experiment subsystem restoration

Restored modules: `experiment.py` and `tests/test_experiment.py`.
The implementation follows `INTERFACES.md` and `IMPLEMENTATION_PLAN.md`.
Evidence below is software validation on synthetic chronological tables. It
does not establish academic predictive performance or a causal benefit.

## Selection protocol

- `VARIANTS` is stock, native, deterministic, global, path, and mcgb. A nonempty
  subset remains usable without fitting readers for omitted learned variants.
- Each development origin is a single semester. Its training table contains
  only rows with semester strictly below that origin. Selection rejects an
  origin whose supplied support audit marks it unsupported.
- Preprocessing is fitted on that origin's training rows. Every seed gets a
  fresh reader and forest. Learned variants may share the immutable pretrained
  reader and root caches inside one origin/seed; no reader state is carried
  between origins or seeds.
- Training uses mean-one inverse faculty-frequency weights. There is no
  failure-class balancing. Candidate AP is computed separately in every
  eligible faculty/origin/seed cell and averaged with equal cell weight.
  Row counts cannot increase a cell's influence. One-class validation cells
  cannot silently enter the average: they contradict the support audit and
  raise an error.
- The candidate-cell key is variant/depth/trees/path/cycle/origin/seed/faculty.
  Duplicate keys and inconsistent candidate cell counts are rejected.
- AP wins first. Exact AP ties choose cycle 0, fewer trees, shallower depth,
  then smaller path strength, using a stable sort.
- Stock HGB independently selects depth and tree budget with
  `early_stopping=False`. Native candidates accumulate one validation traversal
  per new tree in the fitting callback, using the model's learning rate. They
  do not repeatedly rescore every tree prefix.

## Learned memory and co-adaptation

- Global uses learned root evidence with zero path strength. Path considers
  the configured path grid. MCGB considers that grid with cycle 0 and cycle 1.
  Simpler comparison recipes may win.
- Pretraining providers use `cache=False` while the reader changes. Once
  frozen, providers share reusable root caches across path strengths and depths.
- MCGB proposals always use a reference forest of `config.max_trees` trees.
  This is true during development selection and full-history refit, regardless
  of the selected final score budget.
- A development proposal operates on a copy of the pretrained reader so that
  cycle 0 and other recipes retain their original state. The reference forest
  and its provider are discarded after a reader proposal. New providers and a
  new complete forest are then built from the prevalence intercept.
- A cycle-1 final refit trains a new reader on full history, grows the fixed
  maximum reference budget, applies the proposal, discards the whole reference
  forest, and grows a new forest at the selected tree budget.
- Primary scores remain the hard learner's prevalence intercept plus
  learning-rate-scaled hard leaf increments, passed through sigmoid. Reader
  auxiliary failure/grade heads never enter the primary predictor.
- Every reader, adaptation, and forest training record includes the seed and
  phase context. Origin contexts include the origin. Forest records also
  include training rows, latest training semester, reader fingerprint, budget,
  depth, cycle, path strength, and timing.
- Native and stock fits announce their context before fitting. Native forests
  print progress at tree 1, every 16 trees, and the final tree, with context,
  total budget, and elapsed seconds. Faculty AP is printed immediately when an
  existing selection tree-grid checkpoint is scored. Logging never adds a
  whole-prefix prediction pass or another objective computation.

## Checkpoints, reload, and diagnostics

- Bundles contain preprocessing, reader configuration/state, hard forest or
  stock HGB, selected recipe, seed, history length, and embargo. They contain
  no duplicate history bank.
- Reload reconstructs providers from supplied canonical history and target
  tables and checks both saved reader fingerprints and the forest/reader pair.
  Raw and deterministic checkpoints reject an unexpected reader state.
- Reload also checks the baseline forest's path strength, tree count and depth
  against the selected recipe, and its evidence names/comparable-feature count
  against the reconstructed provider. The existing learner check verifies raw
  feature names. Stock fitted iteration count and maximum depth must match its
  recipe. These are load-time baseline checks, so intentional path interventions
  after a consistent load remain available.
- Stock selection, refit, and reload all use the same class-aware failure-score
  helper. A one-class HGB is scored as its fitted class, even when sklearn emits
  two probability columns for that one-class model. Binary models locate class
  1 using `classes_`.
- Regime tables include every faculty and all four full-history strata
  (0, 1–4, 5–16, 17+) plus known/unknown course strata. Empty and one-class strata
  retain row/positive/negative support and undefined discrimination metrics.
- Memory interventions include no memory, no outcomes, uniform attention,
  no path, history length 8, and shuffled history. Raw features are asserted
  unchanged. Reports include faculty metrics and changed-score fraction,
  mean absolute score change, and maximum absolute change from baseline.
  Stock/native intervention frames are empty with stable headers.
- Selection artifacts are `selection_cells.csv`, `selection_summary.csv`,
  `reader_training.csv`, `adaptation.csv`, `forest_training.csv`, and
  `selected_recipes.json`. The CLI preserves/combines selection and refit logs.

## Regression evidence

The experiment tests exercise the real sklearn HGB and restored native,
reader, and adaptation implementations. They verify:

1. Actual staged HGB scores, selection, full refit, and reload with training
   labels all zero and all one.
2. Deterministic tie breaking over cycles, tree budgets, depths, and path.
3. Independent seeds/origins, strict preceding training windows, identical
   supported candidate cells, and equal cell weighting with unequal row counts.
4. Exact incremental native validation scores versus complete hard-tree prefix
   scoring, including the learning-rate factor.
5. Complete six-variant selection on identical faculty/origin/seed cells.
6. Exact predictions after actual `torch.save`/`torch.load` serialization and
   bundle reload for all six variants.
7. Auxiliary-head mutation leaves hard primary predictions unchanged.
8. Changing labels or grades after a selected origin cannot change that origin's
   selection result. Changing target labels/grades cannot change fitted scores.
9. A changed saved reader or mismatched forest fingerprint is rejected.
10. MCGB development reference/regrowth budgets stay at the fixed maximum;
    final refit uses maximum then selected budget, with changed retrieval hashes
    across the real reader proposal and complete forest regrowth.
11. All faculty/history/course regime cells and six interventions are reported,
    and interventions preserve raw inputs.
12. Unsupported supplied origins fail before fitting, and raw intervention
    diagnostics retain empty-frame headers.
13. Captured stdout verifies before-fit native/stock announcements, immediate
    faculty checkpoint AP, tree 1/16/final progress, elapsed time, and complete
    fitting context. Native selection is tested with whole-prefix
    `predict_proba` forbidden, proving progress output preserves incremental
    validation.
14. Tampered native path strength, tree budget, depth, memory names, comparable
    feature count, or raw feature names are rejected, as are mismatched stock
    tree budgets/depths. A properly loaded path model still supports its
    intentional `no_path` intervention.

Commands and observed results (2026-10-02):

```text
python -m pytest tests/test_experiment.py -q
37 passed

python -m pytest -q (before later CLI end-to-end test expansion)
84 passed, 28 subtests passed

python -m pytest -q (expanded suite while concurrent source edits continued)
4 failed, 98 passed, 28 subtests passed

python -m py_compile experiment.py tests/test_experiment.py
exit status 0
```

The first integrated run passed 13 experiment cases and failed two cases because
the concurrently restored `adapt.py` had not yet been created. Those cases
passed after the real adaptation module became available. A new unsupported
origin regression then exposed missing entry-point audit enforcement; the
implementation now validates that audit before any fitting. The experiment
test run including all three progress-output tests and final checkpoint
consistency regressions has no warnings or failures.

The expanded full-suite run passed earlier checkpoint replays, then rejected
the fold-2 global checkpoint because source fingerprints changed while the
end-to-end class was running. Four end-to-end cases consequently failed at
source/runtime provenance checks: all-six replay, changed-input rejection
precedence, complete-fold resume, and tampered-artifact rejection precedence.
This run does not establish a frozen-source end-to-end pass. Final packaging
must rerun that suite after every Python/shell source file is frozen.
