@acms-subir/core 0.3.54 → 0.3.56

package/src/lib/calendar/google/migration.ts

@@ -0,0 +1,71 @@
+// v69: two-way Google Calendar sync (lib/calendar/google/). Nothing goes on
+// the events row: environment sync copies event fields and backups carry
+// them, and a pairing belongs to one site and one Google account. None of
+// these tables are exported, backed up or copied by environment sync.
+//
+// - gcal_account: the one connected Google account (its own OAuth client,
+//   credentials sealed by lib/sealed.ts) and the calendars it can edit
+// - gcal_oauth_states: one-use pending sign-ins (YouTube keeps its own)
+// - gcal_links: a site calendar ⇄ a Google calendar, with its rooms, rules,
+//   sync token and the live module's lease/next_at/failures/revision fields
+// - gcal_items: one row per pair (a site event ⇄ a Google event in one link),
+//   with the hashes of each side's fields as last agreed
+// - gcal_queue: events waiting to go out, one row per event (coalesced),
+//   filled by the triggers below from every write path; `version` lets a
+//   worker finish only the change it handled
+// - gcal_log: Recent changes, kept 90 days
+//
+// The triggers fire on every insert, update and delete of an event (no
+// column list, so later events columns are covered without recreating them),
+// except while a restore runs (webhook_control.suppressed) and on sites with
+// no links. Loop prevention isn't a flag here: a change that already matches
+// what the pair last agreed is never sent (lib/calendar/google/outbound.ts).
+const now = "CAST((julianday('now') - 2440587.5) * 86400000 AS INTEGER)";
+const guard = '(SELECT suppressed FROM webhook_control WHERE id=1)=0 AND EXISTS (SELECT 1 FROM gcal_links)';
+const enqueue = (id: string) => `INSERT INTO gcal_queue (event_id,version,due_at,attempts,claimed_until,error) VALUES (${id},1,${now},0,0,'')
+    ON CONFLICT(event_id) DO UPDATE SET version=version+1,due_at=excluded.due_at,attempts=0,error='';`;
+
+export const GCAL_MIGRATION = { version: 69, statements: [
+  `CREATE TABLE gcal_account (
+    id INTEGER PRIMARY KEY CHECK(id=1), client_id TEXT NOT NULL, encrypted TEXT NOT NULL, email TEXT NOT NULL DEFAULT '',
+    status TEXT NOT NULL DEFAULT 'setup', error TEXT NOT NULL DEFAULT '', site_url TEXT NOT NULL DEFAULT '',
+    calendars TEXT NOT NULL DEFAULT '[]', calendars_at INTEGER NOT NULL DEFAULT 0, connected_by TEXT NOT NULL DEFAULT '',
+    connected_at INTEGER NOT NULL DEFAULT 0, revision INTEGER NOT NULL DEFAULT 1, updated_at INTEGER NOT NULL DEFAULT 0
+  )`,
+  `CREATE TABLE gcal_oauth_states (hash TEXT PRIMARY KEY, session_hash TEXT NOT NULL, revision INTEGER NOT NULL, encrypted TEXT NOT NULL, expires_at INTEGER NOT NULL)`,
+  `CREATE TABLE gcal_links (
+    id TEXT PRIMARY KEY, calendar_id TEXT NOT NULL, google_id TEXT NOT NULL UNIQUE, google_name TEXT NOT NULL DEFAULT '', google_tz TEXT NOT NULL DEFAULT '',
+    direction TEXT NOT NULL DEFAULT 'both' CHECK(direction IN ('both','out','in')), room_ids TEXT NOT NULL DEFAULT '[]',
+    no_room INTEGER NOT NULL DEFAULT 0, rules TEXT NOT NULL DEFAULT '[]', booking_titles TEXT NOT NULL DEFAULT '[]', start_date TEXT NOT NULL,
+    state TEXT NOT NULL DEFAULT 'matching' CHECK(state IN ('matching','active','paused')), paused_reason TEXT NOT NULL DEFAULT '',
+    site_url TEXT NOT NULL, matched_at INTEGER NOT NULL DEFAULT 0, match TEXT,
+    sync_token TEXT NOT NULL DEFAULT '', full_sync INTEGER NOT NULL DEFAULT 1,
+    lease TEXT NOT NULL DEFAULT '', lease_until INTEGER NOT NULL DEFAULT 0, next_at INTEGER NOT NULL DEFAULT 0,
+    failures INTEGER NOT NULL DEFAULT 0, failing_since INTEGER NOT NULL DEFAULT 0, alerted_at INTEGER NOT NULL DEFAULT 0,
+    last_ok_at INTEGER NOT NULL DEFAULT 0, error TEXT NOT NULL DEFAULT '', revision INTEGER NOT NULL DEFAULT 1,
+    created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL
+  )`,
+  `CREATE TABLE gcal_items (
+    link_id TEXT NOT NULL, google_id TEXT NOT NULL, event_id TEXT NOT NULL, ical_uid TEXT NOT NULL DEFAULT '',
+    kind TEXT NOT NULL DEFAULT 'single' CHECK(kind IN ('series','single','segment')), segment_from TEXT NOT NULL DEFAULT '',
+    etag TEXT NOT NULL DEFAULT '', html_link TEXT NOT NULL DEFAULT '', site TEXT NOT NULL DEFAULT '{}', google TEXT NOT NULL DEFAULT '{}',
+    desc_google INTEGER NOT NULL DEFAULT 0, booking INTEGER NOT NULL DEFAULT 0, gone INTEGER NOT NULL DEFAULT 0, conflict TEXT,
+    synced_at INTEGER NOT NULL DEFAULT 0, created_at INTEGER NOT NULL,
+    PRIMARY KEY (link_id, google_id), UNIQUE (link_id, event_id, segment_from)
+  )`,
+  `CREATE INDEX gcal_items_event ON gcal_items (event_id)`,
+  `CREATE TABLE gcal_queue (
+    event_id TEXT PRIMARY KEY, version INTEGER NOT NULL DEFAULT 1, due_at INTEGER NOT NULL, attempts INTEGER NOT NULL DEFAULT 0,
+    claimed_until INTEGER NOT NULL DEFAULT 0, error TEXT NOT NULL DEFAULT ''
+  )`,
+  `CREATE TABLE gcal_log (
+    id INTEGER PRIMARY KEY AUTOINCREMENT, at INTEGER NOT NULL, link_id TEXT NOT NULL DEFAULT '', event_id TEXT NOT NULL DEFAULT '',
+    google_id TEXT NOT NULL DEFAULT '', direction TEXT NOT NULL CHECK(direction IN ('in','out','clash','info')), action TEXT NOT NULL,
+    title TEXT NOT NULL DEFAULT '', summary TEXT NOT NULL DEFAULT '', data TEXT, resolved INTEGER NOT NULL DEFAULT 0
+  )`,
+  `CREATE INDEX gcal_log_at ON gcal_log (at)`,
+  `CREATE INDEX gcal_log_event ON gcal_log (event_id, at)`,
+  `CREATE TRIGGER gcal_queue_insert AFTER INSERT ON events WHEN ${guard} BEGIN ${enqueue('NEW.id')} END`,
+  `CREATE TRIGGER gcal_queue_update AFTER UPDATE ON events WHEN ${guard} BEGIN ${enqueue('NEW.id')} END`,
+  `CREATE TRIGGER gcal_queue_delete AFTER DELETE ON events WHEN ${guard} BEGIN ${enqueue('OLD.id')} END`,
+] };

