> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tuturuuu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AI chat credit settlement

> How chat replies are charged exactly once after streaming, how a failed charge is recorded, and the bounded Cron Control job that settles it.

## 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:

```sql theme={null}
select chat_message_id, count(*)
from public.ai_credit_transactions
where transaction_type = 'deduction' and chat_message_id is not null
  and created_at >= timestamptz '2026-11-21 00:00:00+00'
group by chat_message_id having count(*) > 1;
```

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

| Bound | Per slot (96 a day) |
| - | - |
| Database requests | 1 |
| Rows processed | At most 100, each at most 5 times in its lifetime |
| Processor time | 30 seconds |

## 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

```sql theme={null}
select status, count(*), max(attempts), min(created_at)
from private.ai_credit_unbilled_charges group by status;
```

## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.