@opengeni/core 4.0.1 → 4.0.3-canary.36199476632001

package/src/domain/knowledge-search.test.ts

@@ -1,12 +1,53 @@
 import { afterAll, expect, mock, test } from "bun:test";
+import type { Settings } from "@opengeni/config";
 const list = mock(
-  async (_db: unknown, _context: unknown, _request: unknown, _embedding?: unknown) => ({
-    entries: [],
-    nextCursor: null,
-  }),
+  async (_db: unknown, _context: unknown, _request: unknown, _embedding?: unknown) => {
+    if (failNextRetrieval) {
+      failNextRetrieval = false;
+      throw new Error("retrieval unavailable");
+    }
+    return { entries: [], nextCursor: null };
+  },
 );
-mock.module("@opengeni/db", () => ({ listKnowledgeEntries: list }));
+let balance = 0;
+let usedChunks = 0;
+let queryRateBytes = 0;
+let queryRateMicros = 0;
+let failNextRetrieval = false;
+let failSettlement = false;
+const debits = mock(async (_db: unknown, input: { amountMicros: number }) => {
+  if (failSettlement) throw new Error("settlement unavailable");
+  balance -= input.amountMicros;
+  return { balance: { balanceMicros: balance }, debitedMicros: input.amountMicros };
+});
+const usage = mock(
+  async (_db: unknown, _input: { quantity: number; eventType: string }) => undefined,
+);
+mock.module("@opengeni/db", () => ({
+  listKnowledgeEntries: list,
+  getBillingBalance: async () => ({ balanceMicros: balance }),
+  applyCreditDebitAfterUse: debits,
+  recordUsageEvent: usage,
+  withKnowledgeQueryAccountLock: async (
+    _db: unknown,
+    _account: unknown,
+    _workspace: unknown,
+    fn: (db: unknown) => Promise<unknown>,
+  ) => fn(_db),
+  isCodexBilledTurn: async () => false,
+  sumUsageQuantity: async (_db: unknown, input: { eventType: string }) =>
+    input.eventType === "document.query_embedding_bytes"
+      ? queryRateBytes
+      : input.eventType === "document.query_embedding_cost"
+        ? queryRateMicros
+        : usedChunks,
+  countScheduledTasksForWorkspace: async () => 0,
+  countWorkspacesForAccount: async () => 0,
+  countActiveApiKeysForWorkspace: async () => 0,
+  countActiveOrganizationApiKeysForAccount: async () => 0,
+}));
 const { searchKnowledgeEntries } = await import("./knowledge-search");
