Story 2164: staff can grant a firm credits — once, on the record, and never twice

🛰 Satellite — the one sentence

A single record_adjustment writer appends one signed 'adjustment' row to the append-only billing.credit_ledger — positive grants, negative claws back — idempotent by a caller-supplied adjustment_id, scoped to the firm by RLS, bounded by a config cap, stamped with the staff actor and a mandatory reason, and surfaced as a staff-only POST /admin/firms/{firm_id}/billing/credits/adjustment.

✈️ Airplane — a bank teller’s deposit slip, not a pencilled ledger

Picture the old option as erasing a number in a paper ledger and writing a bigger one: no trace of the change, and if your hand slips you can’t prove what it was. This Story replaces the eraser with a deposit slip. Each grant is a fresh slip (an appended row) that says who (the staff id, taken from their login, never typed into the form), why (a mandatory reason), how much and into which pocket (grant vs top-up bucket). The slip carries a reference number — the adjustment_id — and the teller’s rule is: one slip per reference number, ever. Hand in the same slip twice (a double-click) and the second is filed as a no-op; the balance moves once. And there’s a ceiling stamped on the counter: a single slip over the config cap is refused before any ink touches the ledger.

🔬 Microscopic — the four moving parts

1. The schema the writer needed — migration 0159 (additive, reversible)

The 'adjustment' enum existed; three small pieces did not. Migration 0159 adds them without touching one existing row’s meaning:

• credit_ledger.adjustment_id (UUID, nullable) — the idempotency key, backed by a partial unique index (firm_id, adjustment_id) WHERE event_type='adjustment'. This is the same structural idempotency the run-debit and stripe-event rows already use: the database itself refuses a duplicate, so exactly-once survives even a race, not just a well-behaved caller.
• credit_ledger.staff_user_id (UUID, nullable) — the platform-staff actor, kept distinct from user_id (the firm lawyer on a run debit) so the two identities never blur in an audit read.
• pricing_config.staff_adjust_cap_usd (NUMERIC, default 1000) — the per-adjustment ceiling as a config row, not a Python constant (the S1/ADR-151 discipline), with a >= 0 CHECK.

The entity models mirror it exactly — alembic check reports “No new upgrade operations detected.”

2. The pure math — two testable helpers in credits.py

No I/O, so the money rules are unit-tested without a database. credits_to_millicredits is the signed unit bridge (a +1,000-credit grant is +1,000,000 mc; a −250 clawback is −250,000 mc — no FX, credits are already ₹). adjustment_exceeds_cap bounds the magnitude of both signs against the USD cap (|delta| > cap), so a clawback is capped just like a grant.

3. The writer — record_adjustment, one append, same path as record_topup

Deliberately no new machinery: it reuses the exact append + firm-scope-reset + projection-update shape the top-up writer already uses. The order is the whole correctness story:

reason present? bucket valid? delta != 0? magnitude <= cap?   → else 422 (nothing written)
set app.current_firm_id = firm_id      (staff sessions carry no firm scope; RLS WITH CHECK needs it)
INSERT ... 'adjustment' ... WHERE NOT EXISTS (same firm_id + adjustment_id)  RETURNING id
  → None: already applied, return False   (idempotent no-op, no double-credit)
UPDATE the targeted projection bucket by the signed delta
restore app.current_firm_id  (finally)

Two subtleties worth their titles. Why set the firm scope at all: a staff session runs with is_staff=true but no current_firm_id, and the ledger’s firm_isolation policy’s WITH CHECK would reject a firm-scoped INSERT — so the writer sets the target firm itself and restores it, exactly as seed_starter_credit does. Why a NOT EXISTS guard, not a read-then-write: the idempotency lives in the single atomic INSERT, never in a separate SELECT that a concurrent call could slip between (the ticket’s explicit “DB guard only”). The cap is checked before the insert so a rejected grant writes nothing.

4. The route — staff-only, thin, on the existing billing prefix

POST /admin/firms/{firm_id}/billing/credits/adjustment sits on the existing firm_billing.py router (StaffDbDep). The handler is thin: the service guards the firm exists (404 for a ghost firm, so a phantom balance can never be conjured), calls the writer, and reads back the resulting two-bucket balance for the admin form. The staff id comes from the authenticated session (current_user.user_id), never the request body — audit authority is session-derived, not caller-claimed. The pramaan-admin grant form is a separate fast-follow.

What was deliberately not built

How it was proven (system boundary, not just green units)

• Migration applies to head, 0159 down/up roundtrips, alembic check clean.
• Seven route tests through the real router against a real DB: a grant writes one signed row with the session staff id + reason and moves the bucket by exactly the delta; a replayed adjustment_id returns applied=false with the balance unchanged and one row only; a negative delta claws back; an over-cap grant is 422 with zero rows written; a zero delta is rejected; an unknown firm is 404 with no leaked row.
• RLS isolation suite green (26 tests); existing billing route + service + credit suites green (no regression from the added columns); OpenAPI admin snapshot regenerated.