@opengeni/core 3.0.1 → 3.1.2

package/src/domain/knowledge-search.ts

@@ -1,7 +1,59 @@
-import { KnowledgeEntryListRequest } from "@opengeni/contracts";
-import { listKnowledgeEntries, type Database, type KnowledgeContext } from "@opengeni/db";
+import { KnowledgeEntryListRequest, type KnowledgeEntryListResponse } from "@opengeni/contracts";
+import type { Settings } from "@opengeni/config";
+import {
+  applyCreditDebitAfterUse,
+  checkWorkspaceAllowance,
+  creditDebitAttributionForTurn,
+  getSpendableCreditBalance,
+  listKnowledgeEntries,
+  recordUsageEvent,
+  sumUsageQuantity,
+  withKnowledgeQueryAccountLock,
+  type Database,
+  type KnowledgeContext,
+  type CreditDebitAttribution,
+} from "@opengeni/db";
 import type { DocumentEmbedder } from "@opengeni/documents";
 import type { z } from "zod";
+import { documentEmbeddingCostMicros, paidDocumentEmbedding } from "../billing/limits";
+import { workspaceCreditsDisabled } from "./workspace-credits";
+
+// Safety ceilings, not a commercial tariff. Paid queries have no durable
+// reusable vector cache, so each bounded request consumes the provider once.
+const MAX_PAID_QUERY_BYTES = 4096;
+const MAX_PAID_QUERY_MICROS = 1000;
+const MAX_PAID_QUERY_BYTES_PER_MINUTE = 64 * 1024;
+const MAX_PAID_QUERY_BYTES_PER_MONTH = 8 * 1024 * 1024;
+const MAX_PAID_QUERY_MICROS_PER_MINUTE = 10_000;
+const MAX_PAID_QUERY_MICROS_PER_MONTH = 1_000_000;
+
+export class KnowledgeVectorFundingError extends Error {
+  readonly code = "knowledge_vector_funding_required";
+  constructor() {
+    super("Knowledge vector search needs Opengeni credits; keyword search remains available.");
+    this.name = "KnowledgeVectorFundingError";
+  }
+}
+
+export class KnowledgeVectorCreditsDisabledError extends Error {
+  readonly code = "knowledge_vector_credits_disabled";
+  constructor() {
+    super(
+      "Knowledge vector search uses Opengeni credits, which are turned off in this workspace; keyword search remains available.",
+    );
+    this.name = "KnowledgeVectorCreditsDisabledError";
+  }
+}
+
+export class KnowledgeVectorQueryRejectedError extends Error {
+  constructor(
+    public readonly code: "pagination_unavailable" | "query_limit" | "quota",
+    message: string,
+  ) {
+    super(message);
+    this.name = "KnowledgeVectorQueryRejectedError";
+  }
+}
 
 /** Shared search path for HTTP and both first-party retrieval servers. */
 export async function searchKnowledgeEntries(
@@ -9,8 +61,18 @@ export async function searchKnowledgeEntries(
   context: KnowledgeContext,
   input: z.input<typeof KnowledgeEntryListRequest>,
   embedder: () => DocumentEmbedder,
-) {
+  settings?: Settings,
+): Promise<KnowledgeEntryListResponse> {
   const request = KnowledgeEntryListRequest.parse(input);
+  // Copy trusted actor fields before any provider/lock await. Request lifetime
+  // mutation cannot replace the initiating identity between admission/debit.
+  const billingActor = { ...context.actor };
+  let paidAttribution: CreditDebitAttribution =
+    billingActor.kind === "human"
+      ? { kind: "human", initiatingHumanSubjectId: billingActor.subjectId }
+      : billingActor.kind === "service"
+        ? { kind: "service" }
+        : { kind: "unknown" };
   if (!request.query || request.mode === "keyword") {
     return {
       ...(await listKnowledgeEntries(db, context, request)),
@@ -27,29 +89,184 @@ export async function searchKnowledgeEntries(
   const lexicalRequest = KnowledgeEntryListRequest.safeParse({ ...request, query: lexicalQuery });
   const retrievalRequest =
     request.mode === "hybrid" && lexicalRequest.success ? lexicalRequest.data : request;
-  let embedding: { model: string; values: number[] };
-  try {
-    const provider = embedder();
-    const values = await provider.embedQuery(request.query);
-    if (
-      values.length !== provider.dimensions ||
-      values.some((value) => !Number.isFinite(value)) ||
-      !values.some((value) => value !== 0)
-    ) {
-      throw new Error("Knowledge query embedding is unavailable");
-    }
-    embedding = { model: provider.model, values };
-  } catch (error) {
-    // Exact vector requests cannot silently change meaning. Hybrid search can
-    // continue using the transactional keyword index while a provider is down.
+  const keywordFallback = async (
+    queryDb: Database,
+    error: unknown,
+    fallbackReason: NonNullable<KnowledgeEntryListResponse["fallbackReason"]>,
+  ) => {
     if (request.mode === "vector") throw error;
     return {
-      ...(await listKnowledgeEntries(db, context, { ...retrievalRequest, mode: "keyword" })),
+      ...(await listKnowledgeEntries(queryDb, context, { ...retrievalRequest, mode: "keyword" })),
       searchMode: "keyword" as const,
+      fallbackReason,
     };
-  }
-  return {
-    ...(await listKnowledgeEntries(db, context, retrievalRequest, embedding)),
-    searchMode: request.mode,
   };
+  const bytes = Buffer.byteLength(request.query, "utf8");
+  const paidSettings = settings && paidDocumentEmbedding(settings) ? settings : undefined;
+  // A workspace that turned Opengeni credits off is never debited; it keeps
+  // keyword search (and keyword pagination) instead of paid semantic
+  // retrieval. Nothing is charged here, so no account lock is needed.
+  if (paidSettings && (await workspaceCreditsDisabled(db, context.workspaceId)))
+    return keywordFallback(db, new KnowledgeVectorCreditsDisabledError(), "credits_disabled");
+  // Paid cursors would re-embed and re-charge on each page. Until a durable
+  // vector cache exists, require explicit keyword mode to paginate instead.
+  if (paidSettings && request.cursor)
+    throw new KnowledgeVectorQueryRejectedError(
+      "pagination_unavailable",
+      "Paid semantic Knowledge pagination is unavailable; use keyword mode",
+    );
+  const cost = paidSettings ? documentEmbeddingCostMicros(paidSettings, bytes) : 0;
+  if (paidSettings && (bytes > MAX_PAID_QUERY_BYTES || cost > MAX_PAID_QUERY_MICROS))
+    return keywordFallback(
+      db,
+      new KnowledgeVectorQueryRejectedError(
+        "query_limit",
+        "Paid Knowledge query exceeds the per-request limit",
+      ),
+      "query_limit",
+    );
+
+  const retrieveThenSettle = async (queryDb: Database) => {
+    let embedding: { model: string; values: number[] };
+    try {
+      const provider = embedder();
+      const values = await provider.embedQuery(request.query!);
+      if (
+        values.length !== provider.dimensions ||
+        values.some((value) => !Number.isFinite(value)) ||
+        !values.some((value) => value !== 0)
+      )
+        throw new Error("Knowledge query embedding is unavailable");
+      embedding = { model: provider.model, values };
+    } catch (error) {
+      // Only provider failure may fall back. Retrieval and settlement errors
+      // after use surface; they never masquerade as a successful keyword hit.
+      return keywordFallback(queryDb, error, "provider_unavailable");
+    }
+    // Read before billing, in the same transaction for the paid mode. Failure
+    // here leaves no customer charge and no vector result to return.
+    const found = await listKnowledgeEntries(queryDb, context, retrievalRequest, embedding);
+    if (settings) {
+      const usageId = crypto.randomUUID();
+      await recordUsageEvent(queryDb, {
+        accountId: context.accountId,
+        workspaceId: context.workspaceId,
+        eventType: "document.query_embedding_bytes",
+        quantity: bytes,
+        unit: "byte",
+        sourceResourceType: "knowledge_query",
+        sourceResourceId: usageId,
+        idempotencyKey: `knowledge.query_bytes:${usageId}`,
+      });
+      if (paidSettings && cost > 0)
+        await recordUsageEvent(queryDb, {
+          accountId: context.accountId,
+          workspaceId: context.workspaceId,
+          eventType: "document.query_embedding_cost",
+          quantity: cost,
+          unit: "micro_usd",
+          sourceResourceType: "knowledge_query",
+          sourceResourceId: usageId,
+          idempotencyKey: `knowledge.query_cost:${usageId}`,
+          // Durable receipt inserted before the debit in this same transaction.
+          // The service is the writer, not an inferred causal human.
+          initiator: { kind: "service", subjectId: "worker:knowledge-query" },
+          initiatorContext: { creditDebitAttribution: paidAttribution },
+        });
+      if (paidSettings && cost > 0)
+        await applyCreditDebitAfterUse(queryDb, {
+          accountId: context.accountId,
+          workspaceId: context.workspaceId,
+          type: "document_embedding_debit",
+          amountMicros: cost,
+          sourceType: "knowledge_query",
+          sourceId: usageId,
+          idempotencyKey: `knowledge.query_embedding:${usageId}`,
+          metadata: {
+            model: embedding.model,
+            bytes,
+            // This context is constructed by the trusted HTTP/MCP host, never
+            // from request input. The ledger resolves the immutable exact turn;
+            // an API key's subject (or a session creator) is not a human.
+            ...(billingActor.kind === "agent"
+              ? { turnId: billingActor.turnId }
+              : billingActor.kind === "human"
+                ? { initiatingHumanSubjectId: billingActor.subjectId }
+                : {}),
+          },
+        });
+    }
+    return { ...found, searchMode: request.mode };
+  };
+  if (!paidSettings) return retrieveThenSettle(db);
+  // Serialize paid queries across all workspaces of the account before
+  // checking balance. This is an execution fence, not a credit reservation.
+  return withKnowledgeQueryAccountLock(
+    db,
+    context.accountId,
+    context.workspaceId,
+    async (lockedDb) => {
+      const balance = await getSpendableCreditBalance(lockedDb, context.accountId);
+      if (balance.balanceMicros <= 0)
+        return keywordFallback(lockedDb, new KnowledgeVectorFundingError(), "awaiting_funding");
+      const attribution =
+        billingActor.kind === "agent"
+          ? await creditDebitAttributionForTurn(lockedDb, {
+              accountId: context.accountId,
+              workspaceId: context.workspaceId,
+              turnId: billingActor.turnId,
+            })
+          : null;
+      if (attribution) paidAttribution = attribution;
+      const refusal = await checkWorkspaceAllowance(lockedDb, {
+        accountId: context.accountId,
+        workspaceId: context.workspaceId,
+        subjectId:
+          billingActor.kind === "human"
+            ? billingActor.subjectId
+            : attribution?.kind === "turn"
+              ? attribution.initiatingHumanSubjectId
+              : null,
+      });
+      if (refusal)
+        return keywordFallback(
+          lockedDb,
+          Object.assign(new Error(refusal.message), refusal),
+          "quota",
+        );
+      const now = new Date();
+      const minuteBytes = await sumUsageQuantity(lockedDb, {
+        accountId: context.accountId,
+        eventType: "document.query_embedding_bytes",
+        since: new Date(now.getTime() - 60_000),
+      });
+      const monthBytes = await sumUsageQuantity(lockedDb, {
+        accountId: context.accountId,
+        eventType: "document.query_embedding_bytes",
+        since: new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), 1)),
+      });
+      const minuteMicros = await sumUsageQuantity(lockedDb, {
+        accountId: context.accountId,
+        eventType: "document.query_embedding_cost",
+        since: new Date(now.getTime() - 60_000),
+      });
+      const monthMicros = await sumUsageQuantity(lockedDb, {
+        accountId: context.accountId,
+        eventType: "document.query_embedding_cost",
+        since: new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), 1)),
+      });
+      if (
+        minuteBytes + bytes > MAX_PAID_QUERY_BYTES_PER_MINUTE ||
+        monthBytes + bytes > MAX_PAID_QUERY_BYTES_PER_MONTH ||
+        minuteMicros + cost > MAX_PAID_QUERY_MICROS_PER_MINUTE ||
+        monthMicros + cost > MAX_PAID_QUERY_MICROS_PER_MONTH
+      )
+        return keywordFallback(
+          lockedDb,
+          new KnowledgeVectorQueryRejectedError("quota", "Paid Knowledge query rate limit reached"),
+          "quota",
+        );
+      return retrieveThenSettle(lockedDb);
+    },
+  );
 }

