Skip to main content

Decision

Every assistant chat message is charged at most once, and a charge that fails after the reply was served is recorded, not dropped.
  • Scope: the shared chat route (packages/ai/src/chat/google/route.ts) used by Mira and AI chat on web and mobile. Fixed-cost tool reservations and AI Studio runs settle through their own reservation RPCs.
  • Default: the reply is always delivered and saved first; credits settle from the stream’s onFinish/onAbort, after the response has returned.
  • Exception: a charge with no workspace (wsId) cannot be settled and is only logged.

Exactly once

public.deduct_ai_credits returns the earlier deduction when one already exists for p_chat_message_id, instead of charging again. The wallet row lock serializes concurrent settlements of one message; settlements that resolve different wallets meet at the unique partial index ai_credit_transactions_one_chat_message_deduction, and the loser returns the winner’s row. The index (migration 20261121184400, built CONCURRENTLY so ledger writes continue) covers rows from 2026-11-21 00:00Z on, so older rows cannot block it. Before applying it, confirm no message has two deductions in that window:
Settlement runs outside the request scope (Next after(), Cloudflare waitUntil). Its admin clients use createAdminClient({ noCookie: true }), because the default admin client reads request cookies and throws there.

Unbilled charges

When the post-stream deduction throws or returns success: false, recordUnbilledAiCharge (packages/ai/src/credits/check-credits.ts) calls public.record_unbilled_ai_charge, which inserts one row per message into private.ai_credit_unbilled_charges (first record wins). The log line Failed to deduct AI credits after assistant response. or AI credit deduction returned unsuccessful result. carries the error class, message and recordedUnbilled. The table has row level security, no policies and no grants; only the service-role SECURITY DEFINER functions read or write it. It has no foreign key to the message or the user, so deleting either leaves the record to end abandoned and never bills a deleted user’s charge to the workspace wallet.

Retry job

Cron Control job ai-credit-unbilled-settlement (*/15 * * * *) calls private.settle_unbilled_ai_charges(p_limit) once per slot:
  • At most 100 pending rows per call, oldest first, FOR UPDATE SKIP LOCKED.
  • Each row is charged through deduct_ai_credits, so a replay never charges twice. Success marks it settled.
  • A failure increments attempts and keeps last_error; the fifth failure marks it abandoned, a terminal audit record of uncharged usage. A timeout, deadlock or serialization failure aborts the run without spending an attempt.
  • No in-slot retry. Five failed or unknown slots stop the job durably in the Cron Control ledger.

Cost bounds

Enablement

  1. The gated migration workflow (supabase db push --include-all) applies, in order:
    • 20261121184400: the concurrent unique index, its file’s only statement; the CLI runs it on its own before recording the version. It fails if a chat message already has two deductions since the cutoff, and the push stops there.
    • 20261121184500: refuses with AI_CREDIT_CHAT_DEDUCTION_INDEX_NOT_VALID unless the index is valid, then installs the idempotent deduct_ai_credits, the unbilled store and its functions in one transaction.
    • 20261121194300: the same validity check, as a second gate.
    A failed build leaves an INVALID index that still rejects colliding deduction inserts until it is dropped. To recover: find the duplicates with the query above and resolve them; run drop index concurrently if exists public.ai_credit_transactions_one_chat_message_deduction; outside a transaction; rebuild it with the exact statement in 20261121184400 (by hand if that version is already recorded in supabase_migrations.schema_migrations, since db push will not re-run it); then retry from 20261121184500.
  2. Deploy the web families and Cron Control. Before the migrations, the chat route’s recorder fails soft and logs recordedUnbilled: false.
  3. Only after the migrations are applied in production, a reviewed change adds ai-credit-unbilled-settlement to CRON_CONTROL_ENABLED_JOBS in apps/cron-control/cloudflare.config.ts. Enabling it earlier makes every slot fail until its five-failure durable stop trips.

Stop

  • Fastest: POST /control/jobs/ai-credit-unbilled-settlement/stop (operator token).
  • Database, without a deploy: revoke execute on function private.settle_unbilled_ai_charges(integer) from service_role;
  • Config: remove the id from CRON_CONTROL_ENABLED_JOBS.
  • apps/database/rollbacks/20261121184500_ai_chat_credit_exactly_once.rollback.sql restores the previous wrapper and drops the store; read non-settled rows first.

Inspect

Regression evidence

  • apps/database/supabase/tests/ai-chat-credit-exactly-once.sql: one charge per message across repeated settlement, the index rejecting a second row, first record wins, settlement of pending rows without re-charging an already charged message, abandonment after five attempts, the zero limit, grants and pinned search paths.
  • apps/database/scripts/ai-chat-credit-race.mjs: two real sessions against a disposable Supabase PG17 container (node <script> <supabase_db_tt-...>). Settling one message on two wallets and on one wallet at once charges it once and returns the first charge to the second session.
  • packages/ai/src/chat/google/stream-finish-persistence.test.ts: a thrown or unsuccessful deduction keeps the reply and records it unbilled; a deducted charge is not recorded.
  • packages/ai/src/credits/check-credits-cache.test.ts: settlement and recording use the cookie-free admin client and the ledger’s pricing.
  • apps/cron-control/src/ai-credit-unbilled-settlement.test.ts: registration, default off, one bounded call per slot, durable stop, failure stop and invalid summaries.