Money-path observability, Stripe idempotency, ledger scaling

[ElbertePlinio]

From the 2026-07-19 complementary swarm review (read-only, complementary to #37 — assumed landing; no overlap).

P1 — money-path observability

• Zero logging on the entire money path (no console.* in packages/billing/src, packages/edge-shared/src, supabase/functions). A refund_terminal_failure (money stuck) surfaces as an anonymous 500. Add structured console.error at: createStripeWebhookHandler catch (edge-shared/src/index.ts:849-851), accountErrorResponse sites (:1026,1030), billing databaseError/BillingError throw sites — include event.id, event.type, checkout_session_id, error code.
• recordStripeEventBestEffort swallows every insert error (billing/src/index.ts:919-931). Log swallowed errors; only treat 23505 as ignorable.

P1 — Stripe idempotency

• Checkout Session creation has no idempotencyKey (billing/src/index.ts:295-306) while refunds correctly use one (:647). Add a deterministic idempotency key to session creation.

P1 — ledger scaling

• Balance is sum(amount_cents) over the full ledger, computed twice per router request; ledger grows one row per ~2¢ call. Add a covering index / running-balance or cached-balance strategy (additive migration only, per chore: reconcile hosted Supabase migration history #35).

P2 — simplify

• Delete duplicated settle/finalize/deleteCustomers trio in createDeleteAccountHandler (edge-shared/src/index.ts:728-733).
• Hoist duplicated Deno adapter boilerplate (requiredEnv/createCallerSupabase/withCors) from 5 functions into edge-shared.

Validation

• bun test workspace; deno check all touched functions; pgTAP for any migration.

[ElbertePlinio]

Addressed in #44 (fix/money-path-observability).

• P1 observability — structured, secret-free console.error at the webhook catch, accountErrorResponse 503/500 branches, and the billing refund_incomplete/refund_terminal_failure throw sites (event id/type, checkout_session_id, error code). recordStripeEventBestEffort now logs swallowed failures and only ignores Postgres 23505.
• P1 Stripe idempotency — deterministic checkout-session:<user>:<requestId> key on Checkout Session creation; retries reuse it, distinct purchases never collide.
• P1 ledger scaling — additive covering index (user_id) INCLUDE (amount_cents) (index-only scan proven via EXPLAIN + pgTAP). Running/cached balance documented as deferred.
• P2 — deduplicated the (load-bearing, kept) delete-account settlement pass into a helper; hoisted requiredEnv/createCallerSupabase/withCors into edge-shared.

Validation: typecheck ✅, vitest 354 ✅, coverage gate ✅, build ✅, pgTAP 140 ✅. deno check clean on 4/5 functions; operator-router retains 6 pre-existing (identical on main) strict-mode errors, documented in the PR (deno check isn't in CI).