Specs that ship without revisions.

# Credit Billing — How

## Overview
Credit check and deduction via dedicated service layer.
Uses database row-level locking (SELECT FOR UPDATE).

**Key Design Decisions:**
- Row-level locking over mutexes (survives crashes)
- Immutable ledger (balance derived from ledger sum)
- Cost map cached in Redis (admin updates without deploys)

## Architecture

```mermaid
sequenceDiagram
    participant C as Client
    participant A as API
    participant S as CreditService
    participant D as Database

    C->>A: POST /api/v1/generate-report
    A->>S: check_and_deduct(user_id, action)
    S->>D: SELECT FOR UPDATE balance
    D-->>S: balance = 50
    alt balance >= cost
        S->>D: INSERT ledger + UPDATE balance
        S-->>A: {success: true, balance_after: 40}
    else balance < cost
        S-->>A: {success: false, required: 10}
    end
```

## Existing Code to Reuse
| What | File Path | How to Reuse |
|------|-----------|-------------|
| StripeWebhookHandler | services/payment/stripe.py | Add credit top-up |
| UserModel | models/user.py | Add credit_balance |

## Correctness Properties

### Property 1: Balance Never Negative
*For any* sequence of concurrent deductions, balance SHALL
never go below 0.
**Validates: M-1, Q-2**

# Credit Billing — Now

## Action Items

- [ ] 1. Database: Create ledger table
  - [ ] 1.1 Create Alembic migration `add_credit_billing`
    - Add `credit_balance INTEGER DEFAULT 0` to users
    - Create `credit_ledger` table
    - _Ref: M-1.3_

- [ ] 2. Checkpoint — Database ready
  - Run `alembic upgrade head`

- [ ] 3. Service layer
  - [ ] 3.1 Create `services/billing/credit_service.py`
    - `CreditService.check_and_deduct(db, user_id, action)`
    - Use SELECT FOR UPDATE for row locking
    - _Ref: M-1.1_

- [ ] 4. Checkpoint — Service layer ready
  - Unit test: check_and_deduct() with mock DB

- [ ] 5. API
  - [ ] 5.1 Add credit check to AI endpoints
    - _Ref: M-1.1_

- [ ] 6. Tests
  - [ ] 6.1 Unit tests
  - [ ] 6.2 Property tests (Hypothesis)
  - [ ] 6.3 Integration tests

- [ ] 7. Final checkpoint — All tests pass

## Dependency Graph
```json
{
  "waves": [
    { "id": 0, "tasks": ["1.1"] },
    { "id": 1, "tasks": ["3.1"] },
    { "id": 2, "tasks": ["5.1"] },
    { "id": 3, "tasks": ["6.1", "6.2", "6.3"] }
  ]
}
```