perf(google): concurrent composite channel enumeration + connect/enable-path docs

connectors/AGENTS.md

@@ -155,6 +155,26 @@ Plot but is not dispatched — there is no instance to deliver to.
 
 Set `readonly scopes = Integrations.MergeScopes(MyGoogleConnector.SCOPES, GoogleContacts.SCOPES)` and add `googleContacts: build(GoogleContacts)` to your `build()` return (see `gmail/`, `google-drive/`). Alternatively declare the contacts scopes as an optional `ScopeConfig` group so the user can decline them (see `google-calendar/`).
 
+### Connect / enable-path performance contract
+
+The connect and channel-enable paths are on the user's critical path. The
+runtime keeps them fast, and connectors must not undo that:
+
+- **`getChannels` runs synchronously during connect.** Keep it lean and
+ **parallelize independent enumeration** — when you list resources across
+ several products/APIs, run them with `Promise.all`, never a serial
+ `for … await` loop (see `connectors/google/src/compose.ts`). A serial loop
+ pays the sum of every round-trip while the user waits.
+- **`onChannelEnabled` is dispatched OFF the user's critical path.** When a user
+ activates a connection, the runtime persists the enabled-channel state
+ synchronously and runs `onChannelEnabled` in the background. So: never assume
+ `onChannelEnabled` has run by the time the user sees the connection, and keep
+ using `runTask()` for webhook setup and initial sync — the background dispatch
+ still has the normal per-execution budget. Heavy *inline* work in
+ `onChannelEnabled` (or in `getChannels` on enable) is the recurring mistake;
+ the activate path used to do an inline `getChannels` that paginated every
+ Google Drive folder and blocked for seconds.
+
 ## Architecture
 
 Connectors persist data directly via `integrations.saveLink()` (building `NewLinkWithNotes`). They do not push through a parent twist, and should not call `plot.createThread()`.

connectors/google/src/compose.ts

@@ -34,18 +34,22 @@ export async function composeChannels(
 ): Promise<Channel[]> {
  const grantedScopes = new Set(token.scopes ?? []);
 
- const result: Channel[] = [];
-
- for (const product of products) {
- const hasAllScopes = product.requiredScopes.every((s) => grantedScopes.has(s));
- if (!hasAllScopes) continue;
+ // Enumerate every eligible product concurrently (each getRawChannels is an
+ // independent network call to Google). Order is preserved by enumerating
+ // results in `eligible` order, which is products' declaration order.
+ const eligible = products.filter((product) =>
+ product.requiredScopes.every((s) => grantedScopes.has(s))
+ );
+ const perProduct = await Promise.all(
+ eligible.map((product) => product.getRawChannels(token))
+ );
 
- const rawChannels = await product.getRawChannels(token);
- for (const raw of rawChannels) {
+ const result: Channel[] = [];
+ eligible.forEach((product, i) => {
+ for (const raw of perProduct[i]) {
  result.push(prefixChannel(product.key, raw, product.linkTypes));
  }
- }
-
+ });
  return result;
 }
 

connectors/google/test/compose.test.ts

@@ -149,6 +149,48 @@ describe("composeChannels", () => {
  const channels = await composeChannels([calendarFake, mailFake], token);
  expect(channels).toEqual([]);
  });
+
+ describe("composeChannels (concurrency)", () => {
+ function fakeProduct(key: string, scopes: string[], ids: string[], onCall: () => void, onDone: () => void = () => {}) {
+ return {
+ key,
+ requiredScopes: scopes,
+ linkTypes: [{ type: `${key}-type`, label: key }],
+ getRawChannels: async () => {
+ onCall();
+ // resolve on a later microtask so concurrency is observable
+ await Promise.resolve();
+ onDone(); // call is now resolving — decrement inFlight so serial vs concurrent is distinguishable
+ return ids.map((id) => ({ id, title: id }));
+ },
+ } as any;
+ }
+
+ it("enumerates eligible products concurrently and preserves order", async () => {
+ let inFlight = 0;
+ let maxInFlight = 0;
+ const bump = () => { inFlight++; maxInFlight = Math.max(maxInFlight, inFlight); };
+ const done = () => { inFlight--; };
+ const products = [
+ fakeProduct("mail", ["s.mail"], ["INBOX"], bump, done),
+ fakeProduct("calendar", ["s.cal"], ["primary"], bump, done),
+ ];
+ const token = { token: "t", scopes: ["s.mail", "s.cal"] } as any;
+ const out = await composeChannels(products, token);
+ expect(out.map((c) => c.id)).toEqual(["mail:INBOX", "calendar:primary"]);
+ expect(maxInFlight).toBe(2); // both started before either resolved → concurrent
+ });
+
+ it("skips products whose required scopes are not all granted", async () => {
+ const products = [
+ fakeProduct("mail", ["s.mail"], ["INBOX"], () => {}),
+ fakeProduct("calendar", ["s.cal"], ["primary"], () => {}),
+ ];
+ const token = { token: "t", scopes: ["s.mail"] } as any;
+ const out = await composeChannels(products, token);
+ expect(out.map((c) => c.id)).toEqual(["mail:INBOX"]);
+ });
+ });
 });
 
 // ---------------------------------------------------------------------------