+const { checkLimit } = await import("../billing/limits");
 afterAll(() => mock.restore());
 const unavailable = () => {
   throw new Error("embedding unavailable");
@@ -23,6 +64,7 @@ test("hybrid fallback keeps lexical recall and passes the exact scope and cursor
     unavailable,
   );
   expect(result.searchMode).toBe("keyword");
+  expect(result.fallbackReason).toBe("provider_unavailable");
   expect(list.mock.calls.at(-1)?.[2]).toMatchObject({
     query: '"Acme" OR "renewal" OR "renew" OR "contract" OR "expiration" OR "date"',
     mode: "keyword",
@@ -43,3 +85,287 @@ test("keyword and explicit search syntax remain unchanged", async () => {
   );
   expect(list.mock.calls.at(-1)?.[2]).toMatchObject({ query: "Acme renewal", mode: "keyword" });
 });
+
+test("paid vector queries check funding, debit post-use, and preserve hybrid keyword fallback", async () => {
+  const settings = {
+    documentEmbeddingProvider: "openai",
+    documentEmbeddingBillingMode: "credits",
+    documentEmbeddingRateMicrosPerMillionBytes: 1_000_000,
+  } as Settings;
+  const context = { accountId: "account", workspaceId: "workspace" } as never;
+  let embedded = 0;
+  const provider = () =>
+    ({
+      model: "test",
+      dimensions: 3,
+      embedQuery: async () => {
+        embedded++;
+        return [1, 0, 0];
+      },
+    }) as never;
+  balance = 0;
+  const unfunded = await searchKnowledgeEntries(
+    {} as never,
+    context,
+    { query: "paid" },
+    provider,
+    settings,
+  );
+  expect(unfunded.searchMode).toBe("keyword");
+  expect(unfunded.fallbackReason).toBe("awaiting_funding");
+  await expect(
+    searchKnowledgeEntries(
+      {} as never,
+      context,
+      { query: "paid", mode: "vector" },
+      provider,
+      settings,
+    ),
+  ).rejects.toMatchObject({ code: "knowledge_vector_funding_required" });
+  expect(embedded).toBe(0);
+  balance = 1;
+  const paid = await searchKnowledgeEntries(
+    {} as never,
+    context,
+    { query: "paid", mode: "vector" },
+    provider,
+    settings,
+  );
+  expect(paid.searchMode).toBe("vector");
+  expect(embedded).toBe(1);
+  expect(debits.mock.calls.at(-1)?.[1]).toMatchObject({
+    amountMicros: 4,
+    sourceType: "knowledge_query",
+  });
+  expect(balance).toBe(-3);
+  const priorUsage = usage.mock.calls.length;
+  await searchKnowledgeEntries(
+    {} as never,
+    context,
+    { query: "paid", mode: "keyword" },
+    provider,
+    settings,
+  );
+  expect(embedded).toBe(1);
+  expect(usage.mock.calls.length).toBe(priorUsage);
+});
+
+test("shadow query usage meters bytes without checking or consuming credits", async () => {
+  const settings = {
+    documentEmbeddingProvider: "openai",
+    documentEmbeddingBillingMode: "shadow",
+    documentEmbeddingRateMicrosPerMillionBytes: 1_000_000,
+  } as Settings;
+  balance = 0;
+  const before = debits.mock.calls.length;
+  const found = await searchKnowledgeEntries(
+    {} as never,
+    { accountId: "account", workspaceId: "workspace" } as never,
+    { query: "é", mode: "vector" },
+    () => ({ model: "test", dimensions: 3, embedQuery: async () => [1, 0, 0] }) as never,
+    settings,
+  );
+  expect(found.searchMode).toBe("vector");
+  expect(usage.mock.calls.at(-1)?.[1]).toMatchObject({
+    quantity: 2,
+    eventType: "document.query_embedding_bytes",
+  });
+  expect(debits.mock.calls.length).toBe(before);
+});
+
+test("paid query does not debit when vector retrieval fails after embedding", async () => {
+  const settings = {
+    documentEmbeddingProvider: "openai",
+    documentEmbeddingBillingMode: "credits",
+    documentEmbeddingRateMicrosPerMillionBytes: 1_000_000,
+  } as Settings;
+  balance = 1;
+  const debitsBefore = debits.mock.calls.length;
+  failNextRetrieval = true;
+  await expect(
+    searchKnowledgeEntries(
+      {} as never,
+      { accountId: "account", workspaceId: "workspace" } as never,
+      { query: "paid", mode: "vector" },
+      () => ({ model: "test", dimensions: 3, embedQuery: async () => [1, 0, 0] }) as never,
+      settings,
+    ),
+  ).rejects.toThrow("retrieval unavailable");
+  expect(debits.mock.calls.length).toBe(debitsBefore);
+});
+
+test("paid semantic pagination fails closed before provider use", async () => {
+  let embedded = 0;
+  const before = debits.mock.calls.length;
+  await expect(
+    searchKnowledgeEntries(
+      {} as never,
+      { accountId: "account", workspaceId: "workspace" } as never,
+      { query: "paid", mode: "vector", cursor: "next-page" },
+      () =>
+        ({
+          model: "test",
+          dimensions: 3,
+          embedQuery: async () => {
+            embedded++;
+            return [1, 0, 0];
+          },
+        }) as never,
+      {
+        documentEmbeddingProvider: "openai",
+        documentEmbeddingBillingMode: "credits",
+        documentEmbeddingRateMicrosPerMillionBytes: 1_000_000,
+      } as Settings,
+    ),
+  ).rejects.toThrow("pagination is unavailable");
+  expect(embedded).toBe(0);
+  expect(debits.mock.calls.length).toBe(before);
+});
+
+test("paid query rate ceiling falls back for hybrid and rejects vector without using the provider", async () => {
+  queryRateBytes = 64 * 1024;
+  balance = 1;
+  let embedded = 0;
+  const provider = () =>
+    ({
+      model: "test",
+      dimensions: 3,
+      embedQuery: async () => {
+        embedded++;
+        return [1, 0, 0];
+      },
+    }) as never;
+  const settings = {
+    documentEmbeddingProvider: "openai",
+    documentEmbeddingBillingMode: "credits",
+    documentEmbeddingRateMicrosPerMillionBytes: 1_000_000,
+  } as Settings;
+  try {
+    expect(
+      (
+        await searchKnowledgeEntries(
+          {} as never,
+          { accountId: "account", workspaceId: "workspace" } as never,
+          { query: "paid" },
+          provider,
+          settings,
+        )
+      ).searchMode,
+    ).toBe("keyword");
+    await expect(
+      searchKnowledgeEntries(
+        {} as never,
+        { accountId: "account", workspaceId: "workspace" } as never,
+        { query: "paid", mode: "vector" },
+        provider,
+        settings,
+      ),
+    ).rejects.toThrow("rate limit reached");
+    expect(embedded).toBe(0);
+  } finally {
+    queryRateBytes = 0;
+  }
+});
+
+test("paid micro-cost ceiling blocks repeated tiny queries before embedding", async () => {
+  balance = 1;
+  queryRateMicros = 10_000;
+  let embedded = 0;
+  try {
+    const result = await searchKnowledgeEntries(
+      {} as never,
+      { accountId: "account", workspaceId: "workspace" } as never,
+      { query: "tiny" },
+      () =>
+        ({
+          model: "test",
+          dimensions: 3,
+          embedQuery: async () => {
+            embedded++;
+            return [1, 0, 0];
+          },
+        }) as never,
+      {
+        documentEmbeddingProvider: "openai",
+        documentEmbeddingBillingMode: "credits",
+        documentEmbeddingRateMicrosPerMillionBytes: 1_000_000,
+      } as Settings,
+    );
+    expect(result.searchMode).toBe("keyword");
+    expect(embedded).toBe(0);
+  } finally {
+    queryRateMicros = 0;
+  }
+});
+
+test("paid settlement failure propagates without a fallback", async () => {
+  balance = 1;
+  failSettlement = true;
+  const before = list.mock.calls.length;
+  try {
+    await expect(
+      searchKnowledgeEntries(
+        {} as never,
+        { accountId: "account", workspaceId: "workspace" } as never,
+        { query: "paid" },
+        () => ({ model: "test", dimensions: 3, embedQuery: async () => [1, 0, 0] }) as never,
+        {
+          documentEmbeddingProvider: "openai",
+          documentEmbeddingBillingMode: "credits",
+          documentEmbeddingRateMicrosPerMillionBytes: 1_000_000,
+        } as Settings,
+      ),
+    ).rejects.toThrow("settlement unavailable");
+    expect(list.mock.calls.length).toBe(before + 1);
+  } finally {
+    failSettlement = false;
+  }
+});
+
+test("deterministic embeddings remain unpriced even with credits mode selected", async () => {
+  balance = 0;
+  const before = debits.mock.calls.length;
+  const found = await searchKnowledgeEntries(
+    {} as never,
+    { accountId: "account", workspaceId: "workspace" } as never,
+    { query: "local", mode: "vector" },
+    () => ({ model: "local", dimensions: 3, embedQuery: async () => [1, 0, 0] }) as never,
+    {
+      documentEmbeddingProvider: "deterministic",
+      documentEmbeddingBillingMode: "credits",
+      documentEmbeddingRateMicrosPerMillionBytes: 1_000_000,
+    } as Settings,
+  );
+  expect(found.searchMode).toBe("vector");
+  expect(debits.mock.calls.length).toBe(before);
+});
+
+test("unpriced document source admission ignores zero credits but preserves the monthly chunk quota", async () => {
+  balance = 0;
+  usedChunks = 1;
+  const deps = {
+    db: {} as never,
+    settings: {
+      billingMode: "stripe",
+      usageLimitsMode: "static",
+      staticUsageLimitsJson: JSON.stringify({ maxDocumentIndexedChunksPerWorkspace: 2 }),
+    } as Settings,
+  };
+  expect(
+    await checkLimit(deps, {
+      accountId: "account",
+      workspaceId: "workspace",
+      action: "document:index",
+      quantity: 0,
+    }),
+  ).toMatchObject({ allowed: true });
+  usedChunks = 2;
+  expect(
+    await checkLimit(deps, {
+      accountId: "account",
+      workspaceId: "workspace",
+      action: "document:index",
+      quantity: 1,
+    }),
+  ).toMatchObject({ allowed: false, code: "max_document_indexed_chunks_per_workspace" });
+});

package/src/domain/knowledge-search.ts

@@ -1,7 +1,45 @@
-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,
+  getBillingBalance,
+  listKnowledgeEntries,
+  recordUsageEvent,
+  sumUsageQuantity,
+  withKnowledgeQueryAccountLock,
+  type Database,
+  type KnowledgeContext,
+} from "@opengeni/db";
 import type { DocumentEmbedder } from "@opengeni/documents";
 import type { z } from "zod";
+import { documentEmbeddingCostMicros, paidDocumentEmbedding } from "../billing/limits";
+
+// 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 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,7 +47,8 @@ export async function searchKnowledgeEntries(
   context: KnowledgeContext,
   input: z.input<typeof KnowledgeEntryListRequest>,
   embedder: () => DocumentEmbedder,
-) {
+  settings?: Settings,
+): Promise<KnowledgeEntryListResponse> {
   const request = KnowledgeEntryListRequest.parse(input);
   if (!request.query || request.mode === "keyword") {
     return {
@@ -27,29 +66,139 @@ 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: "awaiting_funding" | "quota" | "provider_unavailable" | "query_limit",
+  ) => {
     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;
+  // 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}`,
+        });
+      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 },
+        });
+    }
+    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 getBillingBalance(lockedDb, context.accountId);
+      if (balance.balanceMicros <= 0)
+        return keywordFallback(lockedDb, new KnowledgeVectorFundingError(), "awaiting_funding");
+      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/session-native-connection-replacement.ts

