Academic Year Rollover Backend Documentation

1. Documentation Evidence

2. Backend Scope and Boundaries

Owns

• The rollover cycle lifecycle: create, sync, review, cancel.
• Per-pupil rollover items: status, exceptions, warnings, target class/roll, inclusion/exclusion.
• Section allocation and roll allocation preview/apply.
• Background processing: leasing, chunked per-item placement, retry, recovery.
• Activation preflight and the trigger to make a target session current (delegated to academic-sessions.service.ts).
• Finalization and source-session locking.
• Post-processing corrections: move, realign, relink, withdraw a placement.
• Rollover settings (strategy defaults, notification channels, capacity policy).
• Read-only insights: event timeline, integrity checks, ID-card readiness, new-admission detection.
• Placement and admin notifications specific to rollover outcomes.

Does Not Own

• Promotion decisions themselves — read-only input from the promotions module. See Promotions backend.
• The academic session entity and is_current switch mechanics — owned by academic-sessions; rollover calls into it, it does not duplicate it.
• Enrollment writing and removal mechanics — owned by enrollments-core; rollover calls ClassEnrollmentsService.enroll rather than inserting rows itself.
• Notification delivery transport (channels, retries, templates infrastructure) — owned by the notifications module; rollover only supplies template kinds and variables.
• ID card generation itself — rollover only reports readiness counts.

Source of Truth

3. Module Composition

4. File and Directory Map

apps/api/src/modules/rollover/
  rollover.module.ts
  cycles/
    admin/rollover-cycles.controller.ts
    core/rollover-cycles.service.ts
    core/rollover-cycle-review.service.ts
    core/rollover-cycle-view.service.ts
    core/rollover-overview.service.ts
    dto/rollover-cycle.dto.ts
  items/
    admin/rollover-items.controller.ts
    core/rollover-items.service.ts
    core/rollover-items-query.service.ts
    dto/rollover-item.dto.ts
  allocation/
    admin/rollover-allocation.controller.ts
    core/rollover-section-allocation.service.ts
    core/rollover-roll-allocation.service.ts
    dto/rollover-allocation.dto.ts
  processing/
    admin/rollover-processing.controller.ts
    core/rollover-processing.service.ts
    dto/rollover-processing.dto.ts
  activation/
    admin/rollover-activation.controller.ts
    core/rollover-activation.service.ts
    dto/rollover-activation.dto.ts
  corrections/
    admin/rollover-corrections.controller.ts
    core/rollover-corrections.service.ts
    core/rollover-realign.service.ts
    dto/rollover-correction.dto.ts
  settings/
    admin/rollover-settings.controller.ts
    core/rollover-settings.service.ts
    dto/rollover-settings.dto.ts
  insights/
    admin/rollover-insights.controller.ts
    core/rollover-insights.service.ts
    dto/rollover-insights.dto.ts
  shared/
    rollover-shared.module.ts
    rollover-codes.ts
    rollover-cycle-access.ts
    rollover-fingerprint.service.ts
    rollover-placement.service.ts
    rollover-process-request.service.ts
    rollover-readiness.service.ts
    rollover-run.service.ts
    rollover-sections-view.service.ts
    rollover-sync.service.ts
    rollover-validation.service.ts
    rollover-worker.contract.ts
    placement-notification.service.ts
    with-lock-retry.ts
    worker-actor.ts
  workers/
    academic-year-worker.module.ts
    academic-year-queue.processor.ts
    academic-year.scheduler.ts
    academic-year-sweep.service.ts
    rollover-runner.service.ts
    rollover-admin-notice.service.ts
apps/api/src/utils/rollover/
  section-allocation.util.ts
  roll-allocation.util.ts
  rollover-fingerprint.util.ts

5. Data Model

5.1 Schema Source

packages/db/src/schema/school/rollover.ts
packages/db/src/schema/school/academic-sessions.ts (lock columns)
packages/db/src/migrations/0035_promotions_rollover.sql
packages/db/src/migrations/0036_promotions_rollover_guards.sql

5.2 Tables

rollover_settings — singleton configuration

rollover_cycles

Constraints: unique public_id; one live cycle per source/target/promotion-cycle triple (WHERE status != 'cancelled'); code format; distinct sessions; lease consistency (a token implies an expiry and vice versa); attempt/recovery_count bounds; running implies run_started_at is set; idle implies no lease; processed implies run_outcome is set; activated/finalized each imply their timestamp/actor pair; notification_attempt in [0,100]; cancelled implies run_state = idle.