connectors/AGENTS.md

@@ -155,6 +155,26 @@ Plot but is not dispatched — there is no instance to deliver to.
 
 Set `readonly scopes = Integrations.MergeScopes(MyGoogleConnector.SCOPES, GoogleContacts.SCOPES)` and add `googleContacts: build(GoogleContacts)` to your `build()` return (see `gmail/`, `google-drive/`). Alternatively declare the contacts scopes as an optional `ScopeConfig` group so the user can decline them (see `google-calendar/`).
 
+### Connect / enable-path performance contract
+
+The connect and channel-enable paths are on the user's critical path. The
+runtime keeps them fast, and connectors must not undo that:
+
+- **`getChannels` runs synchronously during connect.** Keep it lean and
+ **parallelize independent enumeration** — when you list resources across
+ several products/APIs, run them with `Promise.all`, never a serial
+ `for … await` loop (see `connectors/google/src/compose.ts`). A serial loop
+ pays the sum of every round-trip while the user waits.
+- **`onChannelEnabled` is dispatched OFF the user's critical path.** When a user
+ activates a connection, the runtime persists the enabled-channel state
+ synchronously and runs `onChannelEnabled` in the background. So: never assume
+ `onChannelEnabled` has run by the time the user sees the connection, and keep
+ using `runTask()` for webhook setup and initial sync — the background dispatch
+ still has the normal per-execution budget. Heavy *inline* work in
+ `onChannelEnabled` (or in `getChannels` on enable) is the recurring mistake;
+ the activate path used to do an inline `getChannels` that paginated every
+ Google Drive folder and blocked for seconds.
+
 ## Architecture
 
 Connectors persist data directly via `integrations.saveLink()` (building `NewLinkWithNotes`). They do not push through a parent twist, and should not call `plot.createThread()`.

connectors/google/src/compose.ts

@@ -34,18 +34,22 @@ export async function composeChannels(
 ): Promise<Channel[]> {
  const grantedScopes = new Set(token.scopes ?? []);
 
- const result: Channel[] = [];
-
- for (const product of products) {
- const hasAllScopes = product.requiredScopes.every((s) => grantedScopes.has(s));
- if (!hasAllScopes) continue;
+ // Enumerate every eligible product concurrently (each getRawChannels is an
+ // independent network call to Google). Order is preserved by enumerating
+ // results in `eligible` order, which is products' declaration order.
+ const eligible = products.filter((product) =>
+ product.requiredScopes.every((s) => grantedScopes.has(s))
+ );
+ const perProduct = await Promise.all(
+ eligible.map((product) => product.getRawChannels(token))
+ );
 
- const rawChannels = await product.getRawChannels(token);
- for (const raw of rawChannels) {
+ const result: Channel[] = [];
+ eligible.forEach((product, i) => {
+ for (const raw of perProduct[i]) {
  result.push(prefixChannel(product.key, raw, product.linkTypes));
  }
- }
-
+ });
  return result;
 }
 

connectors/google/test/compose.test.ts

@@ -149,6 +149,48 @@ describe("composeChannels", () => {
  const channels = await composeChannels([calendarFake, mailFake], token);
  expect(channels).toEqual([]);
  });
+
+ describe("composeChannels (concurrency)", () => {
+ function fakeProduct(key: string, scopes: string[], ids: string[], onCall: () => void, onDone: () => void = () => {}) {
+ return {
+ key,
+ requiredScopes: scopes,
+ linkTypes: [{ type: `${key}-type`, label: key }],
+ getRawChannels: async () => {
+ onCall();
+ // resolve on a later microtask so concurrency is observable
+ await Promise.resolve();
+ onDone(); // call is now resolving — decrement inFlight so serial vs concurrent is distinguishable
+ return ids.map((id) => ({ id, title: id }));
+ },
+ } as any;
+ }
+
+ it("enumerates eligible products concurrently and preserves order", async () => {
+ let inFlight = 0;
+ let maxInFlight = 0;
+ const bump = () => { inFlight++; maxInFlight = Math.max(maxInFlight, inFlight); };
+ const done = () => { inFlight--; };
+ const products = [
+ fakeProduct("mail", ["s.mail"], ["INBOX"], bump, done),
+ fakeProduct("calendar", ["s.cal"], ["primary"], bump, done),
+ ];
+ const token = { token: "t", scopes: ["s.mail", "s.cal"] } as any;
+ const out = await composeChannels(products, token);
+ expect(out.map((c) => c.id)).toEqual(["mail:INBOX", "calendar:primary"]);
+ expect(maxInFlight).toBe(2); // both started before either resolved → concurrent
+ });
+
+ it("skips products whose required scopes are not all granted", async () => {
+ const products = [
+ fakeProduct("mail", ["s.mail"], ["INBOX"], () => {}),
+ fakeProduct("calendar", ["s.cal"], ["primary"], () => {}),
+ ];
+ const token = { token: "t", scopes: ["s.mail"] } as any;
+ const out = await composeChannels(products, token);
+ expect(out.map((c) => c.id)).toEqual(["mail:INBOX"]);
+ });
+ });
 });
 
 // ---------------------------------------------------------------------------

