@opengeni/core 1.3.0 → 1.4.2

package/src/domain/sessions.ts

@@ -42,6 +42,7 @@ import {
   ORGANIZATION_GATEWAY_MODEL_ID_PREFIX,
   ORGANIZATION_OPENROUTER_MODEL_ID_PREFIX,
   allowedFirstPartyMcpToolsForSession,
+  deploymentUnavailableFirstPartyMcpTools,
   resolveFirstPartyMcpToolPolicy,
   policyProviderIdForModel,
   resolveTurnExecutionPolicyV1,
@@ -2051,6 +2052,11 @@ export async function postUserMessageTurn(
                 : {}),
               controlLockTimeoutMs: workspaceControlRequestLockTimeoutMs(),
             }),
+          undefined,
+          "shared",
+          // Linked-actor capture reauthorizes under the organization-membership
+          // lock; take it before the tenancy fence and the canonical prefix.
+          Boolean(input.captureTurnAuthority),
         ),
     );
   } catch (error) {
@@ -2410,6 +2416,14 @@ async function createSessionForRequestInFileScope(
   requestOptions: SessionCreateRequestOptions = {},
 ): Promise<CreateSessionRequestOutcome> {
   const payload = CreateSessionRequest.parse(rawPayload);
+  // A tool whose backing workload this deployment does not run is dropped, not
+  // rejected: a client echoing a full catalog must not fail on a deployment fact.
+  if (payload.firstPartyMcpTools) {
+    const unavailable = deploymentUnavailableFirstPartyMcpTools(unresolvedDeps.settings);
+    payload.firstPartyMcpTools = payload.firstPartyMcpTools.filter(
+      (tool) => !unavailable.has(tool),
+    );
+  }
   // Read before any await: the Site scope is request-local provenance.
   const surface = resolveTurnSurface({
     grant,
@@ -2581,27 +2595,35 @@ async function createSessionForRequestInFileScope(
     payload.idempotencyKey &&
     (effectiveVisibility !== "user_private" || replayManagedHumanSubjectId !== null)
   ) {
+    const createIdempotencyKey = payload.idempotencyKey;
     try {
-      const initializedReplay = await getInitializedSessionCreateReplay(db, {
-        bundledSkillIds,
-        accountId: grant.accountId,
-        workspaceId,
-        subjectId: replayManagedHumanSubjectId ?? grant.subjectId,
-        ...(replayManagedHumanSubjectId
-          ? { activeManagedHumanSubjectId: replayManagedHumanSubjectId }
-          : {}),
-        createIdempotencyKey: payload.idempotencyKey,
-        selectedInstalledSkillIds: payload.installedSkillIds ?? [],
-        initialAgentLearning: payload.agentLearning,
-        ...sessionScope,
+      const initializedReplay = await measureSessionStartPhase(
+        unresolvedDeps.observability,
+        "idempotent_replay",
+        () =>
+          getInitializedSessionCreateReplay(db, {
+            bundledSkillIds,
+            accountId: grant.accountId,
+            workspaceId,
+            subjectId: replayManagedHumanSubjectId ?? grant.subjectId,
+            ...(replayManagedHumanSubjectId
+              ? { activeManagedHumanSubjectId: replayManagedHumanSubjectId }
+              : {}),
+            createIdempotencyKey,
+            selectedInstalledSkillIds: payload.installedSkillIds ?? [],
+            initialAgentLearning: payload.agentLearning,
+            ...sessionScope,
 
-        ...(payload.requestedSessionId ? { requestedSessionId: payload.requestedSessionId } : {}),
-        visibility: effectiveVisibility,
-        variableSetIds: payload.variableSetIds ?? [],
-        initialPersonalResourceAttachmentIntent: payload.personalResourceAttachment ?? null,
-        deferInitialTurn: payload.startMode === "realtime",
-        agentConfig,
-      });
+            ...(payload.requestedSessionId
+              ? { requestedSessionId: payload.requestedSessionId }
+              : {}),
+            visibility: effectiveVisibility,
+            variableSetIds: payload.variableSetIds ?? [],
+            initialPersonalResourceAttachmentIntent: payload.personalResourceAttachment ?? null,
+            deferInitialTurn: payload.startMode === "realtime",
+            agentConfig,
+          }),
+      );
       if (initializedReplay) {
         if (initializedReplay.outcome === "denied") {
           throw new SessionSpawnDeniedError(SessionSpawnDenial.parse(initializedReplay.denial));
@@ -2979,36 +3001,43 @@ async function createSessionForRequestInFileScope(
   const tools = withFirstPartyTools(selectedTools, runtimeSettings);
 
   const captureLinkedAuthority = prepareExternalLinkTurnAdmission(authorization);
-  await validateGitHubRepositorySelection(db, workspaceId, resources);
-  if (resources.some((resource) => resource.kind === "file") && !objectStorage) {
-    throw new HTTPException(503, {
-      message: "object storage is not configured",
-    });
-  }
-  const attachmentOwnerContext = authorization
-    ? await fileOwnerContextForAccess({ db }, authorization, "sessions:create")
-    : grant.principalKind === "agent_attempt"
-      ? await fileOwnerContextForAgent({ db }, grant, "sessions:create")
-      : undefined;
+  const { attachmentOwnerContext, variableSets } = await measureSessionStartPhase(
+    unresolvedDeps.observability,
+    "resource_validation",
+    async () => {
+      await validateGitHubRepositorySelection(db, workspaceId, resources);
+      if (resources.some((resource) => resource.kind === "file") && !objectStorage) {
+        throw new HTTPException(503, {
+          message: "object storage is not configured",
+        });
+      }
+      const ownerContext = authorization
+        ? await fileOwnerContextForAccess({ db }, authorization, "sessions:create")
+        : grant.principalKind === "agent_attempt"
+          ? await fileOwnerContextForAgent({ db }, grant, "sessions:create")
+          : undefined;
+      await validateFileResources(
+        db,
+        grant.accountId,
+        workspaceId,
+        personalResourceSubjectId ?? grant.subjectId,
+        resources,
+        ownerContext,
+      );
+      // Every selected Variable Set is independently authorized. Scope does not
+      // affect precedence: explicit order is low-to-high and later sets win name
+      // collisions.
+      const validatedVariableSets: VariableSet[] = [];
+      for (const variableSetId of payload.variableSetIds ?? []) {
+        validatedVariableSets.push(
+          await validateVariableSetAttachment({ settings, db }, grant, workspaceId, variableSetId),
+        );
+      }
+      return { attachmentOwnerContext: ownerContext, variableSets: validatedVariableSets };
+    },
+  );
   const attachmentOwner =
     attachmentOwnerContext?.privateFileOwnerSubjectId === grant.subjectId ? grant.subjectId : null;
-  await validateFileResources(
-    db,
-    grant.accountId,
-    workspaceId,
-    personalResourceSubjectId ?? grant.subjectId,
-    resources,
-    attachmentOwnerContext,
-  );
-  // Every selected Variable Set is independently authorized. Scope does not
-  // affect precedence: explicit order is low-to-high and later sets win name
-  // collisions.
-  const variableSets: VariableSet[] = [];
-  for (const variableSetId of payload.variableSetIds ?? []) {
-    variableSets.push(
-      await validateVariableSetAttachment({ settings, db }, grant, workspaceId, variableSetId),
-    );
-  }
   // RIG BINDING (M3). Resolve the rig this session rides — a UUID binds that
   // rig, null explicitly opts out, and omission inherits the workspace default
   // (workspaces.default_rig_id) — then FREEZE both the rig id and its currently-
@@ -3020,22 +3049,27 @@ async function createSessionForRequestInFileScope(
   //   - A stale workspace-default rig (deleted → FK-nulled, or somehow with no
   //     active version) degrades SILENTLY to rig-less: an operator-side default
   //     must never brick every create in the workspace.
-  const requestedRigId =
-    payload.rigId === undefined ? await getWorkspaceDefaultRigId(db, workspaceId) : payload.rigId;
-  let frozenRigId: string | null = null;
-  let frozenRigVersionId: string | null = null;
-  if (requestedRigId) {
-    const rig = await getRig(db, grant, requestedRigId);
-    if (!rig || !rig.activeVersion) {
-      if (payload.rigId) {
-        throw new HTTPException(422, {
-          message: rig
-            ? `sandbox environment ${payload.rigId} has no active version to bind`
-            : `unknown rigId: ${payload.rigId}`,
-        });
+  const { frozenRigId, frozenRigVersionId } = await measureSessionStartPhase(
+    unresolvedDeps.observability,
+    "rig_binding",
+    async () => {
+      const requestedRigId =
+        payload.rigId === undefined
+          ? await getWorkspaceDefaultRigId(db, workspaceId)
+          : payload.rigId;
+      if (!requestedRigId) return { frozenRigId: null, frozenRigVersionId: null };
+      const rig = await getRig(db, grant, requestedRigId);
+      if (!rig || !rig.activeVersion) {
+        if (payload.rigId) {
+          throw new HTTPException(422, {
+            message: rig
+              ? `sandbox environment ${payload.rigId} has no active version to bind`
+              : `unknown rigId: ${payload.rigId}`,
+          });
+        }
+        // else: workspace-default fallback that no longer resolves → rig-less.
+        return { frozenRigId: null, frozenRigVersionId: null };
       }
-      // else: workspace-default fallback that no longer resolves → rig-less.
-    } else {
       for (const defaultVariableSetId of new Set(rig.activeVersion.defaultVariableSetIds)) {
         await validateVariableSetAttachment(
           { settings, db },
@@ -3044,10 +3078,12 @@ async function createSessionForRequestInFileScope(
           defaultVariableSetId,
         );
       }
-      frozenRigId = rig.id;
-      frozenRigVersionId = rig.activeVersion.id;
-    }
-  }
+      return {
+        frozenRigId: rig.id as string | null,
+        frozenRigVersionId: rig.activeVersion.id as string | null,
+      };
+    },
+  );
   // CHANNEL FILING. Pure rail organization: a UUID files the session into that
   // workspace channel, omission/null leaves it unfiled (inbox). Resolved
   // workspace-scoped so a foreign channel id can never attach; an explicit
@@ -3076,25 +3112,27 @@ async function createSessionForRequestInFileScope(
   // inherited calling-turn model, or deployment default — so the policy must
   // vet that effective value, not just explicit ones (a restricted workspace's
   // inherited/default-model session would otherwise be born blocked).
-  await assertWorkspaceModelPolicyAllows(db, settings, workspaceId, model);
-  // Direct creation is a fresh model selection. Child inheritance and keyed
-  // repair preserve the existing accepted-model/authority rules.
-  if (retainedKeyedShellModel === null && !parentSession) {
-    const selections = await resolveCallerWorkspaceModelSelections(db, settings, {
-      accountId: grant.accountId,
-      workspaceId,
-      subjectId: personalResourceSubjectId ?? grant.subjectId,
-      ...(xaiProviderAccountAuthoritySnapshot
-        ? { xaiAuthoritySnapshot: xaiProviderAccountAuthoritySnapshot }
-        : {}),
-      ...(claudeProviderAccountAuthoritySnapshot
-        ? { claudeAuthoritySnapshot: claudeProviderAccountAuthoritySnapshot }
-        : {}),
-    });
-    if (!admissibleWorkspaceModel(selections, model)) {
-      throw new HTTPException(422, { message: `model is not selectable: ${model}` });
+  await measureSessionStartPhase(unresolvedDeps.observability, "model_admission", async () => {
+    await assertWorkspaceModelPolicyAllows(db, settings, workspaceId, model);
+    // Direct creation is a fresh model selection. Child inheritance and keyed
+    // repair preserve the existing accepted-model/authority rules.
+    if (retainedKeyedShellModel === null && !parentSession) {
+      const selections = await resolveCallerWorkspaceModelSelections(db, settings, {
+        accountId: grant.accountId,
+        workspaceId,
+        subjectId: personalResourceSubjectId ?? grant.subjectId,
+        ...(xaiProviderAccountAuthoritySnapshot
+          ? { xaiAuthoritySnapshot: xaiProviderAccountAuthoritySnapshot }
+          : {}),
+        ...(claudeProviderAccountAuthoritySnapshot
+          ? { claudeAuthoritySnapshot: claudeProviderAccountAuthoritySnapshot }
+          : {}),
+      });
+      if (!admissibleWorkspaceModel(selections, model)) {
+        throw new HTTPException(422, { message: `model is not selectable: ${model}` });
+      }
     }
-  }
+  });
   const inheritedReasoningEffort =
     parentCallingTurn?.reasoningEffort ??
     parentSession?.reasoningEffort ??
@@ -3298,18 +3336,23 @@ async function createSessionForRequestInFileScope(
       workspace.settings,
     ),
   });
-  const { personalConnectionDelegations, mcpAccountBindings } = await freezeConnectionAccounts({
-    db,
-    accountId: grant.accountId,
-    workspaceId,
-    settings: runtimeSettings,
-    tools: connectionAccountTools,
-    resources,
-    source: connectionDelegationSource,
-    authoritySelections: payload.connectionAccounts,
-    googleDrivePublicationEnabled,
-    atlassianEnabled,
-  });
+  const { personalConnectionDelegations, mcpAccountBindings } = await measureSessionStartPhase(
+    unresolvedDeps.observability,
+    "connection_freeze",
+    () =>
+      freezeConnectionAccounts({
+        db,
+        accountId: grant.accountId,
+        workspaceId,
+        settings: runtimeSettings,
+        tools: connectionAccountTools,
+        resources,
+        source: connectionDelegationSource,
+        authoritySelections: payload.connectionAccounts,
+        googleDrivePublicationEnabled,
+        atlassianEnabled,
+      }),
+  );
   if (effectiveGoal) {
     const missingGoalTools = ["goal_update", "goal_progress", "goal_complete", "goal_pause"].filter(
       (name) => !firstPartyMcpTools.includes(name as FirstPartyMcpToolName),
@@ -4249,6 +4292,10 @@ async function acceptSessionUserMessageInFileScope(
         (await requireWorkspace(db, workspaceId)).settings,
       ),
     });
+    const existingEffectiveFirstPartyTools = allowedFirstPartyMcpToolsForSession(
+      settings,
+      existingSession.firstPartyMcpTools,
+    );
     const { personalConnectionDelegations, mcpAccountBindings } = await freezeConnectionAccounts({
       db,
       accountId: grant.accountId,
@@ -4259,8 +4306,8 @@ async function acceptSessionUserMessageInFileScope(
       source: connectionDelegationSource,
       targetSessionId: sessionId,
       googleDrivePublicationEnabled:
-        existingSession.firstPartyMcpTools.includes("editable_artifact_export") &&
-        existingSession.firstPartyMcpTools.includes("editable_artifact_export_status") &&
+        existingEffectiveFirstPartyTools.includes("editable_artifact_export") &&
+        existingEffectiveFirstPartyTools.includes("editable_artifact_export_status") &&
         (!existingSession.firstPartyMcpPermissions?.length ||
           (existingSession.firstPartyMcpPermissions.includes("artifacts:read") &&
             existingSession.firstPartyMcpPermissions.includes("artifacts:publish"))),

package/src/domain/voice-input-billing.ts

@@ -0,0 +1,315 @@
+import {
+  calculateVoiceInputCost,
+  configuredStaticUsageLimits,
+  voiceInputCreditBillingActive,
+  voiceInputPricingHasTokenRates,
+  type Settings,
+  type VoiceInputPricing,
+  type VoiceInputUsage,
+} from "@opengeni/config";
+import {
+  applyCreditDebitAfterUse,
+  checkWorkspaceAllowance,
+  creditDebitAttributionMetadata,
+  getSpendableCreditBalance,
+  listUnsettledVoiceTranscriptionCharges,
+  recordUsageEvent,
+  sumUsageQuantity,
+  VOICE_TRANSCRIPTION_DEBIT_TYPE,
+  VOICE_TRANSCRIPTION_SOURCE_TYPE,
+  voiceTranscriptionSettlementKeys,
+  VOICE_CREDIT_USAGE,
+  type CreditDebitAttribution,
+  type Database,
+} from "@opengeni/db";
+import {
+  TranscriptionBillingRefusedError,
+  TranscriptionServiceError,
+  type TranscriptionBilling,
+  type TranscriptionBillingContext,
+} from "../transcription";
+import { voiceCreditStanding, voiceInsufficientCreditsMessage } from "./realtime-voice-billing";
+
+/** Credit debit type and usage source for deployment-funded voice input. */
+export const VOICE_INPUT_DEBIT_TYPE = VOICE_TRANSCRIPTION_DEBIT_TYPE;
+export const VOICE_INPUT_SOURCE_TYPE = VOICE_TRANSCRIPTION_SOURCE_TYPE;
+
+/** How the billed quantity was measured; recorded on the ledger entry. */
+export type VoiceInputBillingBasis =
+  | "provider_tokens"
+  | "provider_duration"
+  | "server_duration"
+  | "reconciled_receipt";
+
+/**
+ * Pick the billed measurement. Provider usage wins when this deployment can
+ * price it (token usage with token rates, or a reported duration). Otherwise
+ * the duration the server measured from WAV bytes it produced bills. Every
+ * deployment-funded call carries that server duration, so an unpriced usage
+ * shape never leaves a call unbillable. A client-reported duration is never a
+ * billing input.
+ */
+export function voiceInputBillableUsage(input: {
+  pricing: VoiceInputPricing;
+  usage: VoiceInputUsage | null;
+  trustedDurationSeconds?: number | undefined;
+}): { usage: VoiceInputUsage; basis: VoiceInputBillingBasis } {
+  if (input.usage?.kind === "tokens" && voiceInputPricingHasTokenRates(input.pricing)) {
+    return { usage: input.usage, basis: "provider_tokens" };
+  }
+  if (input.usage?.kind === "duration") {
+    return { usage: input.usage, basis: "provider_duration" };
+  }
+  if (
+    input.trustedDurationSeconds !== undefined &&
+    Number.isFinite(input.trustedDurationSeconds) &&
+    input.trustedDurationSeconds >= 0
+  ) {
+    return {
+      usage: { kind: "duration", seconds: input.trustedDurationSeconds },
+      basis: "server_duration",
+    };
+  }
+  throw new TranscriptionServiceError({
+    code: "provider",
+    message: "Transcription usage was not reported.",
+  });
+}
+
+function initiatingHuman(attribution: CreditDebitAttribution): string | null {
+  return attribution.kind === "human" || attribution.kind === "turn"
+    ? attribution.initiatingHumanSubjectId
+    : null;
+}
+
+function startOfUtcMonth(): Date {
+  const now = new Date();
+  return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), 1));
+}
+
+/**
+ * Same admission shape as knowledge-search and session admission:
+ * voice-spendable credits (general plus signup, not model-scoped promotional
+ * credits) must be positive, the workspace/member
+ * allowance must not be exhausted, and a static monthly cost cap applies.
+ * Admission is a read, not a reservation; settlement is post-use and may take
+ * an account below zero by at most the concurrent in-flight calls.
+ */
+export function createVoiceInputBilling(deps: {
+  db: Database;
+  settings: Settings;
+  /** Reconciliation is best-effort at admission; failures are reported here. */
+  onReconcileError?: (error: unknown, scope: { accountId: string; workspaceId: string }) => void;
+  /** Minimum spacing of admission-time reconciliation per workspace (default 5 min). */
+  reconcileIntervalMilliseconds?: number;
+}): TranscriptionBilling {
+  const reconcileInterval = deps.reconcileIntervalMilliseconds ?? 5 * 60_000;
+  const lastReconciled = new Map<string, number>();
+  const reconcileDue = (key: string) => {
+    const now = Date.now();
+    const last = lastReconciled.get(key);
+    if (last !== undefined && now - last < reconcileInterval) return false;
+    if (lastReconciled.size >= 10_000) lastReconciled.clear();
+    lastReconciled.set(key, now);
+    return true;
+  };
+  return {
+    async admit({ accountId, workspaceId, attribution }) {
+      if (!voiceInputCreditBillingActive(deps.settings)) return;
+      if (attribution.kind === "unknown") {
+        // Not a microphone problem: the caller's credential has no payer the
+        // ledger can attribute, so the deployment refuses by policy.
+        throw new TranscriptionServiceError({
+          code: "policy_blocked",
+          status: 403,
+          message: "Voice input payer could not be verified.",
+        });
+      }
+      // Debits whose receipt committed but whose ledger write failed are
+      // applied before the balance read, so unsettled use counts against it.
+      // Throttled per workspace: failed debits are rare, the scan is not free.
+      if (reconcileDue(`${accountId}:${workspaceId}`)) {
+        await reconcileUnsettledVoiceInputCharges(deps.db, { accountId, workspaceId }).catch(
+          (error: unknown) => {
+            deps.onReconcileError?.(error, { accountId, workspaceId });
+          },
+        );
+      }
+      const balance = await getSpendableCreditBalance(deps.db, accountId, VOICE_CREDIT_USAGE);
+      if (balance.balanceMicros <= 0) {
+        throw new TranscriptionBillingRefusedError({
+          code: "insufficient_credits",
+          message: voiceInsufficientCreditsMessage("Voice input", voiceCreditStanding(balance)),
+        });
+      }
+      const refusal = await checkWorkspaceAllowance(deps.db, {
+        accountId,
+        workspaceId,
+        subjectId: initiatingHuman(attribution),
+      });
+      if (refusal) {
+        throw new TranscriptionBillingRefusedError({
+          code: refusal.code,
+          message: refusal.message,
+          details: {
+            scope: refusal.scope,
+            resetsAt: refusal.resetsAt,
+            ...(refusal.subjectId ? { subjectId: refusal.subjectId } : {}),
+          },
+        });
+      }
+      if (
+        deps.settings.usageLimitsMode === "static" ||
+        deps.settings.usageLimitsMode === "managed"
+      ) {
+        const cap = configuredStaticUsageLimits(deps.settings).maxMonthlyCostMicrosPerAccount;
+        if (cap) {
+          const used = await sumUsageQuantity(deps.db, {
+            accountId,
+            eventType: "model.cost",
+            since: startOfUtcMonth(),
+          });
+          if (used >= cap) {
+            throw new TranscriptionBillingRefusedError({
+              code: "monthly_model_cost_limit",
+              message: "The monthly model cost limit has been reached.",
+            });
+          }
+        }
+      }
+    },
+
+    async settle(input) {
+      if (!voiceInputCreditBillingActive(deps.settings)) return { creditCostMicros: 0 };
+      const { usage, basis } = voiceInputBillableUsage({
+        pricing: input.pricing,
+        usage: input.usage,
+        trustedDurationSeconds: input.billing.trustedDurationSeconds,
+      });
+      const cost = calculateVoiceInputCost(input.pricing, usage);
+      return await settleVoiceInputUsage(deps.db, {
+        accountId: input.accountId,
+        workspaceId: input.workspaceId,
+        providerId: input.providerId,
+        model: input.model,
+        billing: input.billing,
+        usage,
+        basis,
+        providerCostMicros: cost.providerCostMicros,
+        creditCostMicros: cost.creditCostMicros,
+      });
+    },
+  };
+}
+
+/**
+ * Two commits, in order: the `model.cost` usage receipt (Insights spend,
+ * monthly cost cap, member-allowance attribution), then the post-use credit
+ * debit. The receipt is the first-writer authority for the amount and the
+ * durable record of the charge: if the debit commit fails, the receipt stays
+ * and {@link reconcileUnsettledVoiceInputCharges} applies the same debit (same
+ * idempotency key) on the workspace's next admission. A retried unit settles
+ * exactly once at the originally recorded price.
+ */
+export async function settleVoiceInputUsage(
+  db: Database,
+  input: {
+    accountId: string;
+    workspaceId: string;
+    providerId: string;
+    model: string;
+    billing: TranscriptionBillingContext;
+    usage: VoiceInputUsage;
+    basis: VoiceInputBillingBasis;
+    providerCostMicros: number;
+    creditCostMicros: number;
+  },
+): Promise<{ creditCostMicros: number }> {
+  const attribution = input.billing.attribution;
+  const keys = voiceTranscriptionSettlementKeys({
+    workspaceId: input.workspaceId,
+    sourceId: input.billing.sourceId,
+  });
+  const receipt = await recordUsageEvent(db, {
+    accountId: input.accountId,
+    workspaceId: input.workspaceId,
+    eventType: "model.cost",
+    quantity: input.creditCostMicros,
+    unit: "usd_micros",
+    sourceResourceType: VOICE_TRANSCRIPTION_SOURCE_TYPE,
+    sourceResourceId: input.billing.sourceId,
+    idempotencyKey: keys.usageIdempotencyKey,
+    // The API is the writer; the payer is the trusted attribution snapshot.
+    initiator: { kind: "service", subjectId: "api:voice-input" },
+    initiatorContext: { creditDebitAttribution: attribution },
+  });
+  const amount = Number(receipt.quantity);
+  if (amount > 0) {
+    await applyCreditDebitAfterUse(db, {
+      accountId: input.accountId,
+      workspaceId: input.workspaceId,
+      type: VOICE_TRANSCRIPTION_DEBIT_TYPE,
+      amountMicros: amount,
+      sourceType: VOICE_TRANSCRIPTION_SOURCE_TYPE,
+      sourceId: input.billing.sourceId,
+      idempotencyKey: keys.debitIdempotencyKey,
+      usage: VOICE_CREDIT_USAGE,
+      metadata: {
+        providerId: input.providerId,
+        model: input.model,
+        basis: input.basis,
+        providerCostMicros: input.providerCostMicros,
+        ...(input.usage.kind === "tokens"
+          ? {
+              inputTokens: input.usage.inputTokens,
+              audioInputTokens: input.usage.audioInputTokens,
+              textInputTokens: input.usage.textInputTokens,
+              outputTokens: input.usage.outputTokens,
+            }
+          : { audioMilliseconds: Math.ceil(input.usage.seconds * 1_000) }),
+        ...(attribution.kind === "unknown" ? {} : creditDebitAttributionMetadata(attribution)),
+      },
+    });
+  }
+  return { creditCostMicros: amount };
+}
+
+/**
+ * Apply the debit for every voice usage receipt in this workspace whose debit
+ * never committed. Idempotent with the inline settlement (same key), bounded
+ * per call, and safe to run concurrently.
+ */
+export async function reconcileUnsettledVoiceInputCharges(
+  db: Database,
+  input: { accountId: string; workspaceId: string; minAgeMilliseconds?: number },
+): Promise<{ reconciled: number }> {
+  const pending = await listUnsettledVoiceTranscriptionCharges(db, {
+    accountId: input.accountId,
+    workspaceId: input.workspaceId,
+    ...(input.minAgeMilliseconds !== undefined
+      ? { minAgeMilliseconds: input.minAgeMilliseconds }
+      : {}),
+  });
+  for (const charge of pending) {
+    await applyCreditDebitAfterUse(db, {
+      accountId: input.accountId,
+      workspaceId: input.workspaceId,
+      type: VOICE_TRANSCRIPTION_DEBIT_TYPE,
+      amountMicros: charge.amountMicros,
+      sourceType: VOICE_TRANSCRIPTION_SOURCE_TYPE,
+      sourceId: charge.sourceId,
+      idempotencyKey: voiceTranscriptionSettlementKeys({
+        workspaceId: input.workspaceId,
+        sourceId: charge.sourceId,
+      }).debitIdempotencyKey,
+      usage: VOICE_CREDIT_USAGE,
+      metadata: {
+        basis: "reconciled_receipt" satisfies VoiceInputBillingBasis,
+        ...(charge.attribution.kind === "unknown"
+          ? {}
+          : creditDebitAttributionMetadata(charge.attribution)),
+      },
+    });
+  }
+  return { reconciled: pending.length };
+}