docs(design): managed-warehouse compute-seconds billing plan

[benben]

What

Draft design doc (docs/design/billing-compute-seconds-plan.md) for billing per-org compute usage of managed-warehouse worker pods (remote k8s backend).

Summary of the design

• Billable unit: managed_warehouse_compute_seconds = max(cores, gib/2) × ceil(connection_seconds) — worker size folded into a single scalar (dominant-resource normalization, R=2 ≈ AWS c-family 1:2).
• Metering: bill the whole connection's worker-held wall-clock (incl. idle), reported once at connection end (end reason known then; no per-query accounting, no drip). Hard crash mid-connection loses that bill (accepted).
• Reliability: the query/teardown path only touches an in-process counter — metering never fails a query. Aggregated per-org/time-bucket in a config-store buffer, drained by a leader goroutine.
• Delivery: ship-then-delete (at-least-once) with a deterministic event uuid so retries fold to one in the billable count → effectively exactly-once, never over-bills.
• Transport: capture() events to public ingestion over NAT (like any SDK). They land in ClickHouse and a gather query rides the existing usage_report → billing pipeline — no new infra, no cross-account plumbing. (PrivateLink evaluated and rejected on cost.)
• Scope: remote k8s backend only. No enforcement/limits in v1 — reporting only.

Status

Draft / iterating. One open item: billing-side usage_key + ingestion token registration (not code). Everything else (unit, metering, buffer, drain, delivery, transport) is settled.

Opening as draft for review/iteration.

🤖 Generated with Claude Code