Building a timetable the solver will stand behind

The grid is the shape of the week: each period has a label, a start and an end, and the days it runs on. A period that runs every teaching day needs no days listed.

Break and lunch belong in the grid rather than being left as gaps, marked as non-teaching. A solver that cannot see lunch will schedule a lesson through it, so the way to protect a period is to describe it rather than to omit it.

• Label, start and end time, and the days it runs.
• Non-teaching periods are visible to the solver and never filled.
• With no teaching periods defined, nothing can be generated at all — and the solver says exactly that.

A requirement is one line: this class, this subject, this many periods a week — optionally with the teacher who takes it and the room it needs. That is the whole input, and it is deliberately small, because a timetable argument is usually about the requirements rather than about the algorithm.

Days can be blocked per requirement. This is where the awkward real constraints live, and stating them up front is cheaper than discovering them in the published week.

Generating shows what the solver would produce without writing anything. Requirements it could not fully place are listed as unplaced, each with the reason it failed — a lesson is never forced into a slot that breaks a constraint and left for somebody to discover later.

The candidate is checked for clashes using the same engine the live timetable is checked with, so a proposal cannot be presented as clean on the solver's own say-so.

• Unplaced is information, not a failure — it is the timetable telling you the week is over-subscribed.
• The three real fixes are more periods, a freer teacher, or fewer required periods.
• Nothing reaches the school until the candidate is accepted.

Accepting can either replace the published week or add to it. Replacing starts the solver from an empty week; adding keeps what is already published and fills around it.

The week is solved again on the server at this point rather than taking the candidate the browser sends back. The roster may have moved since the preview, and a client can send anything it likes — neither is a good reason to publish a timetable to a school.

Once published, the week is what teachers, students and families read, and what attendance and cover are organised against. A teacher's view is narrowed to their own teaching rather than the whole school grid.

Keeping the timetable current is covered in Running the day — this doc is about building it in the first place.