Calendar V5: requirements and lessons carried over from the v4 calendar #741

Chronicle's calendar was removed on 11 September (#595) for a ground-up rebuild, "V5". Its old data was deliberately not kept. This issue collects everything the v4 calendar taught us that V5 must get right, so none of it is lost as the old notes are archived. V5 hasn't started, so this is a checklist of requirements, not a plan.

• Design brief and salvage manifest: Cordinator plans/2026-08-21-calendar-v5-design-brief.md and plans/2026-08-21-calendar-v5-salvage-manifest.md.
• Every place in the code that V5 must re-wire is tagged CALV5-PLACEHOLDER: (67 tags).
• 020_calv5_schema stays unwritten until migration 019 has run on the real database (the deploy check, tracked privately).
• What the Foundry module needs from V5: the Foundry module's V5 issue (linked below as a sub-issue).

Replaces keyxmakerx/Cordinator#53 (weather dual-model) and folds in keyxmakerx/Cordinator#34 (Calendaria parity) via the Foundry issue.

Before building starts

• Calendar V5: start later, following the operator's three-step plan — Operator, 2026-09-12: not now (half the weekly usage across projects; wary of the calendar's size). When it starts: (1) a read-only research pass on a lighter model over…
• Build calendar V5 once the clean slate is deployed — After the gate: write migration 020_calv5_schema, add narrow repositories each with a Scan-arity contract test from its first method, then the one-surface…
  • Also recorded as: "Keep the calendar V5 schema unwritten until the wipe has run in production"
• Use the CALV5-PLACEHOLDER markers as the V5 re-wiring checklist — The calendar demolition left 66 CALV5-PLACEHOLDER comments in 29 files marking every seam V5 must re-wire: export/import adapters…
• Check V5's register covers the seven V2-only calendar features now gone — A 2026-08-16 sweep found seven things that die with the V2 shell beyond the gate's prerequisites: (1) the V2 Ledger/'Timeline' view (calendar_v2_ledger.go);…
• Carry the legacy calendar's missing features into the V5 parity list — Features the old calendar had and the v4 surface lacked: the world-state console (49 weather tiles, 16 celestial/world triggers, 8 mood presets, Pause, Reset…
• Calendar V5: test the page that mounts week/day views, not only fixtures — The overnight v4 week/day views and phone GM console (2026-08-16) were reverted before shipping (recoverable from history with a revert of the revert).…

What the Foundry module needs from the sync API

• Calendar V5: restore the calendar endpoints the Foundry module calls — The module's calendar sync calls GET /calendar, GET /calendar/date (including tracks_real_time), PUT /calendar/date (422 on real-time calendars), POST…
• Calendar V5: give Foundry the calendar's seasons and the current season — Request section 1 (High priority): season definitions (name, start and end month/day, colour, icon), a current_season on the date read, and a…
• Calendar V5: give Foundry moon definitions and current moon phases — Request section 2 (High priority): moons with cycle length, reference date and named phases, current_moon_phases on the date read, and…
• Calendar V5: current weather that the GM can read and set — Request section 3, minimal part (Medium priority): GET and PUT /calendar/weather for the current weather (preset, temperature, wind, precipitation, zone) and…
• Calendar V5: weather zones, forecast and history (nice to have) — Request section 3, full part (Lower priority): climate-zone definitions, a multi-day forecast and weather history endpoints. The request itself calls it 'a…
• Calendar V5: expose the calendar structure in a Calendaria-compatible shape — Request section 4 (Medium priority): months (with intercalary days), weekdays with rest days, hours/minutes per day, leap-year rule and epoch, readable by the…
• Calendar V5: keep full event metadata so Calendaria notes round-trip — Request section 5 (High priority): end date/time, all_day, colour, icon, category, and recurrence (interval, end, max occurrences) on events, plus an…
• Calendar V5: eras and zodiac-style cycles for Foundry — Request section 6 (Medium priority): named eras with start and end years, repeating cycles (for example a zodiac), and a calendar.era.changed event. v4…
• Calendar V5: fixed festivals and rest days — Request section 7 (Lower priority): named festivals on fixed dates (including between-month days) and rest-day weekdays; the request notes they could instead…
• Calendar V5: make the sync API serve the real Moon the website shows — In v4 the syncapi calendar handler read raw cal.Moons rows off the calendar service rather than the Block spine, so GET /moons and the date snapshot's…
• Keep Chronicle and Foundry calendars from syncing with mismatched structures — Operator saw calendars 'syncing' although Chronicle had only a default Gregorian calendar. A guard shipped in fix(calendar-sync): hook date off-by-one + back-catalog + structure guard (FM-CAL-SYNC-HOTFIX) Chronicle-Foundry-Module#76; the real fix (structure importer /…
• Design an importer that copies a Calendaria calendar's structure into Chronicle — Coordinator design queue item 2 (B-R9): a structure importer so Chronicle and Foundry calendars can match.

Which calendar a campaign uses, and who may change it

