feat(scripts): repair legacy-migrated series with wrong-frame BYDAY

[tyler-dane]

Summary

Some recurring weekly series migrated into compass_sync from the legacy DB have their RRULE BYDAY captured in the wrong timezone frame relative to the event's own schedule.timeZone. Compass expands BYDAY in schedule.timeZone (occurrence-projection.ts floatingAnchor/floatingRules), so an affected series renders a phantom, wrong-weekday duplicate occurrence every week, alongside the correct one (which comes from a separately-imported exception record holding the real Google-sourced instant). Surfaced live via the founder's own "Review Week" series, reported after the #2525 crash fix shipped.

Adds a standalone, one-off CLI command — not an umzug migration, since packages/scripts/src/migrations/ only ever connects to prod_calendar, and compass_sync is a deliberately isolated database/credential. Mirrors the existing purge-corrupt-sync-events/purge-user pattern: connects via SyncMongoService, default dry-run, --apply to write.

For each affected weekly single-BYDAY series:

1. Derives the true weekday from the strong-majority (>=80%) consensus of the series' own non-cancelled exceptions' real schedule.start — not a naive unanimous vote, which would wrongly skip a series with even one legitimate one-off reschedule buried in years of history (the founder's own series is 711 of 712 exceptions on Saturday, 1 on Sunday).
2. Rewrites only the BYDAY= component of the rule — FREQ/INTERVAL/UNTIL/COUNT/WKST untouched.
3. Shifts the series' own anchor date (schedule.start/end) only when it's on the wrong weekday AND no exception already covers that exact instant — otherwise that one historical date would keep generating its own phantom forever, since occurrence-projection.ts always materializes DTSTART regardless of BYDAY.
4. Persists via EventRepository.replaceExisting (owner-scoped, schema-validated) and reprojects via the existing reprojectMaster/replaceForEvent machinery — the same transactional path every live user edit already goes through.

This is a local read-model correction only. Traced the full outbound path (command.routes.ts → provider-command.service.ts; the job dispatcher's commandApply/reconcile kinds have no producer in this build) — nothing watches a raw Mongo write and pushes it to Google.

Already run against production

Per the internal migration playbook's triage (idempotent per-doc repair, light ceremony — independent per-series writes, convergent on rerun, drives the already-transactional occurrence-replace path every live edit already races against):

1. --dry-run against prod, cross-checked against an independent manual aggregation.
2. Full report (all 2,016 candidate series, their outcome and confidence) shown to the founder for explicit go/no-go.
3. --apply run: 37 series fixed across 9 tenants (all ≥93% exception consensus, 35 of 37 at 100%), 273 skipped as genuinely ambiguous or under-evidenced rather than guessed, 1,706 already correct.
4. Verified: direct Mongo reads confirm the founder's two known-affected series now read BYDAY=SA and materialize exactly one occurrence per week; re-running in dry-run mode reports fixed=0 (full convergence, idempotent).

Cleanup plan

This is a one-off tool for a closed, already-migrated population (confirmed: the current write/import paths are frame-consistent, so this cannot recur for new data). Once this PR is confirmed merged and deployed, a follow-up PR deletes the command file, its subdirectory, and its cli.ts/cli.test.ts registration — mirroring how the 2026-07-29 Sync-cutover one-off tooling (migrate-provider-state.ts, preseed-sync.ts, etc.) was deleted the day after confirmed use, rather than accumulating as permanent dead code.

Test plan

• bun test:scripts — 33 pass, including 8 new tests for the repair logic itself (BYDAY rewrite, anchor-date shift, the "already-excepted, no shift needed" case, strong-majority-with-outlier, ambiguous-history skip, no-exceptions skip, already-correct no-op, and idempotent rerun) and a new cli.test.ts case covering command dispatch.
• bun run type-check — clean.
• biome check — clean on all touched files.
• Manual --dry-run/--apply/re---dry-run cycle against prod, described above.

🤖 Generated with Claude Code