Money & billing

Credits, reserve/settle/refund, async settlement, and payment rails.

Research snapshot of quill-router at main @ 778120494 (2026-10-19). Read-only investigation; no production systems touched. Source paths are relative to the repo root; src/trusted_router/ is abbreviated tr/ in tables.

AGENTS.md: "reserve / settle / refund and anything touching credits are the highest-risk code in the repo. Changes there need a differential or conformance test, never review-by-eye."

1. Overview (the 5-minute version)

Unit of account. All money is integer microdollars (1 USD = 1,000,000 µ$). See tr/money.py. Floats exist only for response compatibility (microdollars_to_float). Token cost is (tokens * rate_micro_per_million + 500_000) // 1_000_000 (round half-up), tr/money.py:57.

Customer price. Upstream provider cost × 1.055 (STANDARD_PRICE_MARKUP_BASIS_POINTS = 550, tr/pricing.py:126), ceiling-rounded, with a floor of $0.01 per million tokens. Prices come from a committed snapshot (tr/data/openrouter_snapshot.json) that an hourly price-refresh bot (.github/workflows/refresh-prices.yml, scripts/pricing/refresh.py) regenerates and auto-commits to main, which auto-deploys. Big price jumps are held unless they appear in tr/pricing_approvals.py.

The ledger ("typed book"). Since 2026-06-26 the only authoritative money book is three native Spanner tables. The JSON-blob book in tr_entities was retired (docs/design/retire-json-credit-ledger.md, billing-dual-system-deletion-handoff.md):

Available balance on a shard = total_credits - total_usage - reserved. A hot workspace can be split across N shards. Each shard is an independent sub-budget, so the global cap holds by construction (docs/design/credit-row-sharding-handoff.md). The JSON credit entity is now metadata only: auto-refill config and Stripe customer/payment-method ids.

Per-request lifecycle. The attested enclave (quill-cloud-proxy) calls the control plane's internal routes: 1. POST /internal/gateway/authorize → authorize_atomic reserves an estimate with one conditional DML per row: UPDATE ... SET reserved = reserved + @est WHERE headroom >= @est AND NOT in_debt. Row-count 1 means accepted, 0 means 402. The reservation row is inserted with expires_at. 2. Optional POST /internal/gateway/heartbeat records started_at plus the usage delivered so far. The reaper can use this later. 3. POST /internal/gateway/settle (success) or /refund (failure) → _settle_gateway_authorization prices the actual usage, freezes the amount into a SettleOutboxRow, then finalizes: - claim the reservation (UPDATE tr_reservation SET settled=true ... WHERE settled=false; first writer wins), - mark the authorization settled, write generation/activity, - release the exact holds and book actual (credit row first, then key row). 4. Reaper (reap_expired_reservations_result) reclaims holds that were never settled. It releases them free, or with Decision 70 snapshot booking it books the last heartbeat usage snapshot. It never frees a hold that a pending/dead settle-outbox row still intends to charge. 5. Settle-outbox drain (/internal/gateway/settle-outbox/drain, every 5 min) replays any intent whose inline finalize didn't land. It applies the frozen amount through a narrow primitive.

Why it's this complicated. Two failure directions: - Double charge. Prevented by the first-writer-wins reservation claim. N replays book at most once. - Lost charge. The request was served but the settle never landed, and the reaper released it free. Prevented by the durable settle outbox plus the reaper guard. Per the design, the reaper guard is the sole correctness mechanism for this direction. Drain timing only buys latency.

Async settlement (in flight, dormant). This is a multi-month program to move finalize off the response path. The enclave gets a 202 after one durable intent commit, and the drain books the charge. It is gated behind an enormous evidence apparatus: "shadow v2", "gates", "packs", "certificates", and a "frozen-main differential" proof_oracle. These prove that the change alters no money behavior before anyone flips it on. Production today: TR_ASYNC_SETTLE_ENABLED=false, TR_ASYNC_SETTLE_PROTECTION=false, TR_ASYNC_SETTLE_SHADOW_POLICY=shadow-v2 for one dedicated probe workspace (scripts/deploy/rollout.sh:659-664).