• Calendar V5: let owners choose which calendar is the campaign default — In v4 there was no way to choose which calendar Chronicle serves a campaign: POST /api/v1/campaigns/:cid/calendar answered 409 calendar_already_exists…
  • Also recorded as: "Let owners choose which calendar is the campaign default"; "In calendar V5, let a campaign choose which calendar is served"; "Calendar V5: let a campaign choose which calendar Foundry syncs"; "Calendar V5: let the sync API serve a calendar chosen by id"
• Calendar V5: one dashboard of every calendar a viewer may see — The operator's vision, restated 2026-09-12 and already signed as HUB-1 (Cordinator/decisions/2026-08-10-operator-answers-hub-eip-realtime-sky.md): the…
• Let an entity type host a widget type (an entity is a calendar) — P4c: an EntityType.hosts_widget_type flag plus a 'Calendars subcategory' create wizard (entity-type-as-host preset, pick-or-create on entity create),…
• Decide whether co-GMs may set the calendar date, not just advance it — Setting the date was Owner-only while co-DMs could only advance a day; adding 'Set date' beside the buttons would loosen permissions. Recommendation was…
• Refuse, rather than silently downgrade, a Scribe's dm_only event — STOP-AND-FLAG: a Scribe POSTing visibility="dm_only" got a 201 with the event stored as "everyone" (a deliberate C-CAL-COGM-CAPABILITY downgrade, but silent),…
• Let a GM reveal the calendar to players only up to a date — C-CALV4-HORIZON-P12: an owner-only 'Reveal through' write that fogs the calendar grid beyond a chosen date for players, booked with its own security review…
• Decide how anonymous traffic to public read routes is rate-limited — The two per-user rate limiters (calendar/routes.go:66, bestiary/ratelimit.go:45) skipped any request with no user id. Deliberately left alone: it is a…

Dates, months, eras and leap years

• Pick one day-count model so weekdays never drift on leap years — Real-time calendars drifted one weekday column per leap year from 2028 because two day counters disagreed.
  • Also recorded as: "Use one day counter for calendar dates and moon phases"; "Fix leap-unaware weekday math now that no stored calendars exist"
• Decide whether editing a calendar's months may strand events — When a month-list edit strands events, should the product warn or refuse? Recommendation: warn, never refuse, never rewrite.
• Warn when editing a calendar's months re-dates or strands events — [GR-17]/[GR-18], reproduced on real MariaDB before any fix: because events store a month INDEX, inserting an intercalary month at position 5 moved 3 of 4…
  • Also recorded as: "Warn at save time when a month edit strands or shifts events"; "Count events whose day no longer exists after a month edit"
• Reconcile events when a calendar's months are edited — C-CAL-MONTHS-RECONCILE: reconcile events by month name where names are unchanged and offer a mapping step where they are not; ambiguity rules for…
• Stop calendar imports silently resetting the current date — C-CAL-IMPORT-STRANDS-THE-CALENDARS-OWN-DATE: ApplyImport forced CurrentMonth/CurrentDay to 1 while replacing the month list, a silent date write the operator…
• Calendar V5: warn before moving a calendar's real-date anchor — Moving the fantasy-to-real date anchor by a day silently re-dates every session, every availability lookup and every 'next game is on...' at once, with…
• Decide whether calendar eras can begin mid-year — The signed render split one month between two eras at day 17/18, but Chronicle eras are year-granular, so a mid-month era boundary cannot be expressed…
• Add era-relative year numbering to the calendar — The signed 'Needs eras' fault had no trigger because Chronicle has no era-relative year numbering; a calendar with zero eras still resolves its date. The…
• Validate that a calendar cycle's entry count fits its declared length — An operator can author an 11-entry cycle with cycle_length 12 and the rotation silently skews. Either validate entries.length <= cycle_length or document the…
• Calendar V5: size colour columns for modern CSS colour strings — calendar_eras.color was VARCHAR(20) with zero headroom: 'oklch(0.55 0.12 200)' is exactly 20 characters, so an alpha form 'oklch(... / 60%)' or a 'deg' suffix…
• Add timezone support and print/PDF export to the calendar — Calendar timezone support and print/PDF export.

Events: multi-day, repeating and deleted

• Support multi-day event spans in the calendar — The signed v4 render drew span ribbons (e.g. 'Eclipse window', 5 days), but Event.OccursOn only places an event on its start day and the Block data had no…
  • Also recorded as: "Design how V5 draws a multi-day event across the month grid"
