@opengeni/api-router 3.0.1 → 3.1.2

package/src/transcription/service.ts

@@ -1,16 +1,26 @@
-import { resolveVoiceInputProviderRegistry, type Settings } from "@opengeni/config";
+import {
+  resolveVoiceInputProviderRegistry,
+  voiceInputCreditBillingActive,
+  type Settings,
+} from "@opengeni/config";
 import { VOICE_INPUT_ACCEPTED_MIME_TYPES } from "@opengeni/contracts";
+import { voiceTranscriptionSettlementKeys } from "@opengeni/db";
 import {
+  createVoiceInputBilling,
   filenameForMimeType,
   isAcceptedMimeType,
   normalizeMimeType,
   TRANSCRIPTION_PROVIDER_REQUEST_TIMEOUT_MILLISECONDS,
   type TranscriptionAvailabilityContext,
+  type TranscriptionBilling,
+  type TranscriptionBillingContext,
   type TranscriptionProvider,
   type TranscriptionService,
   TranscriptionServiceError,
 } from "@opengeni/core";
 import type { Database } from "@opengeni/db";
+import { createFfmpegAudioNormalizer, type TranscriptionAudioNormalizer } from "./normalize";
+import { createMaiTranscriptionProvider } from "./providers/azure-mai";
 import { createAzureOpenAiTranscriptionProvider } from "./providers/azure-openai";
 import { createCodexSubscriptionTranscriptionProvider } from "./providers/codex-subscription";
 import { createOpenAiTranscriptionProvider } from "./providers/openai";
