KeepSoftwareSimple
diff --git a/‎.claude/skills/simplify/SKILL.md‎
Lines changed: 66 additions & 7 deletions b/‎.claude/skills/simplify/SKILL.md‎
Lines changed: 66 additions & 7 deletions
diff --git a/‎docs/architecture/event-and-task-domain-model.md‎
Lines changed: 8 additions & 6 deletions b/‎docs/architecture/event-and-task-domain-model.md‎
Lines changed: 8 additions & 6 deletions
diff --git a/‎docs/self-hosting/event-migration-runbook.md‎
Lines changed: 22 additions & 0 deletions b/‎docs/self-hosting/event-migration-runbook.md‎
Lines changed: 22 additions & 0 deletions
diff --git a/‎e2e/utils/event-test-utils.ts‎
Lines changed: 40 additions & 15 deletions b/‎e2e/utils/event-test-utils.ts‎
Lines changed: 40 additions & 15 deletions
diff --git a/‎handoff/someday/03-event-runtime-cutover.md‎
Lines changed: 11 additions & 0 deletions b/‎handoff/someday/03-event-runtime-cutover.md‎
Lines changed: 11 additions & 0 deletions
diff --git a/‎handoff/someday/05-calendar-aware-crud.md‎
Lines changed: 6 additions & 0 deletions b/‎handoff/someday/05-calendar-aware-crud.md‎
Lines changed: 6 additions & 0 deletions
diff --git a/‎handoff/someday/09-v1-release-hardening.md‎
Lines changed: 4 additions & 0 deletions b/‎handoff/someday/09-v1-release-hardening.md‎
Lines changed: 4 additions & 0 deletions
@@ -19,6 +19,65 @@ make code easier for other contributors to verify and change.
 - Workflow: find existing abstractions first → apply the principles below →
   verify with focused checks → report the diff with principles applied.
 
+## Finding Complexity — Where to Start
+
+Don't read the diff top to bottom hoping smells jump out. Hunt with
+detectors, in rough order of payoff (each proven on this codebase):
+
+1. **Size first.** `git diff <base> --numstat | sort -rn | head -20` — the
+   biggest churn concentrates the smells. Start there, not alphabetically.
+2. **Comment density.** Simple code is mostly self-explanatory. A paragraph
+   of comments explaining _why something works_ means the mechanism is too
+   clever — fix the mechanism and the comments evaporate (a test-override
+   registry that needed the same 6-line explanation in five files collapsed
+   into ordinary constructor defaults that needed none). One-liners that
+   restate the next line (`// save the event`) are pure deletions. Keep only
+   comments stating a constraint the code cannot show (transaction
+   boundaries, spec references, cross-realm quirks).
+3. **Mock volume and shape.** Lots of mocks = missing seam. `mock.module` on
+   a shared singleton is the worst offender: it mutates the process-wide
+   module registry, cannot be un-leaked for already-linked consumers, and
+   fails order-dependently (Linux CI orders files differently than macOS).
+   The fix is never better mock bookkeeping — it's a constructor/parameter
+   default (`constructor(getStore = getOfflineDataStore)`) and a plain fake.
+   Search: `rg "mock.module" --glob "*.test.*"` and treat each hit on a
+   multi-consumer module as a candidate seam.
+4. **Test-only hooks in production code.** Any `setXForTests`,
+   `testOverrides`, `__test__` export, or `if (process.env.NODE_ENV ===
+"test")` branch in a production module means tests are steering design
+   from the wrong side. Replace with dependency injection at the caller.
+5. **Casts.** `as unknown as`, `as any`, and `Parameters<...>[n]` casts in
+   tests mean the fake isn't shaped like the real collaborator — usually
+   because the seam is a whole module instead of a small interface. In
+   production code, casts at construction sites of branded/validated types
+   are tolerable; casts that silence a structural mismatch are debt.
+   Search: `rg "as unknown as"`.
+6. **Copy-pasted scaffolding.** The same open/do/close or
+   iterate/write/guard shape repeated across siblings (session +
+   transaction + endSession in four service methods; seven cache writers
+   each re-implementing iterate-entries → setQueryData → null-guard). Extract
+   ONE helper owning the shape; the variants become one-liners.
+7. **Dead and unreachable code.** Every exported symbol in the diff:
+   `rg "<name>" --type ts` across all packages — zero call sites means
+   delete (including its tests). Every defensive branch: read the callee —
+   a `!x.isActive` check after a query that already filters `isActive: true`
+   can never fire and only misleads readers about invariants.
+8. **Coupling via hidden shared state.** Tests that pass alone but fail in
+   suite (or only on CI) point at module-level mutable state that no reset
+   registry covers. The fix is to register the reset or inject the state —
+   never to reorder tests or widen timeouts.
+9. **Bridges and adapters.** Transition scaffolding is legitimate, but audit
+   it: every adapter function must have a live call site (`rg` each export),
+   and the file should shrink release over release, not grow.
+
+Balance — restraint is part of the skill. Don't unify code that only looks
+similar (two query builders with genuinely different shapes stay separate).
+Don't break a repo-wide convention locally just because it repeats (the
+per-handler try/catch shape in controllers is uniform across the codebase;
+"fixing" one file creates inconsistency, not simplicity). When you decide
+NOT to change something you inspected, say so in the report with the reason
+— "considered, left alone because X" is as valuable as a diff.
+
 ## Before Making Changes
 
 1. **Necessity**: does this change only address what's required?
