Academic recovery.

The marketing line for this module reads "catch-up, remedial, resits, exam-prep." That is the family of ideas. The part this handbook documents in depth — and the part with its own tables, its own admin screen, and its own grade-writeback engine — is academic recovery: the catch-up window a school opens for students who did not pass the term. It is built on two tables, academic_recovery_configs and academic_recovery_enrolments, plus the shared holiday-class window primitive.

The two neighbours are real but separate, and we are honest about that here. Resits are a distinct module with their own rules engine, their own pages (/dashboard/grades/resits and /portal/resits) and their own report-card override. Exam-prep is not a standalone feature at all — it is a purpose tag on a holiday-class window (purpose = 'exam_prep'), scheduled through the holiday-classes surface at /dashboard/timetable/holiday-classes. The last chapter of this book maps those neighbours so you know which screen to open.

Recovery is the term's second chance — granted by rule, paid for or waived, consented to, and recorded against the grade that failed.

Recovery starts where the year ends. When the registrar runs the end-of-year class rollover at /dashboard/grades/promotion/run, the promotion engine writes each student a promotion status — promoted, retained, or conditional. The rollover then makes a best-effort call to the database function auto_route_retained_to_recovery: for every retained or conditional student it works out the subjects they actually failed (each subject scored below the school's pass mark), finds the published recovery window that covers their class, and writes them an enrolment row in status eligible — with the failed subject ids stored on enrollment_subjects and the term that triggered it stamped on triggered_by_term_id.

The routing is idempotent — re-running the rollover never creates a duplicate, because the enrolment table carries a UNIQUE (recovery_window_id, student_id) constraint. It is also wrapped so that a routing failure can never abort a rollover that has already committed promotions. The rollover's result JSON reports a recovery_routed count so the registrar can see how many students were picked up.

Before the routing can know who qualifies, the school writes the rules. A recovery config — created at /dashboard/recovery — is a small policy object: a trigger, an optional threshold, and a rule for what a recovery score does to the grade. The admin page's first section is a form that saves one config; below it, every active config is listed as a row of badges.

A config decides who; a window decides when. Recovery windows are not a separate table — they reuse the same holiday_class_windows primitive that all holiday-class scheduling runs on, tagged with purpose = 'academic_recovery'. A window carries a name, a date range, the classes / sections / subjects it covers, an optional fee, a consent flag, and a published flag. It is created and published from the holiday-classes surface at /dashboard/timetable/holiday-classes.

The auto-router only enrols students into a window that is published and that scopes to their class. So the sequence at year-end is: publish the recovery window first, then run the rollover — the routing slots retained students straight into it.

The second section of the recovery admin page is the window's roster. The admin enters a window's id to load its enrolments; each row shows the student, their status badge, consent and fee-waived markers, and the recovery score once recorded. An enrolment moves through seven statuses: eligible → enrolled → attended → graded → final, with withdrew and no_show as the two off-ramps.

Two actions live on each row. Record consent stamps parent_consent_at for a student whose family has agreed — available to anyone with academic_recovery.manage or students.edit. Grade captures the recovery score and sets the status to final. The grade itself does not touch the report card yet — that is a deliberate second step, covered next.

The bridge between a recovery score and the report card is a single boolean: applied_to_term_grade. While it is false, the score is recorded but advisory. The moment it flips to true, a database trigger (trg_academic_recovery_apply_outcome) fires the function apply_recovery_outcome, which reads the config's outcome rule and writes the result back into the grade ledger.

It does this carefully. Rather than overwrite the original term score, it writes the recovery result against a synthetic, zero-weight RECOVERY exam type (created once per school by get_or_create_recovery_exam_type), so the recovered mark acts as a subject-level override without disturbing the normal CA-plus-exam weighting. For each failed subject it applies the rule — replace-if-pass, best-of-two, or average — resolves the new letter grade and GPA from the school's grade boundaries, and upserts a student_scores row. Under no grade impact it writes nothing and simply records the outcome for the audit trail.

There is a second path to the same trigger. When a recovery window is run as a graded holiday class and a student passes it, a bridge trigger on the holiday-class enrolment flips the matching recovery row to applied_to_term_grade = true automatically — closing the loop without a manual step.

Recovery is not a back-office secret. Every student and parent has a read-only window onto it at /portal/recovery. A parent with more than one child picks a child; the page then lists that student's recovery enrolments. Each card shows the status, the recovery score, an "applied to term ✓" marker when the writeback has fired, the number of subjects under recovery, parent-consent and fee-waived notes, and any free-text note the school added.

The portal is strictly a consumer surface — enrolling, configuring, and grading all stay on the admin web. Row-level security narrows the read to the caller's own (or their child's) enrolments, so a family only ever sees their own.

Resits are the formal re-sit of a paper, governed by per-program resit rules, auto-spawned when a term is compiled, billed (when run as a holiday resit) and overlaid back onto the report card through a resit override. They are a separate module with their own admin page at /dashboard/grades/resits and a family view at /portal/resits. If you are looking for "the student re-sits the exam," that is resits, not recovery.

Exam-prep has no page of its own. It is a holiday window with purpose = 'exam_prep' (and 'resit_prep' for resit revision), scheduled at /dashboard/timetable/holiday-classes. Think of it as recovery's lighter cousin: coaching time before the exam rather than a second chance after it.

The recovery engine is complete and has been verified against the live database; the admin authoring surface is where the rough edges are. These items are planned.