Money in. Payment rails (Stripe card/ACH/auto-refill, x402 stablecoin via Stripe, PayPal, Adyen (dark), Lightning (separate LightningRouter workers)) all funnel into one function: credit_workspace_typed_direct (tr/storage_gcp.py:3183). It is idempotent on a stripe_event marker entity keyed by a rail-specific event id, and it writes a trust "payment fact" in the same transaction.

Money out. Creator earnings from app markup and custom-model markup go to tr_earnings_balance and are paid via Routable ACH (dark, TR_ROUTABLE_ENABLED=false).

2. Invariants (memorize these)

3. Reservation state machine

stateDiagram-v2
    [*] --> Held: authorize_atomic - conditional reserve OK
    [*] --> Rejected: row-count 0 (insufficient / in_debt / paused)
    Rejected --> [*]

    Held --> Held: heartbeat (started_at, delivered usage)
    Held --> IntentDurable: settle/refund - outbox INSERT (two-commit path)
    Held --> SettledCharged: one-commit settle (claim + book + intent done)
    Held --> Refunded: refund claim wins (actual=0)
    Held --> ReapedFree: reaper - expired, no pending/dead intent
    Held --> ReapedSnapshot: reaper - expired, started + snapshot booking

    IntentDurable --> SettledCharged: inline finalize claims reservation
    IntentDurable --> SettledCharged: drain apply_frozen_settle (frozen amount)
    IntentDurable --> Frozen: drain gives up (dead) - reaper blocked
    Frozen --> SettledCharged: human applies manual charge
    Frozen --> ReapedFree: human sets release_approved

    SettledCharged --> [*]: terminal_at armed (30-day retention)
    Refunded --> [*]
    ReapedFree --> [*]
    ReapedSnapshot --> [*]

stateDiagram-v2
    [*] --> Held: authorize_atomic - conditional reserve OK
    [*] --> Rejected: row-count 0 (insufficient / in_debt / paused)
    Rejected --> [*]

    Held --> Held: heartbeat (started_at, delivered usage)
    Held --> IntentDurable: settle/refund - outbox INSERT (two-commit path)
    Held --> SettledCharged: one-commit settle (claim + book + intent done)
    Held --> Refunded: refund claim wins (actual=0)
    Held --> ReapedFree: reaper - expired, no pending/dead intent
    Held --> ReapedSnapshot: reaper - expired, started + snapshot booking

    IntentDurable --> SettledCharged: inline finalize claims reservation
    IntentDurable --> SettledCharged: drain apply_frozen_settle (frozen amount)
    IntentDurable --> Frozen: drain gives up (dead) - reaper blocked
    Frozen --> SettledCharged: human applies manual charge
    Frozen --> ReapedFree: human sets release_approved

    SettledCharged --> [*]: terminal_at armed (30-day retention)
    Refunded --> [*]
    ReapedFree --> [*]
    ReapedSnapshot --> [*]

Notes: - "Claim" is the settled false→true transition. Every arrow into a terminal state goes through claim_reservation, so concurrent inline, drain, and reaper attempts resolve to exactly one winner. - A settle intent and a refund intent can coexist (different PKs). The first reservation claimant wins. The loser drains to already_settled_with_charge, plus a low-priority review flag if a refund lost to a charge. - Fast-admission pilot (TR_FASTPATH_PILOT_ENABLED=true for two workspaces): the hold lives in a lease on the Go "front door" service, not in tr_reservation. The reservation row "holds nothing". Settlement goes through _settle_leased_authorization / tr/services/fastpath_settle.py. TLA+ specs LeaseLifecycle, TerminalOrder, AuditorCommit, KeyCapFence are planned. CreditDebt and AutoRefillHandoff are implemented.

4. Settle sequence: one-commit happy path vs two-commit fallback