@@ -26,6 +36,14 @@ export function createTranscriptionService(input: {
   providerRequestTimeoutMilliseconds?: number;
   /** Test seam for evaluating persisted absolute deadlines after delayed setup. */
   now?: () => Date;
+  /** Credit admission/settlement for deployment-funded providers. */
+  billing?: TranscriptionBilling;
+  /** Test seam: trusted one-shot decode + duration (defaults to ffmpeg). */
+  normalizeAudio?: TranscriptionAudioNormalizer;
+  /** Loud operator log for settlement failures after provider success. */
+  log?: (message: string, attributes: Record<string, string | number | boolean>) => void;
+  /** In-process settlement retry pacing after an inline failure. */
+  settlementRetryDelaysMilliseconds?: readonly number[];
 }): TranscriptionService {
   const providers: TranscriptionProvider[] = resolveVoiceInputProviderRegistry(input.settings).map(
     (config) => {
@@ -35,6 +53,12 @@ export function createTranscriptionService(input: {
             ...config,
             ...(input.fetch ? { fetch: input.fetch } : {}),
           });
+        case "azure-mai":
+          return createMaiTranscriptionProvider({
+            ...config,
+            ffmpegPath: input.settings.voiceInputFfmpegPath,
+            ...(input.fetch ? { fetch: input.fetch } : {}),
+          });
         case "azure-openai":
           return createAzureOpenAiTranscriptionProvider({
             ...config,
@@ -66,16 +90,119 @@ export function createTranscriptionService(input: {
   const providerRequestTimeoutMilliseconds =
     input.providerRequestTimeoutMilliseconds ?? TRANSCRIPTION_PROVIDER_REQUEST_TIMEOUT_MILLISECONDS;
   const now = input.now ?? (() => new Date());
+  const log =
+    input.log ??
+    ((message: string, attributes: Record<string, string | number | boolean>) => {
+      console.error(message, attributes);
+    });
+  const billing =
+    input.billing ??
+    createVoiceInputBilling({
+      db: input.db,
+      settings: input.settings,
+      onReconcileError: (error, scope) => {
+        log("Voice input charge reconciliation failed", {
+          ...scope,
+          errorClass: error instanceof Error ? error.name : "UnknownError",
+          error: boundedErrorMessage(error),
+        });
+      },
+    });
+  let normalizer: TranscriptionAudioNormalizer | undefined = input.normalizeAudio;
+  const normalizeAudio: TranscriptionAudioNormalizer = (request) => {
+    normalizer ??= createFfmpegAudioNormalizer({ ffmpegPath: input.settings.voiceInputFfmpegPath });
+    return normalizer(request);
+  };
+  const retryDelays = input.settlementRetryDelaysMilliseconds ?? [2_000, 15_000, 60_000];
+  type Settlement = Parameters<TranscriptionBilling["settle"]>[0];
+  /**
+   * Post-use settlement never fails the request: the provider already returned
+   * text the user is waiting for. A failure is logged with the exact
+   * idempotency keys and retried in-process; if the receipt committed but the
+   * debit did not, the next admission in the workspace reconciles it.
+   */
+  const settleWithoutFailing = async (settlement: Settlement): Promise<number> => {
+    try {
+      return (await billing.settle(settlement)).creditCostMicros;
+    } catch (error) {
+      reportUnsettled(settlement, error, 0, retryDelays.length > 0 && !deterministic(error));
+      if (!deterministic(error)) scheduleSettlementRetry(settlement, 0);
+      return 0;
+    }
+  };
+  const deterministic = (error: unknown) => error instanceof TranscriptionServiceError;
+  const scheduleSettlementRetry = (settlement: Settlement, attempt: number) => {
+    const delay = retryDelays[attempt];
+    if (delay === undefined) return;
+    const timer = setTimeout(() => {
+      void billing.settle(settlement).then(
+        () => {
+          log("Voice input charge settled on retry", {
+            ...settlementAttributes(settlement),
+            attempt: attempt + 1,
+          });
+        },
+        (error: unknown) => {
+          const more = attempt + 1 < retryDelays.length;
+          reportUnsettled(settlement, error, attempt + 1, more);
+          if (more) scheduleSettlementRetry(settlement, attempt + 1);
+        },
+      );
+    }, delay);
+    (timer as ReturnType<typeof setTimeout> & { unref?: () => void }).unref?.();
+  };
+  const reportUnsettled = (
+    settlement: Settlement,
+    error: unknown,
+    attempt: number,
+    willRetry: boolean,
+  ) => {
+    log(
+      willRetry
+        ? "Voice input charge is unsettled after provider success; retrying"
+        : "Voice input charge is UNSETTLED after provider success; manual reconciliation needed unless its usage receipt committed",
+      {
+        ...settlementAttributes(settlement),
+        attempt,
+        willRetry,
+        errorClass: error instanceof Error ? error.name : "UnknownError",
+        error: boundedErrorMessage(error),
+      },
+    );
+  };
+  const creditBillingActive = voiceInputCreditBillingActive(input.settings);
+  /** Deployment-funded calls are charged; the workspace's own subscriptions never are. */
+  const chargeable = (provider: TranscriptionProvider) =>
+    creditBillingActive && provider.deploymentFunded !== undefined;
   return {
     limits: () => limits,
     async available(context) {
-      return (await Promise.all(providers.map((provider) => provider.available(context)))).some(
-        Boolean,
+      return Boolean(
+        await firstAvailable(orderedProviders(providers, context ?? {}), context ?? {}),
+      );
+    },
+    async availableProviderIds(context) {
+      // Every ready provider, for the workspace provider picker. One failing
+      // probe means that provider is not ready; it never fails the caller.
+      const available = await Promise.all(
+        providers.map(async (provider) => {
+          try {
+            return (await provider.available(context)) ? provider.id : null;
+          } catch {
+            return null;
+          }
+        }),
       );
+      return available.filter((id): id is string => id !== null);
     },
     async selectProvider(context) {
       return (await firstAvailable(orderedProviders(providers, context), context))?.id ?? null;
     },
+    async admit({ providerId, accountId, workspaceId, attribution }) {
+      const provider = providers.find((candidate) => candidate.id === providerId);
+      if (!provider || !chargeable(provider)) return;
+      await billing.admit({ accountId, workspaceId, attribution });
+    },
     async transcribe(request) {
       const mimeType = normalizeMimeType(request.mimeType);
       if (!isAcceptedMimeType(mimeType, limits.acceptedMimeTypes)) {
@@ -120,6 +247,65 @@ export function createTranscriptionService(input: {
           message: "Transcription provider does not support bounded requests.",
         });
       }
+      if (chargeable(provider)) {
+        // Fail closed: a deployment-paid call is never sent without a price
+        // and a trusted settlement identity.
+        if (!provider.deploymentFunded?.pricing || !request.billing) {
+          throw new TranscriptionServiceError({
+            code: "unavailable",
+            message: "Transcription billing is not configured.",
+          });
+        }
+        try {
+          await billing.admit({
+            accountId: request.accountId,
+            workspaceId: request.workspaceId,
+            attribution: request.billing.attribution,
+          });
+        } catch (error) {
+          // Nothing was sent yet: a fallback-safe refusal (Opengeni credits
+          // turned off here) lets the next provider, such as a connected
+          // subscription, serve the request.
+          if (
+            error instanceof TranscriptionServiceError &&
+            error.fallbackSafe &&
+            !request.providerId &&
+            request.fallbackEnabled !== false &&
+            !request.signal?.aborted
+          ) {
+            const excludedProviders = [...(request.excludedProviders ?? []), provider.id];
+            if (
+              await firstAvailable(
+                orderedProviders(providers, { ...request, excludedProviders }),
+                request,
+              )
+            ) {
+              return await this.transcribe({ ...request, excludedProviders });
+            }
+          }
+          throw error;
+        }
+      }
+      let audio = request.audio;
+      let providerMimeType = mimeType;
+      let billingContext: TranscriptionBillingContext | undefined = request.billing;
+      let audioSeconds = request.durationSeconds ?? 0;
+      if (chargeable(provider) && billingContext?.trustedDurationSeconds === undefined) {
+        // A deployment-paid one-shot upload is decoded by the server first, so
+        // the call always carries a duration the server measured from bytes it
+        // produced. That bills any usage shape we cannot price, and bounds
+        // what is sent upstream to the configured maximum recording length.
+        const normalized = await normalizeAudio({
+          audio,
+          mimeType,
+          maxDurationSeconds: limits.maxDurationSeconds,
+          ...(request.signal ? { signal: request.signal } : {}),
+        });
+        audio = normalized.bytes;
+        providerMimeType = "audio/wav";
+        audioSeconds = normalized.durationSeconds;
+        billingContext = { ...billingContext!, trustedDurationSeconds: normalized.durationSeconds };
+      }
       const startedAt = performance.now();
       const remainingMilliseconds = request.providerDeadlineAt
         ? remainingTranscriptionProviderRequestMilliseconds(request.providerDeadlineAt, now())
@@ -135,12 +321,12 @@ export function createTranscriptionService(input: {
         });
       }
       const deadline = createProviderRequestDeadline(request.signal, remainingMilliseconds);
-      let result: { text: string; languages: string[] };
+      let result: Awaited<ReturnType<TranscriptionProvider["transcribe"]>>;
       try {
         result = await provider.transcribe({
-          audio: request.audio,
-          mimeType,
-          filename: filenameForMimeType(mimeType),
+          audio,
+          mimeType: providerMimeType,
+          filename: filenameForMimeType(providerMimeType),
           workspaceId: request.workspaceId,
           accountId: request.accountId,
           subjectId: request.subjectId,
@@ -183,11 +369,30 @@ export function createTranscriptionService(input: {
       } finally {
         deadline.dispose();
       }
+      const latencyMs = Math.round(performance.now() - startedAt);
+      let creditCostMicros = 0;
+      const settle = async () => {
+        if (chargeable(provider) && provider.deploymentFunded?.pricing && billingContext) {
+          creditCostMicros = await settleWithoutFailing({
+            accountId: request.accountId,
+            workspaceId: request.workspaceId,
+            providerId: provider.id,
+            model: provider.deploymentFunded.model,
+            pricing: provider.deploymentFunded.pricing,
+            usage: result.usage ?? null,
+            billing: billingContext,
+          });
+        }
+      };
+      if (!request.deferBillingSettlement) await settle();
       return {
-        ...result,
+        text: result.text,
+        languages: result.languages,
         providerId: provider.id,
-        audioSeconds: request.durationSeconds ?? 0,
-        latencyMs: Math.round(performance.now() - startedAt),
+        audioSeconds,
+        latencyMs,
+        creditCostMicros,
+        ...(request.deferBillingSettlement ? { settleBilling: settle } : {}),
       };
     },
   };
@@ -272,3 +477,27 @@ async function exactAvailable(
   const provider = providers.find((candidate) => candidate.id === providerId);
   return provider && (await provider.available(context)) ? provider : null;
 }
+
+function settlementAttributes(settlement: {
+  accountId: string;
+  workspaceId: string;
+  providerId: string;
+  billing: TranscriptionBillingContext;
+}): Record<string, string> {
+  const keys = voiceTranscriptionSettlementKeys({
+    workspaceId: settlement.workspaceId,
+    sourceId: settlement.billing.sourceId,
+  });
+  return {
+    accountId: settlement.accountId,
+    workspaceId: settlement.workspaceId,
+    providerId: settlement.providerId,
+    sourceId: settlement.billing.sourceId,
+    usageIdempotencyKey: keys.usageIdempotencyKey,
+    debitIdempotencyKey: keys.debitIdempotencyKey,
+  };
+}
+
+function boundedErrorMessage(error: unknown): string {
+  return (error instanceof Error ? error.message : String(error)).slice(0, 500);
+}

package/src/transcription/wav-duration.ts

@@ -0,0 +1,39 @@
+/**
+ * Duration of a PCM RIFF/WAVE buffer the server itself produced (resumable
+ * provider segments are ffmpeg-normalized WAV). Used only as the trusted
+ * billing fallback when a provider reports no usage; never applied to
+ * client-uploaded bytes. Returns null for anything that is not a well-formed
+ * WAV with a positive byte rate.
+ */
+export function wavDurationSeconds(bytes: Uint8Array): number | null {
+  if (bytes.byteLength < 12) return null;
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  if (ascii(bytes, 0) !== "RIFF" || ascii(bytes, 8) !== "WAVE") return null;
+  let offset = 12;
+  let byteRate: number | null = null;
+  while (offset + 8 <= bytes.byteLength) {
+    const id = ascii(bytes, offset);
+    const size = view.getUint32(offset + 4, true);
+    const body = offset + 8;
+    if (id === "fmt " && body + 12 <= bytes.byteLength) {
+      byteRate = view.getUint32(body + 8, true);
+    } else if (id === "data") {
+      if (!byteRate) return null;
+      // Streamed WAV writes a placeholder size; the actual payload is the rest.
+      const available = bytes.byteLength - body;
+      const dataBytes = size === 0 || size === 0xffffffff ? available : Math.min(size, available);
+      return dataBytes / byteRate;
+    }
+    offset = body + size + (size % 2);
+  }
+  return null;
+}
+
+function ascii(bytes: Uint8Array, offset: number): string {
+  return String.fromCharCode(
+    bytes[offset] ?? 0,
+    bytes[offset + 1] ?? 0,
+    bytes[offset + 2] ?? 0,
+    bytes[offset + 3] ?? 0,
+  );
+}

package/src/workspace-deletion.ts

@@ -1,7 +1,12 @@
-import { deleteWorkspaceIfQuiescent, nestedPostgresSqlState } from "@opengeni/db";
+import {
+  deleteWorkspaceIfQuiescent,
+  nestedPostgresSqlState,
+  safeDatabaseErrorFacts,
+} from "@opengeni/db";
 import type { ApiRouteDeps } from "@opengeni/core";
 import { HTTPException } from "hono/http-exception";
 
+import { dropSiteSqlDatabases, siteSqlSitesOfWorkspace } from "./site-sql/service";
 import { processTemporalScheduleCleanupClaims } from "./temporal-schedule-cleanup";
 import { workspaceDeleteObserver } from "./workspace-delete-observability";
 
@@ -14,6 +19,9 @@ export async function deleteWorkspaceForRequest(
   },
 ): Promise<void> {
   const observer = workspaceDeleteObserver(deps.observability, input);
+  // Site SQL rows in Postgres cascade with the workspace; the Durable Objects
+  // holding the data do not, so note them first and drop them after.
+  const siteSqlSites = await siteSqlSitesOfWorkspace(deps, input);
   let deleted;
   try {
     deleted = await deleteWorkspaceIfQuiescent(deps.db, {
@@ -28,6 +36,21 @@ export async function deleteWorkspaceForRequest(
     if (state === "P0002") {
       throw new HTTPException(404, { message: "workspace not found" });
     }
+    if (state === "23503") {
+      // Retention and linked-record FKs are intentional deletion boundaries.
+      // The failed transaction has rolled back: do not erase history, retry
+      // the cascade, or dispatch any external schedule cleanup.
+      // Editable documents, spreadsheets, and presentations keep immutable
+      // version history that only the organization retention lifecycle may
+      // erase, so name that cause without exposing the constraint itself.
+      const constraint = safeDatabaseErrorFacts(error).constraint ?? "";
+      const retainedRecords = constraint.startsWith("editable_artifact")
+        ? "the workspace's editable documents, spreadsheets, or presentations, whose version history is retained"
+        : "retained or linked records";
+      throw new HTTPException(409, {
+        message: `workspace deletion is blocked by ${retainedRecords}; keep the workspace, revoke access, and disable scheduled work instead`,
+      });
+    }
     throw error;
   }
 
@@ -61,4 +84,5 @@ export async function deleteWorkspaceForRequest(
     },
     deleted.temporalScheduleCleanups,
   );
+  await dropSiteSqlDatabases(deps, siteSqlSites, { workspaceId: input.workspaceId });
 }

package/src/workspace-tool-gateway-attestations.ts

@@ -0,0 +1,133 @@
+import type { ToolGatewayCatalog, ToolGatewayIdentity } from "@opengeni/contracts";
+import { digestCanonicalJson } from "@opengeni/tool-gateway";
+
+/**
+ * Content-free memory of complete workspace tool catalogs this API process
+ * produced for one exact caller scope.
+ *
+ * A complete catalog digest covers every enabled connector, so verifying a
+ * call's `catalogDigest` used to require connecting and listing every
+ * connector again. The attestation remembers, per complete digest, only the
+ * canonical digest of each entry. A later call can then prepare just its
+ * target connector live and prove that the entry it is about to execute is
+ * byte-for-byte the entry its caller saw in that complete catalog.
+ *
+ * It never stores credentials, prepared gateways, connections, schemas,
+ * arguments, or results, and grants no authority: every call still resolves
+ * live caller, account, connection, policy, and Site authority. A miss,
+ * expiry, or entry mismatch falls back to complete preparation and the exact
+ * historical stale-catalog contract.
+ */
+export type WorkspaceToolGatewayCatalogAttestations = {
+  record(scope: string, catalog: Pick<ToolGatewayCatalog, "digest" | "entries">): void;
+  /** The attested entry digest, or `undefined` when the catalog is unknown or expired. */
+  entryDigest(
+    scope: string,
+    catalogDigest: string,
+    identity: ToolGatewayIdentity,
+  ): string | undefined;
+  /** Entry digests currently retained (bounded by `maxEntries`). */
+  readonly retainedEntries: number;
+};
+
+export type WorkspaceToolGatewayCatalogAttestationOptions = {
+  /** Fixed lifetime from complete preparation; use never extends it. */
+  ttlMs?: number;
+  maxScopes?: number;
+  maxCatalogsPerScope?: number;
+  /** Global bound on retained entry digests across all scopes and catalogs. */
+  maxEntries?: number;
+  now?: () => number;
+};
+
+export const WORKSPACE_TOOL_GATEWAY_ATTESTATION_TTL_MS = 10 * 60_000;
+const DEFAULT_MAX_SCOPES = 512;
+const DEFAULT_MAX_CATALOGS_PER_SCOPE = 4;
+// About 250k entries * a few hundred bytes: on the order of 100 MiB per API
+// process in the worst case, typically far less.
+const DEFAULT_MAX_ENTRIES = 250_000;
+
+type AttestedCatalog = { expiresAt: number; entries: ReadonlyMap<string, string> };
+
+export function createWorkspaceToolGatewayCatalogAttestations(
+  options: WorkspaceToolGatewayCatalogAttestationOptions = {},
+): WorkspaceToolGatewayCatalogAttestations {
+  const ttlMs = options.ttlMs ?? WORKSPACE_TOOL_GATEWAY_ATTESTATION_TTL_MS;
+  const maxScopes = options.maxScopes ?? DEFAULT_MAX_SCOPES;
+  const maxCatalogsPerScope = options.maxCatalogsPerScope ?? DEFAULT_MAX_CATALOGS_PER_SCOPE;
+  const maxEntries = options.maxEntries ?? DEFAULT_MAX_ENTRIES;
+  const now = options.now ?? Date.now;
+  // Map insertion order is the eviction order (least recently recorded first).
+  const scopes = new Map<string, Map<string, AttestedCatalog>>();
+  let retainedEntries = 0;
+  const drop = (scope: string, catalogs: Map<string, AttestedCatalog>, digest: string) => {
+    const attested = catalogs.get(digest);
+    if (!attested) return;
+    retainedEntries -= attested.entries.size;
+    catalogs.delete(digest);
+    if (catalogs.size === 0) scopes.delete(scope);
+  };
+  const dropOldest = (): boolean => {
+    const oldest = scopes.entries().next().value;
+    if (!oldest) return false;
+    drop(oldest[0], oldest[1], oldest[1].keys().next().value!);
+    return true;
+  };
+  const overBudget = (): boolean => scopes.size > maxScopes || retainedEntries > maxEntries;
+  return {
+    record(scope, catalog) {
+      const at = now();
+      for (const [candidateScope, catalogs] of [...scopes]) {
+        for (const [digest, attested] of [...catalogs]) {
+          if (attested.expiresAt <= at) drop(candidateScope, catalogs, digest);
+        }
+      }
+      // A catalog larger than the whole budget is simply not attested; its
+      // calls keep using complete preparation.
+      if (catalog.entries.length > maxEntries) return;
+      const entries = new Map<string, string>();
+      for (const entry of catalog.entries) {
+        entries.set(
+          workspaceToolGatewayIdentityKey(entry.identity),
+          digestWorkspaceToolGatewayCatalogEntry(entry),
+        );
+      }
+      const existing = scopes.get(scope);
+      if (existing) drop(scope, existing, catalog.digest);
+      const catalogs = scopes.get(scope) ?? new Map<string, AttestedCatalog>();
+      scopes.delete(scope);
+      catalogs.set(catalog.digest, { expiresAt: at + ttlMs, entries });
+      retainedEntries += entries.size;
+      while (catalogs.size > maxCatalogsPerScope) {
+        const oldestDigest = catalogs.keys().next().value!;
+        retainedEntries -= catalogs.get(oldestDigest)!.entries.size;
+        catalogs.delete(oldestDigest);
+      }
+      scopes.set(scope, catalogs);
+      while (overBudget()) {
+        if (!dropOldest()) break;
+      }
+    },
+    entryDigest(scope, catalogDigest, identity) {
+      const catalogs = scopes.get(scope);
+      const attested = catalogs?.get(catalogDigest);
+      if (!catalogs || !attested) return undefined;
+      if (attested.expiresAt <= now()) {
+        drop(scope, catalogs, catalogDigest);
+        return undefined;
+      }
+      return attested.entries.get(workspaceToolGatewayIdentityKey(identity));
+    },
+    get retainedEntries() {
+      return retainedEntries;
+    },
+  };
+}
+
+export function digestWorkspaceToolGatewayCatalogEntry(entry: unknown): string {
+  return digestCanonicalJson(entry);
+}
+
+function workspaceToolGatewayIdentityKey(identity: ToolGatewayIdentity): string {
+  return JSON.stringify([identity.serverId, identity.toolName]);
+}

package/src/workspace-tool-gateway-observability.ts

@@ -15,6 +15,70 @@ export type WorkspaceToolGatewayOutcome =
 
 const DURATION_BUCKETS = [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30, 60];
 
+export function recordWorkspaceToolTargetOperation(
+  observability: Observability | null | undefined,
+  input: {
+    operation: "resolve" | "invoke" | "target-approvals" | "manifest";
+    outcome: "ok" | "failed";
+    durationSeconds: number;
+  },
+): void {
+  try {
+    const labels = { operation: input.operation, outcome: input.outcome };
+    observability?.incrementCounter({
+      name: "opengeni_tool_target_operations_total",
+      help: "Targeted workspace tool requests; never full-catalog fallback.",
+      labels,
+    });
+    observability?.observeHistogram({
+      name: "opengeni_tool_target_duration_seconds",
+      help: "Total targeted request time including metadata, provider preparation and execution.",
+      labels,
+      buckets: DURATION_BUCKETS,
+      value: Math.max(0, input.durationSeconds),
+    });
+  } catch {
+    /* Observation never changes execution. */
+  }
+}
+
+/**
+ * Bounded preparation telemetry: how long the request spent constructing,
+ * credentialing, connecting, and listing connectors before any execution, and
+ * whether a call used target-only preparation through a catalog attestation.
+ */
+export function recordWorkspaceToolGatewayPreparation(
+  observability: Observability | null | undefined,
+  input: {
+    operation: "catalog" | "call";
+    scope: "complete" | "target";
+    attestation: "hit" | "miss" | "mismatch" | "bypass" | "record";
+    durationSeconds: number;
+  },
+): void {
+  try {
+    const labels = {
+      operation: input.operation,
+      scope: input.scope,
+      attestation: input.attestation,
+    };
+    observability?.incrementCounter({
+      name: "opengeni_tool_gateway_preparations_total",
+      help: "Workspace tool gateway HTTP preparations by bounded operation, scope, and catalog attestation outcome.",
+      labels,
+    });
+    observability?.observeHistogram({
+      name: "opengeni_tool_gateway_preparation_duration_seconds",
+      help: "Workspace tool gateway HTTP preparation wall time in seconds, before execution.",
+      labels,
+      buckets: DURATION_BUCKETS,
+      value: Math.max(0, input.durationSeconds),
+    });
+  } catch {
+    // Telemetry must never change gateway execution truth.
+  }
+}
+
 /**
  * Low-cardinality gateway telemetry shared by HTTP/SDK/Site and aggregate MCP
  * adapters. Tool names, workspace/subject ids, arguments, results, credentials,