Skip to content

0035. Sending domains are written through operator endpoints and replicated to project stores in version order

  • Status: Accepted (decided by the maintainer)
  • Date: 2026-11-13
  • Amends: ADR 0034 (settles the replication path its 2026-11-13 amendment left open), ADR 0028 (adds /operator/* to the API routes), ADR 0005 (operator routes are HTTP-only and have no MCP tool, like the endpoint routes /in/*, /u/*, /provider-events/*, and the approval decision endpoint of ADR 0033), ADR 0009 (adds the SenderSetupStore port and its contract suite), ADR 0026 (adds the cl_op_ credential prefix)

ADR 0034 keeps each workspace’s provider tenant and sending domains in the control plane, provisioned by the operator until the domain management API exists, and replicates them to each project store, where claimSend checks the from domain. A store without a replica sends nothing, and skipped:sender_not_verified is terminal. Its 2026-11-13 amendment leaves three things to the replication path: an order between writes, so a delayed older replica cannot bring back a removed domain; a replication on every control-plane write; and a resync that writes the replica of every existing project store, run before or with the deploy of the check and by the development setup.

Facts that shape the path:

  • No code writes the control plane today. Workspaces and projects are inserted by SQL: the development seed, the test fixtures, and the operator.
  • On Cloudflare a project store is a Durable Object, reachable only through a Worker. wrangler d1 execute can write D1 but cannot reach a project store.
  • There are no users or roles yet (ADR 0025 is Proposed), so there is no operator identity to authorize an operator action.
Choice Alternatives Why this one
A per-workspace counter, incremented in the same transaction as each write, orders replicas The write’s timestamp; one tombstone per removed domain A counter has no clock skew between isolates and no ties; the replica stays one whole value, so nothing in the project store has to merge
Replication runs synchronously after each write; a failed store is reported and repaired by a resync Fan-out through the delivery queue; a periodic resync on a cron trigger The validation phase has few projects per workspace. A cron would apply a new domain only at its next tick, and every message claimed before that is skipped for good
Operator endpoints on the api Worker with a bearer token Only wrangler d1 execute; a separate operator Worker; api actions with an admin key SQL alone cannot reach a project store. A separate Worker would duplicate the composition root to host four routes. Provisioning sending domains is not a project’s action: an api action would put it in MCP, where a project’s own AI could verify a domain
  • workspaces.provider_tenant (nullable) and workspaces.sender_version (starting at 0), and sending_domains(workspace_id, domain, status) with status pending or verified and the key (workspace_id, domain).
  • Domains are stored in normal form: lower case, no trailing dot, and IDN labels as A-labels. normalizeSendingDomain in core gets it from the WHATWG URL host parser, which applies the UTS 46 mapping and is in the WinterTC minimum common API on both targets, and declares URL the way log.ts declares console. It refuses anything the parser refuses, IP addresses, input with userinfo, port, path, or escape characters, labels other than letters, digits, and inner hyphens of at most 63 characters, names of one label or longer than 253 characters, and xn-- labels that do not decode or that the parser would not write (it passes them through unchecked; a small RFC 3492 decoder checks them).
  • Each write of a workspace’s domains or tenant increments sender_version in the same transaction (one D1 batch). A write made by SQL instead of the operator endpoints must increment it too; otherwise project stores that already hold that version ignore the change, and a resync does not repair them.
  • The port is SenderSetupStore, apart from ControlStore: only the operator endpoints use it, never a request, job, or the send path. Its contract is that a write and its version increment commit together; describeSenderSetupStore in testing/contracts checks it, and runs on D1 in workerd.
  • The replica is { version, providerTenant, verifiedDomains }, read from the control plane in one consistent read. Domains with any other status are left out.
  • Core’s replaceSenderReplica owns the order, as core owns the message state machine: it reads the stored replica’s version and replaces the replica only if the incoming version is greater. A write of the same or an older version changes nothing, so writes can arrive in any order and more than once. ProjectTx.senderReplica.replace is a plain write. A store with no replica, or one written before versions existed, reads as version -1 and gives way to any control-plane write.
  • Every operator write is followed by a replication of the workspace’s whole setup to each project the control plane lists for the workspace. Replication mints the scope of each listed project (scopeForSenderReplication), a verified source in the Tenant model. A project store that fails is logged by ID and reported; it keeps its older replica until a resync.
  • The resync replicates every workspace, or one on request. It is the backfill for stores that never received a replica: every project store that existed before the deploy reaches project-store schema version 5 (the replica tables, after send approvals at 4) with no replica, and version 6 adds the replica’s version; projects inserted into the control plane by SQL get none either.
  • PUT /operator/workspaces/:workspaceId/sending-domains/:domain with { "status": "pending" | "verified" }, DELETE on the same path, PUT /operator/workspaces/:workspaceId/provider-tenant with { "providerTenant": string | null }, and POST /operator/sender-replicas/resync with an optional { "workspaceId" }. Each answers with the version replicated (read after the write, so a concurrent later write’s version can show here) and the project IDs replicated and failed; a resync of every workspace also lists the workspaces whose setup could not be read. The answer is 200 when every store took the replica and 503 when one did not, so the operator repeats the request or resyncs. Repeating any of them is safe.
  • They are authenticated by Authorization: Bearer (the scheme in any case) with OPERATOR_TOKEN, a platform secret with the credential prefix cl_op_ (32 to 128 characters after it), so log redaction masks it (ADR 0032). Tokens are compared by their SHA-256 hashes. Without OPERATOR_TOKEN the routes do not exist (404); with a malformed one, every operator request fails with a configuration error.
  • They are not actions: they are not in the action registry, MCP, OpenAPI, or the generated docs, and no API key reaches them. ADR 0005’s parity is for a project’s actions; these are operator tooling that the domain management API replaces with api actions.
  • No code creates projects yet. Until it does, the operator runs the workspace’s resync after inserting a project. When project creation is built, it replicates the workspace’s setup before it returns.
  • Deploy order for the sender check and replication: the control-plane migration is applied and the OPERATOR_TOKEN secret is set before the deploy, and the resync runs right after it. The check and the replication are deployed together: no build that has the check without the replication is ever deployed. Messages claimed between the deploy and the resync are skipped for good; the deploy happens while only the fake provider can be wired (ADR 0031), so no real mail is lost.
  • pnpm dev:setup seeds example.test as a verified domain of the development workspace and runs the resync through a short-lived wrangler dev with a one-time operator token. pnpm dev does not enable the operator endpoints unless the developer sets OPERATOR_TOKEN in .dev.vars.
  • A store’s replica converges on the control plane’s latest setup in any order of delivery, and a removed domain stays removed once its write has reached the store.
  • Integration tests provision their sending domains through the operator endpoint, so every send in them goes through the replication path.
  • Open:
    • The check when a send approval is requested (ADR 0033) is built with the approvals. It can read the project store’s replica, as claimSend does, so the request path does not read the control plane either.
    • A domain is not unique across workspaces. The operator verifies ownership before provisioning, and SES tenant association is the guard behind it; the domain management API decides uniqueness together with its DNS checks.
    • Replication runs in the request, one project store at a time. A workspace with many projects needs fan-out through a queue, within the Worker’s subrequest limit.
    • Operator writes are not in the audit log yet.
    • If the control plane is restored to a point before later writes, its versions fall below those the project stores hold, and stores ignore every write until the version passes theirs. A restore of the control plane therefore raises each workspace’s sender_version above any version it handed out before the restore, then resyncs.
    • The SES tenant name format is assumed to be 1 to 64 letters, digits, _, and -; it is confirmed against the SES documentation before the SES tenant is wired (B4).