package/src/domain/mcp-account-bindings.ts

@@ -0,0 +1,169 @@
+import { connectionAccountIdentityLabel } from "@opengeni/contracts/connection-account-label";
+import { createHash } from "node:crypto";
+import type { McpServerConfig } from "@opengeni/config";
+import {
+  McpConnectionAccountBindings,
+  type ConnectionMetadata,
+  type McpConnectionAccountBinding,
+  type McpConnectionAccountSelection,
+  type McpPersonalConnectionDelegation,
+} from "@opengeni/contracts";
+import { ConnectionAccountSelectionError } from "./connection-account-selection-error";
+
+/** Account routes are stable across retries, but are never parsed to discover
+ * authority. The canonical server is retained separately in the binding. */
+export function mcpAccountRouteId(serverId: string, connectionId: string): string {
+  return `account-${createHash("sha256")
+    .update(JSON.stringify([serverId, connectionId]))
+    .digest("hex")}`;
+}
+
+function accountLabel(connection: ConnectionMetadata): string {
+  const identity = connectionAccountIdentityLabel(
+    connection.metadata,
+    `${connection.providerDomain} account ${connection.id.slice(0, 8)}`,
+  );
+  const scope = connection.subjectId === null ? "This workspace" : "Only me";
+  return `${identity} · ${scope}`;
+}
+
+function canonicalResource(value: string): string {
+  try {
+    const url = new URL(value);
+    url.hash = "";
+    url.pathname = url.pathname.replace(/\/+$/u, "") || "/";
+    return url.toString();
+  } catch {
+    return value.trim();
+  }
+}
+
+/** Pure admission projection over an already authorized inventory. Explicit
+ * pairs narrow one connector; omission attaches all eligible accounts. */
+export function mcpAccountBindingsFromVisibleConnections(input: {
+  accountId: string;
+  workspaceId: string;
+  subjectId: string | null;
+  servers: McpServerConfig[];
+  connections: ConnectionMetadata[];
+  selections?: McpConnectionAccountSelection[];
+}): McpConnectionAccountBinding[] {
+  const remaining = new Set(
+    (input.selections ?? []).map((selection) =>
+      JSON.stringify([selection.serverId, selection.connectionId]),
+    ),
+  );
+  const bindings: McpConnectionAccountBinding[] = [];
+  for (const server of input.servers) {
+    const ref = server.connectionRef;
+    if (!ref || ref.authoritySource === "host") continue;
+    // A selector becomes an exact reference at acceptance; do not persist a
+    // selection directive beside the frozen connection UUID.
+    const { accountSelection: _accountSelection, ...exactRef } = ref;
+    const selections = (input.selections ?? []).filter(
+      (selection) => selection.serverId === server.id,
+    );
+    const selectedIds = new Set(selections.map((selection) => selection.connectionId));
+    for (const connection of input.connections) {
+      if (
+        connection.accountId !== input.accountId ||
+        connection.status !== "active" ||
+        connection.providerDomain.toLowerCase() !== ref.providerDomain.toLowerCase() ||
+        (ref.kind && connection.kind !== ref.kind) ||
+        (ref.connectionId !== undefined && ref.connectionId !== connection.id) ||
+        (ref.resource &&
+          (typeof connection.metadata.resource !== "string" ||
+            canonicalResource(connection.metadata.resource) !== canonicalResource(ref.resource))) ||
+        (selectedIds.size > 0 && !selectedIds.has(connection.id))
+      )
+        continue;
+      const personal = connection.subjectId !== null;
+      if (
+        personal
+          ? !input.subjectId || connection.subjectId !== input.subjectId || !connection.authorityId
+          : connection.workspaceId !== input.workspaceId
+      )
+        continue;
+      remaining.delete(JSON.stringify([server.id, connection.id]));
+      bindings.push({
+        serverId: mcpAccountRouteId(server.id, connection.id),
+        canonicalServerId: server.id,
+        connectionId: connection.id,
+        originWorkspaceId: connection.workspaceId,
+        subjectScope: personal ? "subject" : "workspace",
+        ownerSubjectId: connection.subjectId,
+        accountLabel: accountLabel(connection),
+        providerDomain: connection.providerDomain,
+        kind: connection.kind,
+        connectionRef: {
+          ...exactRef,
+          connectionId: connection.id,
+          providerDomain: connection.providerDomain,
+          kind: connection.kind,
+          subjectScope: personal ? "subject" : "workspace",
+        },
+        ...(connection.connectionAuthorityGeneration
+          ? { connectionAuthorityGeneration: connection.connectionAuthorityGeneration }
+          : {}),
+      });
+    }
+  }
+  if (remaining.size > 0) {
+    throw new ConnectionAccountSelectionError(
+      "An attached connector account is unavailable. Review its connection settings.",
+      {
+        version: 1,
+        reason: "selected_account_unavailable",
+        accounts: (input.selections ?? [])
+          .filter((selection) =>
+            remaining.has(JSON.stringify([selection.serverId, selection.connectionId])),
+          )
+          .map((selection) => {
+            const server = input.servers.find((candidate) => candidate.id === selection.serverId);
+            // Only inspect the caller's already-authorized inventory. Never look
+            // up an unavailable account globally merely to improve an error.
+            const connection = input.connections.find(
+              (candidate) => candidate.id === selection.connectionId,
+            );
+            return {
+              serverId: selection.serverId,
+              connectionId: selection.connectionId,
+              reason:
+                !server?.connectionRef || server.connectionRef.authoritySource === "host"
+                  ? ("connector_unavailable" as const)
+                  : !connection
+                    ? ("account_not_visible" as const)
+                    : connection.status !== "active"
+                      ? ("account_inactive" as const)
+                      : ("account_mismatch" as const),
+            };
+          }),
+      },
+    );
+  }
+  return McpConnectionAccountBindings.parse(
+    bindings.sort((left, right) => left.serverId.localeCompare(right.serverId)),
+  );
+}
+
+/** Workspace accounts never acquire a fabricated personal owner/delegation. */
+export function personalDelegationsForAccountBindings(
+  bindings: McpConnectionAccountBinding[],
+): McpPersonalConnectionDelegation[] {
+  return bindings.flatMap((binding) =>
+    binding.subjectScope === "subject" && binding.ownerSubjectId
+      ? [
+          {
+            serverId: binding.serverId,
+            canonicalServerId: binding.canonicalServerId,
+            connectionId: binding.connectionId,
+            originWorkspaceId: binding.originWorkspaceId,
+            ownerSubjectId: binding.ownerSubjectId,
+            providerDomain: binding.providerDomain,
+            kind: binding.kind,
+            connectionType: "mcp" as const,
+          },
+        ]
+      : [],
+  );
+}