connectors/AGENTS.md

@@ -155,6 +155,26 @@ Plot but is not dispatched — there is no instance to deliver to.
 
 Set `readonly scopes = Integrations.MergeScopes(MyGoogleConnector.SCOPES, GoogleContacts.SCOPES)` and add `googleContacts: build(GoogleContacts)` to your `build()` return (see `gmail/`, `google-drive/`). Alternatively declare the contacts scopes as an optional `ScopeConfig` group so the user can decline them (see `google-calendar/`).
 
+### Connect / enable-path performance contract
+
+The connect and channel-enable paths are on the user's critical path. The
+runtime keeps them fast, and connectors must not undo that:
+
+- **`getChannels` runs synchronously during connect.** Keep it lean and
+ **parallelize independent enumeration** — when you list resources across
+ several products/APIs, run them with `Promise.all`, never a serial
+ `for … await` loop (see `connectors/google/src/compose.ts`). A serial loop
+ pays the sum of every round-trip while the user waits.
+- **`onChannelEnabled` is dispatched OFF the user's critical path.** When a user
+ activates a connection, the runtime persists the enabled-channel state
+ synchronously and runs `onChannelEnabled` in the background. So: never assume
+ `onChannelEnabled` has run by the time the user sees the connection, and keep
+ using `runTask()` for webhook setup and initial sync — the background dispatch
+ still has the normal per-execution budget. Heavy *inline* work in
+ `onChannelEnabled` (or in `getChannels` on enable) is the recurring mistake;
+ the activate path used to do an inline `getChannels` that paginated every
+ Google Drive folder and blocked for seconds.
+
 ## Architecture
 
 Connectors persist data directly via `integrations.saveLink()` (building `NewLinkWithNotes`). They do not push through a parent twist, and should not call `plot.createThread()`.

connectors/google/src/compose.ts

@@ -34,18 +34,22 @@ export async function composeChannels(
 ): Promise<Channel[]> {
  const grantedScopes = new Set(token.scopes ?? []);
 
- const result: Channel[] = [];
-
- for (const product of products) {
- const hasAllScopes = product.requiredScopes.every((s) => grantedScopes.has(s));
- if (!hasAllScopes) continue;
+ // Enumerate every eligible product concurrently (each getRawChannels is an
+ // independent network call to Google). Order is preserved by enumerating
+ // results in `eligible` order, which is products' declaration order.
+ const eligible = products.filter((product) =>
+ product.requiredScopes.every((s) => grantedScopes.has(s))
+ );
+ const perProduct = await Promise.all(
+ eligible.map((product) => product.getRawChannels(token))
+ );
 
- const rawChannels = await product.getRawChannels(token);
- for (const raw of rawChannels) {
+ const result: Channel[] = [];
+ eligible.forEach((product, i) => {
+ for (const raw of perProduct[i]) {
  result.push(prefixChannel(product.key, raw, product.linkTypes));
  }
- }
-
+ });
  return result;
 }
 

connectors/google/test/compose.test.ts

@@ -149,6 +149,48 @@ describe("composeChannels", () => {
  const channels = await composeChannels([calendarFake, mailFake], token);
  expect(channels).toEqual([]);
  });
+
+ describe("composeChannels (concurrency)", () => {
+ function fakeProduct(key: string, scopes: string[], ids: string[], onCall: () => void, onDone: () => void = () => {}) {
+ return {
+ key,
+ requiredScopes: scopes,
+ linkTypes: [{ type: `${key}-type`, label: key }],
+ getRawChannels: async () => {
+ onCall();
+ // resolve on a later microtask so concurrency is observable
+ await Promise.resolve();
+ onDone(); // call is now resolving — decrement inFlight so serial vs concurrent is distinguishable
+ return ids.map((id) => ({ id, title: id }));
+ },
+ } as any;
+ }
+
+ it("enumerates eligible products concurrently and preserves order", async () => {
+ let inFlight = 0;
+ let maxInFlight = 0;
+ const bump = () => { inFlight++; maxInFlight = Math.max(maxInFlight, inFlight); };
+ const done = () => { inFlight--; };
+ const products = [
+ fakeProduct("mail", ["s.mail"], ["INBOX"], bump, done),
+ fakeProduct("calendar", ["s.cal"], ["primary"], bump, done),
+ ];
+ const token = { token: "t", scopes: ["s.mail", "s.cal"] } as any;
+ const out = await composeChannels(products, token);
+ expect(out.map((c) => c.id)).toEqual(["mail:INBOX", "calendar:primary"]);
+ expect(maxInFlight).toBe(2); // both started before either resolved → concurrent
+ });
+
+ it("skips products whose required scopes are not all granted", async () => {
+ const products = [
+ fakeProduct("mail", ["s.mail"], ["INBOX"], () => {}),
+ fakeProduct("calendar", ["s.cal"], ["primary"], () => {}),
+ ];
+ const token = { token: "t", scopes: ["s.mail"] } as any;
+ const out = await composeChannels(products, token);
+ expect(out.map((c) => c.id)).toEqual(["mail:INBOX"]);
+ });
+ });
 });
 
 // ---------------------------------------------------------------------------

