@opengeni/core 4.0.1 → 4.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/core",
-  "version": "4.0.1",
+  "version": "4.0.3",
   "description": "OpenGeni framework-agnostic core: the domain, access, and billing layers (neutral access, off-HTTP V2 surface). Behavior-preserving extraction from apps/api — keeps Hono's HTTPException for error throwing (typed-errors cleanup deferred).",
   "license": "Apache-2.0",
   "repository": {
@@ -51,16 +51,16 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@opengeni/capabilities": "^0.3.4",
-    "@opengeni/codex": "^0.2.25",
-    "@opengeni/config": "^2.1.0",
-    "@opengeni/contracts": "^5.1.0",
-    "@opengeni/db": "^6.0.1",
-    "@opengeni/documents": "^0.8.32",
-    "@opengeni/events": "^0.4.30",
+    "@opengeni/codex": "^0.2.26",
+    "@opengeni/config": "^2.1.1",
+    "@opengeni/contracts": "^5.1.1",
+    "@opengeni/db": "^6.0.3",
+    "@opengeni/documents": "^0.8.34",
+    "@opengeni/events": "^0.4.32",
     "@opengeni/network": "^0.3.1",
-    "@opengeni/observability": "^0.8.31",
-    "@opengeni/runtime": "^4.0.1",
-    "@opengeni/storage": "^0.2.132",
+    "@opengeni/observability": "^0.8.32",
+    "@opengeni/runtime": "^4.0.3",
+    "@opengeni/storage": "^0.2.133",
     "hono": "^4.12.18",
     "zod": "^4.2.1"
   },

package/src/billing/limits.ts

@@ -25,6 +25,26 @@ import type { ApiRouteDeps } from "../dependencies";
 
 export type LimitDependencies = Pick<ApiRouteDeps, "db" | "settings">;
 
