@opengeni/db 1.4.0 → 1.4.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/db",
-  "version": "1.4.0",
+  "version": "1.4.4",
   "description": "OpenGeni persistence: Drizzle schema, RLS-scoped query layer, the SQL migration runner, and role provisioning.",
   "license": "Apache-2.0",
   "repository": {
@@ -115,12 +115,12 @@
     "prepublishOnly": "bash ../../scripts/prepublish-guard"
   },
   "dependencies": {
-    "@opengeni/codemode": "1.4.0",
-    "@opengeni/codex": "1.4.0",
-    "@opengeni/config": "1.4.0",
-    "@opengeni/contracts": "1.4.0",
-    "@opengeni/network": "1.4.0",
-    "@opengeni/observability": "1.4.0",
+    "@opengeni/codemode": "1.4.4",
+    "@opengeni/codex": "1.4.4",
+    "@opengeni/config": "1.4.4",
+    "@opengeni/contracts": "1.4.4",
+    "@opengeni/network": "1.4.4",
+    "@opengeni/observability": "1.4.4",
     "drizzle-orm": "^0.45.2",
     "postgres": "^3.4.7"
   },

package/src/codemode-approvals.ts

@@ -277,7 +277,13 @@ export async function adoptCodemodeApproval(
   );
 }
 
