docs(zs): calendar view design memo (T12a)

[wiggdevin]

Summary

T12a's design memo: docs/plans/2026-09-04-calendar-view-design.md, 90 lines, thirteen numbered Decision: … Reason: … entries plus Open verifications and Risks accepted. Docs only — no code in the diff.

What it decides, under the accepted T11 contract (cited by line):

• Event model (1-5). A CalendarEvent DTO keyed by Google's opaque id, start/end as { date } or { dateTime, timeZone? }, text fields carrying a per-field { value, truncated } cap; canEdit/canDelete from T11's accessRole, revalidated at call time. All-day values stay a half-open day range in the calendar's zone; display uses one OS zone per render, so no new time-zone dependency is added. Recurrence expands at Google inside T11's 120-day window — no RRULE parser enters the fork.
• Rendering (6-8, 12). react-day-picker@^10.0.1 stays; one CalendarMonth wrapper overrides the MonthGrid slot, spreading every received prop onto the inner <table> and rendering children inside it, with the segment/"+N more" overlay outside it. The agenda is a flat virtualized list through the existing VirtualizedList, bounded at 5,122 rows by T11's 5,000-row partition cap. Paging stops at T11's horizon and renders a named end-of-window state, never an empty month. No calendar-widget dependency.
• Operation (9-11). Two composite widgets, one tab stop each, roving focus, a named focusable on every navigable row; day naming composes labels.labelDayButton instead of replacing it; the library's two role="status" regions carry month changes and boundary/truncation text. Edits patch changed fields only, are fenced by If-Match/412, use a client-generated insert id for replay, and split Google's 404/410 by T11's terminal-vs-transient probe classes.
• Truncation (13). A batch carries the interval it proves — [window start, min(window end, the last complete page's maximum start)) under orderBy=startTime — plus complete or truncated(reason). In the calendar zone, only a date wholly inside that interval is authoritative; the date holding the bound and every date past it render "unknown, more…", never empty, and none is editable.

GPT-5.6 Sol audit

Three read-only runs (gpt-5.6-sol, model_reasoning_effort=high, -s read-only, exit 0), each triaged against the plan's rubric before anything was applied.

• Run 1 (audit.md) — Sol verdict line 1: BLOCK — the memo is not ready to serve as T12a's implementation contract. Verified after triage: 1 BLOCK, 10 WARN, 3 discarded.
• Run 2 (audit-delta-2.md) — Sol verdict line 1: OPEN. Sol raised 1 BLOCK, 2 WARN, 2 NIT. Verified after triage: 1 BLOCK, 3 WARN, 1 NIT, 2 discarded.
• Run 3 (audit-delta-3.md) — Sol verdict line 1: OPEN. Sol raised 2 BLOCK, 3 WARN, 3 NIT. Verified after triage: 1 BLOCK, 3 WARN, 4 NIT, 1 discarded.

Sol read the vendor docs rather than the installed tree in all three runs; every library claim was re-verified against react-day-picker@10.0.1 in node_modules, and every file:line re-resolved with git show origin/zs/main:<file> | sed -n '<n>p'.

Claude critic rounds 4 to 6

• Round 4 (critic-4.md) — FAIL: one BLOCK (decision 13 closed the proven interval at the last page's maximum end, which orderBy=startTime does not prove, so a cap-stopped walk still painted unread days complete) and one WARN (decision 10 routed announcements to a role="status" region that is neither unique nor mounted when it first announces), plus five NITs.
• Round 5 (critic-5.md) — FAIL: both round-4 findings resolved and no regression anywhere else, but one WARN remained — the proven interval ends at an instant while the rendered unit is a date, and the memo never placed the date holding the bound — with four NITs carried.
• Round 6 (this commit) — applies round 5's W1 and N1 to N4 and stops there by driver decision, with no further critic round. Decision 13 now states that a date is authoritative only when it lies wholly inside the proven interval, in decision 2's calendar zone, so the date holding the bound renders "unknown, more…" with the dates past it and is not editable. Decision 6 says the MonthGrid override spreads every received prop onto the inner <table> and renders children inside it, leaving only the overlay outside. Decision 7 counts the 121 dates a 120-day window anchored at an arbitrary instant touches (5,122 rows, restated in the open verification) and states the list/listitem roles as opt-in props the calendar passes rather than a new default for VirtualizedList's other consumers. Decision 10 gives the agenda/month toggle an accessible name and aria-pressed. Wording elsewhere was tightened only to hold the 90-line limit; just file-size-check exits 0 and git diff --check is clean.

Supersedes

• The plan's T12a bullet names the memo docs/plans/2026-09-xx-calendar-view-design.md; it lands as docs/plans/2026-09-04-calendar-view-design.md.
• The plan's T12a eval reads "Sol reviews the memo". Sol reviewed it three times; rounds 4 to 6 ran as Claude critic passes by driver decision, and round 6 applied the remaining WARN and NITs without a further critic. The eval's substance — every checklist item has a decision, nothing above NIT remains — is what the rounds were held to.
• Decision 13 requires a write on T11's side that the accepted T11 contract does not yet carry: eviction must downgrade every interval it touches to truncated(evicted) in the dropping transaction. T12 inherits that dependency; the memo records the interim gap as a risk.
• Decision 7 changes a component seven surfaces share, but as opt-in props rather than a new shared default, so no other consumer's semantics move.

Follow-ups

• T11 amendment for the truncated(evicted) eviction downgrade. Until it lands, an evicted interval can still paint empty inside stale_after.
• The memo's five open verifications land in T12: the emitted ARIA roles off T12's DOM, labelDayButton composition and announce-once for the Footer line, lane and "+N more" thresholds on the 250-event fixture, agenda traversal at 5,122 rows, If-Match/412 and insert-id replay against the mock server then the live checklist, and the equal-start page-boundary check (defence in depth only).
• Widening the 120-day horizon needs T11 amended; until then a date outside it is reachable only in Google's own UI.
• Flake seen while pushing: desktop/src/features/messages/ui/useComposerLinkPreviews.test.mjs, "a stale in-flight upload cannot publish after the URL re-enters and a fresh upload wins", failed once in the pre-push gate and passed on a clean rerun of the full suite (6391 pass, 0 fail). This branch's tree differs from origin/zs/main in one docs file, so the flake is not from this diff.

🤖 Generated with Claude Code

https://claude.ai/code/session_01E51uwemNnQ6wdrBWU9EhPE

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}