rollover_items

Constraints: unique (cycle_id, student_id); roll range 1–999; placed implies enrollment_id set; graduated implies graduation_id set; excluded triple consistency (inclusion = excluded requires exclusion_source and exclusion_reason); override pair consistency; outcome_code implies a terminal-or-failed status; processed_at implies status is not pending; an excluded item is never processed; text length bounds on reasons; attempts bounded 0–1000.

Indexes: (cycle_id, status, process_order), (cycle_id, target_class_id), (cycle_id, target_grade_id), enrollment_id, student_id.

student_graduations

Constraints: revoked triple consistency. Index: unique per student where revoked_at IS NULL (one live graduation record at a time); session_idx on academic_session_id.

rollover_events — append-only timeline

Constraint: every event has an anchor — either cycle_id or session_id is set. event_type is checked against the known list. Indexes on cycle_id, student_id, session_id.

Event types (29): cycle_created, items_synced, validated, item_excluded, item_included, target_class_changed, roll_changed, capacity_override, allocation_applied, roll_allocation_applied, review_prepared, processing_started, processing_retried, processing_finished, processing_failed, processing_recovered, placement_created, graduation_recorded, placement_corrected, placement_realigned, placement_withdrawn, graduation_revoked, year_activated, cycle_finalized, session_locked, session_unlocked, cycle_cancelled, placement_notifications_queued.

Every item mutation event (rollover-items.service.ts) carries actorUserId. target_class_changed's fromValue/toValue are each { classPublicId }; roll_changed's are each { rollNumber }; capacity_override's toValue is { enabled, reason } (fromValue carries the prior { enabled }). item_excluded and item_included carry no fromValue/toValue — the transition itself is the payload. Corrections write the same target_class_changed shape.

Append-only enforcement: a BEFORE UPDATE OR DELETE trigger raises unless pg_trigger_depth() > 1 (i.e. the mutation is happening as a cascade from a parent delete, such as the cycle itself being removed) — see 0036_promotions_rollover_guards.sql:131-143.

academic_sessions — lock columns (owned by academic-sessions, consumed here)

Constraints: locked_at IS NULL ⟺ lock_reason IS NULL; lock_reason length bound; NOT (is_current AND locked_at IS NOT NULL) — the currently active session can never simultaneously be locked.

5.3 Relationship Diagram

6. Services and Responsibilities

6.1 RolloverCyclesService

6.1a RolloverCycleReviewService

State transitions on an existing cycle, kept apart from RolloverCyclesService so each stays a single-purpose service.

6.2 RolloverCycleViewService / RolloverOverviewService

Read-only mappers. RolloverCycleViewService assembles the detail view including the readiness checklist; RolloverOverviewService assembles the dashboard: current/suggested session, active cycle summary (with readiness omitted for brevity), student/decision counts, and recent cycle history.

6.3 RolloverSyncService

Code flow narrative: the roster is defined as every student with a current promotion decision and an active enrollment in the source session. For each roster member without an existing item, a row is inserted; if their decision outcome is excluded, the item is immediately marked inclusion = excluded, exclusion_source = decision, exclusion_reason = "The current promotion decision outcome is excluded.". For an existing non-terminal item, source-session fields (enrollment, class, grade, section, shift, roll) and the decision/outcome are always resynced; if the resynced target grade differs from what was there before, target_class_id and planned_roll_number are cleared and a target_class_changed event is recorded. Inclusion is only auto-adjusted when the exclusion was itself auto-derived (exclusion_source = decision) — a manual exclusion is never overwritten by sync. Terminal items (placed, graduated, withdrawn) are never touched.

6.4 Section Allocation — RolloverSectionAllocationService and apps/api/src/utils/rollover/section-allocation.util.ts

Capacity counting rule: for a target class C, occupied(C) = used(C) + fixed(C), where used(C) is the live enrollment count in that class (via the class occupancy service) and fixed(C) is the count of this cycle's already-placed-or-pinned items already holding a seat in C that the current preview treats as fixed (onlyUnassigned: true excludes them from being re-shuffled but still counts their seat).

Strategies:

