@mulmoclaude/core 1.11.0 → 1.13.0

package/dist/google/collectionSync.d.ts

@@ -1,7 +1,9 @@
 import { SystemTaskDef } from '../scheduler/adapter.js';
+import { CollectionItem } from '../collection/core/schema.js';
 import { LoadedCollection } from '../collection/server/discoveredCollection.js';
 import { DeleteItemResult, WriteItemResult } from '../collection/server/io.js';
 import { CalendarEventSummary } from './calendar.js';
+import { CalendarPushOutcome } from './collectionPush.js';
 import { ShadowEvent } from './calendarPushState.js';
 export declare const GOOGLE_CALENDAR_SYNC_TASK_ID = "system:google-calendar-sync";
 export interface CalendarCollectionSyncResult {
@@ -11,17 +13,24 @@ export interface CalendarCollectionSyncResult {
     /** Events that can NEVER be stored — e.g. an id the record-file sanitiser
      *  rejects. Reported and skipped rather than retried; see `classifyWrite`. */
     unwritable: string[];
+    /** Events left alone because the record they would overwrite holds an edit
+     *  Google has not seen. NOT an error — the token still advances past them; only
+     *  the baseline is held back, so the next push reports the conflict (#2684). */
+    withheld: string[];
     /** Retryable failures. Any of these hold the sync token back. */
     errors: string[];
 }
 /** `skipped` is a benign no-op; `unwritable` can never succeed so it must NOT
- *  hold the token; `error` is retryable and does hold it. */
+ *  hold the token; `error` is retryable and does hold it; `withheld` is a
+ *  deliberate refusal to overwrite a local edit. */
 type ApplyOutcome = {
     kind: "written";
 } | {
     kind: "removed";
 } | {
     kind: "skipped";
+} | {
+    kind: "withheld";
 } | {
     kind: "unwritable";
     message: string;
@@ -31,6 +40,24 @@ type ApplyOutcome = {
 };
 export declare function classifyWrite(eventId: string, kind: WriteItemResult["kind"]): ApplyOutcome;
 export declare function classifyDelete(eventId: string, kind: DeleteItemResult["kind"]): ApplyOutcome;
+/** Whether this record still says what the workspace last saw Google say.
+ *
+ *  Compared against the baseline as it stood when this run STARTED READING, not
+ *  as it stands now: a full re-walk clears the baseline before writing a new one
+ *  (`restartFullSync`), so reading it live would answer "no baseline" for every
+ *  event and protect nothing exactly when the window is widest (#2684).
+ *
+ *  A record with no baseline at all is NOT withheld — that is an event this
+ *  workspace has never held, so there is no local edit to lose. */
+export declare function unsentEditGuard(schema: LoadedCollection["schema"], baseline: Record<string, ShadowEvent>): (existing: CollectionItem, eventId: string) => boolean;
+/** What the pull may do to the record behind one event.
+ *
+ *  The guard runs BEFORE the status is consulted, and that order is the whole
+ *  fix: "is there something local to lose here?" outranks "what did Google do
+ *  to it?". Asking about the status first is how a cancellation kept deleting
+ *  records that held an edit Google had never seen (#2688), long after the
+ *  same guard had been put in front of the overwrite (#2684). */
+export declare function applyPlanFor(existing: CollectionItem | null, event: CalendarEventSummary, hasUnsentEdit: (existing: CollectionItem, eventId: string) => boolean): "withhold" | "delete" | "write";
 /** The events of a window a pull may act on.
  *
  *  A record the push just refused to send is edited on BOTH sides. Writing
@@ -50,15 +77,15 @@ export type UnpushedBySlug = ReadonlyMap<string, ReadonlySet<string> | null>;
  *  protection — would overwrite the very edits this exists to protect; the read
  *  that failed is no evidence that the pull's own writes would fail too, so they
  *  would land (CodeRabbit review #2666). */
-export declare const PROTECTION_UNKNOWN = "could not work out which records to protect after a failed push";
-/** What ONE collection's pull must leave alone: only what ITS OWN push failed to
+export declare const PROTECTION_UNKNOWN = "could not work out which records to protect from the pull";
+/** What ONE collection's pull must leave alone: only what ITS OWN push did not
  *  send.
  *
- *  Scoped per collection because a calendar can back several of them, and a
- *  conflict in one says nothing about the others. Sharing one set across the
- *  group starved a collection that never even declares `autoPush`: it cannot
- *  conflict, yet a neighbour's conflict froze its records — and the sync token
- *  still advanced, so Google never resent them (Codex review #2666). */
+ *  Scoped per collection because a calendar can back several of them, and one
+ *  collection's unsent edit says nothing about the others. Sharing one set across
+ *  the group starved a collection that never even declares `autoPush`: a
+ *  neighbour's conflict froze its records — and the sync token still advanced, so
+ *  Google never resent them (Codex review #2666). */
 export declare const unpushedFor: (unpushed: UnpushedBySlug, slug: string) => ReadonlySet<string> | null;
 /** What the calendar's BASELINE must leave alone: the union over every
  *  collection.
@@ -74,6 +101,38 @@ export declare const unpushedFor: (unpushed: UnpushedBySlug, slug: string) => Re
  *  A `null` (unknown) entry contributes nothing, because that collection reports
  *  a retryable error instead — which stops the baseline being saved at all. */
 export declare const allUnpushed: (unpushed: UnpushedBySlug) => ReadonlySet<string>;
+/** The I/O the protection rule crosses, injected so every branch of it can be
+ *  exercised with fakes instead of a workspace on disk and a live Google grant.
+ *  The rule is what #2666 and #2683 both got wrong, so it is worth pinning. */
+export interface PullProtectionDeps {
+    pushNow: (collection: LoadedCollection, workspaceRoot: string) => Promise<CalendarPushOutcome>;
+    unsentEdits: (collection: LoadedCollection, workspaceRoot: string) => Promise<string[]>;
+}
+/** What ONE collection's pull must leave alone, pushing it first if it asked to
+ *  be pushed.
+ *
+ *  A collection WITHOUT `autoPush` never pushes, so its local edits are unsent by
+ *  definition — the same state a failed push leaves behind, and it needs the same
+ *  protection. Pulling over them destroys the edit AND advances the baseline past
+ *  it, after which no conflict can be detected any more (#2683). "The push did not
+ *  run" is the condition that matters here; why it did not run is not.
+ *
+ *  MUST run inside the calendar lock the caller already holds — hence
+ *  `pushCollectionNow` rather than `pushCalendarForCollection`, which would take
+ *  the same non-reentrant lock and wait on itself forever.
+ *
+ *  A failed push must not stop the pull: the pull is what keeps the collection
+ *  fresh, and a revoked write grant is no reason to freeze reading. */
+export declare function pullProtectionFor(collection: LoadedCollection, workspaceRoot: string, deps?: PullProtectionDeps): Promise<ReadonlySet<string> | null>;
+/** Push the `autoPush` collections in this group, and answer with what every
+ *  collection's pull must leave alone, keyed by collection. */
+export declare function pushAndProtect(collections: readonly LoadedCollection[], workspaceRoot: string, deps?: PullProtectionDeps): Promise<UnpushedBySlug>;
+/** Whether a run may take the calendar, given what the shared marker says.
+ *
+ *  The scheduled door defers to it; every user-facing door claims regardless,
+ *  because a Refresh click that silently returns nothing reads as an empty
+ *  calendar, not as "another host has this". */
+export type ClaimGuard = (lastSyncedAt: string | null) => boolean;
 /** Sync ONE calendar and fan its events out to every collection bound to it.
  *
  *  The fan-out is not an optimisation, it is correctness: the sync token is
@@ -88,8 +147,17 @@ export declare const allUnpushed: (unpushed: UnpushedBySlug) => ReadonlySet<stri
  *  load the SAME stored token and walk the same window. That is idempotent —
  *  writes are upserts by event id — but it is a wasted full walk. Queued, the
  *  second pass resumes from the token the first just stored and fetches only
- *  what is genuinely new. */
-export declare function syncCalendarGroup(calendarId: string | undefined, collections: readonly LoadedCollection[], workspaceRoot: string): Promise<CalendarCollectionSyncResult[]>;
+ *  what is genuinely new. That queue is module state, so it orders the doors
+ *  into THIS process only; `claimThenSync` is what other hosts can see. */
+export declare function syncCalendarGroup(calendarId: string | undefined, collections: readonly LoadedCollection[], workspaceRoot: string, mayClaim?: ClaimGuard): Promise<CalendarCollectionSyncResult[]>;
+/** Every event whose baseline must NOT advance: what the push could not send,
+ *  plus what the apply refused to overwrite.
+ *
+ *  The two must agree exactly. The apply's refusals only became visible after it
+ *  ran, so they join the union here rather than at push time — leaving them out
+ *  would advance the baseline past a record the pull deliberately left holding a
+ *  local edit, which is the silent overwrite this whole path exists to stop. */
+export declare const heldBack: (unpushed: UnpushedBySlug, results: readonly CalendarCollectionSyncResult[]) => ReadonlySet<string>;
 /** The baseline this window establishes: what Google now says per event, and
  *  `null` for a cancelled one so a recreate cannot resume from a dead baseline.
  *
@@ -98,8 +166,17 @@ export declare function syncCalendarGroup(calendarId: string | undefined, collec
  *  keeps the local one would make the next push read a plain one-sided edit —
  *  no conflict to detect any more — and quietly overwrite Google. Held back, the
  *  baseline stays older than both sides, so the conflict keeps being reported
- *  until someone resolves it (#2620). */
-export declare function shadowUpdates(events: readonly CalendarEventSummary[], unpushed?: ReadonlySet<string>): Record<string, ShadowEvent | null>;
+ *  until someone resolves it (#2620).
+ *
+ *  `held` carries what those events must KEEP. Omitting them is enough on an
+ *  incremental run, where the file is merged rather than replaced — but a full
+ *  re-walk CLEARS the baseline first (`restartFullSync`), and there omission
+ *  drops the entry for good. The next push would then read a conflicted record
+ *  as a brand-new create, hit Google's duplicate-id 409 and refuse it, instead
+ *  of reporting the conflict it actually is. Re-stating the pre-run value makes
+ *  a held-back event behave the same either way (observed during Claude review;
+ *  no bot flagged it). */
+export declare function shadowUpdates(events: readonly CalendarEventSummary[], unpushed?: ReadonlySet<string>, held?: Record<string, ShadowEvent>): Record<string, ShadowEvent | null>;
 /** Liveness of the collections a sync just wrote to, checked against the skill
  *  dir `deleteCollection` removes. `exists` is injected so the rule is testable
  *  without a filesystem. An empty group has no survivor by definition. */
@@ -139,8 +216,15 @@ export declare function orphanedCalendarId(deleted: CalendarDeclaring, remaining
  *  Returns the cleared calendar id, or null when nothing was cleared. Never
  *  throws: a failed cleanup must not fail the delete it follows. */
 export declare function releaseOrphanedCalendarToken(deleted: CalendarDeclaring, workspaceRoot: string): Promise<string | null>;
-/** Sync every collection that declares `googleCalendar`. */
-export declare function syncDueCalendarCollections(workspaceRoot: string): Promise<CalendarCollectionSyncResult[]>;
+/** Sync every collection whose calendar is due — no host in this workspace has
+ *  started one within `intervalMs` (#2678). Without that gate this walked every
+ *  declaring group on every tick, so a second host registering the same task
+ *  simply doubled the runs, concurrently.
+ *
+ *  Dueness is not decided here, only described: the guard is handed down and
+ *  evaluated where the marker is written, so the answer cannot go stale between
+ *  deciding and claiming (Codex review #2680). */
+export declare function syncDueCalendarCollections(workspaceRoot: string, intervalMs?: number): Promise<CalendarCollectionSyncResult[]>;
 /** The groups whose calendar has never synced. A missing token IS the "created
  *  since the last sync" signal — nothing else distinguishes a new collection
  *  from an edited one on the write path this feeds (#2427).
@@ -184,7 +268,12 @@ export interface ManualCalendarSyncDeps {
  *  calendar sends them fixing the wrong thing. */
 export declare function syncCalendarForCollection(slug: string, workspaceRoot: string, deps?: ManualCalendarSyncDeps): Promise<ManualCalendarSyncOutcome>;
 /** Scheduler registration, shaped like `feedRefreshTaskDef` so hosts wire it
- *  with a single line. */
+ *  with a single line.
+ *
+ *  `run` reads the interval back off the definition instead of closing over the
+ *  option: a host rewrites `schedule` from its own overrides file AFTER this
+ *  returns, and the due window has to follow it. Frozen at the default, a
+ *  shortened interval would tick often and skip nearly every tick. */
 export declare function googleCalendarSyncTaskDef(opts?: {
     workspaceRoot?: string;
     intervalMs?: number;