@opengeni/api-router 1.3.0 → 1.4.2

package/src/routes/sessions.ts

@@ -1,3 +1,4 @@
+import { AZURE_LIVE_MODEL_ID, buildSessionAzureLiveBroker } from "../azure-live";
 import { getRetainedProviderCommand } from "@opengeni/db/retained-provider-commands";
 import { assertGoalResumeAllowed, GoalResumeBlockedError } from "@opengeni/core";
 import { UnsupportedLatencyModeError } from "@opengeni/config";
@@ -6,9 +7,17 @@ import { listSessionEventSlices } from "@opengeni/db/session-event-slices";
 import * as sessionPreviewSchema from "@opengeni/db/schema";
 import { and, eq, sql } from "drizzle-orm";
 import { SessionMessageSearchRequest } from "@opengeni/contracts";
-import { scheduledSessionIds } from "@opengeni/db";
+import { requireWorkspace, scheduledSessionIds } from "@opengeni/db";
 import { isVerifiedDelegatedHumanAuthorization, withSiteSessionOrigin } from "@opengeni/core";
 import { freezeSessionRealtimeConnectionAccounts } from "@opengeni/core";
+import {
+  createRealtimeVoiceBilling,
+  RealtimeVoiceUnavailableError,
+  TranscriptionBillingRefusedError,
+} from "@opengeni/core";
+import type { CreditDebitAttribution } from "@opengeni/db";
+import { creditDebitAttributionForGrant } from "../access-grant-rls";
+import { transcriptionBillingRefusal } from "../transcription/billing-refusal";
 import { resolveSiteSessionOrigin, withOptionalSiteCommandOrigin } from "../site-session-origin";
 import { SandboxRecoveryRequest } from "@opengeni/contracts";
 import { getManagedHumanSandboxRecovery, consentManagedHumanSandboxRecovery } from "@opengeni/core";
@@ -376,6 +385,58 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     observability: deps.observability,
   };
   const workspaceCaptureManifestCache = new WorkspaceCaptureManifestCache();
+  const realtimeVoiceBilling = createRealtimeVoiceBilling({ db, settings });
+  /** Credit refusal / unavailable deployment voice as an HTTP response, else null. */
+  const realtimeVoiceRefusalResponse = (c: Context, error: unknown): Response | null => {
+    if (error instanceof TranscriptionBillingRefusedError) {
+      return transcriptionBillingRefusal(c, error);
+    }
+    if (error instanceof RealtimeVoiceUnavailableError) {
+      return c.json(
+        {
+          error: {
+            status: 409,
+            code: "realtime_voice_unavailable",
+            message: error.message,
+            retryable: false,
+            details: { reason: error.code },
+          },
+        },
+        409,
+      );
+    }
+    return null;
+  };
+  /**
+   * Bill every started minute observed so far for a deployment-funded call.
+   * Owner attribution only when the caller is the voice owner. A settlement
+   * failure is logged and retried idempotently on the next heartbeat.
+   */
+  const settleRealtimeVoice = async (input: {
+    grant: { subjectId: string };
+    attribution: CreditDebitAttribution;
+    workspaceId: string;
+    sessionId: string;
+    realtimeId: string;
+  }) => {
+    try {
+      return await realtimeVoiceBilling.settle({
+        workspaceId: input.workspaceId,
+        sessionId: input.sessionId,
+        realtimeId: input.realtimeId,
+        callerSubjectId: input.grant.subjectId,
+        attribution: input.attribution,
+      });
+    } catch (error) {
+      console.error("realtime voice settlement failed", {
+        workspaceId: input.workspaceId,
+        sessionId: input.sessionId,
+        realtimeId: input.realtimeId,
+        error: error instanceof Error ? error.message : String(error),
+      });
+      return null;
+    }
+  };
   const withSiteCommandOrigin = <T>(c: Context, workspaceId: string, run: () => Promise<T>) =>
     withOptionalSiteCommandOrigin(
       db,
@@ -1131,22 +1192,34 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
     if (!session) {
       throw new HTTPException(404, { message: "session not found" });
     }
-    const activity = await backgroundCommandActivityForSessions(db, {
-      accountId: grant.accountId,
-      workspaceId,
-      sessionIds: [sessionId],
-    });
-    const scheduleTargets =
+    // Independent reads of the already-authorized session: the effective
+    // policy context depends only on the session row, not on the activity or
+    // schedule annotations, so all three are read concurrently.
+    const [activity, scheduleTargets, policy] = await Promise.all([
+      backgroundCommandActivityForSessions(db, {
+        accountId: grant.accountId,
+        workspaceId,
+        sessionIds: [sessionId],
+      }),
       hasPermission(grant.permissions, "scheduled_tasks:run") &&
       hasPermission(grant.permissions, "sessions:control")
-        ? await scheduledSessionIds(db, workspaceId, [sessionId])
-        : new Set<string>();
+        ? scheduledSessionIds(db, workspaceId, [sessionId])
+        : Promise.resolve(new Set<string>()),
+      loadEffectivePolicyContext(deps, workspaceId, grant.subjectId, [session]),
+    ]);
     return c.json(
-      await withEffectivePolicy(deps, workspaceId, grant.subjectId, {
-        ...session,
-        hasSchedules: scheduleTargets.has(sessionId),
-        ...(activity.get(sessionId) ? { backgroundCommandActivity: activity.get(sessionId) } : {}),
-      }),
+      sessionWithEffectiveToolPolicy(
+        {
+          ...session,
+          hasSchedules: scheduleTargets.has(sessionId),
+          ...(activity.get(sessionId)
+            ? { backgroundCommandActivity: activity.get(sessionId) }
+            : {}),
+        },
+        policy.workspaceServerIds,
+        policy.workspaceDefaultServerIds,
+        policy.effectiveToolsContext,
+      ),
     );
   });
 