• balanced — sort students by name (locale-aware, numeric-aware collation). For each student, in order, compute their eligible classes (all active classes in the target grade, or same-shift-only when preserveShift narrows it and a same-shift class exists), then assign to the eligible class with the lowest occupied + assignedThisPass (ties broken by section order). A student with no eligible class with room is left unassigned. When rolloverSettings.balanceGender is on and the student's own gender is male or female, the candidate pool is instead narrowed first to the classes within 1 of the minimum projected size, and the assignment within that pool goes to whichever class currently holds the fewest pupils of that same gender (ties broken by projected size, then section order). A pupil recorded as other, prefer_not_to_say, or with no gender is never part of this narrowing — they are placed by size alone, and neither counts toward nor is balanced against anyone else's gender.
• keep_previous — two phases. Phase 1: sort by name; for each student, try to place them back into a class that shares their source section, subject to shift and room; assign if such a class has room. Phase 2: everyone not placed in phase 1 falls through to the balanced algorithm.
• alphabetical — partition students by their eligible-class set (so shift-restricted students form their own group), sort each group by name, sort that group's classes by section order, then distribute in contiguous blocks, one class at a time: blockSize starts at min(capacityLeft(class), ceil(remainingStudents / remainingClasses)), then is raised (water-filled) to at least remainingStudents - totalCapacityLeftInLaterClasses so a later, smaller class can never be left with more students than it has room for, and is finally clamped back to capacityLeft(class). A forward-only pass can still fall short of a perfect partition in rare edge cases the water-fill formula doesn't anticipate, so a spill pass runs afterward: whatever is left over is placed into whatever capacity remains, walking the group's classes in section order. Once a group's classes are all full, remaining students in that group are unassigned.
• previous_roll — identical block-distribution mechanics to alphabetical, but the group is sorted by source roll number ascending (nulls last), then section order, then name.

Unassigned reasons: NO_CLASS (grade has no eligible class at all), NO_CLASS_FOR_SHIFT (shift restriction narrowed eligibility to zero classes), CAPACITY (every eligible class is full).

Worked example — 85 students into two classes of capacity 40, strategy balanced, no shift restriction:

1. Sort all 85 students by name.
2. For the first student: both Section A and Section B have occupied = 0; tie broken by section order → assigned to A. A.assigned = 1.
3. The algorithm keeps assigning each subsequent student to whichever of A/B currently has the lower occupied + assignedThisPass — this alternates, filling both roughly evenly, until one of them reaches capacity 40.
4. Once A reaches 40, every remaining candidate's only eligible class with room is B, so B receives the rest until it, too, reaches 40.
5. Result: A = 40, B = 40, and the remaining 5 students are left unassigned with reason CAPACITY.

Worked example — 60 students into three sections of ample capacity (10 each already reserved elsewhere, effectively unconstrained here), strategy alphabetical: with three classes and 60 students and no capacity bound reached, the block size per pass is ceil(60/3) = 20, so section order 1 receives the first 20 names alphabetically, section order 2 the next 20, and section order 3 the final 20 — a clean 20/20/20 split with zero unassigned.

Applying with onlyUnassigned: false re-computes every item, not just the currently-unassigned ones, so an item the fresh computation now leaves unassigned is not left claiming its previous class: apply clears that item's targetClassId and plannedRollNumber rather than skipping it. With onlyUnassigned: true this never happens, because an already-assigned item is excluded from the movable set and is never revisited.

Endpoints (allocation.controller.ts): GET /rollover/cycles/:publicId/sections (Rollover_READ), POST .../section-allocation/preview (Rollover_UPDATE), POST .../section-allocation/apply (Rollover_UPDATE, token-checked).

6.5 Roll Allocation — RolloverRollAllocationService and apps/api/src/utils/rollover/roll-allocation.util.ts

Max roll number: 999. nextFree(taken, from) scans upward from from and returns the first roll not in taken, or null if none remain up to 999.

Scopes: section — one independent reserved-roll set per target class. grade — one reserved-roll set spanning every class in the grade (so no two sections of the same grade can share a roll number).

Reserved set: for a given scope, the rolls already taken by live, non-rollover enrollments in that scope's class(es), plus any roll already assigned to this cycle's own placed/pending items in that scope.

Strategies:

• keep_previous — phase 1: sort items by source roll ascending (nulls last), then section order, then name; for each, if the source roll is a valid number (1–999) and not already taken in its scope, assign it that same number. Phase 2: everything deferred from phase 1 is sorted the same way and each takes nextFree in order.
• alphabetical — sort items by name; each takes nextFree in that order.
• previous_roll — sort items by source roll then section order; each takes nextFree in that order.

