Add per-domain sending ramp-up (new-domain daily limits)

[jiashuoz]

Summary

Implements per-domain sending ramp-up (a.k.a. domain warm-up): an automatic, transparent daily sending limit that rises for newly sending-verified domains over a configurable window, so a cold domain builds ISP reputation instead of blasting full volume on day one — the same protection SES/Postmark/SendGrid apply to new senders.

The ramp is scoped per domain (mailbox providers track reputation per sending domain, not per agent or account). It begins automatically when a domain first becomes sending-verified while the ramp is enabled and never re-arms on a later re-verify, so a domain that has already built reputation is never dropped back to day-one limits.

Naming: deliberately not "warmup" in customer-facing surfaces (it suggests warmup-as-a-service — synthetic mail we don't send) and not "quota" (it suggests a purchasable plan limit). "Ramp" says temporary + automatic + rising, matching SES's own "ramp-up" language.

Relates to email-warmup-support.

Design (reworked after adversarial review)

Enforced at the wire, not the handler. The gate lives in outbound.Sender.Send — the single chokepoint shared by direct sends, HITL approve (API + magic link), and the TTL auto-approve worker. Held-for-review drafts consume allowance when released, not when queued; loopback self-sends and relay-domain test sends are neither limited nor counted.

Atomic counter. domain_send_counters (one row per registrable domain (eTLD+1) + UTC day, migration 050) is claimed with a single increment-if-below-cap statement (usage.ReserveDomainSend), so concurrent bursts serialize on the row and can never jointly overshoot the cap. The counter is independent of messages/agent_identities, so agent churn (delete + recreate) cannot rewind it. Aggregating at the registrable domain (via x/net/publicsuffix, falling back to the exact domain when underivable) means sibling subdomains ramp on their own anchors but draw from one shared daily pool — verifying m1..mN.spam.example cannot multiply day-one volume by N, and PSL-listed shared apexes (github.io et al) still keep independent senders separate.

Ramp math. Linear ramp (default 50 → 2000/day over 30 days), day-indexed by UTC calendar day — the same boundary the counter resets on and retry_after_seconds points at. A domain past its ramp window is unlimited and uncounted forever (done short-circuit); "completed" is derived, never stored.

Safe enable-later. First verify always stamps the ramp anchor, but the ramp arms only while sending_ramp.enabled is true; migration 050 backfills anchors for domains verified before the feature shipped. Flipping the flag on later can therefore never retroactively limit an established sender.

Limit surface. An over-cap send returns 429 sending_ramp_limited with daily_cap / sent_today / retry_after_seconds details (carried through OutboundError.Details on send/reply/forward and approve). The TTL auto-approve worker defers a limited release to the counter reset (it bumps approval_expires_at by retry_after via identity.DeferApprovalExpiry) — it never auto-rejects on a pacing condition, and deferred rows rotate to the back of the sweep instead of head-of-line blocking other tenants' expirations. The magic-link approve page explains the message stays pending.

Metering. Billable outbound usage is recorded only after a successful delivery (matching the HITL release paths) — a throttled 429, which clients are told to retry against daily, never burns plan quota.

Client surface checklist

• Go handler + integration tests — ramp gate wired into the sender; 429 sending_ramp_limited with pacing details when a domain hits its daily cap
• Migration written + idempotent + safe on prod-sized tables — migration 050 adds sending_ramp_status/sending_ramp_started_at to domains (metadata-only), creates domain_send_counters, and backfills anchors for pre-existing verified domains
• OpenAPI spec + generated types — no new /v1 endpoints; the ramp is enforced transparently on existing send paths (spec byte-identical, TestSpecGoldenNoDrift green)
• TypeScript SDK — no new client surface
• Python SDK sync — no new client surface
• Python SDK async — no new client surface
• CLI command or flag — no new CLI surface
• MCP tool — no new MCP surface

Intentionally skipped: the ramp is a pure server-side reputation optimization on existing send paths; it reuses the standard error envelope (429 + error.code=sending_ramp_limited + details).

Operational risk

Fail-open, logged: the ramp is a reputation optimization, not a correctness gate. If the state read or slot reservation fails (transient DB blip, missing migration), the send proceeds at full volume and the enforcer logs the error — a persistently broken ramp is visible in logs, never silent.

No-op when disabled or unconfigured: disabled by default (sending_ramp.enabled: false). A self-host that never configures sending_ramp: is unaffected. Config defaults are seeded per-field, so a partial block (e.g. only target_daily) keeps the remaining defaults instead of degenerating.

Idempotent arm-once: the ramp anchor is stamped exactly once, on the first sending_status='verified' transition; re-verifies and status flaps never re-arm. Domains verified while the ramp was disabled (or before it shipped) can never be limited retroactively.

Shared relay domain unaffected: the shared relay domain stays sending_ramp_status='inactive' and is never limited.

Reserved-slot conservatism: a slot claimed for a send that subsequently fails downstream stays consumed — an error burst can only slow a ramping domain, never push it over its ramp.

Known follow-ups (not in this PR): no ramp visibility on the domain API yet (429 is the only signal); the ramp day advances by calendar even on idle days; migrating an established domain onto e2a gets day-one limits unless ops pauses the ramp per-domain (sending_ramp_status='paused', manual SQL).

Test plan

• Schedule unit tests — ramp curve, monotonicity, UTC-midnight cap step, clock skew, sanitization
• Enforcer unit tests — reserve semantics, done short-circuit (no counter I/O past ramp), inactive/paused/nil no-ops, fail-open logging on both dependency errors
• usage.ReserveDomainSend DB tests — per-domain/per-day counting, refusal at cap, 40-goroutine concurrent burst grants exactly cap
• identity.SetSendingStatus DB tests — arms on first verify when enabled; stamps anchor without arming when disabled; never re-arms or moves the anchor on re-verify/flap
• Sender unit tests — gate consulted once with the agent's domain before the wire, limit error propagates unwrapped, validation errors don't consume slots
• HTTP API tests — 429 sending_ramp_limited envelope with pacing details via the OutboundError.Details passthrough; plain errors unaffected
• Config tests — partial sending_ramp: block keeps per-field defaults; omitted block stays disabled
• Throttle-branch DB tests (post-review) — the three AsThrottleError seams driven by a REAL throttling sender: direct send → 429 with no usage metered and no message row; HITL approve → 429 with the row still pending_review; TTL worker → defers (never auto-rejects), bumps approval_expires_at ≈ retry_after, deferred row out of the next sweep
• Counter-key tests (post-review) — counterKey eTLD+1 table (incl. PSL apexes + fallback), subdomain aggregation throttles against the shared pool, cap<=0 refused on the INSERT arm with no phantom row

All tests pass locally with make test.

https://claude.ai/code/session_01Auv4sfF5kPY3v4vybLoT8L