@@ -1307,6 +1380,18 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
         message: "invalid session realtime request",
       });
     }
+    try {
+      await realtimeVoiceBilling.admit({
+        accountId: grant.accountId,
+        workspaceId,
+        model: parsed.data.model,
+        attribution: creditDebitAttributionForGrant(grant),
+      });
+    } catch (error) {
+      const refused = realtimeVoiceRefusalResponse(c, error);
+      if (refused) return refused;
+      throw error;
+    }
     try {
       const result = await withWorkspaceSessionActivityRls(db, workspaceId, async (scopedDb) => {
         const accounts = await freezeSessionRealtimeConnectionAccounts({
@@ -1355,6 +1440,16 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
         });
       }
       try {
+        // Settle observed minutes before renewing; out of credits keeps the
+        // current lease so the call drains and ends instead of running free.
+        const settlement = await settleRealtimeVoice({
+          grant,
+          attribution: creditDebitAttributionForGrant(grant),
+          workspaceId,
+          sessionId,
+          realtimeId,
+        });
+        const stop = settlement?.stop ?? null;
         const result = await withWorkspaceSessionActivityRls(db, workspaceId, async (scopedDb) =>
           renewSessionRealtimeInTransaction(scopedDb, {
             workspaceId,
@@ -1362,11 +1457,18 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
             realtimeId,
             ownerSubjectId: grant.subjectId,
             ...parsed.data,
+            extendLease: stop === null,
           }),
         );
         await publishRealtimeMutation(grant.accountId, workspaceId, sessionId, result);
         c.header("cache-control", "private, no-store");
-        return c.json({ mode: result.mode, replay: result.replay });
+        return c.json({
+          mode: result.mode,
+          replay: result.replay,
+          ...(stop && result.mode.state === "active"
+            ? { stop: { code: stop.code, message: stop.message } }
+            : {}),
+        });
       } catch (error) {
         throw sessionRealtimeHttpError(error);
       }
@@ -1403,6 +1505,13 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
         }),
       );
       await publishRealtimeMutation(grant.accountId, workspaceId, sessionId, result);
