@opengeni/core 1.3.0 → 1.4.0

package/src/sandbox/routing.ts

@@ -28,6 +28,7 @@ import {
   readActiveSandbox,
   retainWorkspaceMutationProcess,
   SandboxRetainedProcessPromotionFencedError,
+  SandboxWorkspaceMutationOutputRejectedError,
   retainedProcessSettlementIdentity,
   settleRetainedProcess,
   verifyDirectWorkspaceMutationSettlement,
@@ -43,6 +44,7 @@ import {
   NatsControlRpc,
   NatsOpStreamTransport,
   RoutingSandboxSession,
+  RoutingMutationOutputRejectedError,
   resolveModalCheckpointProviderBindingForSession,
   type ControlRpc,
   type EstablishedSandboxSession,
@@ -359,22 +361,38 @@ export function wrapChannelABoxWithRouting(
           throw new Error(
             "Outcome-unknown command settlement requires its exact retained invocation",
           );
-        await verifyDirectWorkspaceMutationSettlement(db, {
-          accountId: ids.accountId,
-          workspaceId: ids.workspaceId,
-          sessionId: ids.sessionId,
-          requestId: ids.directRequest.requestId,
-          holderId: ids.directRequest.holderId,
-          initiatorSubjectId: ids.resourceSubjectId,
-          sandboxGroupId: homeLease.sandboxGroupId,
-          expectedEpoch: backend.leaseEpoch,
-          expectedInstanceId: backend.providerInstanceId,
-          routeTargetId: exactAdmission.routeTargetId,
-          routeEpoch: exactAdmission.routeEpoch,
-          admission: exactAdmission,
-          operation: op,
-          outcome,
-        });
+        try {
+          await verifyDirectWorkspaceMutationSettlement(db, {
+            accountId: ids.accountId,
+            workspaceId: ids.workspaceId,
+            sessionId: ids.sessionId,
+            requestId: ids.directRequest.requestId,
+            holderId: ids.directRequest.holderId,
+            initiatorSubjectId: ids.resourceSubjectId,
+            sandboxGroupId: homeLease.sandboxGroupId,
+            expectedEpoch: backend.leaseEpoch,
+            expectedInstanceId: backend.providerInstanceId,
+            routeTargetId: exactAdmission.routeTargetId,
+            routeEpoch: exactAdmission.routeEpoch,
+            admission: exactAdmission,
+            operation: op,
+            outcome,
+          });
+        } catch (error) {
+          if (
+            error instanceof SandboxWorkspaceMutationOutputRejectedError &&
+            error.matchesPhysicalSettlement({
+              accountId: ids.accountId,
+              workspaceId: ids.workspaceId,
+              admission: exactAdmission,
+              operation: op,
+              outcome,
+            })
+          ) {
+            throw new RoutingMutationOutputRejectedError(op, error.code, { cause: error });
+          }
+          throw error;
+        }
       }
     : undefined;
   const beforeProcessMutation = homeLease
@@ -419,15 +437,31 @@ export function wrapChannelABoxWithRouting(
         ) {
           throw new Error("API retained-process mutation settlement lacked its exact admission");
         }
-        await verifyRetainedProcessMutationSettlement(db, {
-          accountId: ids.accountId,
-          workspaceId: ids.workspaceId,
-          sessionId: ids.sessionId,
-          processId: process.id,
-          admission: admission as SandboxWorkspaceMutationAdmission,
-          operation: op,
-          outcome,
-        });
+        try {
+          await verifyRetainedProcessMutationSettlement(db, {
+            accountId: ids.accountId,
+            workspaceId: ids.workspaceId,
+            sessionId: ids.sessionId,
+            processId: process.id,
+            admission: admission as SandboxWorkspaceMutationAdmission,
+            operation: op,
+            outcome,
+          });
+        } catch (error) {
+          if (
+            error instanceof SandboxWorkspaceMutationOutputRejectedError &&
+            error.matchesPhysicalSettlement({
+              accountId: ids.accountId,
+              workspaceId: ids.workspaceId,
+              admission: admission as SandboxWorkspaceMutationAdmission,
+              operation: op,
+              outcome,
+            })
+          ) {
+            throw new RoutingMutationOutputRejectedError(op, error.code, { cause: error });
+          }
+          throw error;
+        }
       }
     : undefined;
   const settleProcess = homeLease

package/src/transcription.ts

@@ -1,4 +1,6 @@
+import type { VoiceInputPricing, VoiceInputUsage } from "@opengeni/config";
 import type { TranscribeAudioResponse, VoiceInputErrorCode } from "@opengeni/contracts";
+import type { CreditDebitAttribution } from "@opengeni/db";
 
 /**
  * Server-owned upstream budget for one provider attempt. Resumable recording
@@ -34,6 +36,39 @@ export type TranscriptionRequest = {
   preferredProvider?: string | null | undefined;
   fallbackEnabled?: boolean | undefined;
   excludedProviders?: readonly string[] | undefined;
+  /**
+   * Credit settlement facts for a deployment-funded provider. Required when
+   * the selected provider is deployment-funded and credit billing is active;
+   * the service fails closed without it.
+   */
+  billing?: TranscriptionBillingContext | undefined;
+  /**
+   * Internal: return `settleBilling` instead of settling before returning, so
+   * a resumable segment's transcript commits before any billing write.
+   */
+  deferBillingSettlement?: boolean;
+};
+
+/**
+ * Trusted, server-built settlement identity for one transcription unit. The
+ * usage receipt and debit idempotency keys derive from `workspaceId` +
+ * `sourceId` (see `voiceInputSettlementKeys`), so a retry or a later
+ * reconciliation settles the same unit exactly once.
+ */
+export type TranscriptionBillingContext = {
+  /**
+   * Server-derived unit identity. Never a client-chosen value: a reused id
+   * settles once, so a client-controlled id would make later calls free.
+   */
+  sourceId: string;
+  /** Trusted payer facts from the authenticated request boundary. */
+  attribution: CreditDebitAttribution;
+  /**
+   * Audio duration measured by the server from WAV bytes it produced (the
+   * resumable segment, or the normalized one-shot upload). Bills whenever the
+   * provider reports no usage this deployment has a price for.
+   */
+  trustedDurationSeconds?: number | undefined;
 };
 
 export type TranscriptionResult = TranscribeAudioResponse & {
@@ -41,17 +76,79 @@ export type TranscriptionResult = TranscribeAudioResponse & {
   providerId: string;
   audioSeconds: number;
   latencyMs: number;
+  /** Opengeni credits charged for this call (0 for subscription/free providers). */
+  creditCostMicros?: number | undefined;
+  /**
+   * Server-only settlement callback; never serialized into a public response.
+   * Never rejects: a settlement failure after provider success is logged and
+   * retried, and the transcript is still delivered.
+   */
+  settleBilling?: () => Promise<void>;
+};
+
+export type TranscriptionBillingRefusalCode =
+  | "insufficient_credits"
+  | "allowance_exhausted"
+  | "monthly_model_cost_limit";
+
+/**
+ * Pre-use refusal for deployment-funded transcription: 402 for credits and
+ * allowances (same codes as session admission), 429 for a static monthly cap.
+ */
+export class TranscriptionBillingRefusedError extends Error {
+  readonly status: 402 | 429;
+  readonly code: TranscriptionBillingRefusalCode;
+  readonly details: { scope?: string; resetsAt?: string | null; subjectId?: string };
+
+  constructor(input: {
+    code: TranscriptionBillingRefusalCode;
+    message: string;
+    details?: { scope?: string; resetsAt?: string | null; subjectId?: string };
+  }) {
+    super(input.message);
+    this.name = "TranscriptionBillingRefusedError";
+    this.code = input.code;
+    this.status = input.code === "monthly_model_cost_limit" ? 429 : 402;
+    this.details = input.details ?? {};
+  }
+}
+
+/**
+ * Credit admission and settlement for deployment-funded transcription.
+ * Subscription providers (Codex, SuperGrok) never reach this port.
+ */
+export type TranscriptionBilling = {
+  /** Refuse before any audio is sent when the payer cannot fund the call. */
+  admit(input: {
+    accountId: string;
+    workspaceId: string;
+    attribution: CreditDebitAttribution;
+  }): Promise<void>;
+  /**
+   * Record usage and debit credits once per unit, after use. The usage receipt
+   * commits before the debit, so a failed debit leaves a durable receipt that
+   * `admit` reconciles on the workspace's next voice request.
+   */
+  settle(input: {
+    accountId: string;
+    workspaceId: string;
+    providerId: string;
+    model: string;
+    pricing: VoiceInputPricing;
+    usage: VoiceInputUsage | null;
+    billing: TranscriptionBillingContext;
+  }): Promise<{ creditCostMicros: number }>;
 };
 
 export class TranscriptionServiceError extends Error {
-  readonly code: VoiceInputErrorCode;
+  readonly code: Exclude<VoiceInputErrorCode, TranscriptionBillingRefusalCode>;
   readonly status: number;
   readonly retryable: boolean;
   /** Explicit rejection before any transcription result; safe to try another provider. */
   readonly fallbackSafe: boolean;
 
   constructor(input: {
-    code: VoiceInputErrorCode;
+    code: Exclude<VoiceInputErrorCode, TranscriptionBillingRefusalCode>;
     message: string;
     status?: number;
     retryable?: boolean;
@@ -114,6 +211,14 @@ export type TranscriptionProvider = {
   /** The adapter guarantees that its upstream transport honors AbortSignal. */
   readonly supportsServerDeadline: true;
   readonly experimental?: boolean | undefined;
+  /**
+   * Present when the deployment pays the upstream provider (OpenAI/Azure):
+   * the call is admitted against and settled in Opengeni credits. Absent for
+   * the workspace's own subscriptions, which are never charged.
+   */
+  readonly deploymentFunded?:
+    | { readonly model: string; readonly pricing: VoiceInputPricing | null }
+    | undefined;
   /**
    * Deployment readiness when called without a workspace. When `workspaceId` is
    * provided, providers may require a workspace-attached credential (e.g. Codex).
@@ -128,17 +233,29 @@ export type TranscriptionProvider = {
     subjectId: string;
     requestId: string;
     signal?: AbortSignal | undefined;
-  }): Promise<{ text: string; languages: string[] }>;
+  }): Promise<{ text: string; languages: string[]; usage?: VoiceInputUsage | null | undefined }>;
 };
 
 export type TranscriptionService = {
   limits(): TranscriptionLimits;
   /** True when at least one ready provider can serve requests. */
   available(context?: TranscriptionAvailabilityContext): boolean | Promise<boolean>;
+  availableProviderIds?(context: TranscriptionAvailabilityContext): Promise<string[]>;
   /** Select one provider before a durable segment attempt; retries pin this id. */
   selectProvider?(
     context: TranscriptionAvailabilityContext,
   ): string | null | Promise<string | null>;
+  /**
+   * Credit admission for an exact provider before durable work is claimed.
+   * Resolves for subscription providers; throws TranscriptionBillingRefusedError
+   * when a deployment-funded provider cannot be paid for.
+   */
+  admit?(input: {
+    providerId: string;
+    accountId: string;
+    workspaceId: string;
+    attribution: CreditDebitAttribution;
+  }): Promise<void>;
   transcribe(request: TranscriptionRequest): Promise<TranscriptionResult>;
 };
 
@@ -156,6 +273,8 @@ export type TranscriptionSegmenter = {
     sourceMimeType: string;
     totalDurationMilliseconds: number;
     providerSegmentSeconds: number;
+    /** Hard decode ceiling (`ffmpeg -t`); audio past it is never decoded. */
+    maxDecodeSeconds?: number | undefined;
     chunks: AsyncIterable<Uint8Array>;
     signal?: AbortSignal | undefined;
   }): AsyncIterable<PreparedTranscriptionSegment>;