Student promotion between grades

Promotion is decision-first. Rather than dragging students between classes, you record one PromotionDecision per student for the source academic year, then apply it. Each decision is unique per student and source year, so re-running the apply step updates the existing decision instead of creating a duplicate, which makes the whole operation safe to repeat after a partial failure.

Applying a decision does two writes inside one transaction: it closes the old class membership with a status of PROMOTED, RETAINED, or DROPPED, and it opens an ACTIVE membership for the target academic year. It also syncs the classGrade, section, and stream fields on the student user, which is what most list screens and capacity counts read.

Prerequisites

• The target academic year exists - create it at /academic-year or through /academic-year/rollover
• Target class sections exist and are active for the new year, at /classes
• Decisions are recorded for the source year, otherwise /students/promotions shows nothing to apply
• Every decision carries a target academic year and target class; the apply action refuses a decision missing either

What happens per decision

Handoff

What crosses the boundary is class membership for the target year, and that is what almost everything else keys off. Teacher assignments are made per class and year, attendance and gradebook read the active roster for a class, exam seating pulls the active students of the classes with papers, and admissions seat maths counts the live roster when deciding whether a grade still has room. Apply promotions before anyone starts marking, and before the admissions committee reopens offers for that grade.

Limits

• Promotion does not generate fee instances. Run /fees/bulk-generate for the new year afterwards
• There is no automatic pass or fail rule from marks; a human sets each decision
• Leaving students still need a transfer certificate issued separately at /students/certificates, and deactivation is preferred over deletion