Date: 2026-07-22
Existing V1 authority reused#
This increment implements the R0.3 CalendarSource seam through Oshun's
existing V1 calendar stack. It reuses the authenticated per-user OAuth
connection store, the shared inbound-integration CalendarTransport, and the
existing Google OAuth access-token resolver and event transport. It does not
introduce a second calendar credential or provider-event model.
Google is the only provider with a real read transport in the current V1
composition. A user with no connection, missing Google client credentials, or an
Apple/Outlook connection without an injected real transport receives
calendar_not_configured; the Rail stays on the persisted manual schedule and
says so. Provider or malformed-source failures return calendar_unavailable and
the same visible manual posture. No path fabricates a successful calendar read.
Privacy-bounded adapter#
V1RailCalendarSource reads connections only for the authenticated V1 user and
converts provider events into R0.3's bounded interval shape. Only kind, start,
end, and a one-way SHA-256-derived identifier cross the seam. Titles, locations,
attendees, provider event ids, and account identifiers do not.
Confirmed busy events map to meeting; Google focusTime events map to
focus-time. Cancelled, transparent/free, self-declined, out-of-office,
unsupported event types, invalid ranges, and date-only all-day entries do not
create clamps. Reads and returned batches are bounded, and one unreadable
connected provider fails the whole observation closed.
Daypart authority and presentation#
CalendarAwareDaypartResolver remains kernel-owned. It first resolves the
persisted timezone-correct schedule, asks the calendar source for the exact
observation instant, validates every returned interval, and gives explicit focus
time precedence when it overlaps a meeting. Any active meeting or focus interval
clamps the effective posture to canonical Deep work: ceiling 1 and no adult-ring
eligibility. The scheduled daypart remains in the response for auditability.
The authenticated BFF endpoint
GET /v1/rail/dayparts/resolution?timeZone=…&at=… owns the server-side
composition. The web client validates that the server's scheduled result agrees
with its persisted settings and holds ambient media closed while each calendar
check is pending. Every clamp renders a concise live-status explanation with its
local end time. Missing or unavailable calendars render an explicit manual
schedule notice; an unclamped successful read adds no visual noise.
The status treatment follows the mandatory frontend guidance: it is a slim, integrated line in the existing near-black Rail hierarchy, uses the established single signal accent, and avoids adding a generic card or competing action.
Verification#
Focused automated coverage includes:
- kernel fixture calendars for meeting clamps, focus-time precedence, non-overlap, malformed results, and the original unconfigured fail-loud seam;
- BFF provider mapping, PII exclusion, absent configuration, provider failure, authenticated route composition, manual fallback, and timestamp validation;
- web client validation for automatic and manual responses, including rejection when the server disagrees with persisted schedule authority;
- connected React coverage proving that a clamp holds ambient video and that automatic and manual explanations are visible; and
- Playwright coverage through the real production Rail surface, plus updated calendar responses for every connected-state browser harness.
A Next production build is not run on this 15 GiB host because the repository's small-host rule requires explicit approval. Targeted TypeScript, Vitest, ESLint, and Playwright gates cover the affected kernel, service, and web paths.