@opengeni/api-router 0.23.1 → 0.30.0

package/src/integrations/google-drive.ts

@@ -1,5 +1,6 @@
 import { createHash, randomBytes } from "node:crypto";
 import type { Settings } from "@opengeni/config";
+import type { AccessGrant, ScheduledTask, ScheduledTaskScheduleSpec } from "@opengeni/contracts";
 import {
   bindConnectorDocumentDestination,
   type ConnectorDocumentDestinationSelection,
@@ -9,11 +10,13 @@ import {
   GOOGLE_DRIVE_CREDENTIAL_ROLE,
   GOOGLE_DRIVE_PROVIDER_DOMAIN,
   GOOGLE_DRIVE_READONLY_SCOPE,
+  GoogleDriveKnowledgeSourceConfig,
   GoogleDriveBrowseItem,
   GoogleDriveBrowseResponse,
   GoogleDriveConnectionLifecycle,
   GoogleDriveConnectionMetadata,
   GoogleDriveOAuthStartResponse,
+  SaveGoogleDriveIntegrationSourceRequest,
   SaveGoogleDriveSourceRequest,
   googleDriveOAuthScopeDecision,
   googleDriveScopesAllowCapability,
@@ -21,10 +24,30 @@ import {
   type GoogleDriveLifecycleActionRequest,
   type GoogleDriveOAuthStartRequest,
 } from "@opengeni/contracts/google-drive";
-import { hasPermission, requireEnvironmentEncryption } from "@opengeni/core";
+import {
+  API_INTEGRATION_OAUTH_CREDENTIAL_ROLE,
+  ApiIntegrationOAuthConnectionMetadata,
+  IntegrationFacetMutationResult,
+} from "@opengeni/contracts";
+import {
+  GOOGLE_DRIVE_INTEGRATION_DEFINITION,
+  integrationDefinitionProviderDomain,
+} from "@opengeni/capabilities";
+import {
+  captureScheduledTaskRestoreState,
+  createValidatedScheduledTask,
+  hasPermission,
+  manualScheduledTaskTriggerWorkflowId,
+  requireEnvironmentEncryption,
+  syncCreatedScheduledTask,
+  syncUpdatedScheduledTask,
+} from "@opengeni/core";
 import type { ApiRouteDeps } from "@opengeni/core";
 import {
   buildConnectionTokenResolver,
+  configureIntegrationFacet,
+  appendKnowledgeSourceAclVersion,
+  deauthorizeKnowledgeSourceRetrieval,
   ConnectionDisconnectGenerationError,
   ConnectionDisconnectIdempotencyError,
   consumeIntegrationOAuthStateNonce,
@@ -33,12 +56,21 @@ import {
   disconnectConnectionIdempotently,
   encryptEnvironmentValue,
   getConnectionMetadata,
+  getKnowledgeSourceByExternalIdentityForSyncAuthority,
+  getKnowledgeSourceForSyncAuthority,
   getWorkspaceGrant,
+  listKnowledgeSourceSyncTasksForConnection,
   loadConnectionCredentialForBroker,
+  listIntegrationInstanceFacets,
   transitionConnectionState,
   updateConnection,
+  updateScheduledTask,
+  upsertKnowledgeProvider,
+  upsertKnowledgeSource,
+  recordKnowledgeLifecycleEvent,
   type PermanentConnectionRefreshFailure,
 } from "@opengeni/db";
+import { googleDriveKnowledgeSourceIdentity } from "@opengeni/documents/google-drive";
 import { createSignedState, readSignedState } from "@opengeni/github";
 import { readResponseJsonBounded, type FetchLike } from "@opengeni/network";
 import { HTTPException } from "hono/http-exception";
@@ -75,6 +107,74 @@ type GoogleDriveOAuthState = {
   iat: number;
 };
 
+export async function wakeGoogleDriveSourcesFromWorkspaceEvent(
+  deps: ApiRouteDeps,
+  input: {
+    accountId: string;
+    workspaceId: string;
+    connectionId: string;
+    connectionOwnerSubjectId: string;
+    eventId: string;
+    driveId: string | null;
+  },
+): Promise<{ enabled: boolean; triggered: number }> {
+  if (deps.settings.googleDriveWorkspaceEventsEnabled !== true) {
+    return { enabled: false, triggered: 0 };
+  }
+  const eventId = input.eventId.trim();
+  if (eventId.length < 1 || eventId.length > 1024) {
+    throw new Error("google_drive_workspace_event_id_invalid");
+  }
+  const connection = await getConnectionMetadata(
+    deps.db,
+    input.workspaceId,
+    input.connectionId,
+    input.connectionOwnerSubjectId,
+  );
+  if (!connection || connection.accountId !== input.accountId) {
+    throw new Error("google_drive_workspace_event_connection_not_found");
+  }
+  const metadata = requireGoogleDriveConnection(connection, input.connectionOwnerSubjectId);
+  if (effectiveGoogleDriveLifecycle(connection, metadata).state !== "active") {
+    return { enabled: true, triggered: 0 };
+  }
+  const selectedSources =
+    metadata.selectedSources ?? (metadata.selectedSource ? [metadata.selectedSource] : []);
+  const selectedById = new Map(selectedSources.map((source) => [source.id, source]));
+  const tasks = await listKnowledgeSourceSyncTasksForConnection(
+    deps.db,
+    input.workspaceId,
+    input.connectionId,
+  );
+  let triggered = 0;
+  for (const task of tasks) {
+    if (task.action.kind !== "knowledge_source_sync" || task.status !== "active") continue;
+    const externalSourceId =
+      typeof task.metadata.externalSourceId === "string" ? task.metadata.externalSourceId : null;
+    const selectedSource = externalSourceId ? selectedById.get(externalSourceId) : null;
+    if (
+      !selectedSource ||
+      !selectedSource.syncEnabled ||
+      selectedSource.driveId !== input.driveId
+    ) {
+      continue;
+    }
+    const token = createHash("sha256")
+      .update(`google-drive-workspace-event:${task.id}:${eventId}`)
+      .digest("hex")
+      .slice(0, 48);
+    await deps.workflowClient.triggerScheduledTask({
+      task,
+      agentRunUsageIdempotencyKey: `knowledge-source-sync:provider-event:${task.id}:${token}`,
+      triggerWorkflowId: manualScheduledTaskTriggerWorkflowId(task.id, `provider-event-${token}`),
+      initiator: { kind: "service", subjectId: "google-drive-workspace-events" },
+      triggerType: "provider_event",
+    });
+    triggered += 1;
+  }
+  return { enabled: true, triggered };
+}
+
 type GoogleTokenResponse = {
   accessToken: string;
   refreshToken?: string;
@@ -85,6 +185,18 @@ type GoogleTokenResponse = {
 
 type GoogleDriveConnectionRecord = NonNullable<Awaited<ReturnType<typeof getConnectionMetadata>>>;
 
+type GoogleDriveApiConnection =
+  | {
+      kind: "legacy";
+      connection: GoogleDriveConnectionRecord;
+      metadata: GoogleDriveConnectionMetadata;
+    }
+  | {
+      kind: "integration";
+      connection: GoogleDriveConnectionRecord;
+      metadata: ApiIntegrationOAuthConnectionMetadata;
+    };
+
 export async function startGoogleDriveOAuth(
   deps: ApiRouteDeps,
   input: {
@@ -337,6 +449,21 @@ export async function transitionGoogleDriveLifecycle(
   // Natural convergence makes retried pause/resume requests idempotent even if
   // the caller still carries the pre-transition version.
   if (existing.status === "active" && lifecycle.state === targetState) {
+    if (targetState === "paused") {
+      await deauthorizeGoogleDriveConnectionSources(
+        deps,
+        existing,
+        input.subjectId,
+        "connection_paused",
+        existing.version,
+      );
+    }
+    await setGoogleDriveScheduleStatus(
+      deps,
+      input.workspaceId,
+      input.connectionId,
+      targetState === "active" ? "active" : "paused",
+    );
     return existing;
   }
   if (existing.status === "revoked") {
@@ -358,6 +485,16 @@ export async function transitionGoogleDriveLifecycle(
     throw new HTTPException(409, { message: "Google Drive connection changed; try again" });
   }
 
+  if (input.payload.action === "pause") {
+    await deauthorizeGoogleDriveConnectionSources(
+      deps,
+      existing,
+      input.subjectId,
+      "connection_paused",
+      existing.version + 1,
+    );
+  }
+
   const updated = await transitionConnectionState(deps.db, {
     workspaceId: input.workspaceId,
     connectionId: existing.id,
@@ -381,11 +518,23 @@ export async function transitionGoogleDriveLifecycle(
     if (converged?.status === "active") {
       const convergedMetadata = requireGoogleDriveConnection(converged, input.subjectId);
       if (effectiveGoogleDriveLifecycle(converged, convergedMetadata).state === targetState) {
+        await setGoogleDriveScheduleStatus(
+          deps,
+          input.workspaceId,
+          input.connectionId,
+          targetState === "active" ? "active" : "paused",
+        );
         return converged;
       }
     }
     throw new HTTPException(409, { message: "Google Drive connection changed; try again" });
   }
+  await setGoogleDriveScheduleStatus(
+    deps,
+    input.workspaceId,
+    input.connectionId,
+    targetState === "active" ? "active" : "paused",
+  );
   return updated;
 }
 
@@ -400,7 +549,14 @@ export async function disconnectGoogleDrive(
 ) {
   const metadata = requireGoogleDriveConnection(input.connection, input.subjectId);
   try {
-    return await disconnectConnectionIdempotently(deps.db, {
+    await deauthorizeGoogleDriveConnectionSources(
+      deps,
+      input.connection,
+      input.subjectId,
+      "connection_disconnected",
+      input.connection.version + 1,
+    );
+    const disconnected = await disconnectConnectionIdempotently(deps.db, {
       accountId: input.connection.accountId,
       workspaceId: input.workspaceId,
       subjectId: input.subjectId,
@@ -414,6 +570,8 @@ export async function disconnectGoogleDrive(
       lastError: null,
       updatedBySubjectId: input.subjectId,
     });
+    await setGoogleDriveScheduleStatus(deps, input.workspaceId, input.connection.id, "paused");
+    return disconnected;
   } catch (error) {
     if (error instanceof ConnectionDisconnectIdempotencyError) {
       throw new HTTPException(409, {
@@ -429,6 +587,82 @@ export async function disconnectGoogleDrive(
   }
 }
 
+async function setGoogleDriveScheduleStatus(
+  deps: ApiRouteDeps,
+  workspaceId: string,
+  connectionId: string,
+  status: "active" | "paused",
+): Promise<void> {
+  await forEachGoogleDriveConnectionTask(deps, workspaceId, connectionId, async (task) => {
+    if (knowledgeSourceScheduleControl(task).connectionPaused === (status === "paused")) return;
+    const previous = await captureScheduledTaskRestoreState(deps.db, task);
+    const updated = await updateScheduledTask(deps.db, workspaceId, task.id, {
+      metadata: {
+        ...task.metadata,
+        knowledgeSourceSync: {
+          ...knowledgeSourceScheduleControl(task),
+          connectionPaused: status === "paused",
+        },
+      },
+    });
+    await syncUpdatedScheduledTask({
+      db: deps.db,
+      workflowClient: deps.workflowClient,
+      previous,
+      task: updated,
+    });
+  });
+}
+
+async function deauthorizeGoogleDriveConnectionSources(
+  deps: ApiRouteDeps,
+  connection: GoogleDriveConnectionRecord,
+  subjectId: string,
+  reasonCode: string,
+  authorityVersion: number,
+): Promise<void> {
+  await forEachGoogleDriveConnectionTask(
+    deps,
+    connection.workspaceId,
+    connection.id,
+    async (task) => {
+      if (task.action.initiatingSubjectId !== subjectId) return;
+      const resolved = await getKnowledgeSourceForSyncAuthority(deps.db, {
+        accountId: task.accountId,
+        workspaceId: task.workspaceId,
+        sourceId: task.action.sourceId,
+        initiatingSubjectId: subjectId,
+      });
+      if (!resolved || resolved.source.lifecycleState !== "active") return;
+      await deauthorizeKnowledgeSourceRetrieval(deps.db, {
+        accountId: task.accountId,
+        workspaceId: task.workspaceId,
+        sourceId: task.action.sourceId,
+        audience: task.action.destination,
+        operationId: `google-drive-deauthorize:${connection.id}:${authorityVersion}:${task.action.sourceId}:${reasonCode}`,
+        reasonCode,
+        actor: {
+          kind: "human",
+          subjectId,
+          initiatingHumanSubjectId: subjectId,
+        },
+      });
+    },
+  );
+}
+
+async function forEachGoogleDriveConnectionTask(
+  deps: ApiRouteDeps,
+  workspaceId: string,
+  connectionId: string,
+  fn: (task: ScheduledTask & { action: { kind: "knowledge_source_sync" } }) => Promise<void>,
+): Promise<void> {
+  const tasks = await listKnowledgeSourceSyncTasksForConnection(deps.db, workspaceId, connectionId);
+  for (const task of tasks) {
+    await fn(task);
+  }
+}
+
 export async function browseGoogleDrive(
   deps: ApiRouteDeps,
   input: {
@@ -448,7 +682,7 @@ export async function browseGoogleDrive(
   if (!connection) {
     throw new HTTPException(404, { message: "Google Drive connection not found" });
   }
-  await requireGoogleDriveSourceConnection(deps, connection, input.subjectId);
+  await requireGoogleDriveApiConnection(deps, connection, input.subjectId);
   const parentId = validDriveId(input.parentId, "parentId");
   const currentItem = await resolveGoogleDriveBoundaryItem(deps, {
     workspaceId: input.workspaceId,
@@ -500,6 +734,105 @@ export async function browseGoogleDrive(
   });
 }
 
+export async function browseGoogleDriveFacetSource(
+  deps: ApiRouteDeps,
+  input: {
+    workspaceId: string;
+    subjectId: string;
+    capabilityId: string;
+    instanceKey: string;
+    facetKey: string;
+    parentId: string;
+    pageToken?: string | undefined;
+  },
+) {
+  const context = await requireGoogleDriveIntegrationFacet(deps, input);
+  return await browseGoogleDrive(deps, {
+    workspaceId: input.workspaceId,
+    subjectId: input.subjectId,
+    connectionId: context.connection.id,
+    parentId: input.parentId,
+    ...(input.pageToken ? { pageToken: input.pageToken } : {}),
+  });
+}
+
+export async function saveGoogleDriveFacetSource(
+  deps: ApiRouteDeps,
+  input: {
+    accountId: string;
+    workspaceId: string;
+    subjectId: string;
+    capabilityId: string;
+    instanceKey: string;
+    facetKey: string;
+    payload: unknown;
+    canManageOrganizationDestination: boolean;
+    canManageWorkspaceDestination: boolean;
+    canManagePersonalDestination: boolean;
+  },
+): Promise<IntegrationFacetMutationResult> {
+  const parsedPayload = SaveGoogleDriveIntegrationSourceRequest.safeParse(input.payload);
+  if (!parsedPayload.success) {
+    throw new HTTPException(400, { message: "invalid Google Drive source selection" });
+  }
+  const payload = parsedPayload.data;
+  const context = await requireGoogleDriveIntegrationFacet(deps, input);
+  const documentDestination = googleDriveDocumentDestination(input, payload);
+  const verifiedSources = await verifyGoogleDriveSources(deps, {
+    workspaceId: input.workspaceId,
+    subjectId: input.subjectId,
+    connectionId: context.connection.id,
+    sources: payload.sources,
+  });
+  const config = GoogleDriveKnowledgeSourceConfig.parse({
+    sources: verifiedSources.map((verified) => ({
+      id: verified.id,
+      name: verified.name,
+      mimeType: verified.mimeType,
+      ...(verified.driveId ? { driveId: verified.driveId } : {}),
+      sourceKind:
+        verified.id === "root"
+          ? "my_drive"
+          : verified.driveId === verified.id
+            ? "shared_drive"
+            : "folder",
+      includeDescendants: true,
+    })),
+    destination: {
+      authorityKind: documentDestination.authorityKind,
+      authorityAccountId: documentDestination.authorityAccountId,
+      ...(documentDestination.authorityWorkspaceId
+        ? { authorityWorkspaceId: documentDestination.authorityWorkspaceId }
+        : {}),
+      ...(documentDestination.authoritySubjectId
+        ? { authoritySubjectId: documentDestination.authoritySubjectId }
+        : {}),
+      ...(documentDestination.collectionId
+        ? { collectionId: documentDestination.collectionId }
+        : {}),
+    },
+    syncCadence: payload.syncCadence,
+    readPolicy: payload.readPolicy,
+  });
+  return IntegrationFacetMutationResult.parse(
+    await configureIntegrationFacet(deps.db, {
+      accountId: input.accountId,
+      workspaceId: input.workspaceId,
+      subjectId: input.subjectId,
+      capabilityId: input.capabilityId,
+      instanceKey: input.instanceKey,
+      facetKey: input.facetKey,
+      displayName:
+        context.facet.binding?.displayName ?? `${input.instanceKey} — Google Drive content`,
+      config,
+      ...(payload.expectedVersion !== undefined
+        ? { expectedVersion: payload.expectedVersion }
+        : {}),
+      idempotencyKey: payload.idempotencyKey,
+    }),
+  );
+}
+
 export async function saveGoogleDriveSource(
   deps: ApiRouteDeps,
   input: {
@@ -507,6 +840,7 @@ export async function saveGoogleDriveSource(
     workspaceId: string;
     subjectId: string;
     connectionId: string;
+    grant: AccessGrant;
     payload: unknown;
     canManageOrganizationDestination: boolean;
     canManageWorkspaceDestination: boolean;
@@ -531,6 +865,133 @@ export async function saveGoogleDriveSource(
     throw new HTTPException(403, { message: "Google Drive connection authority mismatch" });
   }
   await requireGoogleDriveSourceConnection(deps, existing, input.subjectId);
+  const documentDestination = googleDriveDocumentDestination(input, payload);
+  const verifiedSources = await verifyGoogleDriveSources(deps, {
+    workspaceId: input.workspaceId,
+    subjectId: input.subjectId,
+    connectionId: input.connectionId,
+    sources: payload.sources,
+  });
+  const latest =
+    (await getConnectionMetadata(
+      deps.db,
+      input.workspaceId,
+      input.connectionId,
+      input.subjectId,
+    )) ?? existing;
+  const latestMetadata = await requireGoogleDriveSourceConnection(deps, latest, input.subjectId);
+  const previousSources =
+    latestMetadata.selectedSources ??
+    (latestMetadata.selectedSource ? [latestMetadata.selectedSource] : []);
+  const updated = await transitionConnectionState(deps.db, {
+    workspaceId: input.workspaceId,
+    connectionId: latest.id,
+    visibleToSubjectId: input.subjectId,
+    expectedVersion: latest.version,
+    metadata: GoogleDriveConnectionMetadata.parse({
+      ...latestMetadata,
+      documentDestination,
+      selectedSource: null,
+      selectedSources: verifiedSources.map((verified) => {
+        const previous = previousSources.find((source) => source.id === verified.id);
+        return {
+          id: verified.id,
+          name: verified.name,
+          mimeType: verified.mimeType,
+          driveId: verified.driveId,
+          destination: documentDestination,
+          syncCadence: payload.syncCadence,
+          syncEnabled: payload.syncEnabled,
+          configGeneration: (previous?.configGeneration ?? 0) + 1,
+          readPolicy: payload.readPolicy,
+          selectedAt: new Date().toISOString(),
+        };
+      }),
+    }),
+    updatedBySubjectId: input.subjectId,
+  });
+  if (!updated) {
+    throw new HTTPException(409, { message: "Google Drive connection changed; try again" });
+  }
+  await materializeGoogleDriveKnowledgeSchedules(deps, {
+    ...input,
+    connection: updated,
+    metadata: GoogleDriveConnectionMetadata.parse(updated.metadata),
+    previouslySelectedSourceIds: new Set(
+      (
+        latestMetadata.selectedSources ??
+        (latestMetadata.selectedSource ? [latestMetadata.selectedSource] : [])
+      ).map((source) => source.id),
+    ),
+    previouslyEnabledSourceIds: new Set(
+      (
+        latestMetadata.selectedSources ??
+        (latestMetadata.selectedSource ? [latestMetadata.selectedSource] : [])
+      )
+        .filter((source) => source.syncEnabled)
+        .map((source) => source.id),
+    ),
+  });
+  return updated;
+}
+
+async function requireGoogleDriveIntegrationFacet(
+  deps: ApiRouteDeps,
+  input: {
+    workspaceId: string;
+    subjectId: string;
+    capabilityId: string;
+    instanceKey: string;
+    facetKey: string;
+  },
+) {
+  const instance = await listIntegrationInstanceFacets(
+    deps.db,
+    input.workspaceId,
+    input.subjectId,
+    input.capabilityId,
+    input.instanceKey,
+  );
+  const facet = instance.facets.find(
+    (candidate) => candidate.definition.facetKey === input.facetKey,
+  );
+  if (
+    !facet ||
+    facet.definition.kind !== "knowledge_source" ||
+    facet.definition.capabilities.provider !== "google-drive"
+  ) {
+    throw new HTTPException(404, { message: "Google Drive knowledge source not found" });
+  }
+  if (!instance.connectionId) {
+    throw new HTTPException(422, { message: "Google Drive Integration has no Connection" });
+  }
+  const connection = await getConnectionMetadata(
+    deps.db,
+    input.workspaceId,
+    instance.connectionId,
+    input.subjectId,
+  );
+  if (!connection) {
+    throw new HTTPException(404, { message: "Google Drive Connection not found" });
+  }
+  await requireGoogleDriveApiConnection(deps, connection, input.subjectId);
+  return { instance, facet, connection };
+}
+
+function googleDriveDocumentDestination(
+  input: {
+    accountId: string;
+    workspaceId: string;
+    subjectId: string;
+    canManageOrganizationDestination: boolean;
+    canManageWorkspaceDestination: boolean;
+    canManagePersonalDestination: boolean;
+  },
+  payload: {
+    destination?: ConnectorDocumentDestinationSelection | undefined;
+    targetScope?: "user" | "workspace" | "organization" | undefined;
+  },
+) {
   const destinationSelection: ConnectorDocumentDestinationSelection = payload.destination ?? {
     authorityKind: "workspace",
     collectionId: null,
@@ -547,13 +1008,24 @@ export async function saveGoogleDriveSource(
   if (destinationSelection.authorityKind === "personal" && !input.canManagePersonalDestination) {
     throw new HTTPException(403, { message: "personal destination requires the exact actor" });
   }
-  const documentDestination = bindConnectorDocumentDestination(destinationSelection, {
+  return bindConnectorDocumentDestination(destinationSelection, {
     accountId: input.accountId,
     workspaceId: input.workspaceId,
     initiatingSubjectId: input.subjectId,
   });
-  const verifiedSources = [];
-  for (const source of payload.sources) {
+}
+
+async function verifyGoogleDriveSources(
+  deps: ApiRouteDeps,
+  input: {
+    workspaceId: string;
+    subjectId: string;
+    connectionId: string;
+    sources: Array<{ id: string; name: string; mimeType: string; driveId: string | null }>;
+  },
+): Promise<GoogleDriveBrowseItem[]> {
+  const verifiedSources: GoogleDriveBrowseItem[] = [];
+  for (const source of input.sources) {
     const sourceId = validDriveId(source.id, "source.id");
     const verified = await resolveGoogleDriveBoundaryItem(deps, {
       workspaceId: input.workspaceId,
@@ -572,40 +1044,380 @@ export async function saveGoogleDriveSource(
     }
     verifiedSources.push(verified);
   }
-  const latest =
-    (await getConnectionMetadata(
-      deps.db,
-      input.workspaceId,
-      input.connectionId,
-      input.subjectId,
-    )) ?? existing;
-  const latestMetadata = await requireGoogleDriveSourceConnection(deps, latest, input.subjectId);
-  const updated = await transitionConnectionState(deps.db, {
-    workspaceId: input.workspaceId,
-    connectionId: latest.id,
-    visibleToSubjectId: input.subjectId,
-    expectedVersion: latest.version,
-    metadata: GoogleDriveConnectionMetadata.parse({
-      ...latestMetadata,
-      documentDestination,
-      selectedSource: null,
-      selectedSources: verifiedSources.map((verified) => ({
-        id: verified.id,
-        name: verified.name,
-        mimeType: verified.mimeType,
-        driveId: verified.driveId,
-        destination: documentDestination,
-        syncCadence: payload.syncCadence,
-        readPolicy: payload.readPolicy,
-        selectedAt: new Date().toISOString(),
-      })),
-    }),
-    updatedBySubjectId: input.subjectId,
+  return verifiedSources;
+}
+async function materializeGoogleDriveKnowledgeSchedules(
+  deps: ApiRouteDeps,
+  input: {
+    accountId: string;
+    workspaceId: string;
+    subjectId: string;
+    connectionId: string;
+    grant: AccessGrant;
+    connection: GoogleDriveConnectionRecord;
+    metadata: ReturnType<typeof GoogleDriveConnectionMetadata.parse>;
+    previouslySelectedSourceIds: Set<string>;
+    previouslyEnabledSourceIds: Set<string>;
+  },
+): Promise<void> {
+  const selectedSources = input.metadata.selectedSources ?? [];
+  const enabledSources = selectedSources.filter((source) => source.syncEnabled);
+  const enabledIds = new Set(enabledSources.map((source) => source.id));
+  const connectionTasks = await listKnowledgeSourceSyncTasksForConnection(
+    deps.db,
+    input.workspaceId,
+    input.connectionId,
+  );
+  const actor = {
+    kind: "human" as const,
+    subjectId: input.subjectId,
+    initiatingHumanSubjectId: input.subjectId,
+  };
+
+  for (const selectedSource of enabledSources) {
+    const explicitlyEnabled = !input.previouslyEnabledSourceIds.has(selectedSource.id);
+    const identity = googleDriveKnowledgeSourceIdentity({
+      googlePermissionId: input.metadata.googlePermissionId,
+      googleEmail: input.metadata.googleEmail,
+      source: selectedSource,
+      accountId: input.accountId,
+      workspaceId: input.workspaceId,
+      connectionSubjectId: input.subjectId,
+    });
+    let source = null as Awaited<ReturnType<typeof upsertKnowledgeSource>> | null;
+    let existingTask = null as (typeof connectionTasks)[number] | null;
+    for (const task of connectionTasks) {
+      if (task.action.kind !== "knowledge_source_sync") continue;
+      const resolved = await getKnowledgeSourceForSyncAuthority(deps.db, {
+        accountId: input.accountId,
+        workspaceId: input.workspaceId,
+        sourceId: task.action.sourceId,
+        initiatingSubjectId: input.subjectId,
+      });
+      if (resolved?.source.externalSourceId !== identity.externalSourceId) continue;
+      source = resolved.source;
+      existingTask = task;
+      break;
+    }
+    if (!source) {
+      const provider = await upsertKnowledgeProvider(deps.db, {
+        accountId: input.accountId,
+        workspaceId: input.workspaceId,
+        scope: identity.scope,
+        providerKey: identity.providerKey,
+        externalTenantId: identity.externalTenantId,
+        operationId: `google-drive-provider:${input.connectionId}`,
+        actor,
+      });
+      source =
+        (await getKnowledgeSourceByExternalIdentityForSyncAuthority(deps.db, {
+          accountId: input.accountId,
+          workspaceId: input.workspaceId,
+          providerId: provider.id,
+          externalSourceId: identity.externalSourceId,
+          initiatingSubjectId: input.subjectId,
+        })) ??
+        (await upsertKnowledgeSource(deps.db, {
+          accountId: input.accountId,
+          workspaceId: input.workspaceId,
+          scope: identity.scope,
+          providerId: provider.id,
+          externalSourceId: identity.externalSourceId,
+          sourceKind: identity.sourceKind,
+          sourceUri: identity.sourceUri,
+          operationId: `google-drive-source:${input.connectionId}:${identity.externalSourceId}`,
+          actor,
+        }));
+    }
+    if (source.lifecycleState !== "active") {
+      if (!explicitlyEnabled) continue;
+      const restored = await recordKnowledgeLifecycleEvent(deps.db, {
+        accountId: input.accountId,
+        workspaceId: input.workspaceId,
+        targetKind: "source",
+        targetId: source.id,
+        eventType: "restored",
+        expectedGeneration: source.lifecycleGeneration,
+        operationId: `google-drive-source-restore:${source.id}:${input.connection.version}`,
+        reasonCode: "source_explicitly_reenabled",
+        actor,
+      });
+      source = {
+        ...source,
+        lifecycleState: "active",
+        lifecycleGeneration: restored.lifecycleGeneration,
+      };
+    }
+    if (!source.currentAclGeneration) {
+      await appendKnowledgeSourceAclVersion(deps.db, {
+        accountId: input.accountId,
+        workspaceId: input.workspaceId,
+        sourceId: source.id,
+        audience: identity.scope,
+        expectedSourceLifecycleGeneration: source.lifecycleGeneration,
+        expectedAclGeneration: 0,
+        aclVersion: `google-drive-destination:${input.connection.version}`,
+        agentAccess: false,
+        operationId: `google-drive-source-acl:${source.id}`,
+        reasonCode: "source_selected",
+        actor,
+      });
+    }
+    const action = {
+      kind: "knowledge_source_sync" as const,
+      sourceId: source.id,
+      sourceGeneration: source.syncGeneration,
+      sourceLifecycleGeneration: source.lifecycleGeneration,
+      sourceConfigGeneration: selectedSource.configGeneration,
+      controlWorkspaceId: input.workspaceId,
+      providerCoordinationKey: `${identity.providerKey}:${identity.externalTenantId}:${selectedSource.driveId ?? "my-drive"}`,
+      destination: identity.scope,
+      initiatingSubjectId: input.subjectId,
+      allDescendants: true,
+      connection: {
+        connectionId: input.connectionId,
+        ownerSubjectId: input.subjectId,
+        connectionVersion: input.connection.version,
+        providerDomain: input.connection.providerDomain,
+        kind: input.connection.kind,
+      },
+      limits: {
+        maxItems: 500,
+        maxBytes: 500_000_000,
+        maxFileBytes: 100_000_000,
+        maxProviderRequests: 1_000,
+        maxElapsedSeconds: 300,
+        maxConcurrency: 4,
+        maxFailureDetails: 25,
+      },
+    };
+    const schedule = googleDriveSchedule(selectedSource.syncCadence);
+    let task;
+    if (existingTask) {
+      const previous = await captureScheduledTaskRestoreState(deps.db, existingTask);
+      task = await updateScheduledTask(deps.db, input.workspaceId, existingTask.id, {
+        name: `Sync Google Drive: ${selectedSource.name}`,
+        overlapPolicy: "buffer_one",
+        action,
+        metadata: {
+          ...existingTask.metadata,
+          connectorKind: "google_drive",
+          connectionId: input.connectionId,
+          externalSourceId: selectedSource.id,
+          knowledgeSourceSync: {
+            ...knowledgeSourceScheduleControl(existingTask),
+            sourceEnabled: true,
+            connectionPaused: false,
+          },
+        },
+      });
+      await syncUpdatedScheduledTask({
+        db: deps.db,
+        workflowClient: deps.workflowClient,
+        previous,
+        task,
+      });
+    } else {
+      task = await createValidatedScheduledTask({
+        settings: deps.settings,
+        db: deps.db,
+        objectStorage: deps.objectStorage,
+        grant: input.grant,
+        authorizationSurface: "http",
+        sessionAuthorization: deps.sessionAuthorization,
+        payload: {
+          name: `Sync Google Drive: ${selectedSource.name}`,
+          status: "active",
+          schedule,
+          overlapPolicy: "buffer_one",
+          action,
+          runMode: "new_session_per_run",
+          targetSessionId: null,
+          agentConfig: {
+            prompt: "Knowledge source synchronization",
+            resources: [],
+            tools: [],
+            metadata: {},
+          },
+          variableSetId: null,
+          environmentId: null,
+          rigId: null,
+          metadata: {
+            connectorKind: "google_drive",
+            connectionId: input.connectionId,
+            externalSourceId: selectedSource.id,
+            knowledgeSourceSync: { sourceEnabled: true, connectionPaused: false },
+          },
+        },
+      });
+      await syncCreatedScheduledTask({ db: deps.db, workflowClient: deps.workflowClient, task });
+    }
+    const triggerToken = `source-save-${input.connection.version}`;
+    await deps.workflowClient.triggerScheduledTask({
+      task,
+      agentRunUsageIdempotencyKey: `knowledge-source-sync:initial:${task.id}:${triggerToken}`,
+      triggerWorkflowId: manualScheduledTaskTriggerWorkflowId(task.id, triggerToken),
+      initiator: { kind: "subject", subjectId: input.subjectId },
+      triggerType: existingTask ? "repair" : "initial",
+    });
+  }
+
+  for (const task of connectionTasks) {
+    if (task.action.kind !== "knowledge_source_sync") continue;
+    const resolved = await getKnowledgeSourceForSyncAuthority(deps.db, {
+      accountId: input.accountId,
+      workspaceId: input.workspaceId,
+      sourceId: task.action.sourceId,
+      initiatingSubjectId: input.subjectId,
+    });
+    if (!resolved || enabledIds.has(resolved.source.externalSourceId)) continue;
+    if (
+      input.previouslySelectedSourceIds.has(resolved.source.externalSourceId) &&
+      resolved.source.lifecycleState === "active"
+    ) {
+      await recordKnowledgeLifecycleEvent(deps.db, {
+        accountId: input.accountId,
+        workspaceId: input.workspaceId,
+        targetKind: "source",
+        targetId: resolved.source.id,
+        eventType: "deleted",
+        expectedGeneration: resolved.source.lifecycleGeneration,
+        operationId: `google-drive-source-deselect:${resolved.source.id}:${input.connection.version}`,
+        reasonCode: "source_deselected",
+        actor,
+      });
+    }
+    const previous = await captureScheduledTaskRestoreState(deps.db, task);
+    const disabled = await updateScheduledTask(deps.db, input.workspaceId, task.id, {
+      metadata: {
+        ...task.metadata,
+        knowledgeSourceSync: {
+          ...knowledgeSourceScheduleControl(task),
+          sourceEnabled: false,
+        },
+      },
+    });
+    await syncUpdatedScheduledTask({
+      db: deps.db,
+      workflowClient: deps.workflowClient,
+      previous,
+      task: disabled,
+    });
+  }
+}
+
+export async function revokeKnowledgeSourceScheduleAuthorization(
+  deps: ApiRouteDeps,
+  input: { task: ScheduledTask; subjectId: string },
+): Promise<void> {
+  const { task } = input;
+  if (task.action.kind !== "knowledge_source_sync") return;
+  if (
+    task.action.initiatingSubjectId !== input.subjectId ||
+    task.action.connection.ownerSubjectId !== input.subjectId
+  ) {
+    throw new HTTPException(403, {
+      message: "knowledge source schedule requires the exact initiating subject",
+    });
+  }
+  if (task.metadata.connectorKind !== "google_drive") {
+    throw new HTTPException(409, {
+      message: "knowledge source schedule connector cannot be durably disabled",
+    });
+  }
+  const externalSourceId =
+    typeof task.metadata.externalSourceId === "string" ? task.metadata.externalSourceId.trim() : "";
+  if (!externalSourceId) {
+    throw new HTTPException(409, { message: "knowledge source schedule identity is incomplete" });
+  }
+  const connection = await getConnectionMetadata(
+    deps.db,
+    task.workspaceId,
+    task.action.connection.connectionId,
+    input.subjectId,
+  );
+  if (!connection) {
+    throw new HTTPException(409, {
+      message: "knowledge source connection is unavailable for durable disable",
+    });
+  }
+  const metadata = requireGoogleDriveConnection(connection, input.subjectId);
+  const sources =
+    metadata.selectedSources ?? (metadata.selectedSource ? [metadata.selectedSource] : []);
+  const selected = sources.find((source) => source.id === externalSourceId);
+  let revocationVersion = connection.version;
+  if (selected?.syncEnabled) {
+    const updated = await transitionConnectionState(deps.db, {
+      workspaceId: task.workspaceId,
+      connectionId: connection.id,
+      visibleToSubjectId: input.subjectId,
+      expectedVersion: connection.version,
+      metadata: GoogleDriveConnectionMetadata.parse({
+        ...metadata,
+        selectedSource: null,
+        selectedSources: sources.map((source) =>
+          source.id === externalSourceId
+            ? {
+                ...source,
+                syncEnabled: false,
+                configGeneration: source.configGeneration + 1,
+              }
+            : source,
+        ),
+      }),
+      updatedBySubjectId: input.subjectId,
+    });
+    if (!updated) {
+      throw new HTTPException(409, {
+        message: "knowledge source connection changed; retry schedule deletion",
+      });
+    }
+    revocationVersion = updated.version;
+  }
+  const resolved = await getKnowledgeSourceForSyncAuthority(deps.db, {
+    accountId: task.accountId,
+    workspaceId: task.workspaceId,
+    sourceId: task.action.sourceId,
+    initiatingSubjectId: input.subjectId,
   });
-  if (!updated) {
-    throw new HTTPException(409, { message: "Google Drive connection changed; try again" });
+  if (resolved?.source.lifecycleState === "active") {
+    await recordKnowledgeLifecycleEvent(deps.db, {
+      accountId: task.accountId,
+      workspaceId: task.workspaceId,
+      targetKind: "source",
+      targetId: resolved.source.id,
+      eventType: "deleted",
+      expectedGeneration: resolved.source.lifecycleGeneration,
+      operationId: `knowledge-schedule-delete:${task.id}:${revocationVersion}`,
+      reasonCode: "schedule_deleted",
+      actor: {
+        kind: "human",
+        subjectId: input.subjectId,
+        initiatingHumanSubjectId: input.subjectId,
+      },
+    });
   }
-  return updated;
+}
+
+function knowledgeSourceScheduleControl(task: ScheduledTask): {
+  sourceEnabled: boolean;
+  connectionPaused: boolean;
+} {
+  const value = task.metadata.knowledgeSourceSync;
+  if (!value || typeof value !== "object") {
+    return { sourceEnabled: true, connectionPaused: false };
+  }
+  const record = value as Record<string, unknown>;
+  return {
+    sourceEnabled: record.sourceEnabled !== false,
+    connectionPaused: record.connectionPaused === true,
+  };
+}
+
+function googleDriveSchedule(cadence: "manual" | "hourly" | "daily"): ScheduledTaskScheduleSpec {
+  if (cadence === "manual") return { type: "manual" };
+  if (cadence === "hourly") return { type: "interval", everySeconds: 3_600 };
+  return { type: "calendar", timeZone: "UTC", hour: 0, minute: 0 };
 }
 
 function googleDriveFileMetadataUrl(fileId: string): URL {
@@ -715,6 +1527,62 @@ function requireGoogleDriveConnection(connection: GoogleDriveConnectionRecord, s
   return parsed.data;
 }
 
+async function requireGoogleDriveApiConnection(
+  deps: ApiRouteDeps,
+  connection: GoogleDriveConnectionRecord,
+  subjectId: string,
+): Promise<GoogleDriveApiConnection> {
+  const legacy = GoogleDriveConnectionMetadata.safeParse(connection.metadata);
+  const integration = ApiIntegrationOAuthConnectionMetadata.safeParse(connection.metadata);
+  const genericProviderDomain = integrationDefinitionProviderDomain(
+    GOOGLE_DRIVE_INTEGRATION_DEFINITION,
+  );
+  const authority: GoogleDriveApiConnection | null =
+    connection.kind === "oauth2" &&
+    connection.subjectId === subjectId &&
+    connection.providerDomain === GOOGLE_DRIVE_PROVIDER_DOMAIN &&
+    legacy.success
+      ? { kind: "legacy", connection, metadata: legacy.data }
+      : connection.kind === "oauth2" &&
+          (connection.subjectId === null || connection.subjectId === subjectId) &&
+          connection.providerDomain === genericProviderDomain &&
+          integration.success &&
+          integration.data.credentialRole === API_INTEGRATION_OAUTH_CREDENTIAL_ROLE &&
+          integration.data.providerFamily === "google" &&
+          integration.data.authorizedDefinitionIds.includes(GOOGLE_DRIVE_INTEGRATION_DEFINITION.id)
+        ? { kind: "integration", connection, metadata: integration.data }
+        : null;
+  if (!authority) {
+    throw new HTTPException(422, { message: "Connection is not compatible with Google Drive" });
+  }
+  if (authority.kind === "legacy") {
+    await requireGoogleDriveSourceConnection(deps, connection, subjectId);
+    return authority;
+  }
+  if (connection.status === "revoked") {
+    throw new HTTPException(409, { message: "Google Drive is disconnected" });
+  }
+  if (connection.status !== "active") {
+    throw new HTTPException(401, { message: "Google Drive needs to be reconnected" });
+  }
+  if (!googleDriveScopesAllowCapability(connection.grantedScopes, "recursive_source_sync")) {
+    await transitionConnectionState(deps.db, {
+      workspaceId: connection.workspaceId,
+      connectionId: connection.id,
+      visibleToSubjectId: subjectId,
+      expectedVersion: connection.version,
+      status: "needs_reauth",
+      metadata: connection.metadata,
+      lastError: "google_drive_reconsent_required",
+      updatedBySubjectId: subjectId,
+    });
+    throw new HTTPException(401, {
+      message: "Google Drive needs permission re-consent for selected-source read access",
+    });
+  }
+  return authority;
+}
+
 function googleDriveLifecycle(
   state: GoogleDriveConnectionLifecycle["state"],
 ): GoogleDriveConnectionLifecycle {
@@ -744,11 +1612,21 @@ async function transitionGoogleDriveConnectionLifecycle(
   lastError: string | null,
 ) {
   const metadata = requireGoogleDriveConnection(connection, subjectId);
-  if (
+  const alreadyCurrent =
     connection.status === status &&
     metadata.lifecycle?.state === lifecycle.state &&
-    metadata.lifecycle.recoverable === lifecycle.recoverable
-  ) {
+    metadata.lifecycle.recoverable === lifecycle.recoverable;
+  if (lifecycle.state !== "active") {
+    await deauthorizeGoogleDriveConnectionSources(
+      deps,
+      connection,
+      subjectId,
+      `connection_${lifecycle.state}`,
+      connection.version + (alreadyCurrent ? 0 : 1),
+    );
+    await setGoogleDriveScheduleStatus(deps, connection.workspaceId, connection.id, "paused");
+  }
+  if (alreadyCurrent) {
     return connection;
   }
   return await transitionConnectionState(deps.db, {
@@ -821,21 +1699,31 @@ function readGoogleDriveOAuthState(
   if (iat === undefined || now < iat || now - iat > oauthStateTtlMs / 1000) {
     throw new HTTPException(400, { message: "invalid or expired Google Drive OAuth state" });
   }
+  const accountId = requiredString(payload.accountId, "state.accountId");
+  const workspaceId = requiredString(payload.workspaceId, "state.workspaceId");
+  const subjectId = requiredString(payload.subjectId, "state.subjectId");
+  const returnPath = requiredString(payload.returnPath, "state.returnPath");
+  if (returnPath !== GOOGLE_DRIVE_RETURN_PATH(workspaceId)) {
+    throw new HTTPException(400, { message: "invalid Google Drive OAuth return path" });
+  }
+  const connectionId = optionalString(payload.connectionId) ?? undefined;
+  const connectionVersion = numberValue(payload.connectionVersion);
+  if (
+    (connectionVersion !== undefined && !Number.isInteger(connectionVersion)) ||
+    Boolean(connectionId) !== Boolean(connectionVersion)
+  ) {
+    throw new HTTPException(400, { message: "invalid Google Drive reconnect state" });
+  }
   return {
-    accountId: requiredString(payload.accountId, "state.accountId"),
-    workspaceId: requiredString(payload.workspaceId, "state.workspaceId"),
-    subjectId: requiredString(payload.subjectId, "state.subjectId"),
-    returnPath: requiredString(payload.returnPath, "state.returnPath"),
+    accountId,
+    workspaceId,
+    subjectId,
+    returnPath,
     encryptedPkceVerifier: requiredString(
       payload.encryptedPkceVerifier,
       "state.encryptedPkceVerifier",
     ),
-    ...(optionalString(payload.connectionId)
-      ? { connectionId: optionalString(payload.connectionId)! }
-      : {}),
-    ...(numberValue(payload.connectionVersion) !== undefined
-      ? { connectionVersion: numberValue(payload.connectionVersion)! }
-      : {}),
+    ...(connectionId ? { connectionId, connectionVersion: connectionVersion! } : {}),
     nonce: requiredString(payload.nonce, "state.nonce"),
     iat,
   };
@@ -1052,11 +1940,15 @@ async function googleDriveApiRequest(
   if (!current) {
     throw new HTTPException(404, { message: "Google Drive connection not found" });
   }
-  await requireGoogleDriveSourceConnection(deps, current, input.subjectId);
+  const authority = await requireGoogleDriveApiConnection(deps, current, input.subjectId);
   const resolver = buildConnectionTokenResolver(deps.db, deps.settings, undefined, {
     ...(deps.googleDriveFetch ? { refreshTransport: { fetchImpl: deps.googleDriveFetch } } : {}),
-    transitionPermanentRefreshFailure: async (failure) =>
-      await transitionGoogleDrivePermanentRefreshFailure(deps, failure),
+    ...(authority.kind === "legacy"
+      ? {
+          transitionPermanentRefreshFailure: async (failure: PermanentConnectionRefreshFailure) =>
+            await transitionGoogleDrivePermanentRefreshFailure(deps, failure),
+        }
+      : {}),
   });
   const resolve = async (forceRefresh: boolean) =>
     await resolver({
@@ -1065,14 +1957,26 @@ async function googleDriveApiRequest(
       serverId: "google-drive-source-browser",
       toolName: input.label,
       connectionRef: {
-        providerDomain: GOOGLE_DRIVE_PROVIDER_DOMAIN,
+        providerDomain: current.providerDomain,
         connectionId: input.connectionId,
         kind: "oauth2",
-        subjectScope: "subject",
+        subjectScope: current.subjectId ? "subject" : "workspace",
       },
       destinationUrl: input.url.toString(),
       forceRefresh,
     });
+  const requireResolvedConnection = async (connectionVersion: number) => {
+    const resolved = await getConnectionMetadata(
+      deps.db,
+      input.workspaceId,
+      input.connectionId,
+      input.subjectId,
+    );
+    if (!resolved || resolved.version !== connectionVersion) {
+      throw new HTTPException(409, { message: "Google Drive connection changed; try again" });
+    }
+    await requireGoogleDriveSourceConnection(deps, resolved, input.subjectId);
+  };
   let credential = await resolve(false);
   if (credential.status !== "ok") {
     throw new HTTPException(401, { message: "Google Drive needs to be reconnected" });
@@ -1081,6 +1985,7 @@ async function googleDriveApiRequest(
   if (providerConnectionVersion === undefined) {
     throw new Error("Google Drive credential resolver omitted the connection version");
   }
+  await requireResolvedConnection(providerConnectionVersion);
   const fetchImpl = deps.googleDriveFetch ?? fetch;
   let response = await providerFetch(fetchImpl, input.url, {
     headers: { ...credential.headers, accept: "application/json" },
@@ -1095,6 +2000,7 @@ async function googleDriveApiRequest(
     if (providerConnectionVersion === undefined) {
       throw new Error("Google Drive credential resolver omitted the connection version");
     }
+    await requireResolvedConnection(providerConnectionVersion);
     response = await providerFetch(fetchImpl, input.url, {
       headers: { ...credential.headers, accept: "application/json" },
     });
@@ -1102,13 +2008,10 @@ async function googleDriveApiRequest(
   if (!response.ok) {
     if (response.status === 401) {
       await response.body?.cancel().catch(() => undefined);
-      await transitionGoogleDriveProviderResponseFailure(deps, {
-        workspaceId: input.workspaceId,
+      await transitionGoogleDriveApiFailure(deps, authority, {
         subjectId: input.subjectId,
-        connectionId: input.connectionId,
         connectionVersion: providerConnectionVersion,
         lifecycle: googleDriveLifecycle("reconnect_required"),
-        status: "needs_reauth",
         lastError: "google_drive_reconnect_required",
       });
       throw new HTTPException(401, { message: "Google Drive needs to be reconnected" });
@@ -1123,13 +2026,10 @@ async function googleDriveApiRequest(
       providerErrorCode &&
       GOOGLE_DRIVE_RECONSENT_ERROR_CODES.has(providerErrorCode)
     ) {
-      await transitionGoogleDriveProviderResponseFailure(deps, {
-        workspaceId: input.workspaceId,
+      await transitionGoogleDriveApiFailure(deps, authority, {
         subjectId: input.subjectId,
-        connectionId: input.connectionId,
         connectionVersion: providerConnectionVersion,
         lifecycle: googleDriveLifecycle("reconsent_required"),
-        status: "needs_reauth",
         lastError: "google_drive_reconsent_required",
       });
     }
@@ -1143,6 +2043,47 @@ async function googleDriveApiRequest(
   return await readResponseJsonBounded<unknown>(response, GOOGLE_RESPONSE_MAX_BYTES, input.label);
 }
 
+async function transitionGoogleDriveApiFailure(
+  deps: ApiRouteDeps,
+  authority: GoogleDriveApiConnection,
+  input: {
+    subjectId: string;
+    connectionVersion: number;
+    lifecycle: GoogleDriveConnectionLifecycle;
+    lastError: string;
+  },
+): Promise<void> {
+  if (authority.kind === "legacy") {
+    await transitionGoogleDriveProviderResponseFailure(deps, {
+      workspaceId: authority.connection.workspaceId,
+      subjectId: input.subjectId,
+      connectionId: authority.connection.id,
+      connectionVersion: input.connectionVersion,
+      lifecycle: input.lifecycle,
+      status: "needs_reauth",
+      lastError: input.lastError,
+    });
+    return;
+  }
+  const latest = await getConnectionMetadata(
+    deps.db,
+    authority.connection.workspaceId,
+    authority.connection.id,
+    input.subjectId,
+  );
+  if (!latest || latest.version !== input.connectionVersion) return;
+  await transitionConnectionState(deps.db, {
+    workspaceId: latest.workspaceId,
+    connectionId: latest.id,
+    visibleToSubjectId: input.subjectId,
+    expectedVersion: latest.version,
+    status: "needs_reauth",
+    metadata: latest.metadata,
+    lastError: input.lastError,
+    updatedBySubjectId: input.subjectId,
+  });
+}
+
 async function providerFetch(
   fetchImpl: FetchLike,
   url: string | URL,