@@ -157,13 +216,13 @@ const getLabel = (type: string) => LABELS[type] ?? "Unknown";
 
 ## Complexity Thresholds
 
-| Metric               | Prefer     | Flag       | Action                       |
-| -------------------- | ---------- | ---------- | ---------------------------- |
-| Function length      | < 20 lines | > 30 lines | Split or extract             |
-| Nesting depth        | ≤ 2 levels | > 3 levels | Guard clauses, early returns |
-| Parameters           | ≤ 3        | > 4        | Options object or context    |
-| Conditional branches | ≤ 3        | > 4        | Record lookup or polymorphism|
-| Similar blocks       | 0          | 2+         | Extract and parameterize     |
+| Metric               | Prefer     | Flag       | Action                        |
+| -------------------- | ---------- | ---------- | ----------------------------- |
+| Function length      | < 20 lines | > 30 lines | Split or extract              |
+| Nesting depth        | ≤ 2 levels | > 3 levels | Guard clauses, early returns  |
+| Parameters           | ≤ 3        | > 4        | Options object or context     |
+| Conditional branches | ≤ 3        | > 4        | Record lookup or polymorphism |
+| Similar blocks       | 0          | 2+         | Extract and parameterize      |
 
 ## Verify
 
 
@@ -2,12 +2,14 @@
 
 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.
+## Current Contracts (sub-calendar v1)
+
+The runtime now uses the strict calendar-owned contracts everywhere: Mongo
+storage, the HTTP API, SSE, IndexedDB, and the web data/state layers. The
+legacy sections further down describe the RETIRED pre-cutover model; they
+remain only until the last web components stop converting shapes through
+`packages/web/src/events/queries/event.legacy-bridge.ts`, after which the
+legacy types are deleted.
 
 - `packages/core/src/types/domain-primitives.ts` — branded ids, `DateOnly`,
   `DateTime` (RFC 3339 with offset), `TimeZone`, `SortOrder`, `RRule`.
 
@@ -16,6 +16,28 @@ Neither migration touches the legacy `event` collection, and nothing starts
 reading `event_new` until the separate runtime-cutover release. Running these
 early is safe; the app keeps serving from legacy data.
 
+## Rollout strategy (sub-calendar v1)
+
+The v1 rollout is staging-first (decision A36 in
+`handoff/someday/master-doc.md`):
+
+1. **Staging cuts over now.** Run the full procedure below (migrate → verify →
+   pause → rename → deploy) against staging when the runtime-cutover release
+   merges. Merges to `main` auto-deploy staging, so every subsequent v1 packet
+   lands there continuously.
+2. **Production stays on the pre-cutover release** the whole time. The
+   `Deploy Production` workflow is manual (`workflow_dispatch`) — do not run
+   it while v1 work is in flight. Production keeps writing legacy `event`
+   data; that is fine, because the backfill is rerunnable and the final
+   production migration run happens inside the production cutover window.
+3. **Production cuts over once, at the end**: after every packet is merged
+   and the plan `09` verification gates pass on staging, execute this runbook
+   against production a single time, then run the `Deploy Production` action.
+   That is the entire production rollout.
+
+Dev databases follow staging: run the migrations + rename locally (or wipe the
+dev database) as soon as you work on a post-cutover branch.
+
 ## Preflight
 
 1. **Back up first.** Follow [Back up & restore](./backup-and-restore.md) in
 
@@ -4,6 +4,10 @@ type SomedaySection = "week" | "month";
 
 const LOCAL_DB_NAME = "compass-local";
 