+      await settleRealtimeVoice({
+        grant,
+        attribution: creditDebitAttributionForGrant(grant),
+        workspaceId,
+        sessionId,
+        realtimeId,
+      });
       c.header("cache-control", "private, no-store");
       return c.json({ mode: result.mode, replay: result.replay });
     } catch (error) {
@@ -1438,21 +1547,34 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
         ...providerRequest
       } = parsed.data;
       const claim = await withWorkspaceRls(db, workspaceId, async (scopedDb) =>
-        scopedDb.transaction(async (tx) =>
-          claimSessionRealtimeConnectionInTransaction(tx as unknown as Database, {
-            workspaceId,
-            sessionId,
-            realtimeId,
-            operationId,
-            ownerSubjectId: grant.subjectId,
-            browserInstanceId,
-            ownerKey,
-            expectedVersion,
-            expectedConnectionEpoch,
-            rotate,
-            promotionMode: browserActivation === "required" ? "staged" : "legacy",
-          }),
-        ),
+        scopedDb.transaction(async (tx) => {
+          const claimed = await claimSessionRealtimeConnectionInTransaction(
+            tx as unknown as Database,
+            {
+              workspaceId,
+              sessionId,
+              realtimeId,
+              operationId,
+              ownerSubjectId: grant.subjectId,
+              browserInstanceId,
+              ownerKey,
+              expectedVersion,
+              expectedConnectionEpoch,
+              rotate,
+              promotionMode: browserActivation === "required" ? "staged" : "legacy",
+            },
+          );
+          if (
+            claimed.mode.model !== "gpt-live-1-boulder-alpha" &&
+            claimed.mode.model !== AZURE_LIVE_MODEL_ID
+          ) {
+            throw new CodexRealtimeBrokerError(
+              "invalid_request",
+              "This voice model does not use WebRTC negotiation",
+            );
+          }
+          return claimed;
+        }),
       );
       if (claim.replay) {
         if (
@@ -1487,7 +1609,7 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
         return c.json({
           sdp: claim.connection.sdpAnswer,
           version: "v3" as const,
-          model: "gpt-live-1-boulder-alpha" as const,
+          model: claim.mode.model,
           connectionId: claim.connection.id,
           connectionEpoch: claim.connection.connectionEpoch,
           startupFenceSequence: claim.connection.startupFenceSequence,
@@ -1495,13 +1617,36 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
           replay: true,
         });
       }
-      const broker = buildSessionCodexRealtimeBroker(
-        db,
-        settings,
-        workspaceId,
-        sessionId,
-        deps.codexFetch,
-      );
+      try {
+        await realtimeVoiceBilling.admit({
+          accountId: grant.accountId,
+          workspaceId,
+          model: claim.mode.model,
+          attribution: creditDebitAttributionForGrant(grant),
+        });
+      } catch (error) {
+        const refused = realtimeVoiceRefusalResponse(c, error);
+        if (!refused) throw error;
+        await withWorkspaceRls(db, workspaceId, async (scopedDb) =>
+          scopedDb.transaction(async (tx) =>
+            failSessionRealtimeConnectionInTransaction(tx as unknown as Database, {
+              workspaceId,
+              sessionId,
+              realtimeId,
+              connectionId: claim.connection.id,
+              operationId,
+              connectionEpoch: claim.connection.connectionEpoch,
+              failureCode: "billing_refused",
+            }),
+          ),
+        ).catch(() => undefined);
+        return refused;
+      }
+      const broker = (
+        claim.mode.model === AZURE_LIVE_MODEL_ID
+          ? buildSessionAzureLiveBroker
+          : buildSessionCodexRealtimeBroker
+      )(db, settings, workspaceId, sessionId, deps.codexFetch);
       try {
         const answer = await broker({
           request: providerRequest,
@@ -1540,6 +1685,13 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
                 ),
               )
             : null;
+        await settleRealtimeVoice({
+          grant,
+          attribution: creditDebitAttributionForGrant(grant),
+          workspaceId,
+          sessionId,
+          realtimeId,
+        });
         return c.json({
           ...answer,
           connectionId: completed.connection.id,
@@ -1640,6 +1792,12 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
           "Realtime Gateway tokens are single-use; reconnect with a new operation",
         );
       }
+      await realtimeVoiceBilling.admit({
+        accountId: grant.accountId,
+        workspaceId,
+        model: claim.mode.model,
+        attribution: creditDebitAttributionForGrant(grant),
+      });
       const secret = await createGatewayRealtimeConnectionSecret({
         db,
         settings,
@@ -1663,6 +1821,13 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
         ),
       );
       connectionCompleted = true;
+      await settleRealtimeVoice({
+        grant,
+        attribution: creditDebitAttributionForGrant(grant),
+        workspaceId,
+        sessionId,
+        realtimeId,
+      });
       return c.json({
         ...secret,
         connectionId: completed.connection.id,
@@ -1684,11 +1849,18 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
               operationId,
               connectionEpoch: claimed.connection.connectionEpoch,
               failureCode:
-                error instanceof GatewayRealtimeBrokerError ? error.code : "gateway_error",
+                error instanceof GatewayRealtimeBrokerError
+                  ? error.code
+                  : error instanceof TranscriptionBillingRefusedError ||
+                      error instanceof RealtimeVoiceUnavailableError
+                    ? "billing_refused"
+                    : "gateway_error",
             }),
           ),
         ).catch(() => undefined);
       }