sequenceDiagram
    participant E as Enclave (quill-cloud-proxy)
    participant R as Router /internal/gateway/settle
    participant S as Spanner
    participant D as Outbox drain (5 min)

    E->>R: POST settle (authorization_id, actual usage)
    R->>S: read gateway authorization
    R->>R: price usage, build frozen SettleOutboxRow

    alt one-commit happy path (typed, outbox available)
        R->>S: read reservation
        R->>S: Batch DML: claim + auth finalize + INSERT intent(status=done) + activity + benchmark + credit release + key release
        S-->>R: commit OK
        R-->>E: 200 settled
    else any deviation: declined, abort, 5s budget, unknown outcome
        R->>S: rollback
        R->>S: commit 1: INSERT intent(status=pending, next_attempt +60s)
        Note over R,S: intent durable here, ALREADY_EXISTS finds a done row if the one-commit actually landed
        R->>S: commit 2: typed_finalize_atomic (claim, book, mark done in same txn)
        alt finalize OK
            S-->>R: settled
            R-->>E: 200 settled
        else finalize fails / crash
            R-->>E: intent_durable (or 5xx)
            D->>S: claim due rows (sharded sparse index, lease 300s)
            D->>S: apply_frozen_settle: claim + book frozen actual_cost_micro
            D->>S: mark done / dead / park (lease-fenced)
        end
    end

sequenceDiagram
    participant E as Enclave (quill-cloud-proxy)
    participant R as Router /internal/gateway/settle
    participant S as Spanner
    participant D as Outbox drain (5 min)

    E->>R: POST settle (authorization_id, actual usage)
    R->>S: read gateway authorization
    R->>R: price usage, build frozen SettleOutboxRow

    alt one-commit happy path (typed, outbox available)
        R->>S: read reservation
        R->>S: Batch DML: claim + auth finalize + INSERT intent(status=done) + activity + benchmark + credit release + key release
        S-->>R: commit OK
        R-->>E: 200 settled
    else any deviation: declined, abort, 5s budget, unknown outcome
        R->>S: rollback
        R->>S: commit 1: INSERT intent(status=pending, next_attempt +60s)
        Note over R,S: intent durable here, ALREADY_EXISTS finds a done row if the one-commit actually landed
        R->>S: commit 2: typed_finalize_atomic (claim, book, mark done in same txn)
        alt finalize OK
            S-->>R: settled
            R-->>E: 200 settled
        else finalize fails / crash
            R-->>E: intent_durable (or 5xx)
            D->>S: claim due rows (sharded sparse index, lease 300s)
            D->>S: apply_frozen_settle: claim + book frozen actual_cost_micro
            D->>S: mark done / dead / park (lease-fenced)
        end
    end

Key facts (docs/design/durable-settle-outbox.md §7, tr/routes/internal/gateway.py:4413-4600): - Per authorize+settle round trip, one-commit takes read-write commits from 4 → 2. - If the one-commit transaction actually landed but reported failure, the fallback is still safe. The enqueue hits ALREADY_EXISTS on a done row, finalize claims 0 rows, and nothing is charged twice. - With settle_outbox_enabled=True (production) and typed request records, a failed enqueue returns 503 ("Settlement durability is temporarily unavailable"). The router does not proceed without durability. - Honest scope: durability starts at the intent commit. A crash before that still depends on enclave redelivery, which is a bounded in-memory retry channel (1,024 jobs, 6 attempts) and does not survive enclave loss.

5. Payment ingestion flow (Stripe webhook → credits)

flowchart TD
    A["Stripe POST /internal/stripe/webhook"] --> B{"stripe-signature valid?"}
    B -- "no / missing" --> X["400"]
    B -- "secret unset in prod" --> X2["503"]
    B -- "yes" --> C["to plain dict (_to_dict_recursive)"]
    C --> D{"adverse event? (charge.refunded, refund.updated, dispute.*)"}
    D -- "yes" --> T["record_adverse_trust_event: recovery debt or trust inbox"]
    D -- "no" --> E{"event type"}
    E -- "checkout.session.completed / async_payment_succeeded" --> F{"mode=setup?"}
    F -- "yes" --> F1["save stripe customer (no credit)"]
    F -- "no" --> G{"payment_status == paid?"}
    G -- "no" --> G1["payment_pending (no credit)"]
    G -- "yes" --> H["principal = credit_amount_microdollars (fee excluded, validated vs amount_total)"]
    E -- "payment_intent.succeeded + auto_refill=true" --> H2["refill principal (validated vs PI amount)"]
    E -- "payment_intent.succeeded + x402" --> H3["credit_x402_payment_intent"]
    E -- "setup_intent.succeeded" --> F1
    H --> I["credit_workspace_typed_direct(event_id)"]
    H2 --> I
    H3 --> I
    I --> J{"stripe_event marker exists?"}
    J -- "yes" --> K["replay: credited=false"]
    J -- "no" --> L["insert trust payment fact (provider + PaymentIntent)"]
    L --> M["total_credits += amount (debt rules: repay negative shards first)"]
    M --> N["insert stripe_event marker, drain matching trust inbox"]
    N --> O["commit, then record_credit_purchase analytics"]

