fix(twister): require channelId on NewLinkWithNotes so write-back can't silently break

NewLinkWithNotes.channelId (the type saveLink()/saveLinks() accept) was
optional, which made it easy to set channelId only inside meta and
forget the top-level field. That compiled fine but silently broke
outbound write-back: the platform reads a link's channel back from the
persisted channelId column, not from meta, when resolving it for
connector callbacks like onNoteCreated. A link built that way would
send replies to nowhere with no error anywhere.

channelId is now required on NewLinkWithNotes, so this fails to compile
instead of failing silently in production. Added CreateLinkResult as
the return type for Connector.onCreateLink(), where channelId stays
optional (the platform auto-fills it from the compose draft when
omitted, since there's no equivalent auto-fill for saveLink()/saveLinks()
calls).

Fixed every connector in this repo affected by the tightened type,
several of which had exactly the bug this catches: channelId set only
in meta, never at the top level.

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>

Author: KrisBraun

.changeset/require-link-channelid.md

@@ -0,0 +1,7 @@
+---
+"@plotday/twister": minor
+---
+
+Changed: `NewLinkWithNotes.channelId` (the type `integrations.saveLink()`/`saveLinks()` accept) is now required instead of optional. It was easy to set `channelId` only inside `meta` and forget the top-level field — that compiled fine but silently broke outbound write-back (`onNoteCreated` reads the channel back from the persisted `channelId`, not from `meta`) and bulk operations like `archiveLinks({ channelId })` on disable, with no error anywhere. The type system now catches this at compile time instead.
+
+Added: `CreateLinkResult` — the return type for `Connector.onCreateLink()`. Identical to `NewLinkWithNotes` except `channelId` stays optional, since the platform auto-fills it from the compose draft when omitted. Connectors implementing `onCreateLink` should update their return type from `NewLinkWithNotes | null` to `CreateLinkResult | null`.

connectors/AGENTS.md

@@ -301,13 +301,17 @@ Previews (`preview` fields) always use plain text — `snippet` or truncated tit
 
 ## Sync metadata injection
 
-Every synced link must carry provider and channel metadata — bulk operations (e.g. `integrations.archiveLinks({ channelId })` on disable) rely on it:
+Every synced link must carry provider and channel metadata:
 
 ```typescript
-link.channelId = resourceId; // first-class field on NewLink
+link.channelId = resourceId; // first-class field on NewLinkWithNotes — REQUIRED
 link.meta = { ...link.meta, syncProvider: "myprovider" };
 ```
 
+`channelId` is required on `NewLinkWithNotes` (the type `saveLink()`/`saveLinks()` accept) precisely because it's easy to set only inside `meta` and forget the top-level field — the type system will reject a link built that way. This isn't just about bulk operations like `integrations.archiveLinks({ channelId })` on disable: the platform persists `channelId` to the link's DB row and reads it back from there — not from `meta` — to populate `thread.meta.channelId` for connector callbacks like `onNoteCreated`. A link with `channelId` only inside `meta` will send replies to nobody: the connector's own `onNoteCreated` reads a channelId that was never actually saved, and typically no-ops silently (no error, nothing captured) because it can't resolve a client for the reply. Set `channelId` at the top level on every value you pass to `saveLink()`/`saveLinks()`.
+
+`onCreateLink` is the one exception: its return type is `CreateLinkResult`, where `channelId` is optional — the platform auto-fills it from `draft.channelId` (the channel the user composed into) if you omit it.
+
 ## Classifier facets (optional)
 
 Messaging-style connectors may set `link.facets` (`format` / `automation` / `reach` from `@plotday/twister/facets`) as internal classifier signal. Set a dimension only when a heuristic is confident; leave it `null`/omitted otherwise. See `gmail/src/gmail-facets.ts` and `slack/src/slack-facets.ts`.