Worked example — 60 students split roughly 20/20/20 across three sections, scope section, strategy alphabetical: each section is its own independent group with its own empty reserved set. Within Section A, the 20 students are sorted by name and assigned rolls 1 through 20 in order (nextFree(∅,1)=1, then nextFree({1},1)=2, …). Section B and Section C run the identical process independently, each also producing rolls 1 through 20 — because the scope is section, not grade, three different pupils across the three sections can legitimately hold roll number "1" simultaneously.

If the settings instead used scope grade for the same 60 students, the reserved set would span all three sections at once, so the assignment would instead produce one continuous sequence, 1 through 60, with no repeats across sections.

Endpoints: POST /rollover/cycles/:publicId/roll-allocation/preview and /apply (Rollover_UPDATE), token-checked against the preview's proposalToken the same way as section allocation — a mismatch raises ROLLOVER_PROPOSAL_STALE.

6.6 RolloverValidationService

Set-based: builds the relevant sets once (occupied rolls per scope, occupied seats per class) rather than issuing one query per item, so cost does not scale linearly with roster size. validateCycle re-runs, in the same transaction as the triggering write, after: cycle creation (which reads the settings row FOR SHARE, so it waits for an in-flight settings save), section allocation apply, roll allocation apply, every correction, every item mutation (include/exclude, target-class change, roll change, capacity override), the end of a processing run, whether the runner finishes it or the recovery sweep stops it after exhausting recoveries (so a settings change made while the cycle was running is applied once it goes idle; both paths read the settings row FOR SHARE first; on the sweep path the re-validation runs in a savepoint, so a validation error is logged and the stop still commits, and a failure on one stalled cycle never stops the sweep from handling the others or from retrying publications and placement notices), and a rollover settings update — the last one locks, in id order, and revalidates every cycle item edits can still reach (status preparing, processed, activated or finalized with runState = 'idle'), not only the cycle being edited, because validateCycle reads capacity policy, conditional-placement and roll-scope settings live rather than storing them per item. It resets exception/warning codes before recomputing, then writes back only the items whose codes changed, in one UPDATE … FROM (VALUES …) per 500 rows ordered by id; validated_at therefore records when an item's codes last changed. Every caller holds the cycle FOR UPDATE, so validating writers on one cycle run one at a time instead of deadlocking on each other's item rows.

Capacity counting rule (exact): this differs by capacity_policy. Under allow_override, every item with capacity_override set is admitted unconditionally and counted first, seeding the class's admitted counter — an override item never receives SECTION_CAPACITY itself. The remaining (non-override) items for that class are then walked in process_order, admitted while used + admitted < capacity, with every item beyond that point receiving SECTION_CAPACITY. Under capacity_policy = "block", capacity_override has no effect: an overridden item is a normal candidate, walked in process_order with everyone else and subject to the same used + admitted < capacity cutoff.

Duplicate roll detection: computed per scope (section or grade, per rolloverSettings.rollScope) by comparing live non-rollover rolls plus this cycle's planned rolls; any collision marks every colliding item DUPLICATE_ROLL.

Exception codes it can set: INVALID_STUDENT_STATUS, MISSING_DECISION, DECISION_PENDING, DECISION_CHANGED, CONDITIONAL_NOT_ALLOWED, MISSING_TARGET_GRADE, TARGET_GRADE_NO_CLASS, MISSING_SECTION, TARGET_CLASS_INVALID, SECTION_CAPACITY, DUPLICATE_PLACEMENT, GRADUATE_HAS_TARGET_PLACEMENT, EXISTING_GRADUATION, DUPLICATE_ROLL, ADMISSION_AFTER_TARGET_END. Warning codes: MISSING_SECTION, MISSING_ROLL, ALREADY_PLACED.

6.7 RolloverFingerprintService

Computes a hash over exactly the state that would change the outcome of processing: every non-terminal item's id, studentId, live currentDecisionId, inclusion, targetClassId, plannedRollNumber, capacityOverride; every relevant target class's id, isActive, capacity, gradeId, and current used occupancy; the settings row's version; the roll policy (strategy, scope); and the target session's isActive/isLocked/startDate/endDate plus the promotion cycle's status/version.