flowchart TD
    A["Stripe POST /internal/stripe/webhook"] --> B{"stripe-signature valid?"}
    B -- "no / missing" --> X["400"]
    B -- "secret unset in prod" --> X2["503"]
    B -- "yes" --> C["to plain dict (_to_dict_recursive)"]
    C --> D{"adverse event? (charge.refunded, refund.updated, dispute.*)"}
    D -- "yes" --> T["record_adverse_trust_event: recovery debt or trust inbox"]
    D -- "no" --> E{"event type"}
    E -- "checkout.session.completed / async_payment_succeeded" --> F{"mode=setup?"}
    F -- "yes" --> F1["save stripe customer (no credit)"]
    F -- "no" --> G{"payment_status == paid?"}
    G -- "no" --> G1["payment_pending (no credit)"]
    G -- "yes" --> H["principal = credit_amount_microdollars (fee excluded, validated vs amount_total)"]
    E -- "payment_intent.succeeded + auto_refill=true" --> H2["refill principal (validated vs PI amount)"]
    E -- "payment_intent.succeeded + x402" --> H3["credit_x402_payment_intent"]
    E -- "setup_intent.succeeded" --> F1
    H --> I["credit_workspace_typed_direct(event_id)"]
    H2 --> I
    H3 --> I
    I --> J{"stripe_event marker exists?"}
    J -- "yes" --> K["replay: credited=false"]
    J -- "no" --> L["insert trust payment fact (provider + PaymentIntent)"]
    L --> M["total_credits += amount (debt rules: repay negative shards first)"]
    M --> N["insert stripe_event marker, drain matching trust inbox"]
    N --> O["commit, then record_credit_purchase analytics"]

Card events key the idempotency marker on the Stripe event id. ACH keys it on stripe_checkout:{payment_intent} so that completed and async_payment_succeeded dedupe (_checkout_credit_event_id, tr/routes/internal/webhook.py:545). One 2026-09-04 fix matters here: if a backfill scan wrote the trust fact before the webhook arrived, the webhook still credits exactly once. Before the fix it answered credited:false, Stripe stopped retrying, and the payment was zeroed (tr/storage_gcp.py:3221-3250).

6. Key modules

6.1 Ledger, reserve, settle, refund, reaper

6.2 Durable settle outbox

6.3 Async settlement and shadow (dormant)

6.4 Payments and payouts

7. What the async-settle vocabulary means

8. Payment rails

9. How to safely change money code (checklist)