• Let V5 events end in a different month than they start — Flagged [!] and never built: the v4 editor could not move an end date past the rendered month. Two measurements explain why: the day-card payload carried no…
• Make every V5 event query find multi-day events by date overlap — GAMEREADY §3 found on a real database that ListEventsForMonth selected on the stored month, so a festival running into the next month was never loaded while…
• Decide how a recurring multi-day event repeats its span in V5 — Measured 2026-08-08 and pinned rather than designed: a weekly three-day rite based on days 5-7 marked 5, 6, 7, 12, 19, 26 — the stored [start, end] window…
• Make deleting a calendar event undoable — C-CAL-EVENT-SOFT-DELETE: real undo for a deleted event (deleted_at, a trash view, a restore path, every read filtered). The repository did a hard DELETE with…
• Restore timeline event counts in V5 together with the visibility filter — When V5 restores the timeline-calendar join, the linked-visibility fragment must come back in the same change. Without it a player reads '12 events' while…

RSVPs, availability and sessions

• Give V5 RSVPs a per-occurrence key before the new schema is written — calendar_event_rsvps was UNIQUE (event_id, user_id) with no occurrence column (migration 013), so a recurring session shared ONE RSVP set across every…
  • Also recorded as: "In calendar V5, give each occurrence of a repeating event its own RSVPs"
• Carry the three RSVP email-link fixes into V5's token flow — [GR-7]/[GR-8]/[GR-9], all found with a real database: (a) the emailed 'Suggest another time' token was consumed before the suggestion was validated, so one…
• Notify RSVPs when a collecting event is moved or deleted — C-CALV4-RSVP-RESCHEDULE-NOTIFY: moving or deleting an event collecting RSVPs notified nobody and kept stale answers; ON DELETE CASCADE on calendar_event_rsvps…
• Calendar V5: let players clear an RSVP note — In v4, once an RSVP note was written nothing could clear it: normalizeRSVPNote mapped '' to nil, UpsertRSVP's COALESCE(VALUES(note), note) then preserved the…
• Let the Director answer their own RSVP or leave them out of the count — In v4 the Director could not record their own attendance anywhere (bench.go: if in.IsGM { return t }) yet was counted in the denominator (in.Total =…
• Calendar V5: decide whether co-DMs can open RSVP collection on events — In calendar v4, PUT .../events/:eid/rsvp-collection sat behind campaigns.RequireRole, which compares the raw MemberRole and never the DM grant, so a…
• Calendar V5: show players' availability on the calendar grid — v4 shipped the day-cell availability strip's CSS and markup complete but dormant; what was missing was the join: DayCell needed an availability field, and…
• Decide whether players see RSVP buttons before the calendar on phones — On a phone a player scrolled ~1,100px past two month grids to answer; putting the answer first is a taste call. Default if unanswered: calendar first, RSVP…
• Decide what the Sessions switch controls now the calendar is being rebuilt — Sessions routes are gated on the Calendar addon (internal/plugins/sessions/routes.go:20 and :74, per ADR-023), not the Sessions toggle; ADR-056 chose a copy…

Moons, sky and seasons on the website

• Calendar V5: make moon phases openable on a real-world calendar — The operator's 2026-08-11 complaint 'I can't see the moons' was only half closed. In the configuration a worldbuilding GM actually has (a real-world Block…
• Attribute stored eclipses to a specific moon — calendar_celestial_events (migration 008) had no moon_id, so a stored eclipse could not be attributed to a moon and MoonDisc.Eclipse stayed false.
• Decide whether V5's moon menu can show rise/set times the data lacks — The v4 sky shipped with two signed-still details it could not honestly reproduce and flagged them for a coordinator signature that never came: the head line's…
• Calendar V5: decide whether new real-world calendars start with seasons — The wizard's real-world preset used to seed four northern-hemisphere seasons; stage 3 removed them, so 'a real-world calendar starts with no seasons' became a…

Phones, keyboards and touch

• Keep every day reachable on phones when a week is very long — [MOB-4]/[MOB-8]: the phone pass found five independently scrolling regions with no overscroll-behavior and, at week length 20, a 624px grid inside a 364px…
• Make V5 day selection reachable by keyboard in every layout — In v4 a day cell's only focusable control (the dayPick radio, instrument.templ:213) was emitted only when the Ledger layer was docked, so a Bench viewer who…
• Give V5's drag-to-create a keyboard equivalent — [DC-11] term 6: v4 drag-create was pointer-only and R2-2b deliberately did not invent a keyboard path, folding it into the day-cell focus work (line 1928).…
• Give V5's drag-to-create a working touch path, or declare it desktop-only — Read from code, never measured on a device: v4 drag-create registered document pointer events with no pointerType filter, set no touch-action anywhere, and…

Look and rendering

• Fix the known v4 token defects before V5 adopts the token set verbatim — Booked six times and never paid: under the signed v4 tokens, --ev-social sits 12-14° from --accent so the event bar and the selection ring read as the same…
• Calendar V5: consider past-day dimming, weather glyphs, gold weekday header — From the tile reference (C-CALV4-TILE-RECIPE.md), not among the operator's four asks: past-day dimming, a weather glyph plus temperature in the day cell's…
• Calendar V5: expose a real render trace instead of copying its rules — calendar.render re-derived the Bench's decisions by mirroring producer rules (twelve pinned source lines) instead of calling the plugin. The honest fix was an…