package/src/lib/calendar/google/outbound.ts

@@ -0,0 +1,272 @@
+// Site → Google. Every write to an event, from any path, queues it
+// (gcal_queue, filled by triggers); each run works the queue and, per link,
+// makes the Google copy match: created when the event starts belonging to the
+// link (published, in its calendar, holding its room), patched field by field
+// when the site changed something since the pair last agreed, and deleted
+// when it stops belonging (unpublished, deleted, another calendar or room:
+// Q7). A cancelled event stays in Google with "Cancelled: " in front of its
+// title. Only the fields the sync owns are patched; guests are never added
+// and Google never emails anyone (sendUpdates=none).
+//
+// A change that already matches what the pair agreed is never sent, which is
+// what stops loops: the site's write of a change that came from Google leaves
+// nothing to send back to that link (only to the event's other links).
+import { hasTag, type CalEvent } from '../../schema';
+import type { SyncContext } from './context';
+import { entry } from './context';
+import { GoogleError } from './client';
+import { applyGoogleChange } from './inbound';
+import {
+  BOOKING_TAG, NONE, changed, dateHash, fieldHashes, fieldWord, googleBody, googleFields, googleIdFor, googlePatch, inWindow, instanceBody,
+  instanceState, keyStart, linkCarries, originalStart, siteFields, windowStart, type DateState, type Fields,
+} from './map';
+import type { GcalItem, GcalLink, GoogleEvent, Hashes, NewLogEntry } from './types';
+
+const LEASE = 5 * 60_000;
+/** a change Google kept refusing is dropped (and listed) after this many runs */
+const MAX_ATTEMPTS = 8;
+
+/** Works the outgoing queue. Returns how many events it finished. Throws GoogleError('auth') when Google refused the sign-in (everything waits). */
+export async function runOutbound(ctx: SyncContext, limit = 25): Promise<number> {
+  const rows = await ctx.repo.gcal.claimQueue(ctx.now, limit, LEASE);
+  let done = 0;
+  for (let i = 0; i < rows.length; i++) {
+    const row = rows[i];
+    try {
+      await pushEvent(ctx, row.eventId);
+      await ctx.repo.gcal.finishQueue(row.eventId, row.version);
+      done++;
+    } catch (e) {
+      const g = e instanceof GoogleError ? e : null;
+      const message = g?.message ?? 'The change couldn’t be sent to Google.';
+      if (!g) console.error('acms google sync: outgoing change failed', e);
+      if (g?.code === 'auth' || g?.code === 'quota') {
+        // the rest of this batch waits too: Google refuses everything for now
+        const at = ctx.now + (g.code === 'quota' ? g.retryAfter : 60_000);
+        for (const r of rows.slice(i)) await ctx.repo.gcal.retryQueue(r.eventId, r.version, at, message);
+        if (g.code === 'auth') throw e;
+        break;
+      }
+      if (row.attempts >= MAX_ATTEMPTS) {
+        const event = await ctx.repo.getEvent(row.eventId).catch(() => null);
+        await ctx.repo.gcal.log([{ direction: 'out', action: 'failed', eventId: row.eventId, title: event?.title ?? '', summary: `Not sent to Google after ${MAX_ATTEMPTS} tries: ${message} Edit the event to try again.` }], ctx.now);
+        await ctx.repo.gcal.finishQueue(row.eventId, row.version);
+        continue;
+      }
+      await ctx.repo.gcal.retryQueue(row.eventId, row.version, ctx.now + Math.min(3600_000, 60_000 * 2 ** row.attempts), message);
+    }
+  }
+  return done;
+}
+
+/**
+ * One event against every link that may carry it. Each link is tried on its
+ * own: one link's error doesn't hold up the others (the event is retried, and
+ * the links already done have nothing left to send). Google refusing one
+ * event (403: someone else's event that only invites the calendar) is listed
+ * once and left as it is in Google.
+ */
+export async function pushEvent(ctx: SyncContext, eventId: string) {
+  const e = await ctx.repo.getEvent(eventId);
+  const items = await ctx.repo.gcal.itemsForEvent(eventId);
+  let failure: unknown = null;
+  for (const link of ctx.links) {
+    if (link.state !== 'active' || link.direction === 'in') continue;
+    const mine = items.filter((i) => i.linkId === link.id);
+    try { await pushToLink(ctx, link, e, mine); }
+    catch (err) {
+      if (err instanceof GoogleError && (err.code === 'auth' || err.code === 'quota')) throw err;
+      if (err instanceof GoogleError && err.code === 'forbidden') { await refused(ctx, link, e, mine.find((i) => i.kind !== 'segment'), err); continue; }
+      failure ??= err;
+    }
+  }
+  if (failure) throw failure;
+}
+
+async function pushToLink(ctx: SyncContext, link: GcalLink, e: CalEvent | null, mine: GcalItem[]) {
+  const main = mine.find((i) => i.kind !== 'segment');
+  const carried = !!e && linkCarries(e, link);
+  // a booked appointment is Google's: never written back, only unpaired
+  if (main?.booking) { if (!carried) await unpair(ctx, link, main, e); return; }
+  if (!carried) { if (main) await removeCopy(ctx, link, main, mine, e); return; }
+  if (!main) {
+    if (!hasTag(e.tags, BOOKING_TAG) && inWindow(e, windowStart(link, ctx.settings), ctx.settings)) await createCopy(ctx, link, e);
+    return;
+  }
+  // deleted from this Google calendar while the event stays in its other copies: it stays out
+  if (main.leftOut) return;
+  // deleted in Google (and so cancelled here, Q6): made again only once the site brings it back
+  if (main.gone) { if (!e.cancelled) await createCopy(ctx, link, e, main); return; }
+  await updateCopy(ctx, link, e, main, mine.some((i) => i.kind === 'segment'));
+}
+
+/** Google won't let the account change this event there: listed once, and the site's change counts as seen (no retries). */
+async function refused(ctx: SyncContext, link: GcalLink, e: CalEvent | null, item: GcalItem | undefined, err: GoogleError) {
+  if (item && e) await ctx.repo.gcal.patchItem(link.id, item.googleId, { site: fieldHashes(siteFields(e, link, ctx.map)), syncedAt: ctx.now });
+  await ctx.repo.gcal.log([entry(link, item ?? (e ? { googleId: '', eventId: e.id } : null), e?.title ?? '', { direction: 'out', action: 'failed', summary: `${err.message} The change stays on the site; ${link.googleName} keeps its copy as it is.` })], ctx.now);
+}
+
+const removedWhy = (e: CalEvent | null, link: GcalLink) =>
+  !e ? 'Deleted on the site' : e.status !== 'published' ? 'Unpublished on the site' : !e.calendarIds.includes(link.calendarId) ? 'Taken out of the linked calendar' : 'No longer holds this calendar’s room';
+
+async function unpair(ctx: SyncContext, link: GcalLink, item: GcalItem, e: CalEvent | null) {
+  await ctx.repo.gcal.deleteItem(link.id, item.googleId);
+  await ctx.repo.gcal.log([entry(link, item, e?.title ?? '', { direction: 'out', action: 'unpaired', summary: `${removedWhy(e, link)}. The booking stays in Google.` })], ctx.now);
+}
+
+async function removeCopy(ctx: SyncContext, link: GcalLink, item: GcalItem, all: GcalItem[], e: CalEvent | null) {
+  // the event's later parts from a Google split go with it
+  for (const i of all) {
+    if (!i.gone) await ctx.client.deleteEvent(link.googleId, i.googleId);
+    await ctx.repo.gcal.deleteItem(link.id, i.googleId);
+  }
+  if (!item.gone) await ctx.repo.gcal.log([entry(link, item, e?.title ?? '', { direction: 'out', action: 'removed', summary: `${removedWhy(e, link)}: removed from ${link.googleName}.` })], ctx.now);
+}
+
+/**
+ * The site's changed fields worth sending: rules no longer on the link are
+ * forgotten, and a rule just added to it (no agreed value on either side yet)
+ * starts from what each side has, like the first match, without a write.
+ */
+function pendingSite(cur: Hashes, item: GcalItem, link: GcalLink, gh: Hashes) {
+  const site = { ...item.site }, google = { ...item.google };
+  const rules = new Set(link.rules.map((r) => `rule:${r.prefix}`));
+  for (const n of Object.keys({ ...site, ...cur })) {
+    if (!n.startsWith('rule:')) continue;
+    if (!rules.has(n)) { delete site[n]; delete google[n]; continue; }
+    if (site[n] === undefined) { site[n] = cur[n]; if (gh[n] !== undefined) google[n] = gh[n]; }
+  }
+  return { item: { ...item, site, google }, ch: changed(cur, site, (n) => !n.startsWith('rule:') || rules.has(n)) };
+}
+
+/** Google's hash names a patch overwrote. */
+function written(patch: Record<string, unknown>, rules: GcalLink['rules']): string[] {
+  const out: string[] = [];
+  if ('summary' in patch) out.push('title', ...rules.map((r) => `rule:${r.prefix}`));
+  if ('description' in patch) out.push('desc');
+  if ('location' in patch) out.push('place');
+  if ('start' in patch) out.push('when');
+  if ('recurrence' in patch) out.push('repeat');
+  return out;
+}
+const masterHashes = (h: Hashes) => Object.fromEntries(Object.entries(h).filter(([k]) => !k.startsWith('date:')));
+
+/** A new Google copy (or a new one after Google deleted the old: `previous`), with the series' changed dates. */
+export async function createCopy(ctx: SyncContext, link: GcalLink, e: CalEvent, previous?: GcalItem) {
+  const f = siteFields(e, link, ctx.map);
+  const body = googleBody(e, f, link, ctx.map, { desc: true });
+  const id = googleIdFor(e.id, previous ? Math.floor(ctx.now / 1000) : 0);
+  let g: GoogleEvent;
+  try { g = await ctx.client.insertEvent(link.googleId, id ? { id, ...body } : body); }
+  catch (err) {
+    if (!(err instanceof GoogleError && err.code === 'conflict' && id)) throw err;
+    // that id is taken: our own copy from a run that stopped before saving the pair, or one Google deleted (ids stay taken)
+    const found = await ctx.client.getEvent(link.googleId, id).catch(() => null);
+    g = found && found.status !== 'cancelled' && found.extendedProperties?.private?.acmsEventId === e.id
+      ? await ctx.client.patchEvent(link.googleId, id, body)
+      : await ctx.client.insertEvent(link.googleId, body);
+  }
+  const gf = googleFields(g, link, ctx.settings);
+  const google: Hashes = gf ? fieldHashes(gf) : {};
+  const notes: NewLogEntry[] = [];
+  const inSiteZone = googleFields(g, link, ctx.settings, f.when.tz);
+  if (gf && inSiteZone) for (const [key, state] of Object.entries(f.dates)) {
+    if (keyStart(key, f.when, ctx.settings) <= ctx.now) continue;
+    const after = await writeDate(ctx, link, g.id, key, state, f, inSiteZone);
+    if (after === null) notes.push(entry(link, { googleId: g.id, eventId: e.id }, e.title, { direction: 'info', action: 'date', summary: `Google has no ${key.replace('T', ' ')} in this series, so that date’s change stays on the site only.` }));
+    else google[`date:${key}`] = dateHash(after);
+  }
+  const item: GcalItem = {
+    linkId: link.id, googleId: g.id, eventId: e.id, icalUid: g.iCalUID ?? '', kind: e.rrule ? 'series' : 'single', segmentFrom: '', etag: g.etag ?? '', htmlLink: g.htmlLink ?? '',
+    site: fieldHashes(f), google, descGoogle: false, booking: false, gone: false, leftOut: false, conflict: null, syncedAt: ctx.now, createdAt: previous?.createdAt ?? ctx.now,
+  };
+  if (previous) await ctx.repo.gcal.replaceItem(previous.googleId, item); else await ctx.repo.gcal.putItem(item);
+  await ctx.repo.gcal.log([entry(link, item, e.title, { direction: 'out', action: 'created',
+    summary: previous ? `Back on the site: made again in ${link.googleName}.` : `Copied to ${link.googleName}${e.cancelled ? ' as cancelled' : ''}.` }), ...notes], ctx.now);
+}
+
+/** Sets one date of the Google series; returns its state there afterwards (null: Google has no such date). */
+async function writeDate(ctx: SyncContext, link: GcalLink, masterId: string, key: string, want: DateState | 'none', site: Fields, google: Fields): Promise<DateState | 'none' | null> {
+  const missing = (e: unknown) => { if (e instanceof GoogleError && (e.code === 'notfound' || e.code === 'gone' || e.code === 'invalid')) return null; throw e; };
+  const start = originalStart(key, site.when);
+  // asked by its original start (documented); else by the id Google is seen to give dates ("<series>_<UTC start>", "<series>_<date>")
+  const inst = await ctx.client.instance(link.googleId, masterId, start).catch(missing)
+    ?? await ctx.client.getEvent(link.googleId, `${masterId}_${start.replace(/[-:]/g, '')}`).catch(missing);
+  if (!inst || inst.recurringEventId !== masterId) return null;
+  const before = instanceState(inst, google, key);
+  if (want === 'cancelled') {
+    if (before !== 'cancelled') await ctx.client.deleteEvent(link.googleId, inst.id);
+    return 'cancelled';
+  }
+  try {
+    return instanceState(await ctx.client.patchEvent(link.googleId, inst.id, instanceBody(want, site, key)), google, key);
+  } catch (e) {
+    // a date Google deleted may not come back (its instance stays cancelled there)
+    if (e instanceof GoogleError && (e.code === 'notfound' || e.code === 'gone') && before === 'cancelled') return 'cancelled';
+    throw e;
+  }
+}
+
+/** Sends the site's changes since the pair last agreed (Google's own changes are taken first, field by field). */
+async function updateCopy(ctx: SyncContext, link: GcalLink, e: CalEvent, item: GcalItem, split: boolean) {
+  let f = siteFields(e, link, ctx.map);
+  if (!pendingSite(fieldHashes(f), item, link, {}).ch.length) return;
+  let g: GoogleEvent | null = await ctx.client.getEvent(link.googleId, item.googleId).catch((err) => {
+    if (err instanceof GoogleError && (err.code === 'notfound' || err.code === 'gone')) return null;
+    throw err;
+  });
+  if (!g || g.status === 'cancelled') {
+    // deleted in Google meanwhile: the incoming side applies that (Q6); a site → Google link puts the copy back
+    if (link.direction === 'out') await createCopy(ctx, link, e, item);
+    return;
+  }
+  let gf = googleFields(g, link, ctx.settings);
+  // Google changed fields too: take those first (the site wins where both changed, Q4), then send what's left
+  if (link.direction === 'both' && gf && changed(masterHashes(fieldHashes(gf)), masterHashes(item.google)).length) {
+    await applyGoogleChange(ctx, link, item, g);
+    const [again, fresh] = await Promise.all([ctx.repo.gcal.getItem(link.id, item.googleId), ctx.repo.getEvent(e.id)]);
+    if (!again || !fresh || again.gone) return;
+    item = again; e = fresh; f = siteFields(e, link, ctx.map);
+  }
+  const cur = fieldHashes(f);
+  const pending = pendingSite(cur, item, link, gf ? fieldHashes(gf) : {});
+  item = pending.item;
+  const ch = pending.ch;
+  if (!ch.length) { await ctx.repo.gcal.patchItem(link.id, item.googleId, { site: item.site, google: item.google }); return; }
+  const notes: NewLogEntry[] = [];
+  let descGoogle = item.descGoogle;
+  if (descGoogle && ch.includes('desc')) {
+    descGoogle = false;
+    notes.push(entry(link, item, e.title, { direction: 'info', action: 'description', summary: 'Description edited on the site: from now on Google gets the site’s text (Q8).' }));
+  }
+  // a series Google split ("this and following") keeps its time and rule until the site has "from this date on"
+  const held: string[] = split ? ch.filter((n) => n === 'when' || n === 'repeat') : [];
+  if (held.length) notes.push(entry(link, item, e.title, { direction: 'info', action: 'split', summary: `${held.map(fieldWord).join(' and ')} changed on the site, but Google split this series (“this and following”), so ${held.length > 1 ? 'they weren’t' : 'it wasn’t'} sent. Change the later part in Google, or both by hand.` }));
+  const fields = ch.filter((n) => !n.startsWith('date:') && !held.includes(n) && !((n === 'desc' || n === 'link') && descGoogle));
+  const patch = fields.length ? googlePatch(e, f, link, ctx.map, fields, { desc: !descGoogle, googleSummary: g.summary ?? '' }) : {};
+  if (Object.keys(patch).length) g = await ctx.client.patchEvent(link.googleId, item.googleId, patch);
+  gf = googleFields(g, link, ctx.settings) ?? gf;
+  const gh = gf ? fieldHashes(gf) : {};
+  const google: Hashes = { ...item.google };
+  for (const n of written(patch, link.rules)) if (gh[n] !== undefined) google[n] = gh[n];
+
+  // single dates, once the series itself is right (read in the site event's zone, where its keys are)
+  const inSiteZone = googleFields(g, link, ctx.settings, f.when.tz);
+  if (!split && inSiteZone) for (const n of ch.filter((x) => x.startsWith('date:'))) {
+    const key = n.slice(5);
+    if (keyStart(key, f.when, ctx.settings) <= ctx.now) continue;
+    const want = f.dates[key] ?? 'none';
+    const after = await writeDate(ctx, link, item.googleId, key, want, f, inSiteZone);
+    if (after === null) { notes.push(entry(link, item, e.title, { direction: 'info', action: 'date', summary: `Google has no ${key.replace('T', ' ')} in this series, so that date’s change stays on the site only.` })); continue; }
+    const h = dateHash(after);
+    if (h === NONE) delete google[n]; else google[n] = h;
+  }
+  const site: Hashes = { ...item.site };
+  for (const n of ch) { if (cur[n] === undefined) delete site[n]; else site[n] = cur[n]; }
+  // the clash note stays until the site edits that field again (sending the site's winning value isn't an edit)
+  const conflict = !item.conflict || !ch.includes(item.conflict.field) ? item.conflict : item.conflict.sent ? null : { ...item.conflict, sent: true };
+  await ctx.repo.gcal.patchItem(link.id, item.googleId, { site, google, descGoogle, conflict, etag: g.etag ?? item.etag, htmlLink: g.htmlLink ?? item.htmlLink, kind: e.rrule ? 'series' : 'single', syncedAt: ctx.now });
+  const sent = [...new Set(ch.filter((n) => !held.includes(n)).map((n) => n.startsWith('date:') ? 'dates' : n.startsWith('rule:') ? 'title' : n === 'status' ? (e.cancelled ? 'cancelled' : 'restored') : n === 'link' ? 'desc' : n))];
+  if (sent.length) notes.unshift(entry(link, item, e.title, { direction: 'out', action: 'updated', summary: `${sent.map((n) => n === 'dates' ? 'Single dates' : n === 'cancelled' ? 'Cancelled' : n === 'restored' ? 'No longer cancelled' : fieldWord(n)).join(', ')} → ${link.googleName}` }));
+  await ctx.repo.gcal.log(notes, ctx.now);
+}

