0013. Workspace send budget and plan-limit behaviour
- Status: Accepted
- Date: 2026-11-08
Context
Section titled “Context”A workspace’s plan allowance (ADR 0014) is shared by all its projects, but each project’s sends are decided in its own store. Checking a global counter on every send would serialize all sends of a workspace and add a round trip inside the send path. Analytics Engine is sampled, so it cannot enforce quotas.
Decision
Section titled “Decision”Budget:
- A
WorkspaceBudgetDurable Object per workspace (a row withFOR UPDATEin containers) holds the period’s allowance. - Project stores obtain budget in chunked leases outside their transactions and consume them locally inside
claimSend. Chunk sizes are bounded so total overshoot of a workspace is at most 100 emails. WhenclaimSendfinds the local lease empty, it returns without claiming; the caller, outside the transaction, requests a new chunk fromWorkspaceBudgetand claims again. A message moves towaiting:plan_limitonly when the workspace budget itself is exhausted. - Transactional sends have a separate small grace pool.
Lease lifecycle:
- A grant from
WorkspaceBudgetcarries a grant ID, the billing period, an amount, and an expiry. A lease request carries an idempotency key from the project store, so a retried request returns the same grant instead of a second one. claimSendreserves one unit from an unexpired lease of the current period. Each reservation settles with billing (ADR 0012), so the allowance and the bill count the same messages:- The Send event: consumed. An
acceptedmessage whose Send event has not arrived keeps its reservation held; if none arrives within 72 hours of the attempt, the reservation is released (the message is not billed) and an alert is raised. skipped,failedbefore acceptance (permanent error),failed:outcome_unknown, and a retryable error that returns the message toqueued: released. A requeued message reserves again at its nextclaimSend. Releasingfailed:outcome_unknownmatches the rule that unresolved unknowns are not billed (ADR 0012).unknown: held until a Send event consumes it or the message becomesfailed:outcome_unknown.- A message SES drops because the address is on its suppression list: the consumed unit is returned to the lease’s allowance when the reversal is written.
- The Send event: consumed. An
- A lease expires. No new reservation is made from an expired lease; reservations already made settle against it. When an expired lease has no unsettled reservations, the project store reports its consumed total to
WorkspaceBudget, keyed by grant ID so a repeated report is a no-op, andWorkspaceBudgetreclaims the remainder. - At period reset, every lease of the old period is void: no reservations are made from it, and reservations already made settle against the old period.
- When a project store moves a message to
waiting:plan_limit, it registers itself withWorkspaceBudgetas waiting. After an upgrade or a period reset,WorkspaceBudgetwakes every registered project; theirtickreturns waiting messages that are within their 72-hour window toqueued. - Billing reads the usage ledger (ADR 0012), not the budget. Analytics Engine is never used for quotas.
At the email limit:
- Workflow and marketing sends wait as
waiting:plan_limit. They resume on upgrade or period reset within 72 hours of first enteringwaiting:plan_limit; at that deadline they becomeskipped:plan_limit(ADR 0011). - Transactional sends count toward the plan. After the grace pool is used, a transactional send request returns a synchronous plan-limit error. (Whether a transactional send API is in the MVP is open; this rule applies whenever one exists.)
- The workspace owner is notified at 80% and 100% of the allowance.
At the event cap (about 8× the plan’s emails), counted per workspace through event leases from the same WorkspaceBudget:
- Past the cap, events are accepted up to 1.5× the cap and the owner is notified.
- Beyond 1.5×, new events are rejected with a plan-limit error until upgrade or period reset.
Self-hosted installations have no budget and no limits (ADR 0003).
Amendment (2026-11-19, ADR 0041): there is no owner role. The notifications above go to the workspace’s admin users.
Consequences
Section titled “Consequences”- Plan-limit reasons (
waiting:plan_limit,skipped:plan_limit) appear in step logs so users can see why a message was delayed or not sent. - Details the plan-limit side of ADR 0014, which superseded ADR 0001: there are no overage charges.
- The exact grace pool size and the lease chunk sizes are set during implementation within the 100-email overshoot bound.