fix(kiloclaw): serialize credit billing mutations

[jeanduplessis]

Summary

Prevent concurrent KiloClaw credit billing operations from overdrawing balances or collapsing distinct Stripe payments.

Why this change is needed

Credit enrollment checked available balance before entering its transaction, so concurrent enrollments for one user could make decisions from the same stale balance. Stripe-funded settlement also keyed deductions by billing period, which could treat separate payments in one period as duplicates and continue after an unexpected deduction conflict.

How this is addressed

• Serialize each user's credit enrollment balance decision and mutation with a row lock.
• Revalidate target instance state inside transaction before deducting credits.
• Key Stripe-funded deductions by payment identity and roll back settlement when deduction cannot be recorded.
• Add regression coverage for concurrent enrollments, distinct same-period Stripe payments, and deduction conflicts.

Human Verification

• Confirmed behavior against KiloClaw billing and billing-lifecycle specs.
• Ran targeted KiloClaw billing tests: 2 suites and 231 tests passed.

Reviewer Notes

Human Reviewer Flags

• Credit enrollment now holds user row lock while calculating effective balance and applying deduction, intentionally serializing concurrent billing operations for same user.
• Stripe-funded deduction identity changes from period-based to payment-based so distinct provider payments remain independently balance-neutral.

Code Reviewer Agent

Code Reviewer Notes

• Settlement deposit and deduction remain in one database transaction; deduction conflicts now throw so deposit and subscription mutation roll back together.
• Transaction rechecks instance ownership and destruction state after acquiring user lock.
• Existing settlement category parser remains compatible because settlement categories do not encode instance IDs.

[kilo-code-bot]

Code Review Summary

Status: 2 Issues Found | Recommendation: Address before merge

Overview

Severity	Count
CRITICAL	0
WARNING	2
SUGGESTION	0

Issue Details (click to expand)

WARNING

File	Line	Issue
apps/web/src/lib/kiloclaw/credit-billing.ts	694	Legacy settlement replay now skips the compensating payment-scoped deduction whenever a period-scoped legacy deduction or same-period settlement log exists, so duplicate delivery can leave an extra Stripe deposit credited and break settlement balance-neutrality.
apps/web/src/lib/kiloclaw/stripe-funded-settlement.test.ts	737	The new legacy-replay regression test now expects that over-credited balance, so it codifies the bug instead of protecting the balance-neutral settlement invariant.

Files Reviewed (2 files)

• apps/web/src/lib/kiloclaw/credit-billing.ts - 1 issue
• apps/web/src/lib/kiloclaw/stripe-funded-settlement.test.ts - 1 issue

Fix these issues in Kilo Cloud

Previous Review Summaries (3 snapshots, latest commit 0c4692b)

Current summary above is authoritative. Previous snapshots are kept for context only.

Previous review (commit 0c4692b)

Status: 1 Issue Found | Recommendation: Address before merge

Overview

Severity	Count
CRITICAL	0
WARNING	1
SUGGESTION	0

Issue Details (click to expand)

WARNING

File	Line	Issue
apps/web/src/lib/kiloclaw/credit-billing.ts	695	Legacy period deductions still trigger reconciliation for replays of the same payment, so post-deploy webhook replays can insert a second deduction and double-charge the user.

Files Reviewed (3 files)

• apps/web/src/lib/kilo-pass/cancel-and-refund.ts - 0 issues
• apps/web/src/lib/kiloclaw/credit-billing.ts - 1 issue
• apps/web/src/lib/kiloclaw/stripe-funded-settlement.test.ts - 0 issues

Fix these issues in Kilo Cloud

Previous review (commit 054144e)

Status: 2 Issues Found | Recommendation: Address before merge

Overview

Severity	Count
CRITICAL	0
WARNING	2
SUGGESTION	0

Issue Details (click to expand)

WARNING

File	Line	Issue
apps/web/src/lib/kilo-pass/cancel-and-refund.ts	181	New user-first lock order can deadlock against existing Kilo Pass flows that lock the subscription row before the user row.
apps/web/src/lib/kiloclaw/credit-billing.ts	673	Duplicate-settlement reconciliation counts same-amount deposits across the whole user, so one subscription replay can consume another subscription's deposit and over-deduct balance.

Files Reviewed (6 files)

• apps/web/src/lib/kilo-pass/cancel-and-refund.ts - 1 issue
• apps/web/src/lib/kilo-pass/state.ts - 0 issues
• apps/web/src/lib/kiloclaw/credit-billing.ts - 1 issue
• apps/web/src/lib/kiloclaw/stripe-funded-settlement.test.ts - 0 issues
• apps/web/src/routers/kiloclaw-billing-router.test.ts - 0 issues
• apps/web/src/routers/user-router.ts - 0 issues

Fix these issues in Kilo Cloud

Previous review (commit a93dae5)

Status: No Issues Found | Recommendation: Merge

Files Reviewed (4 files)

• apps/web/src/lib/kiloclaw/credit-billing.ts
• apps/web/src/lib/kiloclaw/stripe-funded-settlement.test.ts
• apps/web/src/routers/kiloclaw-billing-router.test.ts
• apps/web/src/routers/user-router.ts

---

_{Reviewed by gpt-5.4-20260305 · Input: 104K · Output: 16.1K · Cached: 1.9M}

_{Review guidance: REVIEW.md from base branch main}