@opengeni/db 5.0.1 → 6.0.0

package/src/insights-model-bundle.ts

@@ -540,20 +540,32 @@ export async function readWorkspaceInsightsModelBundle(
         from current_visible fact
       ), contribution_source_rows as (
         select
-          fact.id,
-          contribution->>'source' as source,
-          (contribution->>'items')::bigint as items,
-          (contribution->>'utf8Bytes')::bigint as utf8_bytes,
-          (contribution->>'estimatedTokens')::bigint as estimated_tokens
+          contribution.entry->>'source' as source,
+          (contribution.entry->>'items')::bigint as items,
+          (contribution.entry->>'utf8Bytes')::bigint as utf8_bytes,
+          (contribution.entry->>'estimatedTokens')::bigint as estimated_tokens,
+          -- The validated CHECK rejects duplicate named sources. Its SQL NULL
+          -- semantics still permit repeated null sources; count those only once
+          -- per fact without sorting all contribution rows by raw fact ID.
+          case when contribution.entry->>'source' is not null then true
+            else not exists (
+              select 1
+              from jsonb_array_elements(fact.context_contributions)
+                with ordinality earlier(entry, ordinal)
+              where earlier.ordinal < contribution.ordinal
+                and earlier.entry->>'source' is null
+            )
+          end as first_source
         from current_visible fact
-        cross join lateral jsonb_array_elements(fact.context_contributions) contribution
+        cross join lateral jsonb_array_elements(fact.context_contributions)
+          with ordinality contribution(entry, ordinal)
       ), contribution_rows as (
         select
           source,
           sum(items)::bigint as items,
           sum(utf8_bytes)::bigint as utf8_bytes,
           sum(estimated_tokens)::bigint as estimated_tokens,
-          count(distinct id)::bigint as calls
+          count(*) filter (where first_source)::bigint as calls
         from contribution_source_rows
         group by source
       )

package/src/insights-usage-bundle.ts

