feat(twister): add NewLink.updateOnly to update an existing thread only (#329)

Adds an opt-in `updateOnly` flag to `NewLink`. When set, `saveLink()` /
`saveLinks()` apply the link only as an update to a thread that already
exists for its `source`/`sources`, and never create a new one; when no
matching thread is found the link is skipped and `saveLink()` returns null.

Use it for signals that are only meaningful as an update to an item the
user already has. The Google calendar connector now sets it on the note it
emits for a cancelled occurrence of a recurring event: previously, when the
recurring series itself had not been imported yet (e.g. a newly split
series whose confirmed master had not synced, so only its cancelled future
occurrences arrived), that note materialized a titleless, scheduleless
"cancelled" thread for an event the user never saw. With updateOnly the
cancellation is only ever added to the event's existing thread.

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: KrisBraun

.changeset/link-update-only.md

@@ -0,0 +1,5 @@
+---
+"@plotday/twister": minor
+---
+
+Added: `NewLink.updateOnly` — save a link only as an update to a thread that already exists for its `source`/`sources`, never creating a new one. When no matching thread is found the link is skipped and `saveLink()` returns `null`. Use it for signals that only make sense as an update to an item the user already has (e.g. a calendar cancellation), so they never materialize a standalone thread for something that was never imported.

connectors/google/src/calendar/sync.test.ts

@@ -1061,6 +1061,10 @@ describe("prepareEventInstanceFn — stale occurrence cancellations", () => {
         (n as { key?: string }).key?.startsWith("cancellation-")
       )
     ).toBe(true);
+    // The cancellation link is emitted as update-only: the platform applies it
+    // only if the recurring master's thread already exists, and skips it (no
+    // phantom "cancelled" thread) when the master was never imported.
+    expect((saved[0] as { updateOnly?: boolean }).updateOnly).toBe(true);
   });
 });
 

connectors/google/src/calendar/sync.ts

@@ -533,6 +533,14 @@ export async function prepareEventInstanceFn(
       meta: { syncProvider: "google", syncableId: calendarId },
       scheduleOccurrences: [cancelledOccurrence],
       notes: [cancelNote],
+      // A cancelled occurrence is only meaningful as an annotation on the
+      // recurring master the user already has. When Plot never imported that
+      // master (e.g. a newly split series whose confirmed master hasn't synced
+      // yet, so only its cancelled future occurrences arrived), creating a
+      // thread here would surface a titleless, scheduleless "cancelled" thread
+      // for an event the user never saw. `updateOnly` makes the platform apply
+      // this only if the master's thread already exists, and skip it otherwise.
+      updateOnly: true,
       // Don't flip the thread unread when the user cancelled the occurrence
       // themselves. Cancelled instances are usually sparse (no organizer /
       // attendees), so this rarely fires — best-effort, never over-suppresses.

twister/src/plot.ts

@@ -1366,6 +1366,19 @@ export type NewLink = Partial<
      * {@link Connector.autoThreading}.
      */
     autoThread?: AutoThreadConfig | null;
+    /**
+     * Apply this link only as an UPDATE to a thread that already exists for its
+     * `source`/`sources`; never CREATE a new thread. When no matching thread is
+     * found, `saveLink()`/`saveLinks()` skip the link entirely and return
+     * `null` for it.
+     *
+     * Use for signals that are only meaningful as an update to an item the user
+     * already has — most notably a calendar cancellation, which should annotate
+     * an event that was imported, never materialize a standalone "cancelled"
+     * thread for an occurrence the user never saw. Leave undefined/false for
+     * normal links, which create the thread when absent.
+     */
+    updateOnly?: boolean;
   };
 
 /**