+// LocalEventRecord (B13) nests the event under `.event`; title lives at
+// `.event.content.title` (kind "details") and the schedule is a discriminated
+// union ("timed"/"allDay" use start/end, "someday" uses anchorDate) rather
+// than flat startDate/endDate columns on the row.
 export const getSavedEventsByTitle = (page: Page, title: string) =>
   page.evaluate(async (eventTitle) => {
     const db = await new Promise<IDBDatabase>((resolve, reject) => {
@@ -13,22 +17,43 @@ export const getSavedEventsByTitle = (page: Page, title: string) =>
       request.onsuccess = () => resolve(request.result);
     });
 
+    type LocalEventRecord = {
+      event: {
+        content: { kind: string; title?: string };
+        schedule:
+          | { kind: "timed" | "allDay"; start: string; end: string }
+          | { kind: "someday"; anchorDate: string };
+      };
+    };
+
     try {
-      return await new Promise<
-        { endDate?: string; startDate?: string; title?: string }[]
-      >((resolve, reject) => {
-        const transaction = db.transaction("events", "readonly");
-        const request = transaction.objectStore("events").getAll();
-
-        request.onerror = () => reject(request.error);
-        request.onsuccess = () => {
-          resolve(
-            request.result.filter(
-              (event: { title?: string }) => event.title === eventTitle,
-            ),
-          );
-        };
-      });
+      const records = await new Promise<LocalEventRecord[]>(
+        (resolve, reject) => {
+          const transaction = db.transaction("events", "readonly");
+          const request = transaction.objectStore("events").getAll();
+
+          request.onerror = () => reject(request.error);
+          request.onsuccess = () => resolve(request.result);
+        },
+      );
+
+      return records
+        .filter(
+          (record) =>
+            record.event.content.kind === "details" &&
+            record.event.content.title === eventTitle,
+        )
+        .map(({ event }) => ({
+          title: event.content.title,
+          startDate:
+            event.schedule.kind === "someday"
+              ? event.schedule.anchorDate
+              : event.schedule.start,
+          endDate:
+            event.schedule.kind === "someday"
+              ? event.schedule.anchorDate
+              : event.schedule.end,
+        }));
     } finally {
       db.close();
     }
 
@@ -5,6 +5,17 @@
 Move all core, backend, scripts, and web runtime paths from the legacy
 user-owned event document to the final strict calendar-owned event contracts.
 
+Status (2026-07-11): substantially implemented on
+`refactor/event-runtime-cutover`. Backend, storage, HTTP/SSE contracts,
+IndexedDB, and the web data/state layers are fully cut over with all suites
+and the full local e2e run green. Remaining before this packet's boxes can be
+checked: dissolve `packages/web/src/events/queries/event.legacy-bridge.ts` by
+converting the component/view layer (draft store, grid drag/resize, forms,
+sidebar, shortcuts) off `Schema_Event`, then delete the legacy web event
+types. `event_new.types.ts` stays as long as the frozen 2025 migrations
+import it. Scope-`this` provider sync for series occurrences is deferred to
+`05` (recorded there).
+
 Depends on: `01-domain-contracts.md`, `02-safe-event-data-migration.md`.
 
 ## Design constraint
 
@@ -47,6 +47,12 @@ Depends on: `04-initial-multi-calendar-import.md`.
 4. Pass the resolved provider calendar through Compass-to-Google planning and
    effects. Provider success updates the event's provider reference in the same
    owning calendar.
+   Known `03` gap this packet closes: scope-`this` edits/deletes on a synced
+   series occurrence do not propagate to Google (the `03` pipeline has no way
+   to resolve Google's per-instance event id for Compass-created series).
+   Imported occurrences already carry their instance id in
+   `externalReference`; Compass-created series need an `events.instances`
+   lookup before the per-occurrence `events.patch`/delete.
 5. Scope Google-to-Compass matching by calendar plus provider event id so equal
    event ids in different calendars cannot collide.
 6. Enforce read-only roles before optimistic writes reach Google. Return a
 
@@ -72,6 +72,10 @@ and one `freeBusyReader`) plus the Compass-local calendar:
 
 ## Migration and rollback rehearsal
 
+Per A36 the production cutover happens exactly once, only after every gate in
+this file passes on staging; until then the `Deploy Production` action is not
+run and production stays on the pre-cutover release.
+
 1. Restore a sanitized production-shaped backup into staging.
 2. Record source counts/category hashes and create a fresh backup.
 3. Run forward migrations without modifying old collections.