Used at two points: POST /rollover/cycles/:publicId/review returns the computed fingerprint to the client without storing it; POST /rollover/cycles/:publicId/process recomputes it under lock, compares it with the fingerprint the client sends back, and on a match stores it as confirmedFingerprint — any mismatch (a decision changed, a class's capacity changed, someone else edited an item) rejects the request with ROLLOVER_PREVIEW_STALE rather than silently processing against a plan the admin never actually reviewed.

6.8 RolloverReadinessService

Fifteen checks across seven groups, each returning ready | warning | error | not_applicable | pending:

Each check's warning/error state is meant to tell the operator exactly what to fix before proceeding — e.g. target_grades_have_classes: error means create at least one active class in that grade before allocation can place anyone into it; pending_decisions: warning means some pupils still lack a finalized promotion outcome and will sync in as MISSING_DECISION exceptions.

6.9 Rollover Corrections and Realign services

RolloverCorrectionsService.correct is the controller-facing entry point for the single POST .../items/:studentPublicId/correct route. It locks the cycle (FOR SHARE), the item, and the student, loads the pupil's current promotionDecisions row, then dispatches on dto.action: "move" and "relink" are handled directly by RolloverCorrectionsService; "realign" is delegated to RolloverRealignService.realign, which dispatches again on the item's current status and decision outcome (cases a–f below), all inside the same transaction:

Every case that leaves the item with an enrollment (move, relink, and realign cases c/d) triggers a rollover.placement_changed guardian notification once the transaction commits, unless the cycle is still preparing/processed or rolloverSettings.notifyPlacement is off. RolloverCorrectionsService never issues a raw INSERT into student_class_enrollments — every placement, original or corrected, goes through ClassEnrollmentsService.enroll in enrollments-core, so the corrections path and the original processing path share the same enrollment invariants.

Un-graduating restores access, not just placement. Before cases (d) and (e) mark a graduation revoked, RolloverRealignService calls GraduateAccessService.undoForRevoke to give back whatever ending that graduation's access took — the pupil's role grants always, and sign-in only when the actor performing the realign holds Users_UPDATE (mayRestoreSignIn, resolved once before the transaction opens). An actor without Users_UPDATE can still un-graduate a pupil; the pupil's own sign-in simply stays whatever it already was.

allowOverCapacity applies to move only, and correct checks it in a fixed order so a 409-vs-403 response can never be used to probe the school's rollover settings: (1) before the transaction even opens, an actor sending allowOverCapacity: true without RolloverOverrides_UPDATE gets 403 Forbidden (ROLLOVER_OVER_CAPACITY_NOT_PERMITTED) regardless of dto.action or the current capacity policy; (2) inside the transaction, allowOverCapacity: true on any action other than move gets 400 Bad Request (ROLLOVER_CORRECTION_INVALID); (3) only then is rollover_settings.capacity_policy read — if it is not allow_override, the request gets 409 Conflict (ROLLOVER_OVERRIDE_NOT_ALLOWED). A move that passes all three enrolls over capacity, stamps the item's capacityOverride/overrideReason/overrideByUserId/overrideAt together (an ordinary move without the flag explicitly clears all four rather than leaving a stale override in place), and the placement_corrected event's toValue carries overCapacity: true|false — computed by re-counting the destination class's occupancy after the enrollment, while the class row is still locked, so it reflects the seat this move itself just claimed. overCapacity is present only when allowOverCapacity was set; an ordinary move's event carries no such field.

6.10 RolloverPlacementService

The per-item write path used by both the runner and, indirectly, corrections. Placement sequence: call ClassEnrollmentsService.enroll (never a direct insert), optionally assign the roll number, update the item's status = placed with enrollmentId, and insert a placement_created rollover event. No writes ever touch the source session, its classes, or its enrollments — only the target session is written.

6.11 RolloverActivationService

preflight() evaluates the blocking and warning code sets (see §13) without writing anything. activate() re-checks preflight, then calls academic-sessions.service.ts's switchCurrent(targetSessionId, { via: "rollover" }). Passing via: "rollover" deliberately skips the in-flight-cycle guard that a manual session switch would otherwise trip — the whole point of the call is to complete the cycle that guard would object to. switchCurrent still independently checks that the target session is not locked; that check is not bypassed. On success, activation flips is_current on both sessions inside one transaction, updates the cycle to activated, and — if notifyPlacement is enabled and unnotified placements exist — enqueues NOTIFY_PLACEMENTS. finalize() sets status = finalized and can optionally lock the source session in the same call.

6.12 RolloverCycleAccessService

findCycleByPublicId supports row locking modes: FOR UPDATE for anything that changes cycle-level state (activate, finalize, process request), FOR SHARE for item-level work that must not race a state change but doesn't itself need exclusivity. assertCycleMutable requires the cycle's status to be in an allowed set for the operation and runState = idle — nothing may mutate a cycle mid-run.

6.13 RolloverSectionsViewService

Pure read. For each target class returns occupied (from a live enrollment count query), planned (count of this cycle's items with a matching targetClassId and a placeable outcome), and remaining = capacity - occupied - planned. No writes.

6.14 PlacementNotificationService

enqueuePlacementNotifications is called from three places that all hold the same guarantee — the item rows it will notify for already have a committed placement: RolloverActivationService.activate() (on activation), RolloverRunnerService's finish step (when processing itself finishes against an already-activated/finalized cycle), and RolloverActivationService.retryNotifyPlacements() (the POST .../notify-placements route, for a failed or previously-unsent none state). sendAll (the NOTIFY_PLACEMENTS job handler) refuses to run against a cycle that is not activated or finalized — so even if a job were somehow enqueued early, the handler itself is the second gate against sending a notification for a placement that hasn't actually taken effect yet.

The channel list comes from the cycle's own settingsSnapshot.placementChannels, frozen at cycle creation rather than read live from current settings. sendAll loops in chunks, each chunk one transaction locking only rollover_items (FOR UPDATE SKIP LOCKED) and excluding soft-deleted pupils, draining the un-notified, placed item rows until none remain, then recounting eligible rows before marking the cycle's placement-notification state sent — the same lock/drain/recount shape PromotionPublicationService.publish() uses for promotion decisions.

7. Runtime Flows

7.1 Processing request → enqueue

7.2 Chunked processing loop

• Lease: LEASE_SQL = clock_timestamp() + interval '2 minutes', claimed with a conditional UPDATE ... WHERE id = ? AND attempt = ? AND (lease_expires_at IS NULL OR lease_expires_at < clock_timestamp()) RETURNING *. An unclaimed row (already held by a live lease) raises RolloverLeaseHeldError, which BullMQ's own retry/backoff handles.
• Chunk size: 50 items per pass, fetched with FOR UPDATE SKIP LOCKED ordered by process_order — SKIP LOCKED lets a concurrent admin correction lock an item the runner hasn't reached yet without blocking either side.
• Per-item transaction: each item is processed inside its own db.transaction. An unhandled error is caught, the item is marked failed with outcomeCode = UNEXPECTED_ERROR, attempts incremented (capped at 1000), and the loop continues to the next item rather than aborting the run. A pupil who has been soft-deleted between the process request and this item being reached is marked needs_review/INVALID_STUDENT_STATUS rather than placed — this covers the graduation path in particular, since enroll() already refuses a soft-deleted pupil on the ordinary placement path.
• Deferred effects: cache/audit-adjacent side effects for an item are buffered and flushed only after that item's transaction commits, so a rolled-back item never leaves a stray side effect.
• Heartbeat: checked after every item, but only actually renewed once at least 30 seconds have elapsed since the last renewal — the runner updates lease_expires_at and last_heartbeat_at where lease_token still matches; if another attempt has since claimed the lease, this raises RolloverLeaseLostError, the runner stops writing immediately, and the run reports lease_lost (the sweep will recover it).
• Per-item lock timeout: each item's placement runs in its own transaction with SET LOCAL lock_timeout = '30s'. A lock that doesn't clear in time fails only that item (failed/UNEXPECTED_ERROR) rather than hanging the whole run — a hung run would otherwise hold the ACADEMIC_YEAR queue's single worker slot (concurrency: 1) forever, and the recovery sweep shares that same queue so it could never step in to rescue it. Only an actual lease loss aborts the run itself.
• Finish: computes run_outcome from the item-status counts (or forces partially_completed if a failure_code was set), transitions preparing → processed (other statuses left alone — a re-process of an already-processed cycle doesn't regress it), clears the lease, inserts processing_finished/processing_failed, calls RolloverAdminNoticeService, and — if notifyPlacement is enabled, the cycle is activated/finalized, and unnotified placements exist — enqueues NOTIFY_PLACEMENTS.

7.3 Recovery sweep

Stalled-run predicate: run_state = 'running' AND (lease_expires_at < clock_timestamp() OR (lease_token IS NULL AND last_heartbeat_at < clock_timestamp() - interval '3 minutes')) — the second branch covers a job that was enqueued but never claimed by any worker before being lost.

Recovery: increments recovery_count, clears the dead lease fields, stamps a fresh heartbeat, inserts a processing_recovered event, and re-enqueues via the outbox with a dedupe key of rollover-{publicId}-{attempt}-r{recoveryCount} — the attempt itself does not change, since this is a resumption of the same logical run, not a new one.

Exhaustion: at recoveryCount > 5 (MAX_RECOVERIES = 5), the sweep gives up: run_state = idle, run_outcome = partially_completed, status advances preparing → processed if still preparing, lease cleared, failure_code = RECOVERY_EXHAUSTED, and an admin notice fires with that reason.

Stuck notification recovery: applies the same 10-minute-stuck / 5-attempt-cap pattern independently to promotion publications and to placement notifications, each tracked by its own *QueuedAt/attempt columns.

Graduate-access expiry pass: the same tick also selects up to 200 live graduations (revokedAt IS NULL, portalAccessEndedAt IS NULL, portalAccessUntil < today), ordered so a row that failed a previous attempt (portalAccessSweepFailedAt) sorts after every row that hasn't been tried yet, then by portalAccessUntil and id. Each candidate is re-selected FOR UPDATE SKIP LOCKED and ended in its own transaction via GraduateAccessService.end(tx, id, "expiry", today, null, effects), which re-checks the date under its own row lock before acting — an administrator may have extended access since the scan ran. A failure on one row is caught, logged with the graduation's id, and stamped onto portal_access_sweep_failed_at via recordSweepFailure so a row that keeps failing cannot hold up every later expiry; the pass then continues with the next candidate. This pass runs after the stalled-run and stuck-notification passes in the same tick, each in its own guard, so a failure in one pass never stops the others. Until a graduation's access is successfully ended, a guardian already stops seeing that pupil (see the people module's audience-assertion rules) and the pupil's own portal writes are refused, but the pupil's own portal reads continue — they are gated by the pupil role grant, which only a successful end removes.

7.4 Session lock enforcement

The guard fires for both INSERT/UPDATE/DELETE on student_class_enrollments and classes, checking both OLD and NEW on an UPDATE so a row cannot be moved either into or out from under a locked session. The pg_trigger_depth() > 1 early return is deliberate: it lets a cascading delete (for example, deleting a student, which cascades into their enrollments) proceed even if some of those enrollments belong to a locked historical session, while still blocking any direct edit to a locked year's records.

8. Caching

Rollover has no cache layer of its own. Reads go directly to Postgres on every request; there is no CacheKeyUtil usage anywhere in this module.

9. BullMQ, Schedulers, and Async Work

The processor (academic-year-queue.processor.ts) runs at concurrency 1 — a cycle's lease is held across its whole run, so there is no throughput benefit to running more than one worker process against this queue at a time; concurrency 1 also removes any need to reason about two workers racing the same lease claim.

Scheduler: academic-year.scheduler.ts fires on cron "30 */5 * * * *" (UTC, every 5 minutes at :30 seconds), enqueuing exactly ROLLOVER_RECOVERY_SWEEP with no accompanying database write — the deliberate cron-only exemption from the outbox pattern.

AcademicYearSweepService.run() runs four independent passes on every tick — stalled-run recovery, publication requeue, placement-notice requeue, and expiring graduate access — each wrapped in its own guarded(name, fn) that catches and logs rather than throws, so one pass failing (a single bad row, a transient database error) does not stop the passes after it, and the same 5-minute tick still makes progress everywhere else.

The graduate-access pass, sweepGraduateAccess, selects up to 200 live (revoked_at IS NULL, portal_access_ended_at IS NULL) graduations whose portal_access_until has already passed, ordered by portal_access_sweep_failed_at ASC NULLS FIRST then portal_access_until then id — a row that failed on a previous tick sorts behind every row not yet attempted, so one persistently failing graduation cannot starve the rest of the batch. Each candidate is ended individually, inside its own transaction, through GraduateAccessService.end(tx, graduationId, "expiry", today, null, effects) — the same method the admin endNow route calls with cause: "admin", so the read-only cutover, the sign-in check and the role-grant revocation are identical code regardless of who or what triggered it. A candidate whose end throws is caught per-row: the sweep logs the error, calls GraduateAccessService.recordSweepFailure to write a failure-status Mongo audit entry (module Students, action GRADUATE_ACCESS_ENDED, actor "system") so a repeatedly failing expiry is visible in the activity trail and not only the server log, and separately stamps portal_access_sweep_failed_at on the row (outside the failed transaction, so the stamp survives its rollback) purely to reorder the next tick's batch — it does not block or retry within the same run. result.graduateAccessEnded/graduateAccessFailed are folded into the sweep's summary log line alongside the other three passes' counts.

10. Realtime and Events

No realtime/Socket.IO events. Rollover's "event" vocabulary in this module refers exclusively to the rollover_events audit timeline table (§5.2), not to the platform's realtime gateway.

11. Security, Auth, and Abuse Controls

• Guards: every route sits behind the global JwtAuthGuard plus RoleGuard, which checks the handler's @Permissions() code against the caller's granted permissions.
• Permissions: Rollover (cycle/item/allocation browsing and everyday editing), RolloverProcessing (start/re-run processing), RolloverOverrides (place beyond capacity), RolloverCorrections (move/realign/relink a placement or graduation), RolloverActivation (make the target year current, finalize), AcademicYearLock (lock/unlock a historical session), RolloverSettings (change strategy/policy defaults). Each generates the standard CREATE/READ/UPDATE/DELETE/RESTORE codes.
• Superadmin-only by default: RolloverProcessing, RolloverOverrides, RolloverCorrections, RolloverActivation, AcademicYearLock, and RolloverSettings are all in SUPERADMIN_ONLY_MODULES — only Rollover itself is not. The rationale recorded in the permission catalog: each of these either publishes every child's outcome or placement to their family, moves the whole school into a new year, rewrites history that has already been published, or relaxes one of the gates around those actions through settings — and granting a permission has no automatic revocation path, so the safer default is to require a deliberate, reversible decision by a school to widen it, rather than defaulting wide and hoping nobody misuses it.
• Worker identity: background writes use a synthetic AuthUser built by worker-actor.ts (sessionId: "worker:rollover", no roles), so every audit entry produced during processing is visibly attributable to the background run rather than impersonating a live admin session.
• Fail-closed on locked sessions: enforced at two independent layers — the application guard in academic-sessions.service.ts/enrollment-removal-guards.ts, and the database trigger in 0036_promotions_rollover_guards.sql that fires regardless of which code path reached the table. A bug that bypassed the application check would still be stopped by the trigger.
• Enrollment removal guard: assertEnrollmentRemovable in enrollments-core/shared/enrollment-removal-guards.ts refuses to delete an enrollment if its session is locked, or if the enrollment is linked to a rollover item (ENROLLMENT_LINKED_TO_ROLLOVER) — a rollover-created placement can only be undone through a rollover correction, never a raw delete.
• Append-only audit: the rollover_events trigger makes the timeline tamper-evident even against a superadmin session — no application code path can rewrite it, only a cascading delete of the parent cycle can remove its rows.

13. Error Handling

Domain error codes (apps/api/src/common/types/error-codes.ts)

Non-HTTP outcome/state codes (shared/rollover-codes.ts)

These never appear as an HTTP status — they populate exceptionCodes, warningCodes, outcomeCode, failureCode, or a preflight/integrity report, for an operator to act on.

14. Observability

15. Testing and Validation

Validation commands: pnpm --filter @skoolsewa/api test, pnpm --filter @skoolsewa/api test:structure (route/guard fingerprint), pnpm rules (error codes, job ids). Tests run against the real database per this repo's testing rules — no mocked schema, no mocked queue.

17. Zero-Omission Backend Checklist

• Every controller, service, DTO, schema table, job, and worker in the module is represented above.
• Every table has a field table with nullability, defaults, and constraints.
• Every lifecycle (cycle, item) has a transition table and state diagram (see Feature §7).
• Every runtime flow (process request, chunk loop, sweep, session lock) has a sequence diagram and branch notes.
• Every business invariant enforced by schema constraint or service logic is called out inline.
• Every code in rollover-codes.ts, the error-code registry, and the exception filter mapping is documented.
• Every architectural tradeoff (fingerprint gate, async chunking, superadmin default, sweep design) is documented with rationale.

18. Backend Completion Checklist

• Module boundaries are documented.
• Every controller, service, DTO, schema file, job, and event is covered.
• Every database table has a field table and relationship diagram.
• Every runtime flow has a diagram and branch notes.
• API and feature/flows docs are linked.
• No claim is made without a source file checked this session.

See Also

• API doc: /docs/developer/rollover/api
• Features and flows doc: /docs/developer/rollover/feature
• Promotions: /docs/developer/promotions/backend