connectors/AGENTS.md

@@ -155,6 +155,26 @@ Plot but is not dispatched — there is no instance to deliver to.
 
 Set `readonly scopes = Integrations.MergeScopes(MyGoogleConnector.SCOPES, GoogleContacts.SCOPES)` and add `googleContacts: build(GoogleContacts)` to your `build()` return (see `gmail/`, `google-drive/`). Alternatively declare the contacts scopes as an optional `ScopeConfig` group so the user can decline them (see `google-calendar/`).
 
+### Connect / enable-path performance contract
+
+The connect and channel-enable paths are on the user's critical path. The
+runtime keeps them fast, and connectors must not undo that:
+
+- **`getChannels` runs synchronously during connect.** Keep it lean and
+ **parallelize independent enumeration** — when you list resources across
+ several products/APIs, run them with `Promise.all`, never a serial
+ `for … await` loop (see `connectors/google/src/compose.ts`). A serial loop
+ pays the sum of every round-trip while the user waits.
+- **`onChannelEnabled` is dispatched OFF the user's critical path.** When a user
+ activates a connection, the runtime persists the enabled-channel state
+ synchronously and runs `onChannelEnabled` in the background. So: never assume
+ `onChannelEnabled` has run by the time the user sees the connection, and keep
+ using `runTask()` for webhook setup and initial sync — the background dispatch
+ still has the normal per-execution budget. Heavy *inline* work in
+ `onChannelEnabled` (or in `getChannels` on enable) is the recurring mistake;
+ the activate path used to do an inline `getChannels` that paginated every
+ Google Drive folder and blocked for seconds.
+
 ## Architecture
 
 Connectors persist data directly via `integrations.saveLink()` (building `NewLinkWithNotes`). They do not push through a parent twist, and should not call `plot.createThread()`.

connectors/google/src/compose.ts

@@ -34,18 +34,22 @@ export async function composeChannels(
 ): Promise<Channel[]> {
  const grantedScopes = new Set(token.scopes ?? []);
 
- const result: Channel[] = [];
-
- for (const product of products) {
- const hasAllScopes = product.requiredScopes.every((s) => grantedScopes.has(s));
- if (!hasAllScopes) continue;
+ // Enumerate every eligible product concurrently (each getRawChannels is an
+ // independent network call to Google). Order is preserved by enumerating
+ // results in `eligible` order, which is products' declaration order.
+ const eligible = products.filter((product) =>
+ product.requiredScopes.every((s) => grantedScopes.has(s))
+ );
+ const perProduct = await Promise.all(
+ eligible.map((product) => product.getRawChannels(token))
+ );
 
- const rawChannels = await product.getRawChannels(token);
- for (const raw of rawChannels) {
+ const result: Channel[] = [];
+ eligible.forEach((product, i) => {
+ for (const raw of perProduct[i]) {
  result.push(prefixChannel(product.key, raw, product.linkTypes));
  }
- }
-
+ });
  return result;
 }
 

connectors/google/test/compose.test.ts

@@ -149,6 +149,48 @@ describe("composeChannels", () => {
  const channels = await composeChannels([calendarFake, mailFake], token);
  expect(channels).toEqual([]);
  });
+
+ describe("composeChannels (concurrency)", () => {
+ function fakeProduct(key: string, scopes: string[], ids: string[], onCall: () => void, onDone: () => void = () => {}) {
+ return {
+ key,
+ requiredScopes: scopes,
+ linkTypes: [{ type: `${key}-type`, label: key }],
+ getRawChannels: async () => {
+ onCall();
+ // resolve on a later microtask so concurrency is observable
+ await Promise.resolve();
+ onDone(); // call is now resolving — decrement inFlight so serial vs concurrent is distinguishable
+ return ids.map((id) => ({ id, title: id }));
+ },
+ } as any;
+ }
+
+ it("enumerates eligible products concurrently and preserves order", async () => {
+ let inFlight = 0;
+ let maxInFlight = 0;
+ const bump = () => { inFlight++; maxInFlight = Math.max(maxInFlight, inFlight); };
+ const done = () => { inFlight--; };
+ const products = [
+ fakeProduct("mail", ["s.mail"], ["INBOX"], bump, done),
+ fakeProduct("calendar", ["s.cal"], ["primary"], bump, done),
+ ];
+ const token = { token: "t", scopes: ["s.mail", "s.cal"] } as any;
+ const out = await composeChannels(products, token);
+ expect(out.map((c) => c.id)).toEqual(["mail:INBOX", "calendar:primary"]);
+ expect(maxInFlight).toBe(2); // both started before either resolved → concurrent
+ });
+
+ it("skips products whose required scopes are not all granted", async () => {
+ const products = [
+ fakeProduct("mail", ["s.mail"], ["INBOX"], () => {}),
+ fakeProduct("calendar", ["s.cal"], ["primary"], () => {}),
+ ];
+ const token = { token: "t", scopes: ["s.mail"] } as any;
+ const out = await composeChannels(products, token);
+ expect(out.map((c) => c.id)).toEqual(["mail:INBOX"]);
+ });
+ });
 });
 
 // ---------------------------------------------------------------------------

