plotday · KrisBraun · Jul 8, 2026 · Jul 8, 2026
diff --git a/.changeset/require-link-channelid.md b/.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`.
diff --git a/connectors/AGENTS.md b/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.

diff --git a/connectors/github/src/issue-sync.ts b/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,

diff --git a/connectors/github/src/pr-sync.ts b/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,

diff --git a/connectors/gmail/src/gmail-api.ts b/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",

diff --git a/connectors/gmail/src/gmail.ts b/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);
  }
 

diff --git a/connectors/gmail/src/sync.ts b/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) {

diff --git a/connectors/google-calendar/src/sync.ts b/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",

diff --git a/connectors/google-chat/src/google-chat-api.ts b/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,

diff --git a/connectors/google/src/google.ts b/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);
  }

diff --git a/connectors/jira/src/jira.ts b/connectors/jira/src/jira.ts
@@ -6,6 +6,7 @@ import {
  type Link,
  type Note,
  type Thread,
+ type CreateLinkResult,
  type NewLinkWithNotes,
  NewContact,
 } from "@plotday/twister";
@@ -579,7 +580,6 @@ export class Jira extends Connector<Jira> {
  // Set unread based on sync type (false for initial sync to avoid notification overload)
  linkWithNotes.unread = !state.initialSync;
  // Inject sync metadata for filtering on disable
- linkWithNotes.channelId = projectId;
  linkWithNotes.meta = { ...linkWithNotes.meta, syncProvider: "atlassian", syncableId: projectId };
  await this.tools.integrations.saveLink(linkWithNotes);
  }
@@ -749,6 +749,7 @@ export class Jira extends Connector<Jira> {
  }
 
  return {
+ channelId: projectId,
  ...(source ? { source } : {}),
  type: "issue",
  title: fields.summary || issue.key,
@@ -903,7 +904,7 @@ export class Jira extends Connector<Jira> {
  */
  async onCreateLink(
  draft: CreateLinkDraft
- ): Promise<NewLinkWithNotes | null> {
+ ): Promise<CreateLinkResult | null> {
  if (draft.type !== "issue") return null;
 
  const projectId = draft.channelId;
@@ -1288,6 +1289,7 @@ export class Jira extends Connector<Jira> {
 
  // Create partial link update (empty notes = doesn't touch existing notes)
  const link: NewLinkWithNotes = {
+ channelId: projectId,
  ...(source ? { source } : {}),
  type: "issue",
  title: fields.summary || issue.key,
@@ -1359,6 +1361,7 @@ export class Jira extends Connector<Jira> {
 
  // Create link update with single comment note
  const link: NewLinkWithNotes = {
+ channelId: projectId,
  ...(source ? { source } : {}),
  type: "issue",
  title: issue.fields?.summary || issue.key,

diff --git a/connectors/linear/src/linear-sync.ts b/connectors/linear/src/linear-sync.ts
@@ -215,6 +215,7 @@ export function buildIssueLink(
  }
 
  return {
+ channelId: projectId,
  source: `linear:issue:${issue.id}`,
  type: "issue",
  title: issue.title,

diff --git a/connectors/linear/src/linear.ts b/connectors/linear/src/linear.ts
@@ -13,6 +13,7 @@ import {
  type Note,
  type Thread,
  ThreadMeta,
+ type CreateLinkResult,
  type NewLinkWithNotes,
 } from "@plotday/twister";
 import type { NewContact } from "@plotday/twister/plot";
@@ -490,7 +491,6 @@ export class Linear extends Connector<Linear> {
  const link = buildIssueLink(issue, projectId, state.initialSync);
 
  // Inject sync metadata for bulk operations (e.g. disable filtering)
- link.channelId = projectId;
  link.meta = {
  ...link.meta,
  syncProvider: "linear",
@@ -544,7 +544,7 @@ export class Linear extends Connector<Linear> {
  */
  async onCreateLink(
  draft: CreateLinkDraft
- ): Promise<NewLinkWithNotes | null> {
+ ): Promise<CreateLinkResult | null> {
  if (draft.type !== "issue") return null;
 
  const client = await this.getClient(draft.channelId);

diff --git a/connectors/ms-teams/src/graph-api.ts b/connectors/ms-teams/src/graph-api.ts
@@ -634,6 +634,7 @@ export function transformChannelThread(
  const allMessages = [parentMessage, ...replies];
 
  return {
+ channelId,
  source: `ms-teams:channel:${channelId}:message:${parentMessage.id}`,
  type: "thread",
  title,
@@ -678,7 +679,11 @@ export function transformDmThread(
  );
  const firstMessage = messages[0];
  if (!firstMessage) {
+ // channelId is the DM sentinel constant, which lives in ms-teams.ts and
+ // isn't visible here — the caller always patches the real value in right
+ // after (see "Inject channel ID" in ms-teams.ts) before saving.
  return {
+ channelId: null,
  source: `ms-teams:dm:${chatId}`,
  type: "dm",
  title: "Empty chat",
@@ -692,6 +697,7 @@ export function transformDmThread(
  stripHtml(firstMessage.body.content).substring(0, 50) || "Teams chat";
 
  return {
+ channelId: null,
  source: `ms-teams:dm:${chatId}`,
  type: "dm",
  title,

diff --git a/connectors/ms-teams/src/ms-teams.ts b/connectors/ms-teams/src/ms-teams.ts
@@ -355,7 +355,6 @@ export class MsTeams extends Connector<MsTeams> {
  isInitial
  );
 
- link.channelId = channelId;
  link.meta = {
  ...link.meta,
  syncProvider: "teams",

diff --git a/connectors/outlook-mail/src/enrich.test.ts b/connectors/outlook-mail/src/enrich.test.ts
@@ -83,6 +83,7 @@ describe("enrichLinkContactsFromOutlook", () => {
  : { value: [] }
  );
  const link: NewLinkWithNotes = {
+ channelId: null,
  type: "email",
  title: "t",
  accessContacts: [
@@ -110,6 +111,7 @@ describe("enrichLinkContactsFromOutlook", () => {
  vi.stubGlobal("fetch", fetchSpy);
 
  const link: NewLinkWithNotes = {
+ channelId: null,
  type: "email",
  title: "t",
  accessContacts: [{ email: "ann@x.com" }],

diff --git a/connectors/outlook-mail/src/graph-mail-api.ts b/connectors/outlook-mail/src/graph-mail-api.ts
@@ -601,15 +601,17 @@ export function transformOutlookConversation(opts: {
  attachmentsByMessageId: Map<string, GraphAttachmentMeta[]>;
  accountEmail: string;
 }): NewLinkWithNotes {
+ // 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.
  const sorted = sortConversation(opts.messages).filter((m) => !m.isDraft);
  if (sorted.length === 0) {
- return { type: "email", title: "", notes: [] };
+ return { channelId: null, type: "email", title: "", notes: [] };
  }
 
  const parent = sorted[0];
  const conversationId = parent.conversationId;
  if (!conversationId) {
- return { type: "email", title: "", notes: [] };
+ return { channelId: null, type: "email", title: "", notes: [] };
  }
  const source = conversationSource(opts.accountEmail, conversationId);
 
@@ -634,6 +636,7 @@ export function transformOutlookConversation(opts: {
  }
 
  const plotThread: NewLinkWithNotes = {
+ channelId: null,
  source,
  type: "email",
  title: parent.subject || "Email",

diff --git a/connectors/slack/src/slack-api.ts b/connectors/slack/src/slack-api.ts
@@ -654,6 +654,7 @@ export function transformSlackThread(
  if (!parentMessage) {
  // Return empty structure for invalid threads
  return {
+ channelId,
  type: "thread",
  title: "Empty thread",
  notes: [],
@@ -669,6 +670,7 @@ export function transformSlackThread(
 
  // Create link
  const thread: NewLinkWithNotes = {
+ channelId,
  source: canonicalUrl,
  type: "thread",
  title,