@@ -86,6 +86,9 @@ function stringValue(row: JsonRecord, key: string): string {
  * One read for the three existing usage windows. The event-type arrays are
  * deliberately closed so the authority function can keep selective predicates
  * inside its scan while all rollup math remains outside the billing path.
+ * Only the reused current window needs a second materialization: aggregate the
+ * single-use prior/month SRFs directly, since their volatile calls prevent CTE
+ * inlining even without an explicit MATERIALIZED keyword.
  */
 export async function readWorkspaceInsightsUsageBundle(
   db: Database,
@@ -103,28 +106,12 @@ export async function readWorkspaceInsightsUsageBundle(
       with current_visible as materialized (
         select usage_row.event_type, usage_row.quantity, usage_row.occurred_at,
           usage_row.source_resource_id
-        from opengeni_private.visible_workspace_insights_usage_events(
+        from opengeni_private.visible_workspace_insights_usage_projection(
           ${input.workspaceId},
           ${input.since.toISOString()}::timestamp with time zone,
           ${input.until.toISOString()}::timestamp with time zone,
           array['model.cost', 'sandbox.warm_seconds']::text[]
         ) usage_row
-      ), prior_visible as materialized (
-        select usage_row.event_type, usage_row.quantity
-        from opengeni_private.visible_workspace_insights_usage_events(
-          ${input.workspaceId},
-          ${input.priorSince.toISOString()}::timestamp with time zone,
-          ${input.priorUntil.toISOString()}::timestamp with time zone,
-          array['model.cost', 'sandbox.warm_seconds']::text[]
-        ) usage_row
-      ), month_visible as materialized (
-        select usage_row.event_type, usage_row.quantity, usage_row.occurred_at
-        from opengeni_private.visible_workspace_insights_usage_events(
-          ${input.workspaceId},
-          ${input.monthSince.toISOString()}::timestamp with time zone,
-          'infinity'::timestamp with time zone,
-          array['model.tokens', 'agent_run.created']::text[]
-        ) usage_row
       ), current_totals as (
         select
           coalesce(sum(usage_row.quantity) filter (
@@ -142,7 +129,12 @@ export async function readWorkspaceInsightsUsageBundle(
           coalesce(sum(usage_row.quantity) filter (
             where usage_row.event_type = 'sandbox.warm_seconds'
           ), 0) as prior_warm_seconds
-        from prior_visible usage_row
+        from opengeni_private.visible_workspace_insights_usage_projection(
+          ${input.workspaceId},
+          ${input.priorSince.toISOString()}::timestamp with time zone,
+          ${input.priorUntil.toISOString()}::timestamp with time zone,
+          array['model.cost', 'sandbox.warm_seconds']::text[]
+        ) usage_row
       ), month_totals as (
         select
           coalesce(sum(usage_row.quantity) filter (
@@ -153,7 +145,12 @@ export async function readWorkspaceInsightsUsageBundle(
             where usage_row.event_type = 'agent_run.created'
               and usage_row.occurred_at > ${input.monthSince.toISOString()}::timestamp with time zone
           ), 0) as agent_runs_used
-        from month_visible usage_row
+        from opengeni_private.visible_workspace_insights_usage_projection(
+          ${input.workspaceId},
+          ${input.monthSince.toISOString()}::timestamp with time zone,
+          'infinity'::timestamp with time zone,
+          array['model.tokens', 'agent_run.created']::text[]
+        ) usage_row
       ), bucket_rows as (
         select
           ${bucket} as bucket,

package/src/integration-bindings.ts

@@ -8,7 +8,7 @@ import { effectiveCapabilityOwnerSql } from "./capability-components";
 import * as schema from "./schema";
 
 export type IntegrationFacetBindingOwner = {
-  kind: "direct" | "plugin" | "pack" | "migration";
+  kind: "direct" | "plugin" | "migration";
   id: string;
   removable: boolean;
 };
@@ -358,12 +358,7 @@ async function loadIntegrationFacetBindingOwnersForBindings(
       asc(schema.integrationFacetBindingOwners.ownerId),
     );
   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 Integration instance owner kind: ${row.kind}`);
     }
     ownersByBindingId

package/src/integration-facets.ts

@@ -78,7 +78,7 @@ export type IntegrationFacetRemovalResult = {
   status: "not_configured" | "removed" | "retained_by_other_owners";
   binding: IntegrationFacetBindingSummary | null;
   remainingOwners: {
-    kind: "direct" | "plugin" | "pack" | "migration";
+    kind: "direct" | "plugin" | "migration";
     id: string;
     removable: boolean;
   }[];
@@ -172,8 +172,20 @@ type IntegrationInstanceContext = {
   integrationFacetId: string;
   providerDomain: string;
   connectionId: string | null;
+  apiProtocol: string | null;
+  definitionId: string | null;
+  definitionProvenance: string | null;
 };
 
+/** Trusted server callback, never part of a serialized mutation request. The
+ * caller must acquire its policy fence before invoking the facet operation.
+ * IDs/domains in this context identify installed records, not curated provenance.
+ */
+export type IntegrationFacetAcquisitionAuthorizer = (
+  tx: Database,
+  context: Readonly<IntegrationInstanceContext>,
+) => Promise<void>;
+
 export async function listIntegrationInstanceFacets(
   db: Database,
   workspaceId: string,
@@ -290,6 +302,7 @@ export async function configureIntegrationFacet(
     config: Record<string, unknown>;
     expectedVersion?: number;
     idempotencyKey: string;
+    beforeAcquire?: IntegrationFacetAcquisitionAuthorizer;
   },
 ): Promise<IntegrationFacetMutationResult> {
   const requestDigest = integrationFacetConfigureRequestDigest(input);
@@ -298,6 +311,26 @@ export async function configureIntegrationFacet(
     const definition = await requireFacetDefinition(tx, context, input.facetKey);
     assertFacetConfig(input.config, definition.configSchema);
     await requireFacetConnection(tx, input, context, definition.capabilities);
+    if (input.beforeAcquire) {
+      // Match upsertIntegrationFacetBinding's advisory -> row prefix before
+      // deciding whether this request adds authority. The upsert reuses both
+      // transaction locks, including the absent-row insertion fence.
+      await tx.execute(
+        sql`select pg_advisory_xact_lock(hashtextextended(${`integration-binding:${input.workspaceId}:${definition.id}:${input.instanceKey}`}, 0))`,
+      );
+      const existing = await loadFacetBinding(tx, context, input.instanceKey, definition.id, true);
+      const owner = facetOwner(input.capabilityId, input.instanceKey, input.facetKey);
+      const owners = existing ? await listIntegrationFacetBindingOwners(tx, existing.id) : [];
+      if (
+        !existing ||
+        existing.status !== "active" ||
+        existing.connectionId !== context.connectionId ||
+        stableJson(existing.config) !== stableJson(input.config) ||
+        !owners.some((current) => current.kind === owner.kind && current.id === owner.id)
+      ) {
+        await input.beforeAcquire(tx, context);
+      }
+    }
     const result = await upsertIntegrationFacetBinding(tx, {
       accountId: input.accountId,
       workspaceId: input.workspaceId,
@@ -343,6 +376,7 @@ export async function setIntegrationFacetLifecycle(
     action: "pause" | "resume";
     expectedVersion: number;
     idempotencyKey: string;
+    beforeAcquire?: IntegrationFacetAcquisitionAuthorizer;
   },
 ): Promise<IntegrationFacetMutationResult> {
   const requestDigest = sha256(
@@ -352,6 +386,7 @@ export async function setIntegrationFacetLifecycle(
       workspaceId: undefined,
       subjectId: undefined,
       idempotencyKey: undefined,
+      beforeAcquire: undefined,
     }),
   );
   return await withFacetOperation(db, input, requestDigest, "update", async (tx) => {
@@ -370,6 +405,9 @@ export async function setIntegrationFacetLifecycle(
     }
     await assertDirectFacetOwnership(tx, binding.id, input);
     const targetStatus = input.action === "pause" ? "paused" : "active";
+    if (input.action === "resume" && binding.status !== "active") {
+      await input.beforeAcquire?.(tx, context);
+    }
     let row = binding;
     if (binding.status !== targetStatus) {
       const [updated] = await tx
@@ -653,10 +691,7 @@ function capabilityComponentOwners(value: unknown): IntegrationFacetBindingOwner
     const owner = recordValue(entry);
     if (
       !owner ||
-      (owner.kind !== "direct" &&
-        owner.kind !== "plugin" &&
-        owner.kind !== "pack" &&
-        owner.kind !== "migration") ||
+      (owner.kind !== "direct" && owner.kind !== "plugin" && owner.kind !== "migration") ||
       typeof owner.id !== "string" ||
       typeof owner.removable !== "boolean"
     ) {
@@ -709,6 +744,13 @@ async function loadIntegrationInstanceContext(
       integrationFacetId: schema.integrationFacetDefinitions.integrationFacetId,
       providerDomain: schema.capabilityIntegrationFacets.providerDomain,
       connectionId: schema.integrationFacetBindings.connectionId,
+      apiProtocol: schema.capabilityApiFacets.protocol,
+      definitionId: sql<
+        string | null
+      >`${schema.capabilityPluginVersions.manifest} ->> 'definitionId'`,
+      definitionProvenance: sql<
+        string | null
+      >`${schema.capabilityPluginVersions.manifest} ->> 'definitionProvenance'`,
     })
     .from(schema.integrationFacetBindings)
     .innerJoin(
@@ -740,6 +782,21 @@ async function loadIntegrationInstanceContext(
       schema.capabilityPluginVersions,
       eq(schema.capabilityPluginVersions.id, schema.capabilityPluginInstallations.pluginVersionId),
     )
+    .leftJoin(
+      schema.capabilityApiFacets,
+      and(
+        eq(
+          schema.capabilityApiFacets.integrationFacetId,
+          schema.capabilityIntegrationFacets.facetId,
+        ),
+        sql`exists (
+          select 1 from ${schema.capabilityFacetInstallations} api_installation
+          where api_installation.plugin_installation_id = ${schema.capabilityPluginInstallations.id}
+            and api_installation.facet_id = ${schema.capabilityApiFacets.facetId}
+            and api_installation.status = 'active'
+        )`,
+      ),
+    )
     .where(
       and(
         eq(schema.integrationFacetBindings.workspaceId, workspaceId),
@@ -759,7 +816,17 @@ async function loadIntegrationInstanceContext(
       ),
     )
     .limit(2);
-  if (lock) query = query.for("update") as typeof query;
+  if (lock)
+    query = query.for("update", {
+      of: [
+        schema.integrationFacetBindings,
+        schema.integrationFacetDefinitions,
+        schema.capabilityIntegrationFacets,
+        schema.capabilityFacetInstallations,
+        schema.capabilityPluginInstallations,
+        schema.capabilityPluginVersions,
+      ],
+    }) as typeof query;
   const rows = await query;
   if (rows.length === 0) return null;
   if (rows.length !== 1) throw new Error(`API Integration ${capabilityId} instance is ambiguous`);

package/src/knowledge-entries.ts

@@ -644,12 +644,19 @@ export async function inspectKnowledgeFilePreparation(
 export async function completeKnowledgeFilePreparation(
   db: Database,
   context: KnowledgeContext,
-  input: { fileId: string; title: string; content: string; sourceVersion?: string },
+  input: {
+    fileId: string;
+    title: string;
+    content: string;
+    sourceVersion?: string;
+    purpose?: "evidence" | "reference";
+  },
 ) {
   return KnowledgeFilePreparationResult.parse(
     await knowledgeFilePreparationOperation(db, context, {
       operation: "complete",
       fileId: z.uuid().parse(input.fileId),
+      purpose: z.enum(["evidence", "reference"]).parse(input.purpose ?? "evidence"),
       ...(input.sourceVersion
         ? {
             sourceVersion: z

package/src/live-session-attempt.ts

@@ -2,7 +2,6 @@ import { and, eq, inArray, sql } from "drizzle-orm";
 import { withWorkspaceRls, type Database } from "./database";
 import * as schema from "./schema";
 import { getExternalLinkTurnAuthorization } from "./external-link-work";
-import { initiatorFromStorage } from "./turn-initiator";
 
 /** Shared physical-attempt fence. Does not mutate goal/execution snapshots. */
 export async function getLiveSessionAttemptTurn(
@@ -62,24 +61,3 @@ export async function getLiveSessionAttemptTurn(
     return row.turn;
   });
 }
-
-/** Host credential reads need provenance and live authority, not a runnable
- * execution projection or a write to the turn's frozen goal snapshot. */
-export async function getHostMcpLiveAttempt(
-  db: Database,
-  workspaceId: string,
-  sessionId: string,
-  attemptId: string,
-) {
-  const row = await getLiveSessionAttemptTurn(db, workspaceId, sessionId, attemptId);
-  if (!row) return null;
-  return {
-    ...row,
-    initiator: initiatorFromStorage(
-      row.initiatorKind,
-      row.initiatorSubjectId,
-      row.initiatorContext ?? {},
-    ),
-    initiatorContext: row.initiatorContext ?? {},
-  };
-}

package/src/mcp-account-bindings.ts

@@ -0,0 +1,12 @@
+import {
+  McpConnectionAccountBindings,
+  type McpConnectionAccountBinding,
+} from "@opengeni/contracts";
+
+/** NULL is a pre-account-routing receipt, not an empty accepted selection.
+ * Never default it to [] (or default [] to NULL) during replay/inheritance. */
+export function parseAcceptedMcpAccountBindings(
+  value: unknown,
+): McpConnectionAccountBinding[] | null {
+  return value == null ? null : McpConnectionAccountBindings.parse(value);
+}

package/src/mcp-oauth.ts

@@ -177,6 +177,32 @@ export async function deleteMcpOAuthAuthorizationRequest(
   );
 }
 
+export async function rebindMcpOAuthAuthorizationRequest(
+  db: Database,
+  input: {
+    requestHash: string;
+    subjectId: string;
+    accountId: string;
+    workspaceId: string;
+    permissions: AccessGrant["permissions"];
+    toolIdentities: Array<{ serverId: string; toolName: string }>;
+  },
+): Promise<boolean> {
+  const [row] = await rawRows<{ request_hash: string }>(
+    db,
+    sql`update mcp_oauth_authorization_requests
+      set account_id = ${input.accountId},
+          workspace_id = ${input.workspaceId},
+          permissions = ${JSON.stringify(input.permissions)}::jsonb,
+          tool_identities = ${JSON.stringify(input.toolIdentities)}::jsonb
+      where request_hash = ${input.requestHash}
+        and subject_id = ${input.subjectId}
+        and expires_at > clock_timestamp()
+      returning request_hash`,
+  );
+  return Boolean(row);
+}
+
 export async function consumeMcpOAuthAuthorizationRequest(
   db: Database,
   input: {

package/src/organization-integration-policy.ts

@@ -0,0 +1,235 @@
+import {
+  OrganizationIntegrationPolicy,
+  UpdateOrganizationIntegrationPolicyRequest,
+  assertOrganizationIntegrationAllowed,
+} from "@opengeni/contracts";
+import { sql } from "drizzle-orm";
+import { z } from "zod";
+import {
+  rawRows,
+  rlsContextForWorkspace,
+  setSubjectRlsContext,
+  withRlsContext,
+  type Database,
+} from "./database";
+
+export type OrganizationIntegrationPolicyScope = { accountId: string };
+export type OrganizationIntegrationAcquisitionScope = { accountId: string; workspaceId: string };
+const policyScope = z.object({
+  accountId: z
+    .string()
+    .uuid()
+    .transform((value) => value.toLowerCase()),
+});
+const acquisitionScope = policyScope.extend({
+  workspaceId: z
+    .string()
+    .uuid()
+    .transform((value) => value.toLowerCase()),
+});
+/** Trusted application adapter MUST verify canonical human/local organization-admin
+ * provenance or accountScopedApiKeyWorkspaceAuthority (exact account + workspace:admin).
+ * This callback is a server dependency, never deserialized request data. The returned
+ * subject alone is NOT authentication. DB checks below are live authority fences only.
+ */
+export type AuthorizeOrganizationIntegrationPolicyAdministration = () => Promise<{
+  accountId: string;
+  subjectId: string;
+}>;
+
+async function requireReadCommitted(tx: Database): Promise<void> {
+  const [isolation] = await rawRows<{ level: string }>(
+    tx,
+    sql`select current_setting('transaction_isolation') as level`,
+  );
+  if (isolation?.level !== "read committed") {
+    throw new Error("Organization integration policy requires read committed isolation");
+  }
+}
+
+async function read(
+  tx: Database,
+  scope: OrganizationIntegrationPolicyScope,
+): Promise<OrganizationIntegrationPolicy> {
+  const [row] = await rawRows<{ policy: unknown }>(
+    tx,
+    sql`select jsonb_build_object('mode', mode, 'allowedIntegrationKeys', allowed_integration_keys, 'revision', revision) as policy from organization_integration_policies where account_id = ${scope.accountId}::uuid`,
+  );
+  return OrganizationIntegrationPolicy.parse(row?.policy ?? {});
+}
+
+/** Own only the subject setting this policy operation changes. The enclosing
+ * withRlsContext transaction/savepoint restores all settings on failure; on
+ * success it restores account/workspace only, so restore our subject explicitly.
+ * Do not run restoration after a failed SQL statement in an aborted transaction.
+ */
+async function withAdministratorSubject<T>(
+  tx: Database,
+  subjectId: string,
+  use: () => Promise<T>,
+): Promise<T> {
+  const [previous] = await rawRows<{ subject: string | null }>(
+    tx,
+    sql`select current_setting('opengeni.subject_id', true) as subject`,
+  );
+  await setSubjectRlsContext(tx, subjectId);
+  const result = await use();
+  const expected = previous?.subject ?? "";
+  const [restored] = await rawRows<{ subject: string }>(
+    tx,
+    sql`select set_config('opengeni.subject_id', ${expected}, true) as subject`,
+  );
+  if (restored?.subject !== expected)
+    throw new Error("Integration policy subject scope was not restored");
+  return result;
+}
+
+export async function getOrganizationIntegrationPolicy(
+  db: Database,
+  inputScope: OrganizationIntegrationPolicyScope,
+  authorize: AuthorizeOrganizationIntegrationPolicyAdministration,
+): Promise<OrganizationIntegrationPolicy> {
+  const scope = policyScope.parse(inputScope);
+  const actor = await authorize();
+  if (actor.accountId.toLowerCase() !== scope.accountId || !actor.subjectId)
+    throw new Error("Canonical organization administrator required");
+  return withRlsContext(
+    db,
+    { ...scope, workspaceId: null },
+    async (tx) => {
+      await requireReadCommitted(tx);
+      return withAdministratorSubject(tx, actor.subjectId, async () => {
+        // Live authority only: no policy or organization advisory lock on reads.
+        await tx.execute(
+          sql`select opengeni_private.assert_organization_integration_policy_administrator(${scope.accountId}::uuid, ${actor.subjectId})`,
+        );
+        return read(tx, scope);
+      });
+    },
+    undefined,
+    "none",
+  );
+}
+
+/** Call before acquiring membership/workspace/credential locks in any enclosing
+ * transaction. The SQL operation owns policy-exclusive -> membership -> admin
+ * row order; it never locks a workspace and rejects acquisition-lock upgrades.
+ */
+export async function updateOrganizationIntegrationPolicy(
+  db: Database,
+  inputScope: OrganizationIntegrationPolicyScope,
+  input: UpdateOrganizationIntegrationPolicyRequest,
+  authorize: AuthorizeOrganizationIntegrationPolicyAdministration,
+): Promise<OrganizationIntegrationPolicy> {
+  const scope = policyScope.parse(inputScope);
+  const request = UpdateOrganizationIntegrationPolicyRequest.parse(input);
+  const actor = await authorize();
+  if (actor.accountId.toLowerCase() !== scope.accountId || !actor.subjectId)
+    throw new Error("Canonical organization administrator required");
+  return withRlsContext(
+    db,
+    { ...scope, workspaceId: null },
+    async (tx) => {
+      await requireReadCommitted(tx);
+      return withAdministratorSubject(tx, actor.subjectId, async () => {
+        const [row] = await rawRows<{ result: unknown }>(
+          tx,
+          sql`select opengeni_private.update_organization_integration_policy(${scope.accountId}::uuid, ${actor.subjectId}, ${JSON.stringify(request)}::jsonb) as result`,
+        );
+        return OrganizationIntegrationPolicy.parse(row?.result);
+      });
+    },
+    undefined,
+    "none",
+  );
+}
+
+/** Internal serialization primitive, NOT acquisition authorization. Authenticate
+ * the caller normally. A callback may first return an exact completed receipt;
+ * before any new claim, uncommitted progress, or commit it MUST assert the trusted
+ * integration classification against the supplied runtime-frozen policy snapshot.
+ * Do not put network operations or retries inside this transaction.
+ *
+ * Requires read committed isolation. The shared policy fence precedes EVERY
+ * organization-membership, workspace/tenancy, and credential lock. In particular,
+ * persistProviderOAuthConnection may take the membership fence inside acquire.
+ * Policy writers take exclusive policy -> membership -> live administrator rows,
+ * and never workspace rows. Ordinary connection lifecycle writers do not take
+ * the policy fence. A caller passing an existing transaction must honor this
+ * prefix. Never administer policy inside or after an acquisition in that transaction:
+ * the SQL writer rejects shared-to-exclusive upgrades rather than risking deadlock.
+ * All final persistence must use tx, never a separate connection. No automatic
+ * retries: external effects cannot be rolled back. For slow external preparation,
+ * preflight separately and use this guard for final persistence. Existing execution,
+ * refresh, credential lifecycle, and cleanup do not belong behind this guard.
+ */
+export async function withOrganizationIntegrationPolicyFence<T>(
+  db: Database,
+  inputScope: OrganizationIntegrationAcquisitionScope,
+  run: (tx: Database, policy: OrganizationIntegrationPolicy) => Promise<T>,
+): Promise<T> {
+  const requested = acquisitionScope.parse(inputScope);
+  // Non-locking authoritative resolution before any new lock; repeat under the
+  // policy fence below so a moved/deleted workspace cannot retain stale scope.
+  const resolved = await rlsContextForWorkspace(db, requested.workspaceId);
+  if (resolved.accountId !== requested.accountId)
+    throw new Error("Organization integration policy workspace scope invalid");
+  const scope = { accountId: resolved.accountId, workspaceId: requested.workspaceId };
+  return withRlsContext(
+    db,
+    scope,
+    async (tx) => {
+      await requireReadCommitted(tx);
+      await tx.execute(
+        sql`select pg_advisory_xact_lock_shared(hashtextextended(${`organization-integration-policy:${scope.accountId}`}, 0))`,
+      );
+      // No row lock here: the existing writer owns its canonical membership ->
+      // workspace prefix. All policy checks and callback writes share this tx.
+      const [workspace] = await rawRows(
+        tx,
+        sql`select id from workspaces where id = ${scope.workspaceId}::uuid and account_id = ${scope.accountId}::uuid`,
+      );
+      if (!workspace) throw new Error("Organization integration policy workspace scope invalid");
+      const policy = await read(tx, scope);
+      Object.freeze(policy.allowedIntegrationKeys);
+      Object.freeze(policy);
+      const result = await run(tx, policy);
+      const [finalWorkspace] = await rawRows(
+        tx,
+        sql`select id from workspaces where id = ${scope.workspaceId}::uuid and account_id = ${scope.accountId}::uuid for key share`,
+      );
+      if (!finalWorkspace)
+        throw new Error("Organization integration policy workspace scope changed before commit");
+      return result;
+    },
+    undefined,
+    "none",
+  );
+}
+
+/** New acquisitions always assert before effects and before returning to commit.
+ * The immutable snapshot stays authoritative through commit: the shared fence
+ * excludes policy writers and the SQL writer rejects same-transaction upgrades.
+ * Receipt-aware callers instead use withOrganizationIntegrationPolicyFence and
+ * assert only after distinguishing completed replay from new workflow progress.
+ */
+export async function withOrganizationIntegrationAcquisition<T>(
+  db: Database,
+  inputScope: OrganizationIntegrationAcquisitionScope,
+  integrationKeys: readonly (string | null)[],
+  acquire: (tx: Database) => Promise<T>,
+): Promise<T> {
+  // Snapshot classifications before the first await, including workspace lookup.
+  const keys = [...integrationKeys];
+  if (!keys.length)
+    throw new Error("Acquisition requires at least one trusted integration classification");
+  return withOrganizationIntegrationPolicyFence(db, inputScope, async (tx, policy) => {
+    const assert = () => {
+      for (const key of keys) assertOrganizationIntegrationAllowed(policy, key);
+    };
+    assert();
+    const result = await acquire(tx);
+    assert();
+    return result;
+  });
+}