@@ -520,7 +524,7 @@ For closed-roster DM-style compose set `compose.targets: "contacts"`; for open a
 Then implement `onCreateLink` — return the link, do NOT call `integrations.saveLink()` (platform wires it to the originating thread):
 
 ```typescript
-async onCreateLink(draft: CreateLinkDraft): Promise<NewLinkWithNotes | null> {
+async onCreateLink(draft: CreateLinkDraft): Promise<CreateLinkResult | null> {
   if (draft.type !== "issue") return null;
   const client = await this.getClient(draft.channelId);
   const payload = await client.createIssue({
@@ -609,7 +613,7 @@ Add to `pnpm-workspace.yaml` if not already covered by a glob.
 - [ ] Batch state writes use `this.setMany()`, never a per-item `set()` loop
 - [ ] Canonical, globally-unique `source` using immutable ids; mutable keys in `meta` only
 - [ ] `note.key` for note-level upserts
-- [ ] Set `link.channelId` and inject `syncProvider` into `link.meta`
+- [ ] Set `link.channelId` (top-level field, required) and inject `syncProvider` into `link.meta`
 - [ ] `contentType: "html"` for HTML — never strip tags locally
 - [ ] `created` on notes = external timestamp, not sync time
 - [ ] `initialSync` propagated through every entry point and batch; set `unread: false, archived: false` on initial, omit on incremental
@@ -622,7 +626,7 @@ Add to `pnpm-workspace.yaml` if not already covered by a glob.
 ## Common pitfalls
 
 1. Passing functions/`undefined`/RPC stubs to `this.callback()` → use tokens + `null`.
-2. Forgetting sync metadata (`link.channelId`, `meta.syncProvider`) → breaks bulk archive on disable.
+2. Setting `channelId` only inside `link.meta` instead of at the top level → `NewLinkWithNotes.channelId` is what the platform actually persists and reads back for connector callbacks (`thread.meta.channelId` in `onNoteCreated`, etc.) and for bulk operations like `integrations.archiveLinks({ channelId })` on disable. A `meta`-only channelId compiles fine structurally but leaves outbound replies (and disable-time cleanup) silently broken — no error, nothing captured. The type system now requires the top-level field on `NewLinkWithNotes`, so this fails to compile instead of failing silently in production.
 3. Not propagating `initialSync` through the whole pipeline → notification spam.
 4. Mutable ids in `source` (e.g. Jira issue key) → use immutable id, store key in `meta`.
 5. `source` that's only unique within one user's account → breaks cross-user dedup; add workspace/tenant/mailbox qualifier.

connectors/github/src/issue-sync.ts

@@ -94,7 +94,6 @@ export async function syncIssueBatch(
     );
 
     if (link) {
-      link.channelId = repositoryId;
       link.meta = {
         ...link.meta,
         syncProvider: "github",
@@ -209,6 +208,7 @@ async function convertIssueToLink(
   }
 
   const link: NewLinkWithNotes = {
+    channelId: repositoryId,
     source: `github:issue:${owner}/${repo}/${issue.number}`,
     type: "issue",
     title: issue.title,

connectors/github/src/pr-sync.ts

@@ -102,7 +102,6 @@ export async function syncPRBatch(
     );
 
     if (thread) {
-      thread.channelId = repositoryId;
       thread.meta = {
         ...thread.meta,
         syncProvider: "github",
@@ -219,6 +218,7 @@ async function convertPRToThread(
   }
 
   const thread: NewLinkWithNotes = {
+    channelId: repositoryId,
     source: `github:pr:${owner}/${repo}/${pr.number}`,
     type: "pull_request",
     title: pr.title,

connectors/gmail/src/gmail-api.ts

@@ -855,8 +855,11 @@ export function collectAttachments(
  */
 export function transformGmailThread(thread: GmailThread): NewLinkWithNotes {
   if (!thread.messages || thread.messages.length === 0) {
-    // Return empty structure for invalid threads
+    // Return empty structure for invalid threads. channelId is unknown at
+    // this call site — the caller always sets the real value right after
+    // (see "Inject channel ID" in sync.ts) before saving.
     return {
+      channelId: null,
       type: "email",
       title: "",
       notes: [],
@@ -909,8 +912,10 @@ export function transformGmailThread(thread: GmailThread): NewLinkWithNotes {
     }
   }
 
-  // Create link
+  // Create link. channelId is unknown here — the caller always sets the
+  // real value right after (see "Inject channel ID" in sync.ts) before saving.
   const plotThread: NewLinkWithNotes = {
+    channelId: null,
     source: canonicalUrl,
     type: "email",
     title: subject || "Email",

connectors/gmail/src/gmail.ts

@@ -4,7 +4,7 @@ import {
   type NoteWriteBackResult,
   type ToolBuilder,
 } from "@plotday/twister";
-import type { Actor, NewLinkWithNotes, Note, Thread } from "@plotday/twister/plot";
+import type { Actor, CreateLinkResult, Note, Thread } from "@plotday/twister/plot";
 import {
   AuthProvider,
   type AuthToken,
@@ -774,7 +774,7 @@ export class Gmail extends Connector<Gmail> {
    */
   override async onCreateLink(
     draft: CreateLinkDraft
-  ): Promise<NewLinkWithNotes | null> {
+  ): Promise<CreateLinkResult | null> {
     return onCreateLinkFn(this.makeHost(), draft);
   }
 

connectors/gmail/src/sync.ts

@@ -26,6 +26,7 @@ import { ActionType } from "@plotday/twister/plot";
 import type {
   Actor,
   ActorId,
+  CreateLinkResult,
   NewLinkWithNotes,
   Note,
   Thread,
@@ -1968,7 +1969,7 @@ async function onCreateLinkForwardFn(
   host: GmailSyncHost,
   draft: CreateLinkDraft,
   forwardKey: string
-): Promise<NewLinkWithNotes | null> {
+): Promise<CreateLinkResult | null> {
   const api = await getApiAnyFn(host);
   if (!api) {
     console.error(
@@ -2154,7 +2155,7 @@ async function onCreateLinkForwardFn(
 export async function onCreateLinkFn(
   host: GmailSyncHost,
   draft: CreateLinkDraft
-): Promise<NewLinkWithNotes | null> {
+): Promise<CreateLinkResult | null> {
   if (draft.type !== "email") return null;
 
   if (draft.forward) {

connectors/google-calendar/src/sync.ts

@@ -725,6 +725,7 @@ export async function processCalendarEventsFn(
           };
 
           const link: NewLinkWithNotes = {
+            channelId: calendarId,
             source: canonicalUrl,
             sources: buildEventSources({
               iCalUID: event.iCalUID,
@@ -760,7 +761,6 @@ export async function processCalendarEventsFn(
             ...(initialSync ? { archived: false } : {}),
           };
 
-          link.channelId = calendarId;
           link.meta = {
             ...link.meta,
             syncProvider: "google",
@@ -880,6 +880,7 @@ export async function processCalendarEventsFn(
         const notes = descriptionNote ? [descriptionNote] : [];
 
         const link: NewLinkWithNotes = {
+          channelId: calendarId,
           source: canonicalUrl,
           sources: buildEventSources({
             iCalUID: event.iCalUID,
@@ -913,7 +914,6 @@ export async function processCalendarEventsFn(
           ...(initialSync ? { archived: false } : {}),
         };
 
-        link.channelId = calendarId;
         link.meta = {
           ...link.meta,
           syncProvider: "google",

connectors/google-chat/src/google-chat-api.ts

@@ -657,6 +657,7 @@ export function transformChatThread(
   const preview = firstMessage.text?.substring(0, 200) ?? null;
 
   return {
+    channelId: spaceId,
     source: `google-chat:${spaceId}:thread:${threadKey}`,
     type: "thread",
     title,

connectors/google/src/google.ts

@@ -67,7 +67,7 @@ import type {
   Thread,
   ToolBuilder,
 } from "@plotday/twister";
-import type { NewLinkWithNotes, Note } from "@plotday/twister/plot";
+import type { CreateLinkResult, Note } from "@plotday/twister/plot";
 import type { ScheduleContactStatus } from "@plotday/twister/schedule";
 import {
   AuthProvider,
@@ -863,7 +863,7 @@ export class Google extends Connector<Google> {
    */
   override async onCreateLink(
     draft: CreateLinkDraft
-  ): Promise<NewLinkWithNotes | null> {
+  ): Promise<CreateLinkResult | null> {
     if (draft.type === "task") {
       return tasksOnCreateLinkFn(this.makeTasksHost(), draft);
     }