connectors/AGENTS.md

@@ -155,6 +155,26 @@ Plot but is not dispatched — there is no instance to deliver to.
 
 Set `readonly scopes = Integrations.MergeScopes(MyGoogleConnector.SCOPES, GoogleContacts.SCOPES)` and add `googleContacts: build(GoogleContacts)` to your `build()` return (see `gmail/`, `google-drive/`). Alternatively declare the contacts scopes as an optional `ScopeConfig` group so the user can decline them (see `google-calendar/`).
 
+### Connect / enable-path performance contract
+
+The connect and channel-enable paths are on the user's critical path. The
+runtime keeps them fast, and connectors must not undo that:
+
+- **`getChannels` runs synchronously during connect.** Keep it lean and
+ **parallelize independent enumeration** — when you list resources across
+ several products/APIs, run them with `Promise.all`, never a serial
+ `for … await` loop (see `connectors/google/src/compose.ts`). A serial loop
+ pays the sum of every round-trip while the user waits.
+- **`onChannelEnabled` is dispatched OFF the user's critical path.** When a user
+ activates a connection, the runtime persists the enabled-channel state
+ synchronously and runs `onChannelEnabled` in the background. So: never assume
+ `onChannelEnabled` has run by the time the user sees the connection, and keep
+ using `runTask()` for webhook setup and initial sync — the background dispatch
+ still has the normal per-execution budget. Heavy *inline* work in
+ `onChannelEnabled` (or in `getChannels` on enable) is the recurring mistake;
+ the activate path used to do an inline `getChannels` that paginated every
+ Google Drive folder and blocked for seconds.
+
 ## Architecture
 
 Connectors persist data directly via `integrations.saveLink()` (building `NewLinkWithNotes`). They do not push through a parent twist, and should not call `plot.createThread()`.

connectors/google/src/compose.ts

@@ -34,18 +34,22 @@ export async function composeChannels(
 ): Promise<Channel[]> {
  const grantedScopes = new Set(token.scopes ?? []);
 
- const result: Channel[] = [];
-
- for (const product of products) {
- const hasAllScopes = product.requiredScopes.every((s) => grantedScopes.has(s));
- if (!hasAllScopes) continue;
+ // Enumerate every eligible product concurrently (each getRawChannels is an
+ // independent network call to Google). Order is preserved by enumerating
+ // results in `eligible` order, which is products' declaration order.
+ const eligible = products.filter((product) =>
+ product.requiredScopes.every((s) => grantedScopes.has(s))
+ );
+ const perProduct = await Promise.all(
+ eligible.map((product) => product.getRawChannels(token))
+ );
 
- const rawChannels = await product.getRawChannels(token);
- for (const raw of rawChannels) {
+ const result: Channel[] = [];
+ eligible.forEach((product, i) => {
+ for (const raw of perProduct[i]) {
  result.push(prefixChannel(product.key, raw, product.linkTypes));
  }
- }
-
+ });
  return result;
 }
 

connectors/google/test/compose.test.ts

@@ -149,6 +149,48 @@ describe("composeChannels", () => {
  const channels = await composeChannels([calendarFake, mailFake], token);
  expect(channels).toEqual([]);
  });
+
+ describe("composeChannels (concurrency)", () => {
+ function fakeProduct(key: string, scopes: string[], ids: string[], onCall: () => void, onDone: () => void = () => {}) {
+ return {
+ key,
+ requiredScopes: scopes,
+ linkTypes: [{ type: `${key}-type`, label: key }],
+ getRawChannels: async () => {
+ onCall();
+ // resolve on a later microtask so concurrency is observable
+ await Promise.resolve();
+ onDone(); // call is now resolving — decrement inFlight so serial vs concurrent is distinguishable
+ return ids.map((id) => ({ id, title: id }));
+ },
+ } as any;
+ }
+
+ it("enumerates eligible products concurrently and preserves order", async () => {
+ let inFlight = 0;
+ let maxInFlight = 0;
+ const bump = () => { inFlight++; maxInFlight = Math.max(maxInFlight, inFlight); };
+ const done = () => { inFlight--; };
+ const products = [
+ fakeProduct("mail", ["s.mail"], ["INBOX"], bump, done),
+ fakeProduct("calendar", ["s.cal"], ["primary"], bump, done),
+ ];
+ const token = { token: "t", scopes: ["s.mail", "s.cal"] } as any;
+ const out = await composeChannels(products, token);
+ expect(out.map((c) => c.id)).toEqual(["mail:INBOX", "calendar:primary"]);
+ expect(maxInFlight).toBe(2); // both started before either resolved → concurrent
+ });
+
+ it("skips products whose required scopes are not all granted", async () => {
+ const products = [
+ fakeProduct("mail", ["s.mail"], ["INBOX"], () => {}),
+ fakeProduct("calendar", ["s.cal"], ["primary"], () => {}),
+ ];
+ const token = { token: "t", scopes: ["s.mail"] } as any;
+ const out = await composeChannels(products, token);
+ expect(out.map((c) => c.id)).toEqual(["mail:INBOX"]);
+ });
+ });
 });
 
 // ---------------------------------------------------------------------------