-/** Read a handle with the current exact attempt and same original caller; old bearer authority is insufficient. */
+/**
+ * Read a handle with the current exact attempt and same original caller; old
+ * bearer authority is insufficient. This is a status read polled while a
+ * caller waits, so it is one plain snapshot select: it proves the exact live
+ * attempt in the same statement but takes no session/turn/attempt row locks
+ * and is not refused by a pending Pause/Steer, which owns the write fence only.
+ */
 export async function readTurnCodemodeOperation(
   db: Database,
   input: CodemodeContinuationScope & {
@@ -285,27 +291,51 @@ export async function readTurnCodemodeOperation(
     callerSubjectId: string;
   },
 ): Promise<CodemodeOperation | null> {
-  return await withRlsContext(
-    db,
-    input,
-    async (scoped) =>
-      await scoped.transaction(async (tx) => {
-        await lockActiveTurn(tx as unknown as Database, input);
-        const [row] = await tx
-          .select()
-          .from(schema.sessionAttemptCodemodeCalls)
-          .where(
-            and(
-              eq(schema.sessionAttemptCodemodeCalls.workspaceId, input.workspaceId),
-              eq(schema.sessionAttemptCodemodeCalls.sessionId, input.sessionId),
-              eq(schema.sessionAttemptCodemodeCalls.turnId, input.turnId),
-              eq(schema.sessionAttemptCodemodeCalls.operationId, input.operationId),
-            ),
-          )
-          .limit(1);
-        return row && codemodeCallerCanContinue(row, input) ? mapCodemodeOperation(row) : null;
-      }),
-  );
+  return await withRlsContext(db, input, async (scoped) => {
+    const [live] = await scoped
+      .select({ attemptId: schema.sessionTurnAttempts.id })
+      .from(schema.sessionTurns)
+      .innerJoin(
+        schema.sessionTurnAttempts,
+        and(
+          eq(schema.sessionTurnAttempts.id, schema.sessionTurns.activeAttemptId),
+          eq(schema.sessionTurnAttempts.turnId, schema.sessionTurns.id),
+          eq(schema.sessionTurnAttempts.sessionId, schema.sessionTurns.sessionId),
+          eq(schema.sessionTurnAttempts.accountId, schema.sessionTurns.accountId),
+          eq(
+            schema.sessionTurnAttempts.executionGeneration,
+            schema.sessionTurns.executionGeneration,
+          ),
+        ),
+      )
+      .where(
+        and(
+          eq(schema.sessionTurns.id, input.turnId),
+          eq(schema.sessionTurns.accountId, input.accountId),
+          eq(schema.sessionTurns.workspaceId, input.workspaceId),
+          eq(schema.sessionTurns.sessionId, input.sessionId),
+          eq(schema.sessionTurns.status, "running"),
+          eq(schema.sessionTurns.activeAttemptId, input.attemptId),
+          eq(schema.sessionTurns.executionGeneration, input.executionGeneration),
+          inArray(schema.sessionTurnAttempts.state, ["claimed", "running"]),
+        ),
+      )
+      .limit(1);
+    if (!live) throw new CodemodeOperationNotExecutableError();
+    const [row] = await scoped
+      .select()
+      .from(schema.sessionAttemptCodemodeCalls)
+      .where(
+        and(
+          eq(schema.sessionAttemptCodemodeCalls.workspaceId, input.workspaceId),
+          eq(schema.sessionAttemptCodemodeCalls.sessionId, input.sessionId),
+          eq(schema.sessionAttemptCodemodeCalls.turnId, input.turnId),
+          eq(schema.sessionAttemptCodemodeCalls.operationId, input.operationId),
+        ),
+      )
+      .limit(1);
+    return row && codemodeCallerCanContinue(row, input) ? mapCodemodeOperation(row) : null;
+  });
 }
 
 /** Signed sandbox subjects are attempt-bound; only the same owning turn can use this mapping. */

package/src/codemode-operations.ts

@@ -18,6 +18,7 @@ import {
 import { and, eq, sql } from "drizzle-orm";
 import type { Database } from "./database";
 import { withRlsContext } from "./database";
+import { runIdempotentPersistenceTransaction } from "./persistence-errors";
 import * as schema from "./schema";
 
 export class CodemodeOperationConflictError extends Error {
@@ -101,106 +102,114 @@ export async function submitCodemodeOperation(
   if (call.caller.kind !== "codemode") throw new CodemodeOperationNotExecutableError();
   assertJsonBytes(call.arguments, CODEMODE_ARGUMENTS_MAX_BYTES, "arguments");
   const requestDigest = digestCodemodeOperationRequest(call);
-  return await withRlsContext(
-    db,
-    { accountId: input.accountId, workspaceId: input.workspaceId },
-    async (scopedDb) =>
-      await scopedDb.transaction(async (tx) => {
-        // Serialize the caller-owned id before testing for an existing row.
-        // Without this fence, two first submissions can both observe absence
-        // and the later insert fails its unique constraint instead of replaying.
-        await tx.execute(sql`
+  // The whole admission is one idempotent transaction keyed by the
+  // caller-owned operation id (identical bytes replay the same row), so a
+  // deadlock/serialization victim rolls back completely and is retried here
+  // instead of surfacing as an HTTP failure. No external effect runs inside.
+  return await runIdempotentPersistenceTransaction(
+    { stage: "codemode.operation.submit", maxAttempts: 3 },
+    async () =>
+      await withRlsContext(
+        db,
+        { accountId: input.accountId, workspaceId: input.workspaceId },
+        async (scopedDb) =>
+          await scopedDb.transaction(async (tx) => {
+            // Serialize the caller-owned id before testing for an existing row.
+            // Without this fence, two first submissions can both observe absence
+            // and the later insert fails its unique constraint instead of replaying.
+            await tx.execute(sql`
           select pg_advisory_xact_lock(
             hashtextextended(${`codemode-operation:${input.workspaceId}:${call.operationId}`}, 0)
           )
         `);
-        const fence = await lockTurnAttemptWriteFenceTx(tx as unknown as Database, input);
-        if (
-          !fence.allowed ||
-          fence.turn.accountId !== input.accountId ||
-          fence.turn.status !== "running"
-        )
-          throw new CodemodeOperationNotExecutableError();
-        const [existing] = await tx
-          .select()
-          .from(schema.sessionAttemptCodemodeCalls)
-          .where(eq(schema.sessionAttemptCodemodeCalls.operationId, call.operationId))
-          .for("update")
-          .limit(1);
-        if (existing) {
-          assertExistingRequest(existing, input, requestDigest);
-          return { operation: mapCodemodeOperation(existing), created: false };
-        }
-
-        const [catalogRow] = await tx
-          .select({ catalog: schema.sessionAttemptToolCatalogs.catalog })
-          .from(schema.sessionAttemptToolCatalogs)
-          .where(
-            and(
-              eq(schema.sessionAttemptToolCatalogs.attemptId, input.attemptId),
-              eq(schema.sessionAttemptToolCatalogs.digest, call.catalogDigest),
-            ),
-          )
-          .limit(1);
-        if (!catalogRow) throw new CodemodeOperationNotExecutableError();
-        const catalog = parseVerifiedAttemptToolCatalog(catalogRow.catalog);
-        if (
-          catalog.accountId !== input.accountId ||
-          catalog.workspaceId !== input.workspaceId ||
-          catalog.sessionId !== input.sessionId ||
-          catalog.turnId !== input.turnId ||
-          catalog.attemptId !== input.attemptId ||
-          catalog.executionGeneration !== input.executionGeneration
-        ) {
-          throw new CodemodeOperationNotExecutableError();
-        }
-        const catalogEntry = catalog.entries.find(
-          (entry) =>
-            entry.identity.serverId === call.identity.serverId &&
-            entry.identity.toolName === call.identity.toolName,
-        );
-        if (!catalogEntry) {
-          throw new CodemodeToolNotInCatalogError();
-        }
-        if (catalogEntry.approval === "human" && input.durableApproval !== true) {
-          throw new CodemodeToolApprovalRequiredError();
-        }
-
-        // The turn lock also serializes admission; completed receipts never consume this budget.
-        const active = await tx
-          .select({ operationId: schema.sessionAttemptCodemodeCalls.operationId })
-          .from(schema.sessionAttemptCodemodeCalls)
-          .where(
-            and(
-              eq(schema.sessionAttemptCodemodeCalls.turnId, input.turnId),
-              sql`${schema.sessionAttemptCodemodeCalls.state} in ('queued', 'running', 'waiting_for_approval')`,
-            ),
-          )
-          .limit(128);
-        if (active.length >= 128) throw new CodemodeOperationLimitError();
-
-        const [created] = await tx
-          .insert(schema.sessionAttemptCodemodeCalls)
-          .values({
-            operationId: call.operationId,
-            accountId: input.accountId,
-            workspaceId: input.workspaceId,
-            sessionId: input.sessionId,
-            turnId: input.turnId,
-            attemptId: input.attemptId,
-            executionGeneration: input.executionGeneration,
-            catalogDigest: call.catalogDigest,
-            requestDigest,
-            durableApproval: input.durableApproval === true,
-            serverId: call.identity.serverId,
-            toolName: call.identity.toolName,
-            arguments: call.arguments,
-            callerSubjectId: call.caller.subjectId,
-          })
-          .returning();
-        if (!created) throw new Error("Failed to create Codemode operation");
-        return { operation: mapCodemodeOperation(created), created: true };
-      }),
+            const fence = await lockTurnAttemptWriteFenceTx(tx as unknown as Database, input);
+            if (
+              !fence.allowed ||
+              fence.turn.accountId !== input.accountId ||
+              fence.turn.status !== "running"
+            )
+              throw new CodemodeOperationNotExecutableError();
+            const [existing] = await tx
+              .select()
+              .from(schema.sessionAttemptCodemodeCalls)
+              .where(eq(schema.sessionAttemptCodemodeCalls.operationId, call.operationId))
+              .for("update")
+              .limit(1);
+            if (existing) {
+              assertExistingRequest(existing, input, requestDigest);
+              return { operation: mapCodemodeOperation(existing), created: false };
+            }
+
+            const [catalogRow] = await tx
+              .select({ catalog: schema.sessionAttemptToolCatalogs.catalog })
+              .from(schema.sessionAttemptToolCatalogs)
+              .where(
+                and(
+                  eq(schema.sessionAttemptToolCatalogs.attemptId, input.attemptId),
+                  eq(schema.sessionAttemptToolCatalogs.digest, call.catalogDigest),
+                ),
+              )
+              .limit(1);
+            if (!catalogRow) throw new CodemodeOperationNotExecutableError();
+            const catalog = parseVerifiedAttemptToolCatalog(catalogRow.catalog);
+            if (
+              catalog.accountId !== input.accountId ||
+              catalog.workspaceId !== input.workspaceId ||
+              catalog.sessionId !== input.sessionId ||
+              catalog.turnId !== input.turnId ||
+              catalog.attemptId !== input.attemptId ||
+              catalog.executionGeneration !== input.executionGeneration
+            ) {
+              throw new CodemodeOperationNotExecutableError();
+            }
+            const catalogEntry = catalog.entries.find(
+              (entry) =>
+                entry.identity.serverId === call.identity.serverId &&
+                entry.identity.toolName === call.identity.toolName,
+            );
+            if (!catalogEntry) {
+              throw new CodemodeToolNotInCatalogError();
+            }
+            if (catalogEntry.approval === "human" && input.durableApproval !== true) {
+              throw new CodemodeToolApprovalRequiredError();
+            }
+
+            // The turn lock also serializes admission; completed receipts never consume this budget.
+            const active = await tx
+              .select({ operationId: schema.sessionAttemptCodemodeCalls.operationId })
+              .from(schema.sessionAttemptCodemodeCalls)
+              .where(
+                and(
+                  eq(schema.sessionAttemptCodemodeCalls.turnId, input.turnId),
+                  sql`${schema.sessionAttemptCodemodeCalls.state} in ('queued', 'running', 'waiting_for_approval')`,
+                ),
+              )
+              .limit(128);
+            if (active.length >= 128) throw new CodemodeOperationLimitError();
+
+            const [created] = await tx
+              .insert(schema.sessionAttemptCodemodeCalls)
+              .values({
+                operationId: call.operationId,
+                accountId: input.accountId,
+                workspaceId: input.workspaceId,
+                sessionId: input.sessionId,
+                turnId: input.turnId,
+                attemptId: input.attemptId,
+                executionGeneration: input.executionGeneration,
+                catalogDigest: call.catalogDigest,
+                requestDigest,
+                durableApproval: input.durableApproval === true,
+                serverId: call.identity.serverId,
+                toolName: call.identity.toolName,
+                arguments: call.arguments,
+                callerSubjectId: call.caller.subjectId,
+              })
+              .returning();
+            if (!created) throw new Error("Failed to create Codemode operation");
+            return { operation: mapCodemodeOperation(created), created: true };
+          }),
+      ),
   );
 }
 
@@ -255,94 +264,102 @@ export async function claimCodemodeOperation(
     claimLeaseMs?: number;
   },
 ): Promise<ClaimCodemodeOperationResult> {
-  return await withRlsContext(
-    db,
-    { accountId: input.accountId, workspaceId: input.workspaceId },
-    async (scopedDb) =>
-      await scopedDb.transaction(async (tx) => {
-        const fence = await lockTurnAttemptWriteFenceTx(tx as unknown as Database, input);
-        if (
-          !fence.allowed ||
-          fence.turn.accountId !== input.accountId ||
-          fence.turn.status !== "running"
-        )
-          return { status: "rejected", operation: null };
-        let [row] = await tx
-          .select()
-          .from(schema.sessionAttemptCodemodeCalls)
-          .where(eq(schema.sessionAttemptCodemodeCalls.operationId, input.operationId))
-          .for("update")
-          .limit(1);
-        if (!row || !operationMatchesAuthority(row, input)) {
-          return { status: "rejected", operation: row ? mapCodemodeOperation(row) : null };
-        }
-        const now = input.now ?? new Date();
-        const claimExpiresAt = new Date(now.getTime() + boundedClaimLeaseMs(input.claimLeaseMs));
-        let reclaimed = false;
-        if (row.state === "running") {
-          if (!row.claimExpiresAt || row.claimExpiresAt.getTime() > now.getTime()) {
-            return { status: "already_running", operation: mapCodemodeOperation(row) };
-          }
-          if (row.executionStartedAt) {
-            if (!row.claimId) {
-              throw new Error("Codemode running operation is missing its claim id");
+  // Pure database transaction keyed by the caller's claim id; a rolled-back
+  // deadlock victim committed nothing and is safe to repeat.
+  return await runIdempotentPersistenceTransaction(
+    { stage: "codemode.operation.claim", maxAttempts: 3 },
+    async () =>
+      await withRlsContext(
+        db,
+        { accountId: input.accountId, workspaceId: input.workspaceId },
+        async (scopedDb) =>
+          await scopedDb.transaction(async (tx) => {
+            const fence = await lockTurnAttemptWriteFenceTx(tx as unknown as Database, input);
+            if (
+              !fence.allowed ||
+              fence.turn.accountId !== input.accountId ||
+              fence.turn.status !== "running"
+            )
+              return { status: "rejected", operation: null };
+            let [row] = await tx
+              .select()
+              .from(schema.sessionAttemptCodemodeCalls)
+              .where(eq(schema.sessionAttemptCodemodeCalls.operationId, input.operationId))
+              .for("update")
+              .limit(1);
+            if (!row || !operationMatchesAuthority(row, input)) {
+              return { status: "rejected", operation: row ? mapCodemodeOperation(row) : null };
             }
+            const now = input.now ?? new Date();
+            const claimExpiresAt = new Date(
+              now.getTime() + boundedClaimLeaseMs(input.claimLeaseMs),
+            );
+            let reclaimed = false;
+            if (row.state === "running") {
+              if (!row.claimExpiresAt || row.claimExpiresAt.getTime() > now.getTime()) {
+                return { status: "already_running", operation: mapCodemodeOperation(row) };
+              }
+              if (row.executionStartedAt) {
+                if (!row.claimId) {
+                  throw new Error("Codemode running operation is missing its claim id");
+                }
+                return {
+                  status: "execution_owner_lost",
+                  operation: mapCodemodeOperation(row),
+                  claimId: row.claimId,
+                };
+              }
+              const [requeued] = await tx
+                .update(schema.sessionAttemptCodemodeCalls)
+                .set({
+                  state: "queued",
+                  claimId: null,
+                  claimedAt: null,
+                  claimExpiresAt: null,
+                  updatedAt: now,
+                })
+                .where(
+                  and(
+                    eq(schema.sessionAttemptCodemodeCalls.operationId, input.operationId),
+                    eq(schema.sessionAttemptCodemodeCalls.state, "running"),
+                    eq(schema.sessionAttemptCodemodeCalls.claimId, row.claimId!),
+                  ),
+                )
+                .returning();
+              if (!requeued) throw new Error("Codemode expired claim recovery lost its row lock");
+              row = requeued;
+              reclaimed = true;
+            }
+            if (row.state === "waiting_for_approval")
+              return { status: "terminal", operation: mapCodemodeOperation(row) };
+            if (isTerminalState(row.state))
+              return { status: "terminal", operation: mapCodemodeOperation(row) };
+
+            const [claimed] = await tx
+              .update(schema.sessionAttemptCodemodeCalls)
+              .set({
+                state: "running",
+                claimId: input.claimId,
+                claimedAt: now,
+                claimExpiresAt,
+                updatedAt: now,
+              })
+              .where(
+                and(
+                  eq(schema.sessionAttemptCodemodeCalls.operationId, input.operationId),
+                  eq(schema.sessionAttemptCodemodeCalls.state, "queued"),
+                ),
+              )
+              .returning();
+            if (!claimed) throw new Error("Codemode operation claim lost its row lock");
             return {
-              status: "execution_owner_lost",
-              operation: mapCodemodeOperation(row),
-              claimId: row.claimId,
+              status: "claimed",
+              operation: mapCodemodeOperation(claimed),
+              claimId: input.claimId,
+              reclaimed,
             };
-          }
-          const [requeued] = await tx
-            .update(schema.sessionAttemptCodemodeCalls)
-            .set({
-              state: "queued",
-              claimId: null,
-              claimedAt: null,
-              claimExpiresAt: null,
-              updatedAt: now,
-            })
-            .where(
-              and(
-                eq(schema.sessionAttemptCodemodeCalls.operationId, input.operationId),
-                eq(schema.sessionAttemptCodemodeCalls.state, "running"),
-                eq(schema.sessionAttemptCodemodeCalls.claimId, row.claimId!),
-              ),
-            )
-            .returning();
-          if (!requeued) throw new Error("Codemode expired claim recovery lost its row lock");
-          row = requeued;
-          reclaimed = true;
-        }
-        if (row.state === "waiting_for_approval")
-          return { status: "terminal", operation: mapCodemodeOperation(row) };
-        if (isTerminalState(row.state))
-          return { status: "terminal", operation: mapCodemodeOperation(row) };
-
-        const [claimed] = await tx
-          .update(schema.sessionAttemptCodemodeCalls)
-          .set({
-            state: "running",
-            claimId: input.claimId,
-            claimedAt: now,
-            claimExpiresAt,
-            updatedAt: now,
-          })
-          .where(
-            and(
-              eq(schema.sessionAttemptCodemodeCalls.operationId, input.operationId),
-              eq(schema.sessionAttemptCodemodeCalls.state, "queued"),
-            ),
-          )
-          .returning();
-        if (!claimed) throw new Error("Codemode operation claim lost its row lock");
-        return {
-          status: "claimed",
-          operation: mapCodemodeOperation(claimed),
-          claimId: input.claimId,
-          reclaimed,
-        };
-      }),
+          }),
+      ),
   );
 }
 

package/src/credit-balances.ts

@@ -38,7 +38,8 @@ export async function getBillingBalance(
                 else policy->'offers'->(g.metadata->>'creditOfferId')->'eligibleModelIds' end,
               policy->'defaultModelIds'
             ) from current_policy), to_jsonb(g.eligible_model_ids)),
-          'remainingMicros', g.amount_micros - coalesce(used.amount, 0)
+          'remainingMicros', g.amount_micros - coalesce(used.amount, 0),
+          'coversVoice', g.source_type = 'verified_signup_trial'
         ) order by g.created_at, g.id)
           from ${schema.creditLedgerEntries} g
           left join (
@@ -66,13 +67,28 @@ export async function getBillingBalance(
   });
 }
 
-/** Missing model means a non-model resource, which can only use general credits. */
-export function spendableCreditMicros(balance: BillingBalance, modelId?: string): number {
+/**
+ * What a charge pays for. A canonical model ID uses grants scoped to that
+ * model; {@link VOICE_CREDIT_USAGE} (dictation and live voice) uses grants
+ * that cover voice, which are the verified-signup trial credits. Omitted means
+ * a non-model resource, which can only use general credits.
+ */
+export type CreditUsage = string | { readonly kind: "voice" } | undefined;
+
+/** Deployment-funded dictation and live voice. */
+export const VOICE_CREDIT_USAGE: { readonly kind: "voice" } = Object.freeze({ kind: "voice" });
+
+function grantCovers(grant: PromotionalCreditBalance, usage: CreditUsage): boolean {
+  if (!usage) return false;
+  if (typeof usage === "string") return grant.eligibleModelIds.includes(usage);
+  return grant.coversVoice === true;
+}
+
+export function spendableCreditMicros(balance: BillingBalance, usage?: CreditUsage): number {
   return (
     Math.max(0, balance.generalBalanceMicros ?? balance.balanceMicros) +
     (balance.promotionalCredits ?? []).reduce(
-      (sum, grant) =>
-        sum + (modelId && grant.eligibleModelIds.includes(modelId) ? grant.remainingMicros : 0),
+      (sum, grant) => sum + (grantCovers(grant, usage) ? grant.remainingMicros : 0),
       0,
     )
   );
@@ -81,29 +97,54 @@ export function spendableCreditMicros(balance: BillingBalance, modelId?: string)
 export async function getSpendableCreditBalance(
   db: Database,
   accountId: string,
-  modelId?: string,
+  usage?: CreditUsage,
   policyRevision?: number,
 ): Promise<CreditBalanceSnapshot> {
   const balance = await getBillingBalance(db, accountId, policyRevision);
-  return { ...balance, balanceMicros: spendableCreditMicros(balance, modelId) };
+  return { ...balance, balanceMicros: spendableCreditMicros(balance, usage) };
+}
+
+/** Covering grants pay first, oldest first; the rest is general credit. */
+function allocateToCoveringGrants(
+  balance: BillingBalance,
+  amountMicros: number,
+  usage: CreditUsage,
+) {
+  let remaining = amountMicros;
+  const allocations: { grantEntryId: string; amountMicros: number }[] = [];
+  for (const grant of balance.promotionalCredits ?? []) {
+    if (!remaining || !grantCovers(grant, usage) || grant.remainingMicros <= 0) continue;
+    const allocated = Math.min(remaining, grant.remainingMicros);
+    allocations.push({ grantEntryId: grant.grantId, amountMicros: allocated });
+    remaining -= allocated;
+  }
+  return allocations;
 }
 
 export function planCreditDebit(
   balance: BillingBalance,
   requestedMicros: number,
-  modelId?: string,
+  usage?: CreditUsage,
 ) {
   if (!Number.isSafeInteger(requestedMicros) || requestedMicros <= 0) {
     throw new Error("credit debit requires a positive, safe integer micro amount");
   }
-  const debitedMicros = Math.min(requestedMicros, spendableCreditMicros(balance, modelId));
-  let remaining = debitedMicros;
-  const allocations: { grantEntryId: string; amountMicros: number }[] = [];
-  for (const grant of balance.promotionalCredits ?? []) {
-    if (!remaining || !modelId || !grant.eligibleModelIds.includes(modelId)) continue;
-    const amountMicros = Math.min(remaining, grant.remainingMicros);
-    allocations.push({ grantEntryId: grant.grantId, amountMicros });
-    remaining -= amountMicros;
+  const debitedMicros = Math.min(requestedMicros, spendableCreditMicros(balance, usage));
+  return { debitedMicros, allocations: allocateToCoveringGrants(balance, debitedMicros, usage) };
+}
+
+/**
+ * Allocations for an already-consumed charge of the full amount: covering
+ * grants pay what they can and general credit takes the rest, possibly going
+ * negative.
+ */
+export function planPostUseCreditAllocations(
+  balance: BillingBalance,
+  amountMicros: number,
+  usage: CreditUsage,
+) {
+  if (!Number.isSafeInteger(amountMicros) || amountMicros <= 0) {
+    throw new Error("credit debit requires a positive, safe integer micro amount");
   }
-  return { debitedMicros, allocations };
+  return allocateToCoveringGrants(balance, amountMicros, usage);
 }