+      const refused = realtimeVoiceRefusalResponse(c, error);
+      if (refused) return refused;
       if (error instanceof SessionRealtimeConflictError) throw sessionRealtimeHttpError(error);
       if (!(error instanceof GatewayRealtimeBrokerError)) throw error;
       const status = error.code === "credential_unavailable" ? 409 : 502;
@@ -1897,29 +2069,37 @@ export function registerSessionRoutes(app: Hono, deps: SessionRouteDeps): void {
         });
       }
       try {
-        const result = await withWorkspaceSessionActivityRls(db, workspaceId, async (scopedDb) => {
-          // Acquire origin authority before inference/session locks. A deferred
-          // realtime session has no initial worker turn; capture its exact
-          // linked actor when the ledger actually admits ordinary agent work.
-          await beforeCommit?.(scopedDb as unknown as Database);
-          return syncSessionRealtimeLedgerInTransaction(
-            scopedDb,
-            {
-              workspaceId,
-              sessionId,
-              realtimeId,
-              ownerSubjectId: grant.subjectId,
-              ...parsed.data,
-              controlLockTimeoutMs: workspaceControlRequestLockTimeoutMs(),
-            },
-            captureLinked
-              ? {
-                  afterDelegationAdmission: async ({ turnId }) =>
-                    captureLinked(scopedDb as unknown as Database, sessionId, turnId),
-                }
-              : {},
-          );
-        });
+        const result = await withWorkspaceSessionActivityRls(
+          db,
+          workspaceId,
+          async (scopedDb) => {
+            // Acquire origin authority before inference/session locks. A deferred
+            // realtime session has no initial worker turn; capture its exact
+            // linked actor when the ledger actually admits ordinary agent work.
+            await beforeCommit?.(scopedDb as unknown as Database);
+            return syncSessionRealtimeLedgerInTransaction(
+              scopedDb,
+              {
+                workspaceId,
+                sessionId,
+                realtimeId,
+                ownerSubjectId: grant.subjectId,
+                ...parsed.data,
+                controlLockTimeoutMs: workspaceControlRequestLockTimeoutMs(),
+              },
+              captureLinked
+                ? {
+                    afterDelegationAdmission: async ({ turnId }) =>
+                      captureLinked(scopedDb as unknown as Database, sessionId, turnId),
+                  }
+                : {},
+            );
+          },
+          undefined,
+          // External reauthorization takes the organization-membership lock,
+          // which precedes the tenancy fence and the canonical session prefix.
+          Boolean(beforeCommit),
+        );
         await publishRealtimeMutation(grant.accountId, workspaceId, sessionId, result);
         c.header("cache-control", "private, no-store");
         return c.json({ accepted: result.accepted, outbound: result.outbound });
@@ -5021,11 +5201,19 @@ function codexRealtimeHttpFailure(error: CodexRealtimeBrokerError): {
   }
 }
 