+/** Deterministic/local embeddings never debit credits, even in paid mode. */
+export function paidDocumentEmbedding(settings: Settings): boolean {
+  return (
+    settings.documentEmbeddingBillingMode === "credits" &&
+    settings.documentEmbeddingProvider === "openai"
+  );
+}
+
+/** Round up each provider request so a positive input cannot become a free debit. */
+export function documentEmbeddingCostMicros(settings: Settings, inputBytes: number): number {
+  if (!Number.isSafeInteger(inputBytes) || inputBytes < 0)
+    throw new Error("invalid embedding bytes");
+  const amount =
+    (BigInt(inputBytes) * BigInt(settings.documentEmbeddingRateMicrosPerMillionBytes) + 999_999n) /
+    1_000_000n;
+  if (amount > BigInt(Number.MAX_SAFE_INTEGER))
+    throw new Error("embedding cost exceeds safe integer");
+  return Number(amount);
+}
+
 export type LimitCheckInput = {
   accountId: string;
   workspaceId?: string;
@@ -296,9 +316,10 @@ function usesCreditLimits(deps: LimitDependencies): boolean {
 }
 
 function isCostlyAction(action: LimitAction): boolean {
-  return (
-    action === "agent_run:create" || action === "tokens:consume" || action === "document:index"
-  );
+  // Document admission retains the monthly chunk quota above, but parsing and
+  // source retention do not consume embedding credits. The worker admits paid
+  // embedding separately and settles its actual provider input after use.
+  return action === "agent_run:create" || action === "tokens:consume";
 }
 
 function blocked(code: string, message: string): LimitDecision {

package/src/domain/capabilities.ts

@@ -1314,6 +1314,7 @@ function fikenCatalogItem(fikenConnections: ConnectionMetadata[]): CapabilityCat
     metadata: {
       connectorMode: "first_party_fiken",
       ownership: "workspace",
+      connectionStatus: fikenConnection?.status ?? null,
       // Derived from the contracts catalog so a new fiken_* tool cannot be
       // registered without also appearing on the capability tile.
       firstPartyMcpTools: FIRST_PARTY_MCP_TOOL_NAMES.filter((name) => name.startsWith("fiken_")),
@@ -1563,6 +1564,11 @@ export function applyCapabilityEnablement(
   item: CapabilityCatalogItem,
   installation: CapabilityInstallation | undefined,
 ): CapabilityCatalogItem {
+  if (item.surfaceType === "first_party_fiken") {
+    // Fiken is an API item with connection-derived state, not a generic API
+    // installation. Preserve that state before the non-MCP fallback below.
+    return { ...item, connectionRef: null };
+  }
   if (item.kind === "skill" || item.kind === "api" || item.kind === "plugin") {
     return { ...item, enabled: false, enabledReason: null, connectionRef: null };
   }
@@ -1572,12 +1578,6 @@ export function applyCapabilityEnablement(
     // publishes a personal connection UUID or collapses many accounts to one.
     return { ...item, connectionRef: null };
   }
-  if (item.surfaceType === "first_party_fiken") {
-    // Fiken connector state is derived from the authoritative workspace
-    // connection row while the catalog is built; browseable never means an
-    // account is already connected.
-    return { ...item, connectionRef: null };
-  }
   if (item.surfaceType === "codex_apps") {
     // Unlike ordinary built-ins, Apps availability is derived from the exact
     // active workspace designation above. Do not overwrite it with the

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

@@ -221,6 +221,31 @@ test("published and pending searches reuse one query embedding", async () => {
   expect(calls).toBe(1);
 });
 
+test("a keyword fallback in the first view never retries an unfunded provider in the review view", async () => {
+  const searches: Array<{ mode: string | undefined; settingsProvided: boolean }> = [];
+  await prepareKnowledgeSave(
+    db,
+    context,
+    { query: "Acme renewal" },
+    () => {
+      throw new Error("An unfunded provider was called");
+    },
+    {
+      list: async () => ({ entries: [], nextCursor: null }),
+      get: async () => null,
+      search: async (_db, _context, request, _embedder, settings) => {
+        searches.push({ mode: request.mode, settingsProvided: !!settings });
+        return { entries: [], nextCursor: null, searchMode: "keyword" };
+      },
+    },
+    { documentEmbeddingProvider: "openai", documentEmbeddingBillingMode: "credits" } as never,
+  );
+  expect(searches).toEqual([
+    { mode: "keyword", settingsProvided: false },
+    { mode: "keyword", settingsProvided: false },
+  ]);
+});
+
 test("catalog rechecks current metadata after a collection changes", async () => {
   const old = group("Old name");
   const current = {

package/src/domain/knowledge-preparation.ts

@@ -9,6 +9,8 @@ import {
   type KnowledgeContext,
 } from "@opengeni/db";
 import type { DocumentEmbedder } from "@opengeni/documents";
+import type { Settings } from "@opengeni/config";
+import { paidDocumentEmbedding } from "../billing/limits";
 import { searchKnowledgeEntries } from "./knowledge-search";
 
 const defaults = {
@@ -29,6 +31,7 @@ export async function prepareKnowledgeSave(
   input: KnowledgeSavePreparationRequest,
   embedder: () => DocumentEmbedder,
   services = defaults,
+  settings?: Settings,
 ): Promise<KnowledgeSavePreparationResponse> {
   const request = KnowledgeSavePreparationRequest.parse(input);
   if (context.actor.kind !== "agent" && !(context.actor.kind === "human" && context.actor.review)) {
@@ -56,20 +59,38 @@ export async function prepareKnowledgeSave(
   };
   // Search is independent of collection placement and always includes the
   // separate unapproved view. No authoring policy or write is invoked here.
-  const matches = {
-    published: await services.search(
-      db,
-      context,
-      { query: request.query, limit: request.limit, view: "published" },
-      sharedEmbedder,
-    ),
-    needs_review: await services.search(
-      db,
-      context,
-      { query: request.query, limit: request.limit, view: "needs_review" },
-      sharedEmbedder,
-    ),
-  };
+  // Preparation returns BOTH views plus a catalog. A charge on the first
+  // semantic search would precede the second view and catalog; any later
+  // failure would leave no deliverable preparation result. Paid mode uses
+  // keyword discovery until a single-operation settlement seam exists.
+  const paid = settings != null && paidDocumentEmbedding(settings);
+  const published = await services.search(
+    db,
+    context,
+    {
+      query: request.query,
+      limit: request.limit,
+      view: "published",
+      ...(paid ? { mode: "keyword" as const } : {}),
+    },
+    sharedEmbedder,
+    paid ? undefined : settings,
+  );
+  // Reuse the first request's provider result (and charge). If it fell back
+  // to keyword because funding or the provider was unavailable, do not retry
+  // an unfunded embedding request in the second review view.
+  const needsReview = await services.search(
+    db,
+    context,
+    {
+      query: request.query,
+      limit: request.limit,
+      view: "needs_review",
+      ...(published.searchMode === "keyword" ? { mode: "keyword" as const } : {}),
+    },
+    sharedEmbedder,
+  );
+  const matches = { published, needs_review: needsReview };
   for (const view of ["published", "needs_review"] as const) {
     if (request.collectionCursors && request.collectionCursors[view] === null) continue;
     let cursor = request.collectionCursors?.[view] ?? undefined;

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" });
+});