@opengeni/api-router 1.3.0 → 1.4.0

package/src/routes/session-artifact-associations.ts

@@ -1,5 +1,6 @@
 import {
-  requireAccessGrant,
+  fileOwnerContextForAccess,
+  requireAccessGrantAuthorization,
   requirePermission,
   requireSessionAuthorization,
   SessionAuthorizationDeniedError,
@@ -7,10 +8,15 @@ import {
   type ApiRouteDeps,
 } from "@opengeni/core";
 import {
+  getGeneratedImageArtifact,
+  getGeneratedVideoArtifact,
+  getRetainedFileArtifact,
   hasEditableArtifactSessionLink,
   hasWorkspaceArtifactSessionLink,
+  listArtifactCatalogCandidates,
   transactionallyAuthorizeEditableArtifactActor,
   withRlsContext,
+  withSessionRlsActorContext,
 } from "@opengeni/db";
 import type { Hono } from "hono";
 import { HTTPException } from "hono/http-exception";
@@ -27,16 +33,26 @@ export function registerSessionArtifactAssociationRoutes(app: Hono, deps: ApiRou
     "/v1/workspaces/:workspaceId/sessions/:sessionId/artifact-associations/:artifactId",
     async (context) => {
       const workspaceId = context.req.param("workspaceId");
-      const grant = await requireAccessGrant(context, deps, workspaceId, "artifacts:read");
-      requirePermission(grant, "sessions:read");
       const sessionId = context.req.param("sessionId");
       const artifactId = context.req.param("artifactId");
+      const requestedKind = context.req.query("kind");
+      // A UUID names a Site unless the caller asks for a retained artifact
+      // (generated image or video, or a published sandbox file) explicitly.
       const kind = EditableArtifactId.safeParse(artifactId).success
         ? "editable"
         : SessionId.safeParse(artifactId).success
-          ? "site"
+          ? requestedKind === "retained"
+            ? "retained"
+            : "site"
           : null;
-      const requestedKind = context.req.query("kind");
+      const authorization = await requireAccessGrantAuthorization(
+        context,
+        deps,
+        workspaceId,
+        kind === "retained" ? "files:read" : "artifacts:read",
+      );
+      const grant = authorization.grant;
+      requirePermission(grant, "sessions:read");
       if (
         !SessionId.safeParse(sessionId).success ||
         !kind ||
@@ -55,7 +71,20 @@ export function registerSessionArtifactAssociationRoutes(app: Hono, deps: ApiRou
           const linked =
             kind === "editable"
               ? await hasEditableArtifactSessionLink(deps.db, scope, sessionId, artifactId)
-              : await hasWorkspaceArtifactSessionLink(deps.db, workspaceId, sessionId, artifactId);
+              : kind === "retained"
+                ? await hasRetainedArtifactSessionLink(
+                    deps,
+                    authorization,
+                    workspaceId,
+                    sessionId,
+                    artifactId.toLowerCase(),
+                  )
+                : await hasWorkspaceArtifactSessionLink(
+                    deps.db,
+                    workspaceId,
+                    sessionId,
+                    artifactId,
+                  );
           if (!linked) throw new HTTPException(404, { message: "Artifact association not found" });
           if (kind === "editable") {
             const decision = await withRlsContext(deps.db, scope, (tx) =>
@@ -85,3 +114,48 @@ export function registerSessionArtifactAssociationRoutes(app: Hono, deps: ApiRou
     },
   );
 }
+
+/**
+ * Whether a retained artifact originated in this exact session: a generated
+ * image or video the session produced, or a sandbox file it published. Never
+ * inferred from an artifact id appearing in a message.
+ */
+async function hasRetainedArtifactSessionLink(
+  deps: ApiRouteDeps,
+  authorization: Awaited<ReturnType<typeof requireAccessGrantAuthorization>>,
+  workspaceId: string,
+  sessionId: string,
+  artifactId: string,
+): Promise<boolean> {
+  const image = await getGeneratedImageArtifact(deps.db, workspaceId, artifactId);
+  if (image) return image.sessionId === sessionId;
+  const video = await getGeneratedVideoArtifact(deps.db, workspaceId, artifactId);
+  if (video) return !video.artifact.deletedAt && video.artifact.sessionId === sessionId;
+  const file = await getRetainedFileArtifact(deps.db, workspaceId, artifactId);
+  if (!file) return false;
+  // Publication receipts are private; the bounded catalog seam filters them
+  // by source session and this file's name, then the exact id must match.
+  const grant = authorization.grant;
+  const actor = await fileOwnerContextForAccess(deps, authorization, "files:read");
+  const candidates = await withSessionRlsActorContext(actor, () =>
+    listArtifactCatalogCandidates(
+      deps.db,
+      { accountId: grant.accountId, workspaceId },
+      {
+        query: {
+          sourceSessionId: sessionId,
+          q: file.file.filename.slice(0, 200),
+          sort: "newest",
+          status: "active",
+          limit: 100,
+        },
+        kinds: ["file", "image"],
+        snapshotAt: new Date().toISOString(),
+        limit: 201,
+      },
+    ),
+  );
+  return candidates.some(
+    (candidate) => candidate.origin === "sandbox_file" && candidate.id === artifactId,
+  );
+}

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";
@@ -9,6 +10,14 @@ import { SessionMessageSearchRequest } from "@opengeni/contracts";
 import { 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,
@@ -1307,6 +1368,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 +1428,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 +1445,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 +1493,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 +1535,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 +1597,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 +1605,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 +1673,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 +1780,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 +1809,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 +1837,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;

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