Scheduling engine

Who this is for: Developers and advanced admins
What you'll achieve: Understand materialise → recompute → publish

Implementation lives in packages/domain (especially engine.ts) and is invoked from apps/web day services.

Pipeline

flowchart LR
  Template[Weekly template] --> Build[Build day]
  Build --> Absences[Apply absences]
  Absences --> Gaps[Find gaps]
  Gaps --> Score[Score candidates]
  Score --> Propose[Propose revision]
  Propose --> Publish[Explicit publish]
  Publish --> Notify[Notification rules]

1. Build: copy template slots/assignments into a day revision
2. Apply absences: remove unavailable people
3. Find gaps: unmet headcount / lead / capability requirements
4. Score candidates: duty tiers, grade priority, capabilities, fairness heuristics
5. Propose: write a draft revision with explanations
6. Publish: lock revision; fire notifications

Hard rules (product)

• Engine output is a proposal: a duty lead must confirm publish. Approving a staff rota change request is that confirm step: it reruns proposeRecompute (absences, approved change-request windows, availability, skills, lunch) and republishes if the day was already live.
• Split sessions share one session group only when you used Split session (or the matching chat action). Someone already on one half cannot take the other half of that sitting. Rebuild does not cut long lunch posts into tiles.
• Last-resort placements must remain visible and explainable
• Audit trail records publish and material config changes

Same-day ops

Recording an absence triggers a propose recompute. Duty leads can review and publish from Today or Timetable. Lesson-cover assignment, review week, and clash resolve remain on Today. See Recording absences. Approved staff change requests add a duty-window unavailability and call the same recompute path.

Tests

pnpm test

Domain unit tests cover constraint and scoring behaviour.

Related

• Today board
• docs/SYSTEM_PLAN.md §10