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:
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 returnssuccess: 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 jobai-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 itsettled. - A failure increments
attemptsand keepslast_error; the fifth failure marks itabandoned, 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
-
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 withAI_CREDIT_CHAT_DEDUCTION_INDEX_NOT_VALIDunless the index is valid, then installs the idempotentdeduct_ai_credits, the unbilled store and its functions in one transaction.20261121194300: the same validity check, as a second gate.
drop index concurrently if exists public.ai_credit_transactions_one_chat_message_deduction;outside a transaction; rebuild it with the exact statement in20261121184400(by hand if that version is already recorded insupabase_migrations.schema_migrations, sincedb pushwill not re-run it); then retry from20261121184500. -
Deploy the web families and Cron Control. Before the migrations, the
chat route’s recorder fails soft and logs
recordedUnbilled: false. -
Only after the migrations are applied in production, a reviewed change
adds
ai-credit-unbilled-settlementtoCRON_CONTROL_ENABLED_JOBSinapps/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.sqlrestores 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.