refactor(core): define strict event contracts (#2015)

Implement plan packet 01 from the sub-calendar v1 roadmap (PR #2012):
calendar-owned event contracts shared by core, backend, and web, alongside
the legacy model (runtime cutover follows in packet 03).

- core: branded domain primitives; discriminated Event
  (content/schedule/recurrence), BusyPeriod, Calendar with derived
  capabilities; command contracts incl. optional client create id and the
  someday<->scheduled transition; strict SSE ServerMessage union
- backend: CalendarRecord/EventRecord schemas (zObjectId, single nullable
  externalReference, no origin); Google CalendarList/Event adapters with
  busy-content heuristic, timezone fallback ladder, exclusive all-day ends,
  and events.patch write bodies
- web: EventDraft/view types, LocalEventRecord (v2, isDemo), and
  parseEventDraft gating every draft through the core input schemas
- docs: target-contract section in the architecture domain model

499 new tests across the packages; all suites green (core 265, web 1260,
backend 543, scripts 64), type-check and lint clean on new files.

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: tyler-dane

docs/architecture/event-and-task-domain-model.md

@@ -2,6 +2,37 @@
 
 The event domain is the most cross-cutting part of Compass. Read this before changing event shape, recurrence logic, sync behavior, or local persistence.
 
+## Target Contracts (sub-calendar v1, pre-cutover)
+
+Strict calendar-owned contracts exist alongside the legacy model and become the
+runtime shape at the sub-calendar v1 cutover. Until then the legacy sections
+below describe live behavior; the contracts describe where every consumer is
+headed.
+
+- `packages/core/src/types/domain-primitives.ts` — branded ids, `DateOnly`,
+  `DateTime` (RFC 3339 with offset), `TimeZone`, `SortOrder`, `RRule`.
+- `packages/core/src/types/event.contracts.ts` — canonical `Event`: required
+  `calendarId`, discriminated `content` (`details` | `busy`), `schedule`
+  (`timed` | `allDay` | `someday`, exclusive all-day ends), `recurrence`
+  (`single` | `series` | `occurrence`), plus `BusyPeriod` for free/busy-only
+  calendars.
+- `packages/core/src/types/event-command.contracts.ts` — create (optional
+  client id), full-replace, delete, someday reorder, the someday↔scheduled
+  transition (the only command that changes an event's calendar), list and
+  availability queries.
+- `packages/core/src/types/calendar.contracts.ts` — `Calendar` read model with
+  provider/access and derived capabilities (`getCalendarCapabilities`).
+- `packages/core/src/types/server-message.contracts.ts` — the discriminated
+  SSE union every backend publish site must emit.
+- `packages/backend/src/calendar/calendar.record.ts`,
+  `packages/backend/src/event/event.record.ts` — Mongo record shapes
+  (ObjectIds/BSON dates, single nullable `externalReference`, no `origin`).
+- `packages/backend/src/event/google-event.adapter.ts` — Google↔record
+  mapping; provider writes are `events.patch` bodies.
+- `packages/web/src/events/event-draft.types.ts` + `event-draft.parser.ts` —
+  the only intentionally incomplete event shape and the single parser that can
+  turn it into a command.
+
 ## Core Event Schema
 
 Primary source:

packages/backend/src/calendar/calendar.record.mapper.test.ts

@@ -0,0 +1,170 @@
+import { type calendar_v3 } from "@googleapis/calendar";
+import { ObjectId } from "mongodb";
+import {
+  CalendarSchema,
+  getCalendarCapabilities,
+} from "@core/types/calendar.contracts";
+import { type CalendarRecord } from "@backend/calendar/calendar.record";
+import {
+  mapCalendarRecord,
+  mapGoogleCalendar,
+} from "@backend/calendar/calendar.record.mapper";
+
+const fullEntry = (): calendar_v3.Schema$CalendarListEntry => ({
+  id: "gcal-1",
+  etag: "etag-1",
+  summary: "Work",
+  summaryOverride: "My Work",
+  description: "Company schedule",
+  timeZone: "America/Denver",
+  foregroundColor: "#ffffff",
+  backgroundColor: "#5b6cff",
+  accessRole: "writer",
+  primary: false,
+  selected: true,
+});
+
+describe("mapGoogleCalendar", () => {
+  const userId = new ObjectId();
+
+  it("maps a full entry", () => {
+    const record = mapGoogleCalendar(fullEntry(), { userId });
+    expect(record.name).toBe("My Work");
+    expect(record.description).toBe("Company schedule");
+    expect(record.timeZone).toBe("America/Denver");
+    expect(record.foregroundColor).toBe("#ffffff");
+    expect(record.backgroundColor).toBe("#5b6cff");
+    expect(record.access).toBe("writer");
+    expect(record.isPrimary).toBe(false);
+    expect(record.isVisible).toBe(true);
+    expect(record.isActive).toBe(true);
+    expect(record.userId).toBe(userId);
+    expect(record.source).toEqual({
+      provider: "google",
+      calendarId: "gcal-1",
+      etag: "etag-1",
+    });
+  });
+
+  it("prefers summaryOverride over summary", () => {
+    const record = mapGoogleCalendar(
+      { ...fullEntry(), summaryOverride: "Custom name" },
+      { userId },
+    );
+    expect(record.name).toBe("Custom name");
+  });
+
+  it("falls back to summary when summaryOverride is absent", () => {
+    const entry = fullEntry();
+    delete entry.summaryOverride;
+    const record = mapGoogleCalendar(entry, { userId });
+    expect(record.name).toBe("Work");
+  });
+
+  it("defaults missing colors", () => {
+    const entry = fullEntry();
+    delete entry.foregroundColor;
+    delete entry.backgroundColor;
+    const record = mapGoogleCalendar(entry, { userId });
+    expect(record.backgroundColor).toBe("#9e9e9e");
+    expect(record.foregroundColor).toBe("#000000");
+  });
+
+  it("seeds isVisible from selected only when there is no existing record", () => {
+    const record = mapGoogleCalendar(
+      { ...fullEntry(), selected: false },
+      { userId },
+    );
+    expect(record.isVisible).toBe(false);
+  });
+
+  it("preserves _id and isVisible from an existing record", () => {
+    const existingId = new ObjectId();
+    const record = mapGoogleCalendar(
+      { ...fullEntry(), selected: false },
+      { userId, existing: { _id: existingId, isVisible: true } },
+    );
+    expect(record._id).toBe(existingId);
+    expect(record.isVisible).toBe(true);
+  });
+
+  it("maps reader and freeBusyReader access roles", () => {
+    const reader = mapGoogleCalendar(
+      { ...fullEntry(), accessRole: "reader" },
+      { userId },
+    );
+    expect(reader.access).toBe("reader");
+
+    const freeBusyReader = mapGoogleCalendar(
+      { ...fullEntry(), accessRole: "freeBusyReader" },
+      { userId },
+    );
+    expect(freeBusyReader.access).toBe("freeBusyReader");
+  });
+
+  it("throws when id is missing", () => {
+    const entry = fullEntry();
+    delete entry.id;
+    expect(() => mapGoogleCalendar(entry, { userId })).toThrow();
+  });
+
+  it("throws when etag is missing", () => {
+    const entry = fullEntry();
+    delete entry.etag;
+    expect(() => mapGoogleCalendar(entry, { userId })).toThrow();
+  });
+
+  it("throws when accessRole is invalid", () => {
+    const entry = { ...fullEntry(), accessRole: "bogus" };
+    expect(() => mapGoogleCalendar(entry, { userId })).toThrow();
+  });
+});
+
+describe("mapCalendarRecord", () => {
+  const buildRecord = (
+    overrides: Partial<CalendarRecord> = {},
+  ): CalendarRecord => ({
+    _id: new ObjectId(),
+    userId: new ObjectId(),
+    name: "Work",
+    description: "",
+    timeZone: "America/Denver",
+    foregroundColor: "#ffffff",
+    backgroundColor: "#5b6cff",
+    access: "writer",
+    isPrimary: false,
+    isVisible: true,
+    isActive: true,
+    source: { provider: "google", calendarId: "gcal-1", etag: "etag-1" },
+    createdAt: new Date(),
+    updatedAt: null,
+    ...overrides,
+  });
+
+  it("produces output that parses with CalendarSchema", () => {
+    const record = buildRecord();
+    const calendar = mapCalendarRecord(record);
+    expect(() => CalendarSchema.parse(calendar)).not.toThrow();
+    expect(calendar.id).toBe(record._id.toHexString());
+    expect(calendar.provider).toBe("google");
+  });
+
+  it("derives capabilities from the access role", () => {
+    const record = buildRecord({ access: "freeBusyReader" });
+    const calendar = mapCalendarRecord(record);
+    expect(calendar.capabilities).toEqual(
+      getCalendarCapabilities("freeBusyReader"),
+    );
+  });
+
+  it("does not leak provider ids, etags, or userId", () => {
+    const record = buildRecord();
+    const calendar = mapCalendarRecord(record) as unknown as Record<
+      string,
+      unknown
+    >;
+    expect(calendar).not.toHaveProperty("userId");
+    expect(calendar).not.toHaveProperty("source");
+    expect(calendar).not.toHaveProperty("etag");
+  });
+});

packages/backend/src/calendar/calendar.record.mapper.ts

@@ -0,0 +1,70 @@
+import { type calendar_v3 } from "@googleapis/calendar";
+import { ObjectId } from "mongodb";
+import {
+  type Calendar,
+  CalendarAccessSchema,
+  getCalendarCapabilities,
+} from "@core/types/calendar.contracts";
+import { type CalendarId, type TimeZone } from "@core/types/domain-primitives";
+import { type CalendarRecord } from "@backend/calendar/calendar.record";
+
+export const mapGoogleCalendar = (
+  entry: calendar_v3.Schema$CalendarListEntry,
+  context: {
+    userId: ObjectId;
+    existing?: Pick<CalendarRecord, "_id" | "isVisible">;
+  },
+): CalendarRecord => {
+  if (!entry.id) {
+    throw new Error("Google calendar entry is missing an id");
+  }
+  if (!entry.etag) {
+    throw new Error("Google calendar entry is missing an etag");
+  }
+
+  const accessResult = CalendarAccessSchema.safeParse(entry.accessRole);
+  if (!accessResult.success) {
+    throw new Error(
+      `Google calendar entry has an invalid accessRole: ${String(entry.accessRole)}`,
+    );
+  }
+
+  return {
+    _id: context.existing?._id ?? new ObjectId(),
+    userId: context.userId,
+    name: entry.summaryOverride ?? entry.summary ?? "",
+    description: entry.description ?? "",
+    timeZone: (entry.timeZone ?? null) as TimeZone | null,
+    // Match the legacy Google calendar mapper's defaults (map.calendar.ts).
+    backgroundColor: entry.backgroundColor ?? "#9e9e9e",
+    foregroundColor: entry.foregroundColor ?? "#000000",
+    access: accessResult.data,
+    isPrimary: entry.primary ?? false,
+    // Google's `selected` only seeds visibility on first insert; an existing
+    // record's user-controlled visibility must never be overwritten by sync.
+    isVisible: context.existing?.isVisible ?? entry.selected ?? true,
+    isActive: true,
+    source: {
+      provider: "google",
+      calendarId: entry.id,
+      etag: entry.etag,
+    },
+    createdAt: new Date(),
+    updatedAt: null,
+  };
+};
+
+export const mapCalendarRecord = (record: CalendarRecord): Calendar => ({
+  id: record._id.toHexString() as CalendarId,
+  name: record.name,
+  description: record.description,
+  timeZone: record.timeZone,
+  foregroundColor: record.foregroundColor,
+  backgroundColor: record.backgroundColor,
+  provider: record.source.provider,
+  access: record.access,
+  capabilities: getCalendarCapabilities(record.access),
+  isPrimary: record.isPrimary,
+  isVisible: record.isVisible,
+  isActive: record.isActive,
+});

packages/backend/src/calendar/calendar.record.test.ts

@@ -0,0 +1,110 @@
+import { ObjectId as BsonObjectId } from "bson";
+import { ObjectId } from "mongodb";
+import {
+  CalendarRecordSchema,
+  CalendarSourceRecordSchema,
+  GoogleCalendarSourceRecordSchema,
+  LocalCalendarSourceRecordSchema,
+} from "@backend/calendar/calendar.record";
+
+const baseRecord = () => ({
+  _id: new ObjectId(),
+  userId: new ObjectId(),
+  name: "Work",
+  description: "",
+  timeZone: "America/Denver",
+  foregroundColor: "#ffffff",
+  backgroundColor: "#5b6cff",
+  access: "owner" as const,
+  isPrimary: false,
+  isVisible: true,
+  isActive: true,
+  source: { provider: "local" as const },
+  createdAt: new Date(),
+  updatedAt: null,
+});
+
+describe("CalendarSourceRecordSchema", () => {
+  it("parses a local source", () => {
+    const result = LocalCalendarSourceRecordSchema.safeParse({
+      provider: "local",
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it("parses a google source", () => {
+    const result = GoogleCalendarSourceRecordSchema.safeParse({
+      provider: "google",
+      calendarId: "gcal-1",
+      etag: "etag-1",
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it("rejects unknown keys", () => {
+    const result = CalendarSourceRecordSchema.safeParse({
+      provider: "local",
+      extra: true,
+    });
+    expect(result.success).toBe(false);
+  });
+});
+
+describe("CalendarRecordSchema", () => {
+  it("parses a valid local calendar record", () => {
+    const result = CalendarRecordSchema.safeParse(baseRecord());
+    expect(result.success).toBe(true);
+  });
+
+  it("parses a valid google calendar record", () => {
+    const result = CalendarRecordSchema.safeParse({
+      ...baseRecord(),
+      access: "writer",
+      source: {
+        provider: "google",
+        calendarId: "gcal-1",
+        etag: "etag-1",
+      },
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it("rejects a local-source calendar with non-owner access", () => {
+    const result = CalendarRecordSchema.safeParse({
+      ...baseRecord(),
+      access: "writer",
+    });
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(result.error.issues[0]?.path).toEqual(["access"]);
+    }
+  });
+
+  it("rejects unknown keys", () => {
+    const result = CalendarRecordSchema.safeParse({
+      ...baseRecord(),
+      extra: "nope",
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it("transforms a 24-hex string _id into an ObjectId instance", () => {
+    const hex = new ObjectId().toHexString();
+    const result = CalendarRecordSchema.safeParse({
+      ...baseRecord(),
+      _id: hex,
+    });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data._id).toBeInstanceOf(BsonObjectId);
+    }
+  });
+
+  it("accepts an ObjectId instance directly for _id", () => {
+    const result = CalendarRecordSchema.safeParse(baseRecord());
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data._id).toBeInstanceOf(BsonObjectId);
+    }
+  });
+});