@mulmoclaude/core 1.12.0 → 1.14.0

package/dist/google/calendar.d.ts

@@ -194,18 +194,32 @@ export interface CalendarListPage {
 /** Pagination loop for CalendarList.list, extracted so it can be tested without
  *  network. Stops at the last page (no token) or the runaway page cap. */
 export declare function collectCalendarPages(fetchPage: (pageToken?: string) => Promise<CalendarListPage>, maxPages?: number): Promise<CalendarSummary[]>;
+/** What a calendar absent from the user's list can still tell about itself. */
+export interface CalendarMeta {
+    /** IANA zone (`Asia/Tokyo`), `""` when Google omits it. */
+    timeZone: string;
+    /** `owner` / `writer` / `reader` / `freeBusyReader`, `""` when unreported. */
+    accessRole: string;
+}
+export declare const toCalendarMeta: (value: unknown) => CalendarMeta;
+/** One calendar's zone and the caller's role on it, read by id rather than
+ *  looked up in the user's list.
+ *
+ *  `calendarList` only holds calendars the user has ADDED; a calendar shared
+ *  with them can be readable and writable by id without appearing there, and a
+ *  push still needs its zone to send an offset-less `dateTime`.
+ *
+ *  Deliberately `events.list` and NOT `calendars.get`: the latter takes only
+ *  full-calendar scopes (`calendar`, `calendar.readonly`, `calendar.calendars*`)
+ *  and this app asks for none of them, so it answers 403 for every account it
+ *  links (#2735). The events list carries the same `timeZone` — plus the
+ *  `accessRole` the calendar resource does not have — under `calendar.events`,
+ *  which the push already holds because it writes with it. Only the envelope is
+ *  read; the one event asked for is the smallest page Google will serve. */
+export declare function getCalendarMeta(accessToken: string, calendarId: string | undefined): Promise<CalendarMeta>;
 /** The calendars the user has added/subscribed to (primary + secondary +
  *  shared), each with its id, name and colour, following pagination. Needs the
  *  calendar-list read scope (GOOGLE_CALENDARLIST_SCOPE). */
-/** One calendar's own resource, addressed by id rather than looked up in the
- *  user's list.
- *
- *  `calendarList` only holds calendars the user has ADDED; a calendar shared
- *  with them can be readable and writable by id without appearing there. This is
- *  how a push learns such a calendar's `timeZone`. Note the resource carries no
- *  `accessRole` — that is a calendarList property — so reachability here says
- *  nothing about writability. */
-export declare function getCalendar(accessToken: string, calendarId: string | undefined): Promise<CalendarSummary>;
 export declare function listCalendars(accessToken: string): Promise<CalendarSummary[]>;
 /** Resolve a `colorId` (on an event or calendar) to its hex background/foreground. */
 export declare function getCalendarColors(accessToken: string): Promise<CalendarColors>;

package/dist/google/calendarStateLock.d.ts

@@ -0,0 +1,23 @@
+/** The clock and the sleep, injected so the timing rules can be exercised
+ *  without real waits. */
+export interface LockClock {
+    now: () => number;
+    sleep: (delay_ms: number) => Promise<void>;
+}
+export declare const liveLockClock: LockClock;
+/** Run `mutate` with no other process mutating the same file.
+ *
+ *  Fails OPEN. A workspace that cannot create the lock file — a read-only
+ *  mount, a missing directory, an exhausted disk — still syncs, the way it did
+ *  before #2679; the lock removes a race, it is not a precondition for
+ *  correctness. The same applies to waiting the timeout out: proceeding
+ *  unlocked risks the lost update this exists to prevent, whereas refusing
+ *  would stop the sync outright.
+ *
+ *  Note what this cannot promise. `O_EXCL` is atomic on a local filesystem and
+ *  on NFSv3+, but a workspace living in a consumer sync folder (Dropbox,
+ *  iCloud, Drive) has no such guarantee — there the file is replicated after
+ *  the fact and both hosts believe they hold it. */
+export declare function withCalendarStateLock<T>(lockPath: string, mutate: () => Promise<T>, clock?: LockClock): Promise<T>;
+/** `<state file>.lock`, so each state file is serialised on its own. */
+export declare const stateLockPath: (statePath: string) => string;

package/dist/google/collectionProjection.d.ts

@@ -8,11 +8,3 @@ export type GoogleCalendarSourceField = (typeof GOOGLE_CALENDAR_SOURCE_FIELDS)[n
  *  primary field always takes the event id — upsert-by-id is what keeps the
  *  sync idempotent, so it is deliberately not remappable. */
 export declare function toCollectionRecord(event: CalendarEventSummary, map: Record<string, GoogleCalendarSourceField>, primaryKey: string, fields: Record<string, CollectionFieldSpec>): CollectionItem;
-/** Google's mapped values laid over whatever the record already holds.
- *
- *  A record file is written whole (`writeItem`), so projecting alone would drop
- *  every column the map does not name — a collection cannot then carry a local
- *  note next to a mirrored event, because the next pull that touches that event
- *  silently deletes it. The projection still wins on the fields it covers: those
- *  are Google's to own. */
-export declare function mergeIntoExisting(existing: CollectionItem | null, projected: CollectionItem): CollectionItem;

package/dist/google/collectionPush.d.ts

@@ -5,21 +5,26 @@ import { ShadowEvent } from './calendarPushState.js';
 import { PushableSourceField } from './pushPlan.js';
 /** What the up-front writability gate knows about the target calendar. */
 export interface CalendarWriteTarget {
-    /** The role from the user's calendar LIST, or null when the calendar is not in
-     *  it. Null means unknown, never read-only: `calendarList` holds only the
-     *  calendars the user has added, so one shared with write access can be absent
-     *  from it (Codex review). */
+    /** The caller's role on the calendar, or null when neither source reported one.
+     *  Null means unknown, never read-only: hard-denying an unknown role would
+     *  refuse a calendar the user can in fact write to. */
     accessRole: string | null;
     /** IANA zone for rebuilding a zone-less stored clock, `""` when unreported. */
     timeZone: string;
 }
 /** Whether to refuse the whole push before touching a single event.
  *
- *  Only on POSITIVE evidence of a non-writable role. An unlisted calendar is
- *  unknown and must fall through: hard-denying it would block the feature
- *  outright for a calendar the user can in fact write to. Those attempts surface
- *  Google's own 403 per record if the write really is not allowed. */
+ *  Only on POSITIVE evidence of a non-writable role. A calendar whose role
+ *  neither source reported is unknown and must fall through: hard-denying it
+ *  would block the feature outright for a calendar the user can in fact write
+ *  to. Those attempts surface Google's own 403 per record if the write really is
+ *  not allowed. */
 export declare const isDeniedAccessRole: (accessRole: string | null) => boolean;
+/** A role Google left blank is UNKNOWN, not a denial. `isDeniedAccessRole`
+ *  refuses every role it does not recognise — `""` included — so passing an
+ *  unreported one straight through would refuse a calendar Google simply said
+ *  nothing about. */
+export declare const reportedAccessRole: (accessRole: string) => string | null;
 export interface CalendarCollectionPushResult {
     slug: string;
     created: number;

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,32 @@ 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,
@@ -97,6 +150,14 @@ export type ClaimGuard = (lastSyncedAt: string | null) => boolean;
  *  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.
  *
@@ -105,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. */