-function sessionRealtimeHttpError(error: unknown): HTTPException {
+/** Conflicts a person can hit by starting voice; the browser shows these verbatim. */
+const SESSION_REALTIME_USER_MESSAGES: Partial<Record<string, string>> = {
+  REALTIME_ACTIVE:
+    "Voice is already on for this session in another tab or window. End it there, or try again in a minute.",
+  CONTROL_NOT_ACTIVE: "Resume this session to start voice.",
+  SESSION_CANCELLED: "This session was cancelled, so voice can't start.",
+};
+
+export function sessionRealtimeHttpError(error: unknown): HTTPException {
   if (error instanceof HTTPException) return error;
   if (error instanceof SessionRealtimeConflictError) {
     return new HTTPException(error.code === "REALTIME_NOT_FOUND" ? 404 : 409, {
-      message: error.message,
+      message: SESSION_REALTIME_USER_MESSAGES[error.code] ?? error.message,
       cause: error,
     });
   }
@@ -6045,9 +6233,18 @@ async function loadEffectivePolicyContext(
   subjectId: string,
   sessions: readonly Session[],
 ): Promise<EffectivePolicyContext> {
+  // Both projections read the same workspace row; hydrate it once.
+  const workspaceRead = requireWorkspace(deps.db, workspaceId);
+  void workspaceRead.catch(() => undefined);
   const [policy, effectiveToolsContext] = await Promise.all([
-    workspaceSessionToolPolicyContext(deps.db, workspaceId, deps.settings, subjectId),
-    workspaceSessionEffectiveToolsContext(deps, workspaceId, subjectId, sessions),
+    workspaceSessionToolPolicyContext(
+      deps.db,
+      workspaceId,
+      deps.settings,
+      subjectId,
+      workspaceRead,
+    ),
+    workspaceSessionEffectiveToolsContext(deps, workspaceId, subjectId, sessions, workspaceRead),
   ]);
   return { ...policy, effectiveToolsContext };
 }

package/src/routes/transcription-recordings.ts

@@ -15,6 +15,7 @@ import {
   normalizeMimeType,
   requireAccessGrant,
   TRANSCRIPTION_PROVIDER_REQUEST_TIMEOUT_MILLISECONDS,
+  TranscriptionBillingRefusedError,
   TranscriptionServiceError,
   type ApiRouteDeps,
 } from "@opengeni/core";
@@ -45,10 +46,13 @@ import {
   TranscriptionRecordingStateError,
   isSessionEventPersistenceError,
 } from "@opengeni/db";
-import { getWorkspace } from "@opengeni/db";
+import { getWorkspace, type CreditDebitAttribution } from "@opengeni/db";
 import type { Context, Hono } from "hono";
+import { creditDebitAttributionForGrant } from "../access-grant-rls";
 import { ApiHttpError } from "../http/api-error";
+import { wavDurationSeconds } from "../transcription/wav-duration";
 import { TranscriptionSegmenterError } from "../transcription/segmenter";
+import { transcriptionBillingRefusal } from "../transcription/billing-refusal";
 
 const CHUNK_SHA256_HEADER = "x-opengeni-chunk-sha256";
 const CHUNK_START_HEADER = "x-opengeni-chunk-start-milliseconds";
@@ -60,6 +64,8 @@ type RecordingAuthority = {
   workspaceId: string;
   subjectId: string;
   voiceInput?: WorkspaceVoiceInputSettings | undefined;
+  /** Trusted payer for deployment-funded segments. */
+  attribution: CreditDebitAttribution;
 };
 
 class RecordingProcessingError extends Error {
@@ -370,6 +376,8 @@ export function registerResumableTranscriptionRoutes(app: Hono, deps: ApiRouteDe
           !(await service.available({
             workspaceId: authority.workspaceId,
             subjectId: authority.subjectId,
+            preferredProvider: authority.voiceInput?.preferredProvider,
+            fallbackEnabled: authority.voiceInput?.fallbackEnabled,
           }))
         ) {
           return c.json({ code: "unavailable" }, 503);
@@ -420,6 +428,37 @@ export function registerResumableTranscriptionRoutes(app: Hono, deps: ApiRouteDe
             false,
           );
         }
+        const segmentProviderId =
+          claim.segment.providerId && claim.segment.providerId !== "host"
+            ? claim.segment.providerId
+            : null;
+        // Credit admission for the exact pinned provider, before the durable
+        // provider-start fence. A refusal releases the claim untouched (no
+        // audio sent) and surfaces 402 so the client stops retrying.
+        if (segmentProviderId && service.admit) {
+          try {
+            await service.admit({
+              providerId: segmentProviderId,
+              accountId: authority.accountId,
+              workspaceId: authority.workspaceId,
+              attribution: authority.attribution,
+            });
+          } catch (error) {
+            if (!(error instanceof TranscriptionBillingRefusedError)) throw error;
+            await failTranscriptionRecordingSegment(deps.db, {
+              workspaceId: authority.workspaceId,
+              subjectId: authority.subjectId,
+              recordingId: uuidParam(c, "recordingId"),
+              segmentNumber,
+              attemptId,
+              fallbackProviderId: null,
+              // The real refusal, so a reloaded recording still explains it.
+              errorCode: error.code,
+              retryable: true,
+            }).catch(() => null);
+            return transcriptionBillingRefusal(c, error);
+          }
+        }
         const providerStartedAt = new Date();
         const providerDeadlineAt = new Date(
           providerStartedAt.getTime() + TRANSCRIPTION_PROVIDER_REQUEST_TIMEOUT_MILLISECONDS,
@@ -442,10 +481,22 @@ export function registerResumableTranscriptionRoutes(app: Hono, deps: ApiRouteDe
           durationSeconds: claim.segment.durationMilliseconds / 1_000,
           requestId: attemptId,
           providerDeadlineAt,
-          ...(claim.segment.providerId && claim.segment.providerId !== "host"
-            ? { providerId: claim.segment.providerId }
-            : {}),
+          deferBillingSettlement: true,
+          ...(segmentProviderId ? { providerId: segmentProviderId } : {}),
+          billing: {
+            // One settlement per prepared segment of this exact recording,
+            // however many provider attempts it takes. The recording id is
+            // client-chosen, so the unit id also binds its server creation
+            // time and the server-produced segment bytes.
+            sourceId: `${claim.recording.recording.id}:${Date.parse(claim.recording.recording.createdAt)}:${segmentNumber}:${claim.segment.sha256}`,
+            attribution: authority.attribution,
+            trustedDurationSeconds: wavDurationSeconds(stored.bytes) ?? undefined,
+          },
         });
+        // The transcript commits first and on its own: a billing failure can
+        // never roll back text the user already waited for. Only the attempt
+        // that durably completed the segment settles it (a stale attempt is
+        // refused here and never charges); settlement itself never throws.
         const completed = await completeTranscriptionRecordingSegment(deps.db, {
           workspaceId: authority.workspaceId,
           subjectId: authority.subjectId,
@@ -456,6 +507,9 @@ export function registerResumableTranscriptionRoutes(app: Hono, deps: ApiRouteDe
           languages: result.languages,
           providerId: claim.segment.providerId ?? result.providerId,
         });
+        // Never rejects for the built-in service (it logs and retries); a
+        // custom service's failure must not turn a durable transcript into an error.
+        await result.settleBilling?.().catch(() => undefined);
         return c.json(await cleanupTerminalObjects(deps, authority, completed));
       } catch (error) {
         if (authority && attemptId && segmentNumber !== null) {
@@ -489,6 +543,11 @@ export function registerResumableTranscriptionRoutes(app: Hono, deps: ApiRouteDe
             errorCode: failure.code,
             retryable: failure.retryable,
           }).catch(() => null);
+          // A credit refusal sent no audio; the released segment stays
+          // retryable, but the client must see the definitive refusal.
+          if (error instanceof TranscriptionBillingRefusedError) {
+            return transcriptionBillingRefusal(c, error);
+          }
           if (persisted) return c.json(persisted);
         }
         return routeError(c, error);
@@ -545,6 +604,7 @@ async function requireRecordingAuthority(
     accountId: grant.accountId,
     workspaceId,
     subjectId: grant.subjectId,
+    attribution: creditDebitAttributionForGrant(grant),
   };
 }
 
@@ -641,6 +701,10 @@ function processingFailure(error: unknown): {
   if (error instanceof TranscriptionSegmenterError) {
     return { code: error.code, retryable: error.retryable };
   }
+  if (error instanceof TranscriptionBillingRefusedError) {
+    // Refused before any audio was sent; retryable once the payer is funded.
+    return { code: error.code, retryable: true };
+  }
   if (error instanceof TranscriptionServiceError) {
     return {
       code: error.code,
@@ -663,6 +727,9 @@ function routeError(c: Context, error: unknown): Response | Promise<Response> {
   if (error instanceof TranscriptionRecordingNotFoundError) {
     return c.json({ code: "not_found" }, 404);
   }
+  if (error instanceof TranscriptionBillingRefusedError) {
+    return transcriptionBillingRefusal(c, error);
+  }
   if (error instanceof TranscriptionRecordingConflictError) {
     return c.json({ code: "conflict" }, 409);
   }

package/src/routes/transcriptions.ts

@@ -3,9 +3,16 @@ import {
   WorkspaceVoiceInputSettings,
   type TranscribeAudioResponse,
 } from "@opengeni/contracts";
-import { type ApiRouteDeps, requireAccessGrant, TranscriptionServiceError } from "@opengeni/core";
+import {
+  type ApiRouteDeps,
+  requireAccessGrant,
+  TranscriptionBillingRefusedError,
+  TranscriptionServiceError,
+} from "@opengeni/core";
 import { getWorkspace } from "@opengeni/db";
 import type { Hono } from "hono";
+import { creditDebitAttributionForGrant } from "../access-grant-rls";
+import { transcriptionBillingRefusal } from "../transcription/billing-refusal";
 import { registerResumableTranscriptionRoutes } from "./transcription-recordings";
 
 export function registerTranscriptionRoutes(app: Hono, deps: ApiRouteDeps): void {
@@ -20,12 +27,26 @@ export function registerTranscriptionRoutes(app: Hono, deps: ApiRouteDeps): void
     }
     const preferences = WorkspaceVoiceInputSettings.safeParse(workspace.settings.voiceInput).data;
     const service = deps.transcription;
-    if (!service || !(await service.available({ workspaceId, subjectId: grant.subjectId }))) {
+    if (
+      !service ||
+      !(await service.available({
+        workspaceId,
+        subjectId: grant.subjectId,
+        preferredProvider: preferences?.preferredProvider,
+        fallbackEnabled: preferences?.fallbackEnabled,
+      }))
+    ) {
       return c.json({ code: "unavailable" }, 503);
     }
     try {
       const body = await audioRequest(c.req.raw, service.limits().maxSizeBytes);
+      // Server-generated: the correlation id is client-chosen and a reused
+      // settlement key would make every later call with it free.
       const result = await service.transcribe({
+        billing: {
+          sourceId: crypto.randomUUID(),
+          attribution: creditDebitAttributionForGrant(grant),
+        },
         preferredProvider: preferences?.preferredProvider,
         fallbackEnabled: preferences?.fallbackEnabled,
         workspaceId,
@@ -46,6 +67,9 @@ export function registerTranscriptionRoutes(app: Hono, deps: ApiRouteDeps): void
       if (error instanceof TranscriptionServiceError) {
         return c.json({ code: error.code }, error.status as never);
       }
+      if (error instanceof TranscriptionBillingRefusedError) {
+        return transcriptionBillingRefusal(c, error);
+      }
       if (isAbort(error)) return c.json({ code: "cancelled" }, 499 as never);
       return c.json({ code: "unknown" }, 500);
     }