@opengeni/db 5.0.1 → 6.0.0

package/src/capability-integrations.ts

@@ -1,6 +1,11 @@
 import { createHash } from "node:crypto";
 
-import { stableJson, type McpServerConnectionRef } from "@opengeni/contracts";
+import {
+  assertOrganizationIntegrationAllowed,
+  stableJson,
+  type IntegrationSource,
+  type McpServerConnectionRef,
+} from "@opengeni/contracts";
 import { and, asc, eq, inArray, ne, or, sql } from "drizzle-orm";
 
 import {
@@ -16,6 +21,7 @@ import {
   type Database,
 } from "./database";
 import { connectionScopeKey } from "./connection-scopes";
+import { withOrganizationIntegrationPolicyFence } from "./organization-integration-policy";
 import {
   ensureIntegrationFacetDefinition,
   integrationBindingKey,
@@ -184,7 +190,7 @@ export type ApiIntegrationRuntime = {
 };
 
 export type ApiIntegrationOwner = {
-  kind: "direct" | "plugin" | "pack" | "migration";
+  kind: "direct" | "plugin" | "migration";
   id: string;
   removable: boolean;
 };
@@ -227,6 +233,25 @@ export class ApiIntegrationInstallationVersionConflictError extends Error {
 export async function installApiIntegration(
   db: Database,
   input: InstallApiIntegrationInput,
+): Promise<InstalledApiIntegration> {
+  // Inputs here are server-resolved immutable previews, not deserialized client
+  // provenance. Custom documents never gain curated permission by their URL.
+  const snapshot = structuredClone(input);
+  const key =
+    snapshot.definitionProvenance === "curated"
+      ? snapshot.definitionId
+      : `custom:${snapshot.protocol}`;
+  return withOrganizationIntegrationPolicyFence(db, snapshot, (tx, policy) =>
+    installApiIntegrationInScope(tx, snapshot, () =>
+      assertOrganizationIntegrationAllowed(policy, key),
+    ),
+  );
+}
+
+async function installApiIntegrationInScope(
+  db: Database,
+  input: InstallApiIntegrationInput,
+  assertAcquisition: () => void,
 ): Promise<InstalledApiIntegration> {
   assertInstallInput(input);
   return await withRlsContext(
@@ -407,6 +432,12 @@ export async function installApiIntegration(
         const displayName =
           input.displayName?.trim() ||
           (instanceKey === "default" ? input.name : `${input.name} — connected account`);
+        // Capture immutable definition identity before any ensure helper can
+        // repair it. A repair/addition is acquisition, not unchanged replay.
+        const previousDefinitions = await tx
+          .select()
+          .from(schema.integrationFacetDefinitions)
+          .where(eq(schema.integrationFacetDefinitions.integrationFacetId, integrationFacet.id));
         const toolsFacet = await ensureIntegrationFacetDefinition(tx as unknown as Database, {
           integrationFacetId: integrationFacet.id,
           facetKey: "tools",
@@ -536,6 +567,116 @@ export async function installApiIntegration(
         const approvalRequiredTools = input.revision.tools
           .filter((tool) => selectedTools.includes(tool.id) && tool.approvalMode === "ask")
           .map((tool) => tool.id);
+        const nextConfig = {
+          baseServerId: input.serverId,
+          allowedTools: selectedTools,
+          requireApproval: approvalRequiredTools,
+          connectionKind: connection?.kind ?? null,
+          subjectScope: connection?.subjectId ? "subject" : connection ? "workspace" : "none",
+        };
+        // This is the same advisory -> row prefix used by the binding upsert.
+        // All preceding ensure writes are local to this transaction and roll
+        // back if admission below denies a new acquisition.
+        await tx.execute(
+          sql`select pg_advisory_xact_lock(hashtextextended(${`integration-binding:${input.workspaceId}:${runtimeServerId}`}, 0))`,
+        );
+        const [previousBinding] = await tx
+          .select()
+          .from(schema.integrationFacetBindings)
+          .where(
+            and(
+              eq(schema.integrationFacetBindings.workspaceId, input.workspaceId),
+              eq(schema.integrationFacetBindings.runtimeKey, runtimeServerId),
+            ),
+          )
+          .for("update")
+          .limit(1);
+        const bindingOwners = previousBinding
+          ? await listIntegrationFacetBindingOwners(tx as unknown as Database, previousBinding.id)
+          : [];
+        const componentOwners = await tx
+          .select()
+          .from(schema.capabilityComponentOwners)
+          .where(
+            inArray(schema.capabilityComponentOwners.facetInstallationId, [
+              integrationFacetInstallation.id,
+              apiFacetInstallation.id,
+            ]),
+          );
+        const [storedSpec] = await tx
+          .select()
+          .from(schema.integrationSpecRevisions)
+          .where(
+            and(
+              eq(schema.integrationSpecRevisions.apiFacetId, apiFacet.id),
+              eq(schema.integrationSpecRevisions.status, "active"),
+            ),
+          )
+          .limit(1);
+        const [storedAuthority] = await tx
+          .select()
+          .from(schema.capabilityIntegrationFacets)
+          .where(eq(schema.capabilityIntegrationFacets.facetId, integrationFacet.id))
+          .limit(1);
+        const [storedApi] = await tx
+          .select()
+          .from(schema.capabilityApiFacets)
+          .where(eq(schema.capabilityApiFacets.facetId, apiFacet.id))
+          .limit(1);
+        const sameOwner = (candidate: { kind: string; id: string; removable: boolean }) =>
+          candidate.kind === owner.kind &&
+          candidate.id === owner.id &&
+          candidate.removable === owner.removable;
+        const unchangedAuthority =
+          existingPluginInstallation?.status === "active" &&
+          existingPluginInstallation.pluginVersionId === pluginVersion.id &&
+          !integrationFacetInstallationResult.changed &&
+          !apiFacetInstallationResult.changed &&
+          previousBinding?.status === "active" &&
+          previousBinding.bindingKey === instanceKey &&
+          previousBinding.integrationFacetInstallationId === integrationFacetInstallation.id &&
+          previousBinding.facetDefinitionId === toolsFacet.id &&
+          previousBinding.connectionId === (input.connectionId ?? null) &&
+          isApiIntegrationPermissionReduction(previousBinding.config, nextConfig) &&
+          bindingOwners.some(sameOwner) &&
+          [integrationFacetInstallation.id, apiFacetInstallation.id].every((id) =>
+            componentOwners.some(
+              (candidate) =>
+                candidate.facetInstallationId === id &&
+                sameOwner({
+                  kind: candidate.ownerKind,
+                  id: candidate.ownerId,
+                  removable: candidate.removable,
+                }),
+            ),
+          ) &&
+          stableJson(storedSpec?.spec) === stableJson(input.revision) &&
+          storedApi?.protocol === input.protocol &&
+          storedApi.baseUrl === input.baseUrl &&
+          storedApi.specSourceUrl === (input.sourceUrl ?? null) &&
+          storedAuthority?.providerDomain === input.providerDomain &&
+          stableJson(storedApi?.authScheme) === stableJson(input.authScheme ?? {}) &&
+          stableJson(storedAuthority?.requiredScopes) ===
+            stableJson(normalizedStrings(input.requiredScopes ?? [], 256)) &&
+          storedAuthority?.ownership ===
+            (input.ownership ?? (connection?.subjectId ? "subject" : "workspace")) &&
+          previousDefinitions.some(
+            (definition) =>
+              definition.id === toolsFacet.id &&
+              definition.kind === toolsFacet.kind &&
+              stableJson(definition.configSchema) === stableJson(toolsFacet.configSchema) &&
+              stableJson(definition.capabilities) === stableJson(toolsFacet.capabilities),
+          ) &&
+          (input.facetDefinitions ?? []).every((definition) =>
+            previousDefinitions.some(
+              (old) =>
+                old.facetKey === definition.facetKey &&
+                old.kind === definition.kind &&
+                stableJson(old.configSchema) === stableJson(definition.configSchema) &&
+                stableJson(old.capabilities) === stableJson(definition.capabilities),
+            ),
+          );
+        if (!unchangedAuthority) assertAcquisition();
         const bindingResult = await upsertIntegrationFacetBinding(tx as unknown as Database, {
           accountId: input.accountId,
           workspaceId: input.workspaceId,
@@ -545,13 +686,7 @@ export async function installApiIntegration(
           displayName,
           runtimeKey: runtimeServerId,
           connectionId: input.connectionId ?? null,
-          config: {
-            baseServerId: input.serverId,
-            allowedTools: selectedTools,
-            requireApproval: approvalRequiredTools,
-            connectionKind: connection?.kind ?? null,
-            subjectScope: connection?.subjectId ? "subject" : connection ? "workspace" : "none",
-          },
+          config: nextConfig,
           createdBySubjectId: input.subjectId,
           owner,
           ...(input.expectedInstanceVersion !== undefined
@@ -812,12 +947,6 @@ export async function listInstalledApiIntegrationServerIdsForDelegations(
   return [...byServerId];
 }
 
-/**
- * Read installed API Integrations from a transaction that already carries the
- * workspace RLS context. This is intentionally separate from the public
- * wrapper so compound Plugin/Pack lifecycle transactions never open a nested
- * transaction or lose their advisory locks.
- */
 export async function listInstalledApiIntegrationsInRlsContext(
   scopedDb: Database,
   workspaceId: string,
@@ -1078,6 +1207,133 @@ export async function getApiIntegrationUninstallPreview(
   });
 }
 
+/** No discovery or new authority: recover only an exact, currently visible and
+ * directly owned installed source. The installer must still lock and recheck
+ * the snapshot before committing; this read is not installation admission.
+ */
+export async function getApiIntegrationReconciliationSnapshot(
+  db: Database,
+  input: {
+    accountId: string;
+    workspaceId: string;
+    subjectId: string;
+    source: IntegrationSource;
+    connectionId?: string;
+    instanceKey?: string;
+    expectedRevisionId: string;
+    expectedContentSha256: string;
+    allowedTools?: string[];
+  },
+): Promise<{
+  runtime: ApiIntegrationRuntime;
+  baseServerId: string;
+  name: string;
+  provider: string | null;
+  requiredScopes: string[];
+} | null> {
+  return withWorkspaceSubjectRls(db, input.workspaceId, input.subjectId, async (tx) => {
+    const instanceKey = integrationBindingKey(input.connectionId, input.instanceKey);
+    const candidates = (
+      await listInstalledApiIntegrationsInRlsContext(tx, input.workspaceId, input.subjectId)
+    ).filter((runtime) => {
+      if (
+        runtime.instanceKey !== instanceKey ||
+        (runtime.connectionRef?.connectionId ?? null) !== (input.connectionId ?? null) ||
+        runtime.revision.id !== input.expectedRevisionId ||
+        runtime.revision.contentSha256 !== input.expectedContentSha256 ||
+        !(input.allowedTools ?? runtime.revision.tools.map((tool) => tool.id)).every((tool) =>
+          runtime.allowedTools.includes(tool),
+        )
+      )
+        return false;
+      const source = input.source;
+      if (source.kind === "definition")
+        return (
+          runtime.definitionProvenance === "curated" && runtime.definitionId === source.definitionId
+        );
+      if (runtime.definitionProvenance !== "workspace") return false;
+      if (source.kind === "graphql")
+        return runtime.protocol === "graphql" && source.endpoint === runtime.sourceUrl;
+      return (
+        (source.kind === "auto" || runtime.protocol === "openapi") &&
+        source.url === runtime.sourceUrl &&
+        (source.baseUrl === undefined || source.baseUrl === runtime.baseUrl)
+      );
+    });
+    if (candidates.length !== 1) return null;
+    const runtime = candidates[0]!;
+    const owners = await listIntegrationFacetBindingOwners(tx, runtime.instanceId);
+    if (
+      !owners.some(
+        (owner) => owner.kind === "direct" && owner.id === runtime.capabilityId && owner.removable,
+      )
+    )
+      return null;
+    const [stored] = await tx
+      .select({
+        manifest: schema.capabilityPluginVersions.manifest,
+        name: schema.capabilityPlugins.name,
+        requiredScopes: schema.capabilityIntegrationFacets.requiredScopes,
+      })
+      .from(schema.capabilityPluginInstallations)
+      .innerJoin(
+        schema.capabilityPlugins,
+        eq(schema.capabilityPlugins.id, schema.capabilityPluginInstallations.pluginId),
+      )
+      .innerJoin(
+        schema.capabilityPluginVersions,
+        eq(
+          schema.capabilityPluginVersions.id,
+          schema.capabilityPluginInstallations.pluginVersionId,
+        ),
+      )
+      .innerJoin(
+        schema.integrationFacetBindings,
+        eq(schema.integrationFacetBindings.id, runtime.instanceId),
+      )
+      .innerJoin(
+        schema.integrationFacetDefinitions,
+        eq(
+          schema.integrationFacetDefinitions.id,
+          schema.integrationFacetBindings.facetDefinitionId,
+        ),
+      )
+      .innerJoin(
+        schema.capabilityIntegrationFacets,
+        eq(
+          schema.capabilityIntegrationFacets.facetId,
+          schema.integrationFacetDefinitions.integrationFacetId,
+        ),
+      )
+      .where(
+        and(
+          eq(schema.capabilityPluginInstallations.id, runtime.pluginInstallationId),
+          eq(schema.capabilityPluginInstallations.accountId, input.accountId),
+          eq(schema.capabilityPluginInstallations.workspaceId, input.workspaceId),
+          eq(schema.capabilityPluginInstallations.status, "active"),
+        ),
+      )
+      .limit(1);
+    const manifest = objectValue(stored?.manifest);
+    const baseServerId = stringValue(manifest.serverId);
+    if (
+      !stored ||
+      !baseServerId ||
+      manifest.revisionId !== runtime.revision.id ||
+      manifest.contentSha256 !== runtime.revision.contentSha256 ||
+      manifest.capabilityId !== runtime.capabilityId
+    )
+      return null;
+    return {
+      runtime,
+      baseServerId,
+      name: stored.name,
+      provider: stringValue(manifest.provider) ?? null,
+      requiredScopes: stored.requiredScopes,
+    };
+  });
+}
+
 export async function uninstallApiIntegration(
   db: Database,
   input: {
@@ -1631,12 +1887,7 @@ async function integrationOwners(
     );
   const owners = new Map<string, ApiIntegrationOwner>();
   for (const row of rows) {
-    if (
-      row.kind !== "direct" &&
-      row.kind !== "plugin" &&
-      row.kind !== "pack" &&
-      row.kind !== "migration"
-    ) {
+    if (row.kind !== "direct" && row.kind !== "plugin" && row.kind !== "migration") {
       throw new Error(`Unknown API Integration owner kind: ${row.kind}`);
     }
     const key = `${row.kind}\0${row.id}`;
@@ -1703,6 +1954,35 @@ function selectedToolIds(input: InstallApiIntegrationInput): string[] {
   return selected;
 }
 
+function isApiIntegrationPermissionReduction(
+  previous: Record<string, unknown>,
+  next: Record<string, unknown>,
+): boolean {
+  const {
+    allowedTools: previousTools,
+    requireApproval: previousApproval,
+    ...previousIdentity
+  } = previous;
+  const { allowedTools: nextTools, requireApproval: nextApproval, ...nextIdentity } = next;
+  const before = stringArray(previousTools);
+  const after = stringArray(nextTools);
+  const requiredBefore = stringArray(previousApproval);
+  const requiredAfter = stringArray(nextApproval);
+  return (
+    before !== undefined &&
+    after !== undefined &&
+    requiredAfter !== undefined &&
+    (previousApproval === true || requiredBefore !== undefined) &&
+    stableJson(previousIdentity) === stableJson(nextIdentity) &&
+    after.every(
+      (tool) =>
+        before.includes(tool) &&
+        (!(previousApproval === true || requiredBefore?.includes(tool)) ||
+          requiredAfter.includes(tool)),
+    )
+  );
+}
+
 function storedRevision(value: Record<string, unknown>): StoredApiIntegrationRevision {
   const protocol = value.protocol;
   const tools = value.tools;

package/src/capability-reconciliation.ts

@@ -0,0 +1,19 @@
+import { sql } from "drizzle-orm";
+import { withWorkspaceRls, type Database } from "./database";
+
+/** Retain the installation row through the caller's outer transaction. This is
+ * a no-write reconciliation read; it never activates or alters an installation.
+ * Acquisition callers must already hold the organization policy fence. */
+export async function withLockedCapabilityInstallation<T>(
+  db: Database,
+  workspaceId: string,
+  capabilityId: string,
+  read: (tx: Database) => Promise<T>,
+) {
+  return withWorkspaceRls(db, workspaceId, async (tx) => {
+    await tx.execute(sql`select id from capability_installations
+      where workspace_id = ${workspaceId}::uuid and capability_id = ${capabilityId}
+      for update`);
+    return read(tx);
+  });
+}

package/src/codex-capacity-recovery.ts

@@ -0,0 +1,47 @@
+/** Durable logical-turn state; checks and quota/account signals never spend this budget. */
+export const CODEX_CAPACITY_RECOVERY_KEY = "codexCapacityRecoveryV1";
+export const CODEX_CAPACITY_FALSE_RESUMPTION_LIMIT = 10;
+
+export type CodexCapacityRecovery = {
+  falseResumptions: number;
+  resumeGeneration: number | null;
+  retryNotBefore: string | null;
+};
+
+export function readCodexCapacityRecovery(
+  metadata: Record<string, unknown> | null | undefined,
+): CodexCapacityRecovery {
+  const value = metadata?.[CODEX_CAPACITY_RECOVERY_KEY];
+  if (value === undefined) {
+    return { falseResumptions: 0, resumeGeneration: null, retryNotBefore: null };
+  }
+  const state = value as CodexCapacityRecovery | null;
+  if (
+    !state ||
+    !Number.isSafeInteger(state.falseResumptions) ||
+    state.falseResumptions < 0 ||
+    state.falseResumptions > CODEX_CAPACITY_FALSE_RESUMPTION_LIMIT ||
+    (state.resumeGeneration !== null &&
+      (!Number.isSafeInteger(state.resumeGeneration) || state.resumeGeneration < 1)) ||
+    (state.retryNotBefore !== null &&
+      (typeof state.retryNotBefore !== "string" ||
+        !Number.isFinite(Date.parse(state.retryNotBefore))))
+  ) {
+    throw new Error("Invalid persisted Codex capacity recovery state");
+  }
+  return state;
+}
+
+/** Equal jitter, 30–60 seconds initially, capped at 15 minutes. Persist the chosen deadline. */
+export function codexFalseResumptionBackoffMs(count: number, random = Math.random()): number {
+  const cap = Math.min(60_000 * 2 ** Math.max(0, Math.min(count - 1, 4)), 900_000);
+  return Math.floor(cap * (0.5 + Math.max(0, Math.min(random, 1)) / 2));
+}
+
+export function clearCodexCapacityRecovery(
+  metadata: Record<string, unknown>,
+): Record<string, unknown> {
+  const next = { ...metadata };
+  delete next[CODEX_CAPACITY_RECOVERY_KEY];
+  return next;
+}

package/src/codex-failure-eligibility.ts

@@ -0,0 +1,93 @@
+/** Refusal-specific, ordered recovery evidence; never erase the failure ledger. */
+export function unresolvedCodexCredentialFailures(
+  metadata: Record<string, unknown> | null | undefined,
+  accounts: readonly {
+    id: string;
+    status: string;
+    exhaustedUntil: Date | null;
+    exhaustedKind: string | null;
+    exhaustedRevision?: number;
+    credentialVersion?: number;
+  }[],
+  now = new Date(),
+): string[] {
+  const failedIds = Array.isArray(metadata?.codexCredentialFailedIds)
+    ? metadata.codexCredentialFailedIds.filter(
+        (id): id is string => typeof id === "string" && id.length > 0,
+      )
+    : [];
+  const rawRevisions = metadata?.codexCredentialFailureCooldownRevisions;
+  const revisions =
+    rawRevisions && typeof rawRevisions === "object" && !Array.isArray(rawRevisions)
+      ? (rawRevisions as Record<string, unknown>)
+      : null;
+  const rawEvidence = metadata?.codexCredentialFailureEvidenceV1;
+  const evidence =
+    rawEvidence && typeof rawEvidence === "object" && !Array.isArray(rawEvidence)
+      ? (rawEvidence as Record<string, unknown>)
+      : null;
+  return [...new Set(failedIds)].filter((id) => {
+    const account = accounts.find((candidate) => candidate.id === id);
+    const revision = account?.exhaustedRevision;
+    const baseline = revisions?.[id];
+    const rawReceipt = evidence?.[id];
+    const receipt =
+      rawReceipt && typeof rawReceipt === "object" && !Array.isArray(rawReceipt)
+        ? (rawReceipt as Record<string, unknown>)
+        : null;
+    if (
+      rawReceipt !== undefined &&
+      (!receipt || !["quota", "rate_limit", "status"].includes(String(receipt.kind)))
+    )
+      return true;
+    // The earlier atomic quarantine writer used explicit null only for status
+    // refusals (it wrote needs_relogin/error in the same transaction). Seeing
+    // active again therefore proves a later repair. Missing ID-only evidence
+    // is different and remains excluded. New receipts additionally fence the
+    // repaired credential version below.
+    if (!receipt && baseline === null && account?.status === "active") return false;
+    if (account?.status === "active" && receipt?.kind === "status") {
+      return !(
+        typeof receipt.credentialVersion === "number" &&
+        Number.isSafeInteger(receipt.credentialVersion) &&
+        receipt.credentialVersion >= 1 &&
+        typeof account.credentialVersion === "number" &&
+        Number.isSafeInteger(account.credentialVersion) &&
+        account.credentialVersion > receipt.credentialVersion
+      );
+    }
+    if (
+      account?.status === "active" &&
+      ((receipt?.kind === "rate_limit" &&
+        typeof receipt.cooldownRevision === "number" &&
+        Number.isSafeInteger(receipt.cooldownRevision) &&
+        receipt.cooldownRevision >= 1 &&
+        typeof revision === "number" &&
+        revision >= receipt.cooldownRevision) ||
+        (!receipt &&
+          typeof baseline === "number" &&
+          Number.isSafeInteger(baseline) &&
+          baseline >= 1 &&
+          revision === baseline)) &&
+      typeof revision === "number" &&
+      Number.isSafeInteger(revision) &&
+      account.exhaustedKind === "rate_limit" &&
+      account.exhaustedUntil !== null &&
+      account.exhaustedUntil.getTime() <= now.getTime()
+    ) {
+      return false;
+    }
+    // Quota recovery needs an ordered explicit clear, including older numeric receipts.
+    return !(
+      account?.status === "active" &&
+      account.exhaustedUntil === null &&
+      account.exhaustedKind === null &&
+      typeof baseline === "number" &&
+      Number.isSafeInteger(baseline) &&
+      baseline >= 1 &&
+      typeof revision === "number" &&
+      Number.isSafeInteger(revision) &&
+      revision > baseline
+    );
+  });
+}

package/src/connect-attempts.ts

@@ -98,6 +98,45 @@ function validateOperation(id: string, digest: string): void {
 
 /** Caller must establish live workspace/actor authority before this storage
  * seam. RLS scope is a consistency boundary, not proof of authentication. */
+type ConnectBeginIdentity = {
+  idempotencyKey: string;
+  requestDigest: string;
+  returnUrl: string;
+  externalContinuation?: ExternalActorContinuation;
+};
+
+/** Recover only an exact saved begin request, under the caller's live actor
+ * admission. This performs no provider work or acquisition. */
+export async function getConnectBeginReplay(
+  db: Database,
+  scope: ConnectActorScope,
+  input: ConnectBeginIdentity,
+): Promise<Attempt | null> {
+  validateOperation(input.idempotencyKey, input.requestDigest);
+  const origin = input.externalContinuation
+    ? ExternalActorContinuation.parse(input.externalContinuation)
+    : null;
+  const key = createHash("sha256").update(input.idempotencyKey).digest("hex");
+  return scoped(db, scope, async (tx) => {
+    const [existing] = await rawRows<Row>(
+      tx,
+      sql`select * from connect_attempts
+      where workspace_id = ${scope.workspaceId}::uuid and subject_id = ${scope.subjectId}
+        and idempotency_key_hash = ${key} and account_id = ${scope.accountId}::uuid`,
+    );
+    if (!existing) return null;
+    if (
+      existing.request_digest !== input.requestDigest ||
+      existing.return_url !== input.returnUrl ||
+      stableJson(existing.external_continuation ?? null) !== stableJson(origin)
+    )
+      throw new ConnectAttemptConflictError(
+        "Connect idempotency key was reused with different input",
+      );
+    return projection(existing, scope);
+  });
+}
+
 export async function beginConnectAttempt(
   db: Database,
   scope: ConnectActorScope,
@@ -107,6 +146,7 @@ export async function beginConnectAttempt(
     returnUrl: string;
     attempt: Attempt;
     externalContinuation?: ExternalActorContinuation;
+    authorizeAcquisition?: (tx: Database) => Promise<void>;
   },
 ): Promise<Attempt> {
   const value = ConnectAttempt.parse(input.attempt);
@@ -128,24 +168,9 @@ export async function beginConnectAttempt(
         and expires_at < now() - interval '30 days'
       order by expires_at, id limit 100 for update skip locked
     ) delete from connect_attempts where id in (select id from expired)`);
-    const [existing] = await rawRows<Row>(
-      tx,
-      sql`select * from connect_attempts
-      where workspace_id = ${scope.workspaceId}::uuid and subject_id = ${scope.subjectId}
-        and idempotency_key_hash = ${key} and account_id = ${scope.accountId}::uuid`,
-    );
-    if (existing) {
-      if (
-        existing.request_digest !== input.requestDigest ||
-        existing.return_url !== input.returnUrl ||
-        stableJson(existing.external_continuation ?? null) !== stableJson(origin)
-      ) {
-        throw new ConnectAttemptConflictError(
-          "Connect idempotency key was reused with different input",
-        );
-      }
-      return projection(existing, scope);
-    }
+    const existing = await getConnectBeginReplay(tx, scope, input);
+    if (existing) return existing;
+    await input.authorizeAcquisition?.(tx);
     const [count] = await rawRows<{ count: number }>(
       tx,
       sql`select count(*)::int as count from connect_attempts
@@ -227,6 +252,8 @@ export async function claimConnectOperation(
     operationId: string;
     inputDigest: string;
     authorize?: ConnectOperationAuthorization;
+    /** Additional acquisition admission, only after exact no-effect receipt replay. */
+    authorizeAcquisition?: (tx: Database, attempt: Attempt) => Promise<void>;
   },
 ): Promise<{ status: "claimed"; attempt: Attempt } | { status: "replayed"; attempt: Attempt }> {
   validateOperation(input.operationId, input.inputDigest);
@@ -242,6 +269,7 @@ export async function claimConnectOperation(
     if (receipt) {
       return { status: "replayed", attempt: receipt };
     }
+    await input.authorizeAcquisition?.(tx, structuredClone(current));
     if (row.operation_id)
       throw new ConnectAttemptConflictError(
         "Connect operation is in flight or uncertain; reconcile before retrying",
@@ -272,6 +300,8 @@ export async function finishConnectOperation(
     inputDigest: string;
     commit: (tx: Database, current: Attempt) => Promise<Attempt>;
     authorize?: ConnectOperationAuthorization;
+    /** Additional acquisition admission, only after exact no-effect receipt replay. */
+    authorizeAcquisition?: (tx: Database, attempt: Attempt) => Promise<void>;
   },
 ): Promise<Attempt> {
   validateOperation(input.operationId, input.inputDigest);
@@ -287,6 +317,7 @@ export async function finishConnectOperation(
     if (receipt) {
       return receipt;
     }
+    await input.authorizeAcquisition?.(tx, structuredClone(current));
     if (row.operation_id !== input.operationId || row.operation_digest !== input.inputDigest)
       throw new ConnectAttemptConflictError();
     const next = ConnectAttempt.parse(await input.commit(tx, structuredClone(current)));