connectors/AGENTS.md

@@ -155,6 +155,26 @@ Plot but is not dispatched — there is no instance to deliver to.
 
 Set `readonly scopes = Integrations.MergeScopes(MyGoogleConnector.SCOPES, GoogleContacts.SCOPES)` and add `googleContacts: build(GoogleContacts)` to your `build()` return (see `gmail/`, `google-drive/`). Alternatively declare the contacts scopes as an optional `ScopeConfig` group so the user can decline them (see `google-calendar/`).
 
+### Connect / enable-path performance contract
+
+The connect and channel-enable paths are on the user's critical path. The
+runtime keeps them fast, and connectors must not undo that:
+
+- **`getChannels` runs synchronously during connect.** Keep it lean and
+ **parallelize independent enumeration** — when you list resources across
+ several products/APIs, run them with `Promise.all`, never a serial
+ `for … await` loop (see `connectors/google/src/compose.ts`). A serial loop
+ pays the sum of every round-trip while the user waits.
+- **`onChannelEnabled` is dispatched OFF the user's critical path.** When a user
+ activates a connection, the runtime persists the enabled-channel state
+ synchronously and runs `onChannelEnabled` in the background. So: never assume
+ `onChannelEnabled` has run by the time the user sees the connection, and keep
+ using `runTask()` for webhook setup and initial sync — the background dispatch
+ still has the normal per-execution budget. Heavy *inline* work in
+ `onChannelEnabled` (or in `getChannels` on enable) is the recurring mistake;
+ the activate path used to do an inline `getChannels` that paginated every
+ Google Drive folder and blocked for seconds.
+
 ## Architecture
 
 Connectors persist data directly via `integrations.saveLink()` (building `NewLinkWithNotes`). They do not push through a parent twist, and should not call `plot.createThread()`.

connectors/google/src/compose.ts

@@ -34,18 +34,22 @@ export async function composeChannels(
 ): Promise<Channel[]> {
  const grantedScopes = new Set(token.scopes ?? []);
 
- const result: Channel[] = [];
-
- for (const product of products) {
- const hasAllScopes = product.requiredScopes.every((s) => grantedScopes.has(s));
- if (!hasAllScopes) continue;
+ // Enumerate every eligible product concurrently (each getRawChannels is an
+ // independent network call to Google). Order is preserved by enumerating
+ // results in `eligible` order, which is products' declaration order.
+ const eligible = products.filter((product) =>
+ product.requiredScopes.every((s) => grantedScopes.has(s))
+ );
+ const perProduct = await Promise.all(
+ eligible.map((product) => product.getRawChannels(token))
+ );
 
- const rawChannels = await product.getRawChannels(token);
- for (const raw of rawChannels) {
+ const result: Channel[] = [];
+ eligible.forEach((product, i) => {
+ for (const raw of perProduct[i]) {
  result.push(prefixChannel(product.key, raw, product.linkTypes));
  }
- }
-
+ });
  return result;
 }
 

connectors/google/test/compose.test.ts

@@ -149,6 +149,48 @@ describe("composeChannels", () => {
  const channels = await composeChannels([calendarFake, mailFake], token);
  expect(channels).toEqual([]);
  });
+
+ describe("composeChannels (concurrency)", () => {
+ function fakeProduct(key: string, scopes: string[], ids: string[], onCall: () => void, onDone: () => void = () => {}) {
+ return {
+ key,
+ requiredScopes: scopes,
+ linkTypes: [{ type: `${key}-type`, label: key }],
+ getRawChannels: async () => {
+ onCall();
+ // resolve on a later microtask so concurrency is observable
+ await Promise.resolve();
+ onDone(); // call is now resolving — decrement inFlight so serial vs concurrent is distinguishable
+ return ids.map((id) => ({ id, title: id }));
+ },
+ } as any;
+ }
+
+ it("enumerates eligible products concurrently and preserves order", async () => {
+ let inFlight = 0;
+ let maxInFlight = 0;
+ const bump = () => { inFlight++; maxInFlight = Math.max(maxInFlight, inFlight); };
+ const done = () => { inFlight--; };
+ const products = [
+ fakeProduct("mail", ["s.mail"], ["INBOX"], bump, done),
+ fakeProduct("calendar", ["s.cal"], ["primary"], bump, done),
+ ];
+ const token = { token: "t", scopes: ["s.mail", "s.cal"] } as any;
+ const out = await composeChannels(products, token);
+ expect(out.map((c) => c.id)).toEqual(["mail:INBOX", "calendar:primary"]);
+ expect(maxInFlight).toBe(2); // both started before either resolved → concurrent
+ });
+
+ it("skips products whose required scopes are not all granted", async () => {
+ const products = [
+ fakeProduct("mail", ["s.mail"], ["INBOX"], () => {}),
+ fakeProduct("calendar", ["s.cal"], ["primary"], () => {}),
+ ];
+ const token = { token: "t", scopes: ["s.mail"] } as any;
+ const out = await composeChannels(products, token);
+ expect(out.map((c) => c.id)).toEqual(["mail:INBOX"]);
+ });
+ });
 });
 
 // ---------------------------------------------------------------------------