package/src/lib/calendar/google/service.ts

@@ -0,0 +1,193 @@
+// The Google Calendar sync as a whole: the scheduler job (outgoing changes on
+// every tick, each link's incoming changes every 2 minutes), "Sync now",
+// failures (backoff as YouTube does; staff get an email once a link has
+// failed for an hour), and what the admin shows.
+import { ApiError } from '../../api';
+import type { ContentRepository } from '../../repo/types';
+import { principalCan } from '../../permissions/access';
+import { kickEmail } from '../../email/service';
+import { waitUntilFrom } from '../../webhooks';
+import { GoogleError } from './client';
+import { accountClient, CALLBACK_PATH, gcalSeal, markReconnect, siteOriginOf } from './connect';
+import { siteContext, syncContext, type SyncContext } from './context';
+import { syncIncoming, useGoogleValue } from './inbound';
+import { PAUSE_WORDS, siteGuard } from './links';
+import { buildMatch, startSyncing } from './match';
+import { runOutbound } from './outbound';
+import type { GcalLink } from './types';
+
+const READ_EVERY = 120_000;
+const ALERT_AFTER = 3600_000;
+
+function delayFor(e: unknown, failures: number) {
+  if (e instanceof GoogleError && e.code === 'quota') return Math.max(e.retryAfter, 600_000);
+  if (e instanceof GoogleError && (e.code === 'auth' || e.code === 'forbidden')) return 600_000;
+  return Math.min(3600_000, 60_000 * 2 ** Math.min(failures, 6));
+}
+const messageOf = (e: unknown) => e instanceof GoogleError || e instanceof ApiError ? e.message : 'The sync didn’t finish. It tries again shortly.';
+
+async function noteFailure(repo: ContentRepository, link: GcalLink, e: unknown, now: number, lease?: string) {
+  const failures = link.failures + 1;
+  await repo.gcal.patchLink(link.id, { failures, failingSince: link.failingSince || now, error: messageOf(e), nextAt: now + delayFor(e, failures) + Math.floor(Math.random() * 5000) }, link.revision, lease);
+}
+
+/** The sync's scheduler job. Returns how many changes it handled. */
+export async function syncGoogle(repo: ContentRepository, locals?: unknown, opts: { now?: number } = {}): Promise<number> {
+  const now = opts.now ?? Date.now();
+  let links = await repo.gcal.listLinks();
+  if (!links.length) return 0;
+  const settings = await repo.getSettings();
+  // a link only runs on the site that made it (a copy elsewhere must not write into the real calendar)
+  for (const l of links) if (l.state !== 'paused' && siteGuard(l, settings)) await repo.gcal.patchLink(l.id, { state: 'paused', pausedReason: 'other-site' }, l.revision);
+  await repo.gcal.purgeLog(now);
+  links = await repo.gcal.listLinks();
+  const active = links.filter((l) => l.state === 'active');
+  if (!active.length) return 0;
+  let ctx: SyncContext;
+  try {
+    const { client } = await accountClient(repo, AbortSignal.timeout(110_000), locals);
+    ctx = syncContext(repo, client, settings, siteOriginOf(settings.siteUrl)!, links, locals, now);
+  } catch (e) {
+    // no usable sign-in: changes wait in the queue, and staff hear after an hour
+    for (const l of active) if (l.nextAt <= now) await noteFailure(repo, l, e, now);
+    await alertFailing(repo, locals, now);
+    return 0;
+  }
+  let handled = 0;
+  try {
+    handled += await runOutbound(ctx);
+  } catch (e) {
+    if (e instanceof GoogleError && e.code === 'auth') {
+      await markReconnect(repo, e.message);
+      for (const l of active) await noteFailure(repo, l, e, now);
+      await alertFailing(repo, locals, now);
+      return handled;
+    }
+    throw e;
+  }
+  for (const l of active) {
+    if (l.direction === 'out') {
+      // nothing to read: it's healthy while its changes go out
+      if (l.error || l.lastOkAt < now - READ_EVERY) await repo.gcal.patchLink(l.id, { failures: 0, failingSince: 0, error: '', lastOkAt: now }, l.revision);
+      continue;
+    }
+    // the real clock, not the run's start: earlier jobs and the outgoing changes took time
+    const claimed = await repo.gcal.claimLink(l.id, Math.max(now, Date.now()));
+    if (!claimed) continue;
+    try {
+      const r = await syncIncoming(ctx, claimed);
+      handled += r.handled;
+      await repo.gcal.patchLink(l.id, { syncToken: r.syncToken, fullSync: false, failures: 0, failingSince: 0, error: '', lastOkAt: now, nextAt: now + READ_EVERY + Math.floor(Math.random() * 10_000) }, claimed.revision, claimed.lease);
+    } catch (e) {
+      if (!(e instanceof GoogleError)) console.error('acms google sync: reading a calendar failed', e);
+      await noteFailure(repo, claimed, e, now, claimed.lease);
+      if (e instanceof GoogleError && e.code === 'auth') { await markReconnect(repo, e.message); break; }
+    }
+  }
+  await alertFailing(repo, locals, now);
+  return handled;
+}
+
+/** "Sync now" (and the first match's "Start syncing", `start`): one link, at once, both ways. Errors come back as ApiErrors to show. */
+export async function syncLinkNow(repo: ContentRepository, linkId: string, locals?: unknown, opts: { start?: boolean; now?: number } = {}) {
+  const now = opts.now ?? Date.now();
+  const settings = await repo.getSettings();
+  const link = await repo.gcal.getLink(linkId);
+  if (!link) throw new ApiError(404, 'That link no longer exists.');
+  if (siteGuard(link, settings)) throw new ApiError(400, PAUSE_WORDS['other-site']);
+  if (link.state === 'paused') throw new ApiError(400, 'Resume the link first.');
+  if (link.state === 'matching' && !opts.start) throw new ApiError(400, 'Review the first match first.');
+  const claimed = await repo.gcal.claimLink(link.id, Math.max(now, Date.now()), true);
+  if (!claimed) throw new ApiError(409, 'This link is syncing right now. Try again in a minute.');
+  try {
+    const { client } = await accountClient(repo, AbortSignal.timeout(110_000), locals);
+    const ctx = syncContext(repo, client, settings, siteOriginOf(settings.siteUrl)!, await repo.gcal.listLinks(), locals, now);
+    if (opts.start) {
+      await startSyncing(ctx, claimed);
+      ctx.links = await repo.gcal.listLinks();
+      await runOutbound(ctx, 50);
+      return;
+    }
+    const r = link.direction === 'out' ? null : await syncIncoming(ctx, claimed);
+    await repo.gcal.patchLink(link.id, { ...(r ? { syncToken: r.syncToken, fullSync: false } : {}), failures: 0, failingSince: 0, error: '', lastOkAt: now, nextAt: now + READ_EVERY }, claimed.revision, claimed.lease);
+    await runOutbound(ctx, 50);
+  } catch (e) {
+    const fresh = await repo.gcal.getLink(link.id);
+    if (fresh?.lease === claimed.lease) await noteFailure(repo, fresh, e, now, claimed.lease);
+    if (e instanceof GoogleError && e.code === 'auth') await markReconnect(repo, e.message);
+    if (e instanceof ApiError) throw e;
+    throw new ApiError(400, messageOf(e));
+  }
+}
+
+/** Builds (or rebuilds) a link's first-match review. Writes nothing to either calendar. */
+export async function reviewMatch(repo: ContentRepository, linkId: string, locals?: unknown) {
+  const settings = await repo.getSettings();
+  const link = await repo.gcal.getLink(linkId);
+  if (!link || link.state !== 'matching') throw new ApiError(409, 'This link isn’t waiting for a match.');
+  if (siteGuard(link, settings)) throw new ApiError(400, PAUSE_WORDS['other-site']);
+  try {
+    const { client } = await accountClient(repo, AbortSignal.timeout(110_000), locals);
+    const ctx = syncContext(repo, client, settings, siteOriginOf(settings.siteUrl)!, await repo.gcal.listLinks(), locals);
+    const match = await buildMatch(ctx, link);
+    if (!await repo.gcal.patchLink(link.id, { match }, link.revision)) throw new ApiError(409, 'The link changed meanwhile. Reload and try again.');
+    return match;
+  } catch (e) {
+    if (e instanceof GoogleError && e.code === 'auth') await markReconnect(repo, e.message);
+    if (e instanceof ApiError) throw e;
+    throw new ApiError(400, messageOf(e));
+  }
+}
+
+/** "Use Google's version" on a clash in Recent changes or the event's note. */
+export async function useGoogleVersion(repo: ContentRepository, logId: number, url: URL, locals?: unknown) {
+  const settings = await repo.getSettings();
+  const origin = siteOriginOf(settings.siteUrl) ?? url.origin;
+  try { return await useGoogleValue(siteContext(repo, settings, origin, locals), logId); }
+  catch (e) {
+    if (e instanceof ApiError) throw e;
+    throw new ApiError((e as { status?: number }).status ?? 400, e instanceof Error ? e.message : 'That didn’t work. Try again.');
+  }
+}
+
+/** Staff hear once when a link has been failing for an hour (and again if it recovers and fails again). */
+async function alertFailing(repo: ContentRepository, locals: unknown, now: number) {
+  const due = (await repo.gcal.listLinks()).filter((l) => l.state === 'active' && l.failingSince && now - l.failingSince >= ALERT_AFTER && l.alertedAt < l.failingSince);
+  if (!due.length) return;
+  const users = await repo.listUsers();
+  const recipients: string[] = [];
+  for (const u of users) if (u.email && (u.role === 'owner' || await principalCan(repo, { user: u }, 'schedule.manage').catch(() => false))) recipients.push(u.email);
+  const version = (await repo.email.config().catch(() => null))?.version ?? 0;
+  for (const l of due) {
+    for (const to of [...new Set(recipients)]) {
+      await repo.email.enqueue({ dedupe: `gcal-alert:${l.id}:${l.failingSince}:${to}`, kind: 'gcal-alert', recipient: to,
+        payload: JSON.stringify({ linkId: l.id, since: l.failingSince }), configVersion: version, expiresAt: now + 2 * 86_400_000 });
+    }
+    await repo.gcal.patchLink(l.id, { alertedAt: now }, l.revision);
+  }
+  if (recipients.length) await kickEmail(repo, locals, waitUntilFrom(locals)).catch(() => {});
+}
+
+/** What Calendar settings → Synced with Google shows. */
+export async function googleSyncState(repo: ContentRepository, url: URL, locals?: unknown) {
+  const [settings, account, links, counts, queue, log, calendars, resources, scheduler] = await Promise.all([
+    repo.getSettings(), repo.gcal.account(), repo.gcal.listLinks(), repo.gcal.countItems(), repo.gcal.queueStats(), repo.gcal.listLog({ limit: 25 }),
+    repo.listCalendars(), repo.listResources(), repo.email.schedulerStatus().catch(() => null),
+  ]);
+  const origin = siteOriginOf(settings.siteUrl);
+  let authorized = false;
+  if (account) { try { authorized = !!gcalSeal.decrypt<{ refreshToken?: string }>(account.encrypted, 'account', locals).refreshToken; } catch { /* needs reconnect */ } }
+  return {
+    origin,
+    callbackUrl: `${origin ?? url.origin}${CALLBACK_PATH}`,
+    encryptionReady: gcalSeal.ready(locals),
+    account: account && { clientId: account.clientId, email: account.email, status: account.status, error: account.error, authorized, calendars: account.calendars, calendarsAt: account.calendarsAt, connectedAt: account.connectedAt, siteUrl: account.siteUrl },
+    links: links.map(({ lease: _l, leaseUntil: _u, syncToken: _t, match: _m, ...l }) => ({ ...l, pairs: counts.get(l.id) ?? 0, guard: siteGuard(l, settings), matching: l.state === 'matching' })),
+    calendars: calendars.filter((c) => c.kind === 'native'),
+    resources,
+    queue,
+    log,
+    scheduler: scheduler ? { lastAt: scheduler.finishedAt, healthy: scheduler.finishedAt > Date.now() - 300_000 } : { lastAt: 0, healthy: false },
+  };
+}
+export type GoogleSyncState = Awaited<ReturnType<typeof googleSyncState>>;