package/src/domain/mcp-account-routes.ts

@@ -0,0 +1,152 @@
+import type { Settings } from "@opengeni/config";
+import type {
+  McpAccountRouteLabel,
+  McpConnectionAccountBinding,
+  ToolRef,
+} from "@opengeni/contracts";
+import type { ApiIntegrationRuntime } from "@opengeni/db";
+
+const ACCOUNT_SCOPE_SUFFIX = / · (?:Only me|This workspace)$/u;
+
+/** "alice@example.com · Only me" → "alice@example.com". */
+function accountIdentity(binding: McpConnectionAccountBinding): string {
+  return binding.accountLabel.replace(ACCOUNT_SCOPE_SUFFIX, "") || binding.accountLabel;
+}
+
+/** Expand only after canonical tool-policy admission. Aliases are execution
+ * identities, never an alternate way to gain admission to a connector. */
+export function expandMcpAccountRoutes(input: {
+  settings: Settings;
+  tools: ToolRef[];
+  bindings: readonly McpConnectionAccountBinding[] | null | undefined;
+}): {
+  settings: Settings;
+  tools: ToolRef[];
+  accountLabels: ReadonlyMap<string, McpAccountRouteLabel>;
+} {
+  // Only historical work has no binding snapshot. A present empty snapshot is
+  // an explicit lack of account authority, never a request for current defaults.
+  if (input.bindings == null) {
+    return { settings: input.settings, tools: input.tools, accountLabels: new Map() };
+  }
+  const configured = new Map(input.settings.mcpServers.map((server) => [server.id, server]));
+  const byCanonical = new Map<string, McpConnectionAccountBinding[]>();
+  const routes = new Set<string>();
+  const accounts = new Set<string>();
+  for (const binding of input.bindings) {
+    const account = JSON.stringify([binding.canonicalServerId, binding.connectionId]);
+    if (
+      routes.has(binding.serverId) ||
+      accounts.has(account) ||
+      configured.has(binding.serverId) ||
+      (binding.subjectScope === "subject") !== (binding.ownerSubjectId !== null) ||
+      binding.connectionRef.authoritySource === "host" ||
+      binding.connectionRef.connectionId !== binding.connectionId ||
+      binding.connectionRef.subjectScope !== binding.subjectScope ||
+      binding.connectionRef.providerDomain !== binding.providerDomain ||
+      binding.connectionRef.kind !== binding.kind
+    ) {
+      throw new Error("Invalid accepted MCP account route");
+    }
+    routes.add(binding.serverId);
+    accounts.add(account);
+    const siblings = byCanonical.get(binding.canonicalServerId) ?? [];
+    siblings.push(binding);
+    byCanonical.set(binding.canonicalServerId, siblings);
+  }
+  const servers: Settings["mcpServers"] = [];
+  const tools: ToolRef[] = [];
+  const accountLabels = new Map<string, McpAccountRouteLabel>();
+  for (const tool of input.tools) {
+    const bindings = byCanonical.get(tool.id);
+    const canonical = configured.get(tool.id);
+    // A connector reconfigured after acceptance (removed, made public, or moved
+    // to another provider) drops its frozen account routes. The route is
+    // never rebound to the new configuration, and the rest of the turn keeps
+    // its other tools instead of failing on one stale connector.
+    if (!bindings || !canonical?.connectionRef) {
+      if (!canonical?.connectionRef) tools.push(tool);
+      continue;
+    }
+    const usable = bindings.filter(
+      (binding) =>
+        canonical.connectionRef!.authoritySource !== "host" &&
+        canonical.connectionRef!.providerDomain === binding.providerDomain &&
+        (!canonical.connectionRef!.kind || canonical.connectionRef!.kind === binding.kind),
+    );
+    const connector = canonical.name ?? canonical.id;
+    // People only need the account to tell several apart. Two accounts with the
+    // same identity (personal and workspace) keep their scope to stay distinct.
+    const identities = usable.map(accountIdentity);
+    for (const [index, binding] of usable.entries()) {
+      // Static headers can belong to the formerly selected account. Credentials
+      // for account-qualified routes come exclusively from the native resolver.
+      const { headers: _headers, ...config } = canonical;
+      const label = `${connector} — ${binding.subjectScope === "subject" ? "Personal" : "Workspace"}: ${binding.accountLabel}`;
+      const identity = identities[index]!;
+      const account =
+        usable.length < 2
+          ? undefined
+          : identities.indexOf(identity) === identities.lastIndexOf(identity)
+            ? identity
+            : binding.accountLabel;
+      servers.push({
+        ...config,
+        id: binding.serverId,
+        name: label,
+        connectionRef: structuredClone(binding.connectionRef),
+      });
+      tools.push({ ...tool, id: binding.serverId });
+      accountLabels.set(binding.serverId, {
+        model: label,
+        connector,
+        providerDomain: binding.providerDomain,
+        ...(account ? { account } : {}),
+      });
+    }
+  }
+  return {
+    settings: {
+      ...input.settings,
+      mcpServers: [
+        ...input.settings.mcpServers.filter((server) => !server.connectionRef),
+        ...servers,
+      ],
+    },
+    tools,
+    accountLabels,
+  };
+}
+
+/** Each adapter closes over its own immutable credential ref and authority
+ * generation. Sharing a provider transport never shares a credential resolver. */
+export function expandApiIntegrationAccountRoutes(input: {
+  integrations: readonly ApiIntegrationRuntime[];
+  bindings: readonly McpConnectionAccountBinding[] | null | undefined;
+  tools: readonly ToolRef[];
+}): ApiIntegrationRuntime[] {
+  const selected = new Set(input.tools.map((tool) => tool.id));
+  if (input.bindings == null)
+    return input.integrations.filter((item) => selected.has(item.serverId));
+  const acceptedBindings = input.bindings;
+  return input.integrations.flatMap((integration) => {
+    const bindings = acceptedBindings.filter(
+      (binding) => binding.canonicalServerId === integration.serverId,
+    );
+    if (bindings.length === 0)
+      return !integration.connectionRef && selected.has(integration.serverId) ? [integration] : [];
+    return bindings
+      .filter((binding) => selected.has(binding.serverId))
+      .map((binding) => {
+        if (binding.connectionAuthorityGeneration === undefined) {
+          throw new Error("Accepted API integration account route has no authority generation");
+        }
+        return {
+          ...integration,
+          serverId: binding.serverId,
+          connectionRef: structuredClone(binding.connectionRef),
+          connectionAuthorityGeneration: binding.connectionAuthorityGeneration,
+        };
+      });
+  });
+}

package/src/domain/native-mcp-connection-admission.ts

@@ -0,0 +1,14 @@
+import type { McpServerConnectionRef } from "@opengeni/contracts";
+import { HTTPException } from "hono/http-exception";
+
+/** Reject retired authority sources instead of aliasing them to native IDs. */
+export function assertNativeMcpConnectionRef(
+  connectionRef: McpServerConnectionRef | null | undefined,
+): void {
+  if (connectionRef?.authoritySource === "host") {
+    throw new HTTPException(422, {
+      message:
+        "host-owned MCP connection refs are no longer supported; select an ordinary native connection",
+    });
+  }
+}