connectors/AGENTS.md

@@ -155,6 +155,26 @@ Plot but is not dispatched — there is no instance to deliver to.
 
 Set `readonly scopes = Integrations.MergeScopes(MyGoogleConnector.SCOPES, GoogleContacts.SCOPES)` and add `googleContacts: build(GoogleContacts)` to your `build()` return (see `gmail/`, `google-drive/`). Alternatively declare the contacts scopes as an optional `ScopeConfig` group so the user can decline them (see `google-calendar/`).
 
+### Connect / enable-path performance contract
+
+The connect and channel-enable paths are on the user's critical path. The
+runtime keeps them fast, and connectors must not undo that:
+
+- **`getChannels` runs synchronously during connect.** Keep it lean and
+ **parallelize independent enumeration** — when you list resources across
+ several products/APIs, run them with `Promise.all`, never a serial
+ `for … await` loop (see `connectors/google/src/compose.ts`). A serial loop
+ pays the sum of every round-trip while the user waits.
+- **`onChannelEnabled` is dispatched OFF the user's critical path.** When a user
+ activates a connection, the runtime persists the enabled-channel state
+ synchronously and runs `onChannelEnabled` in the background. So: never assume
+ `onChannelEnabled` has run by the time the user sees the connection, and keep
+ using `runTask()` for webhook setup and initial sync — the background dispatch
+ still has the normal per-execution budget. Heavy *inline* work in
+ `onChannelEnabled` (or in `getChannels` on enable) is the recurring mistake;
+ the activate path used to do an inline `getChannels` that paginated every
+ Google Drive folder and blocked for seconds.
+
 ## Architecture
 
 Connectors persist data directly via `integrations.saveLink()` (building `NewLinkWithNotes`). They do not push through a parent twist, and should not call `plot.createThread()`.

connectors/google/src/compose.ts

@@ -34,18 +34,22 @@ export async function composeChannels(
 ): Promise<Channel[]> {
  const grantedScopes = new Set(token.scopes ?? []);
 
- const result: Channel[] = [];
-
- for (const product of products) {
- const hasAllScopes = product.requiredScopes.every((s) => grantedScopes.has(s));
- if (!hasAllScopes) continue;
+ // Enumerate every eligible product concurrently (each getRawChannels is an
+ // independent network call to Google). Order is preserved by enumerating
+ // results in `eligible` order, which is products' declaration order.
+ const eligible = products.filter((product) =>
+ product.requiredScopes.every((s) => grantedScopes.has(s))
+ );
+ const perProduct = await Promise.all(
+ eligible.map((product) => product.getRawChannels(token))
+ );
 
- const rawChannels = await product.getRawChannels(token);
- for (const raw of rawChannels) {
+ const result: Channel[] = [];
+ eligible.forEach((product, i) => {
+ for (const raw of perProduct[i]) {
  result.push(prefixChannel(product.key, raw, product.linkTypes));
  }
- }
-
+ });
  return result;
 }
 

connectors/google/test/compose.test.ts

@@ -149,6 +149,48 @@ describe("composeChannels", () => {
  const channels = await composeChannels([calendarFake, mailFake], token);
  expect(channels).toEqual([]);
  });
+
+ describe("composeChannels (concurrency)", () => {
+ function fakeProduct(key: string, scopes: string[], ids: string[], onCall: () => void, onDone: () => void = () => {}) {
+ return {
+ key,
+ requiredScopes: scopes,
+ linkTypes: [{ type: `${key}-type`, label: key }],
+ getRawChannels: async () => {
+ onCall();
+ // resolve on a later microtask so concurrency is observable
+ await Promise.resolve();
+ onDone(); // call is now resolving — decrement inFlight so serial vs concurrent is distinguishable
+ return ids.map((id) => ({ id, title: id }));
+ },
+ } as any;
+ }
+
+ it("enumerates eligible products concurrently and preserves order", async () => {
+ let inFlight = 0;
+ let maxInFlight = 0;
+ const bump = () => { inFlight++; maxInFlight = Math.max(maxInFlight, inFlight); };
+ const done = () => { inFlight--; };
+ const products = [
+ fakeProduct("mail", ["s.mail"], ["INBOX"], bump, done),
+ fakeProduct("calendar", ["s.cal"], ["primary"], bump, done),
+ ];
+ const token = { token: "t", scopes: ["s.mail", "s.cal"] } as any;
+ const out = await composeChannels(products, token);
+ expect(out.map((c) => c.id)).toEqual(["mail:INBOX", "calendar:primary"]);
+ expect(maxInFlight).toBe(2); // both started before either resolved → concurrent
+ });
+
+ it("skips products whose required scopes are not all granted", async () => {
+ const products = [
+ fakeProduct("mail", ["s.mail"], ["INBOX"], () => {}),
+ fakeProduct("calendar", ["s.cal"], ["primary"], () => {}),
+ ];
+ const token = { token: "t", scopes: ["s.mail"] } as any;
+ const out = await composeChannels(products, token);
+ expect(out.map((c) => c.id)).toEqual(["mail:INBOX"]);
+ });
+ });
 });
 
 // ---------------------------------------------------------------------------