1. Read first: docs/design/durable-settle-outbox.md §3–§7, docs/design/billing-typed-counters.md, AGENTS.md "Money code", and the async-settle design docs if you touch settle or outbox.
2. Ship dormant. Put new behavior behind a default-off flag. Flag-off SQL, params, and RPC sequence must stay byte-identical. Production flags live only in scripts/deploy/rollout.sh ENV_VARS. Hand-set Cloud Run env vars are overwritten.
3. Prove it, don't eyeball it. Add a differential, conformance, or mutation test: - tests/conformance/ for Store-protocol behavior (memory, postgres, spanner-pg). Never weaken one. - Frozen-main oracle when touching settle, outbox, authorize, or billing: uv run pytest -q -n 4 -m proof_oracle tests/test_async_settle_proof_oracle.py. If your change is intended, re-pin via scripts/async_settle/freeze_reference.py and regenerate the inventory. - Add a mutant (tests/*_mutations.py) for any new guard. Confirm that removing the guard fails a test.
4. Fake fidelity (MF6). tests/fakes/spanner.py is a substring SQL interpreter. Any predicate you add to an already-matched SQL string needs a matching fake change plus _require_pred, or the fake silently ignores it and your guard tests are theater.
5. Patch the class, not STORE. monkeypatch.setattr(STORE, …) poisons later tests (issue #333). Run the full suite: uv run ruff check . && uv run mypy && uv run pytest -q. Never run ruff format ..
6. Preserve the spine. Claim-first-writer-wins, exact-hold release with row-count == 1, credit-then-key lock order, the in-txn reaper guard, frozen amount and origin, INSERT-as-claim, and no new read→write upgrade on hot counter rows.
7. Never touch analytics inside the money txn except the documented one-commit ride-along with full fallback.
8. Interleavings? If the change is a protocol (leases, handoffs, multi-shard), extend or add a TLA+ spec in proofs/ with mutants and a guard table. CI runs ./proofs/check.sh.
9. Rebase before trusting a failure. The hourly price bot moves main.
10. Production safety. Never run raw or ad-hoc DML on billing tables. Use reviewed CLIs (scripts/grant_credit.py, audit_typed_counters.py, ramp_typed_billing.py). Never full-scan tr_entities.body. Use scripts/inspect_payment_owner.py for Stripe attribution. Verify with the typed audit after any mutation.
11. Review gate. Historical practice for billing PRs: an adversarial review (codex) before merge, no auto-merge armed in parallel, and owner (Joseph) sign-off for any flag flip that changes live enforcement.
12. Hotspots. Any new Spanner index or key on a monotonic timestamp must lead with a hash shard (cf. the tr_settle_outbox_due_v2 incident, durable-settle-outbox.md §10.1). Don't "fix" latency alerts by loosening thresholds.

10. Open risks and sharp edges

1. Pre-intent loss window. A crash between receiving settle and the intent commit relies on enclave redelivery. That is an in-memory channel and does not survive enclave loss. Enclave-side durability is a cross-repo change with no owner go yet (durable-settle-outbox.md §9).
2. Overrun exposure. A settle above its hold books anyway and can push shards into debt (in_debt marks). Async adds pending exposure that the design admits has no C-only numerical worst-case bound. The admission predicate is a cached lag guard, not a hard cap (async-settle-outbox-v1.md §6). This is unresolved policy before any pilot.
3. Complexity of the shadow apparatus. About 95 shadow_v2 modules plus about 130 async-settle test files, for a feature that is still off. It is a large maintenance surface, and very few people can reason about it. Its own docs call the production observations "gatekeeper-reported". Risk: evidence tooling drifts from the live code, or blocks unrelated changes through frozen pins and inventories.
4. Frozen-main re-pin churn. Any intended change to pinned modules (gateway, authorize, settle outbox, config, partner_billing, …) needs a re-freeze plus inventory regeneration. It is easy to forget, and the oracle is skipped by default locally.
5. Dead outbox rows freeze holds indefinitely. They need a human runbook (manual charge, then release_approved). Confirm alerting on dead count and age exists and is watched.
6. Snapshot booking is live (TR_REAP_SNAPSHOT_BOOKING_ENABLED=true). The reaper now books money based on heartbeat-delivered usage, which is a newer billing behavior (Decision 70). Interactions with outbox intents and partial streams deserve scrutiny.
7. Fast-admission pilot (Go front door, leases) runs for real workspaces, yet 4 of its 6 TLA+ specs are still "planned". The hold lives outside Spanner on that path.
8. Webhook handler shape. tr/routes/internal/webhook.py is a long if-chain over dicts. The 2026-05-23 StripeObject.get regression shows SDK upgrades can silently break crediting. Synthetic chain tests are the safety net.
9. Refund/dispute handling is mostly manual for Adyen, x402, and PayPal edge cases. Recovery debt can stay unrecovered (alerts via alert_unrecovered_principal).
10. The price bot auto-commits to main hourly and auto-deploys. A parser self-heal driven by an LLM is sandboxed and spike-gated, but a bad price ships straight into the frozen per-request cost. The settle outbox will faithfully book it (MF5).
11. Multiple fake backends (memory storage.py, postgres, spanner-pg, fake Spanner). Behavior parity relies on the conformance suite plus _require_pred discipline.