@@ -0,0 +1,64 @@
+import type { ConnectionMetadata, McpServerConnectionRef } from "@opengeni/contracts";
+import { connectionMetadataMatchesBinding } from "@opengeni/db/session-mcp-credential-rotation";
+
+/** Selection is restricted to the caller's already-authorized inventory. This
+ * projection grants no execution authority: subsequent admission and physical
+ * credential use still validate the exact native account normally. */
+export function nativeSessionConnectionReplacement(input: {
+  accountId: string;
+  workspaceId: string;
+  subjectId: string | null;
+  serverUrl: string;
+  replacementServerUrl?: string;
+  currentRef: McpServerConnectionRef | null;
+  nativeConnectionId: string;
+  connections: ConnectionMetadata[];
+}): McpServerConnectionRef {
+  const connection = input.connections.find(
+    (candidate) => candidate.id === input.nativeConnectionId,
+  );
+  if (
+    !connection ||
+    connection.accountId !== input.accountId ||
+    connection.status !== "active" ||
+    (connection.subjectId === null
+      ? connection.workspaceId !== input.workspaceId
+      : !input.subjectId || connection.subjectId !== input.subjectId || !connection.authorityId)
+  ) {
+    throw new Error("native connection unavailable");
+  }
+  const {
+    authoritySource: _authoritySource,
+    hostBinding: _hostBinding,
+    accountSelection: _accountSelection,
+    ...retained
+  } = input.currentRef ?? {};
+  // Preserve provider, resource, scope and selected-resource restrictions.
+  // Retired host identity is never interpreted as a native connection ID.
+  if (
+    input.currentRef &&
+    input.currentRef.providerDomain.toLowerCase() !== connection.providerDomain.toLowerCase()
+  )
+    throw new Error("native connection provider mismatch");
+  const ref: McpServerConnectionRef = {
+    ...retained,
+    ...(!input.currentRef?.resource && typeof connection.metadata.resource === "string"
+      ? { resource: connection.metadata.resource }
+      : {}),
+    connectionId: connection.id,
+    providerDomain: connection.providerDomain,
+    kind: connection.kind,
+    subjectScope: connection.subjectId === null ? "workspace" : "subject",
+  };
+  const destination = input.replacementServerUrl ?? input.serverUrl;
+  // A redirect must be explicitly requested and bound in the account metadata;
+  // the broker's legacy provider-host fallback is insufficient for rebinding.
+  if (
+    input.replacementServerUrl &&
+    (typeof connection.metadata.mcpUrl !== "string" || !connection.metadata.mcpUrl.trim())
+  )
+    throw new Error("native connection destination unavailable");
+  if (!connectionMetadataMatchesBinding(connection, ref, destination))
+    throw new Error("native connection binding mismatch");
+  return ref;
+}