# Chronological data and protocol restoration

Restored on 2026-10-02 against the approved `INTERFACES.md` and `IMPLEMENTATION_PLAN.md`. This subsystem restores software behavior; synthetic validation is not academic-performance evidence.

## Source and scope

`data.py` is copied from the surviving vetted Suite26 `mint_data.py`, with only the intended Suite27 preprocessing-version and history-embargo changes. `make_synthetic_cache.py` is an unchanged copy of the Suite26 fixture generator. Changes are confined to these modules, new `protocol.py`, the two assigned test files, and this report.

The canonical-cache contract retains complete historical rows regardless of CF coverage, honors structured `train_row_index` reordering, preserves covered course metadata, and reconstructs uncovered course statistics using strictly earlier full semesters across selected faculties. IDs normalize numeric CSV coercions while preserving meaningful leading zeros. Binary labels, semester encodings, row counts, unique sample IDs, known-grade bounds and grade/failure consistency remain validated. Target grades are checked then removed from model tables. Global history/target overlap fails before fitting.

`committee` remains part of `Table`, because the vetted cache/reporting contract uses it. The older `chronological_split` and `MemoryDataset` APIs are retained for compatibility and covered by inherited tests; Suite27 origin selection is implemented separately in `protocol.py`.

## Suite27 behavior

- `Preprocessor` serialization is explicitly version 2. `Prepared.x` concatenates standardized full `Table.x`, finite-presence flags for every original x column, and faculty indicators. Thus its width is `2*len(feature_names)+len(faculty_names)`. Course metadata remains 17 standardized values plus 17 presence flags. Fitting uses only supplied training indices; unseen course IDs map to zero. Version 1 states fail instead of silently acquiring a different input schema.
- `build_history(..., allowed=None, embargo=0)` preserves the earlier allowed-mask positional argument. A historical event must satisfy `bank.semester < query.semester - embargo`. Full support counts, retention, recency and same-course indicators all derive from those permitted rows, with label-independent chronological/sample-ID ties.
- `faculty_weights` assigns mean-one inverse observed-faculty-count weights. Faculty outcome proportions do not alter weights; each observed faculty contributes equal total mass.
- `prior_evidence` produces float32 `[N,2]` cumulative faculty means with the same strict cutoff and embargo. Failure uses historical y; performance uses historical grade/10 when known and 1-y otherwise. Missing earlier faculty support defaults to `.1,.65`. It requires matching feature/faculty schemas and does not read query y or grade.
- `choose_origins` selects the latest earlier integer semesters having the target term modulo three, returned in ascending order. Every validation faculty cell must meet row/positive/negative support; both outcomes are required even when an explicit class minimum is zero. Default coverage 1 requires every selected schema faculty. Every eligible faculty must also have sufficient earlier training support, and global earlier rows must meet the global training minimum. An explicit lower coverage may admit only supported faculty cells, but it cannot excuse inadequate training for an otherwise eligible cell.
- The audit includes every observed semester crossed with every schema faculty, including absent cells. `eligible` is validation-cell support; `origin_eligible` includes calendar/global/coverage/prior-training constraints. `selected` marks eligible cells at chosen origins. `origin_cells` returns eligible faculty names in schema order. Zero supported origins raises `UnsupportedOriginsError` with a full `.audit`, including headers for an empty history; the caller must print/save this audit. The protocol does not substitute an unsupported origin.

## Verification evidence

The inherited/cache test restoration was exercised while data.py was absent (16 explicit missing-module assertion failures). After copying Suite26 unchanged, the 13 unaffected tests passed, while the newly required raw missingness/schema tests failed and embargo invocation identified its absent parameter. After the intended changes, all 16 cache tests passed.

The nine protocol tests were written and run before protocol.py existed (nine explicit missing-module assertion failures). After implementation, all nine passed. Expectations are hand-checked and cover unsorted cumulative priors, equal/future-outcome invariance, changed-earlier-outcome sensitivity, missing-grade fallback, empty-bank defaults, embargo, schema rejection, faculty balancing, latest same-term selection, full failed-origin audits, absent faculties, partial coverage, prior faculty training support, one-class rejection, future-origin rejection, and parameter validation.

Commands run from the Suite27 package directory:

```bash
python -m unittest discover -s tests -p test_cache_contract.py -v
python -m unittest discover -s tests -p test_protocol.py -v
python -m unittest discover -s tests -v
```

Targeted results: 16/16 cache tests and 9/9 protocol tests pass. Full discovery at the time of this subsystem handoff ran 31 tests, with 29 passing and two import errors: `test_memory` lacked the in-progress `memory.py`; `test_experiment` lacked the in-progress `experiment.py`. These are concurrent restoration dependencies, not a claim that the complete package is verified. Parent must rerun full discovery after those modules are restored. The primary runtime does not include pytest, so verification uses the existing unittest test style.

A real joblib integration probe generated 16-student IT/BUS synthetic folds 1 and 2, loaded both through the restored cache layer, fitted preprocessing, constructed embargo=1 histories and priors, and selected supported development origins. Fold 1: 224 history rows, 32 target rows, 48 x columns, origin 6064, 14 audit cells and 14 absent historical grades. Fold 2: 256 history rows, 32 target rows, 48 x columns, origin 6065, 16 audit cells and 16 absent historical grades. Every retained history event satisfied the strict embargo; evidence was finite and faculty weights averaged one. The fixture is software-only and was removed with its temporary directory.

## Limits and integration notes

Existing source-cache assumptions are unchanged: previous-semester grades are assumed released by the next semester because canonical caches have no release timestamps. Positive embargo filters retrieved outcomes and prior means; original canonical row-time features and preserved structured course features retain their supplied source semantics. The caller remains responsible for creating a fresh training-only preprocessor at every origin and for saving/printing unsupported audits outside this library layer.

The checkout has no git metadata, so source comparison and SHA256 fingerprints were used for restoration provenance. Root owns persistence and packaging of the complete deliverable.

## Restored file SHA256

- `data.py`: `330d7cc7c35358000ac34250a94458309019b021b4503191439d884addfbaa3a`
- `protocol.py`: `cb4c533e33ac7fe8bd04e544ecde90bfc5c4442087d3fe2ae8fe43fd6d126a89`
- `make_synthetic_cache.py`: `b551c0ed4d99aed1db872dd0d8024d57434b74edd8d9d6c48b11c3c79043a5a1`
- `tests/test_cache_contract.py`: `efa9a2b2d40bfff0d86342b004be7626e02ad52bfaef275c46f70cb58dd72f4f`
- `tests/test_protocol.py`: `1745e79aae9126d537836dbf6fbd32d71692df52145c6ef6ec7aea6931ee3611`

## Final support-rule correction

The initial restoration mistakenly applied `min_rows` to each faculty. The approved 2,000-row minimum applies to the entire single-semester cohort; `min_faculty_rows=30` applies to each validation faculty and its earlier training support. The corrected audit includes `origin_rows`. Red/green regressions cover total cohort 24 accepted with minimum20 and rejected with minimum25, and large cohorts with an unsupported faculty. Twelve protocol tests passed after correction. Later package validation records supersede early import-pending counts above.