connectors/AGENTS.md

@@ -155,6 +155,26 @@ Plot but is not dispatched — there is no instance to deliver to.
 
 Set `readonly scopes = Integrations.MergeScopes(MyGoogleConnector.SCOPES, GoogleContacts.SCOPES)` and add `googleContacts: build(GoogleContacts)` to your `build()` return (see `gmail/`, `google-drive/`). Alternatively declare the contacts scopes as an optional `ScopeConfig` group so the user can decline them (see `google-calendar/`).
 
+### Connect / enable-path performance contract
+
+The connect and channel-enable paths are on the user's critical path. The
+runtime keeps them fast, and connectors must not undo that:
+
+- **`getChannels` runs synchronously during connect.** Keep it lean and
+ **parallelize independent enumeration** — when you list resources across
+ several products/APIs, run them with `Promise.all`, never a serial
+ `for … await` loop (see `connectors/google/src/compose.ts`). A serial loop
+ pays the sum of every round-trip while the user waits.
+- **`onChannelEnabled` is dispatched OFF the user's critical path.** When a user
+ activates a connection, the runtime persists the enabled-channel state
+ synchronously and runs `onChannelEnabled` in the background. So: never assume
+ `onChannelEnabled` has run by the time the user sees the connection, and keep
+ using `runTask()` for webhook setup and initial sync — the background dispatch
+ still has the normal per-execution budget. Heavy *inline* work in
+ `onChannelEnabled` (or in `getChannels` on enable) is the recurring mistake;
+ the activate path used to do an inline `getChannels` that paginated every
+ Google Drive folder and blocked for seconds.
+
 ## Architecture
 
 Connectors persist data directly via `integrations.saveLink()` (building `NewLinkWithNotes`). They do not push through a parent twist, and should not call `plot.createThread()`.

connectors/google/src/compose.ts

@@ -34,18 +34,22 @@ export async function composeChannels(
 ): Promise<Channel[]> {
  const grantedScopes = new Set(token.scopes ?? []);
 
- const result: Channel[] = [];
-
- for (const product of products) {
- const hasAllScopes = product.requiredScopes.every((s) => grantedScopes.has(s));
- if (!hasAllScopes) continue;
+ // Enumerate every eligible product concurrently (each getRawChannels is an
+ // independent network call to Google). Order is preserved by enumerating
+ // results in `eligible` order, which is products' declaration order.
+ const eligible = products.filter((product) =>
+ product.requiredScopes.every((s) => grantedScopes.has(s))
+ );
+ const perProduct = await Promise.all(
+ eligible.map((product) => product.getRawChannels(token))
+ );
 
- const rawChannels = await product.getRawChannels(token);
- for (const raw of rawChannels) {
+ const result: Channel[] = [];
+ eligible.forEach((product, i) => {
+ for (const raw of perProduct[i]) {
  result.push(prefixChannel(product.key, raw, product.linkTypes));
  }
- }
-
+ });
  return result;
 }
 

connectors/google/test/compose.test.ts

@@ -149,6 +149,48 @@ describe("composeChannels", () => {
  const channels = await composeChannels([calendarFake, mailFake], token);
  expect(channels).toEqual([]);
  });
+
+ describe("composeChannels (concurrency)", () => {
+ function fakeProduct(key: string, scopes: string[], ids: string[], onCall: () => void, onDone: () => void = () => {}) {
+ return {
+ key,
+ requiredScopes: scopes,
+ linkTypes: [{ type: `${key}-type`, label: key }],
+ getRawChannels: async () => {
+ onCall();
+ // resolve on a later microtask so concurrency is observable
+ await Promise.resolve();
+ onDone(); // call is now resolving — decrement inFlight so serial vs concurrent is distinguishable
+ return ids.map((id) => ({ id, title: id }));
+ },
+ } as any;
+ }
+
+ it("enumerates eligible products concurrently and preserves order", async () => {
+ let inFlight = 0;
+ let maxInFlight = 0;
+ const bump = () => { inFlight++; maxInFlight = Math.max(maxInFlight, inFlight); };
+ const done = () => { inFlight--; };
+ const products = [
+ fakeProduct("mail", ["s.mail"], ["INBOX"], bump, done),
+ fakeProduct("calendar", ["s.cal"], ["primary"], bump, done),
+ ];
+ const token = { token: "t", scopes: ["s.mail", "s.cal"] } as any;
+ const out = await composeChannels(products, token);
+ expect(out.map((c) => c.id)).toEqual(["mail:INBOX", "calendar:primary"]);
+ expect(maxInFlight).toBe(2); // both started before either resolved → concurrent
+ });
+
+ it("skips products whose required scopes are not all granted", async () => {
+ const products = [
+ fakeProduct("mail", ["s.mail"], ["INBOX"], () => {}),
+ fakeProduct("calendar", ["s.cal"], ["primary"], () => {}),
+ ];
+ const token = { token: "t", scopes: ["s.mail"] } as any;
+ const out = await composeChannels(products, token);
+ expect(out.map((c) => c.id)).toEqual(["mail:INBOX"]);
+ });
+ });
 });
 
 // ---------------------------------------------------------------------------