Skip to content

Architecture

This document describes how Customer.lite is intended to work. The first code, the walking skeleton of the first validation milestone, exists; most of what follows is not built yet.

Each section is labelled:

  • Decided — recorded in an ADR and not reopened without a new ADR.
  • Proposed — the current plan; validate it during implementation and record the outcome in an ADR.
  • Open — listed in Open items, the single list of open decisions and deferred work.

Decided (ADR 0008): a modular monolith with a hexagonal core. Core talks to the platform only through ports, and two deployment targets implement them.

  • Managed service: Cloudflare only. One SQLite-backed Durable Object (DO) per project holds the project’s data and schedules its runs with alarms; Queues carry delivery work; D1 is the control plane; R2 holds blobs and archives; Amazon SES sends email.
  • Self-host: the same Cloudflare deployment, or containers: the apps/node Docker image on Postgres. The container path is required before the open-source release.
flowchart LR
App[User's application] -- "REST /api: customers, events" --> API
Ext[External service, e.g. Stripe] -- "signed inbound webhook /in" --> API
AI[User's AI assistant] -- "MCP /mcp" --> API
Browser[Dashboard SPA] -- "/api via generated client" --> API
Reader[Email recipient] -- "click /c, open pixel /o (Proposed) on the tracking domain" --> Tracker
Reader -- "unsubscribe /u" --> API
subgraph Cloudflare
API[Worker api: REST, MCP, webhooks, queue consumers]
Tracker[Worker tracker: click redirects, open pixel]
PDO[(ProjectDO per project: SQLite data, alarms, outbox)]
WB[(WorkspaceBudget DO)]
Q[Queues: deliveries, tracking]
D1[(D1 control plane and roll-ups)]
R2[(R2 archives)]
AE[(Analytics Engine: operational metrics)]
end
API -- "execute(command)" --> PDO
PDO -- outbox --> Q
Q --> API
API -- "claimSend / recordOutcome" --> PDO
PDO -- chunked leases --> WB
API -- send --> SES[Amazon SES]
SES -- "events (Send, Bounce, ...)" --> API
Tracker -- "classified click and open records" --> Q
PDO -- ledger export, next-wake index --> D1
PDO -- archive --> R2
PDO -- health metrics --> AE
API -- lookups --> D1

Decided (ADR 0008, ADR 0020, ADR 0028). Same-origin routing on the app domain, on both targets:

Path Goes to Purpose
/api/auth/* API Better Auth routes: sign-in, sessions, OAuth authorization
/api/* API api actions
/mcp API MCP
/.well-known/* API reserved for the API: OAuth discovery metadata for MCP (RFC 9728, RFC 8414)
/in/* API endpoint: inbound webhooks
/provider-events/ses API endpoint: SES event receiver
/u/* API endpoint: unsubscribe (GET shows a page, POST unsubscribes)
/operator/* API operator endpoints for sending domains, the provider tenant, and the sender replica resync; absent unless OPERATOR_TOKEN is set (ADR 0035)
everything else dashboard SPA

Click redirects (/c/*) are served by the tracker on a separate tracking domain, never on the app domain. Proposed (ADR 0046): the tracker also serves the open pixel (/o/*) there.

On Cloudflare the api Worker serves the dashboard’s build (apps/dashboard/dist) as static assets and runs first for every path, so the API’s paths never fall back to the SPA. Build the dashboard (pnpm --filter @customer-lite/app-dashboard build) before wrangler deploy; wrangler refuses a missing assets directory. The dashboard signs in through the auth module of surfaces/api-client, against /api/auth/* on its own origin (ADR 0040).

Unit Cloudflare (apps/workers) Containers (apps/node)
API: REST, MCP, inbound and provider webhooks Worker api, which also runs the Queue consumers and exports the ProjectDO class service api
Delivery consumer inside api service delivery (jobs table by default, or SQS)
Scheduler and outbox drain DO alarms, plus a cron sweeper service scheduler (several replicas are safe with SKIP LOCKED)
Click redirect Worker tracker, deployed separately service tracker
Dashboard Workers static assets S3 and CloudFront, or the all image
Public site: landing, pricing, legal pages, docs, llms.txt (managed service only, ADR 0042) assets-only Worker on the apex domain, built from the private cloud/site/ none
Small installation two wrangler deploy runs plus assets one container with the all entrypoint and Postgres (docker compose)

Decided (ADR 0018, ADR 0022). TypeScript, pnpm workspaces, one package per directory.

Responsibility Location
Domain, ports, workflow engine and step types, action registry, auth (sole minter of ProjectScope), ingest, tracking, billing, webhooks, extension points core/ (for example core/engine/steps/, core/actions/, core/extensions/)
Shared Kysely repositories, SQLite and Postgres migrations, DO dialect adapters/sql/
Cloudflare adapters: ProjectDO, WorkspaceBudget DO, rate-limiter DO, D1, Queues, R2, secrets, fetch adapters/cloudflare/
Node and SQLite adapters for tests and development adapters/node-sqlite/
Postgres adapters: executor, scheduler poller, jobs table, ControlStore, rate-limiter and budget rows adapters/postgres/
AWS adapters: SQS, S3, Secrets Manager adapters/aws/
Signing and encryption adapters/webcrypto/
Sign-in and sessions with Better Auth (ADR 0040) adapters/auth-better-auth/
Email providers adapters/email-ses/, adapters/email-fake/
HTTP app generated from the registry surfaces/http/
MCP tools generated from the registry surfaces/mcp/
Typed client generated from OpenAPI, and the hand-written auth module (ADR 0040) surfaces/api-client/
Port contract suites testing/contracts/
Composition roots apps/workers/, apps/node/, apps/dashboard/
Cloud-only extensions and the cloud composition root, with their own cloud/AGENTS.md cloud/ (never synced to the public repository)
Documentation, ADRs, llms.txt (the managed service’s public site renders them, ADR 0042) docs/

Decided (ADR 0018). Enforced by pnpm strict dependencies and exports, tsc -b project references, dependency-cruiser, and an ESLint determinism ban in core. The check-dependencies skill explains how to fix a violation.

flowchart BT
core[core]
sql[adapters/sql] --> core
cfa[adapters/cloudflare] --> sql
nsa[adapters/node-sqlite] --> sql
pga[adapters/postgres] --> sql
aws[adapters/aws] --> core
oth[adapters/webcrypto, adapters/email-*, adapters/auth-better-auth] --> core
http[surfaces/http] --> core
mcp[surfaces/mcp] --> core
cli[surfaces/api-client] -. generated from OpenAPI .-> http
contracts[testing/contracts] --> core
appcf[apps/workers] --> cfa & oth & http & mcp
appn[apps/node] --> pga & nsa & aws & oth & http & mcp
dash[apps/dashboard] --> cli
cloudroot[cloud/ composition root] --> appcf
  • cloudflare:* and Workers types only in adapters/cloudflare and apps/workers. node:* and the AWS SDK only in adapters/node-sqlite, adapters/postgres, adapters/aws, and apps/node. Adapters that run on both targets use only fetch and WebCrypto; adapters/auth-better-auth’s dependency also uses AsyncLocalStorage from node:async_hooks, which both targets provide (ADR 0040).
  • apps/dashboard imports only surfaces/api-client and UI libraries.
  • Public code never imports cloud/.
  • Core reads time and randomness only through Clock and IdGenerator (including IdGenerator.secret() for approval link secrets, ADR 0033).

Decided (ADR 0009). Ports: ProjectExecutor and ProjectTx (including wakeAt and outbox), DeliveryQueue, DeliveryRateLimiter, ControlStore, SenderSetupStore (ADR 0035), BlobStore, SecretProvider, OutboundHttp, EmailProvider, SystemMailer, ApprovalDelivery (ADR 0033), SessionVerifier (ADR 0040), OperatorAlerts (an extension point, ADR 0038), Clock, IdGenerator, Signer, SecretCipher.

  • ProjectExecutor.execute(scope, command, input) runs a core command atomically. Commands for one project are serialized; a command awaits only ProjectTx methods, never external I/O.
  • One contract suite per port in testing/contracts runs against every adapter: Cloudflare adapters in Miniflare through @cloudflare/vitest-plugin and adapters/node-sqlite on every pull request; concurrency contracts for adapters/postgres on a real Postgres (PGlite only for repository tests); the deployed Cloudflare environment nightly, including DO eviction and crashes.
  • Tests call DOs through their stubs, never through runInDurableObject.
  • A port change updates every adapter in the same pull request.
Term Meaning
workspace A billing account with users and roles, containing one or more projects. One workspace is one SES tenant
project The isolation boundary for customer data. On Cloudflare, one ProjectDO
tenant In “tenant isolation” and check-tenant-safety, the project. “SES tenant” is the SES resource, one per workspace. Elsewhere we say workspace or project
action One operation declared in core/actions/: api (REST, MCP, OpenAPI, docs) or endpoint (HTTP only)
run One customer’s pass through one pinned workflow version
step One node of a workflow definition, with a stable step ID
goal A workflow-level exit condition, rechecked before each send
message The email one send step produces for one run; unique per (run, step)
send attempt One provider call for a message, identified by attempt_id
state and reason A message or run state with its explanation, written state:reason, for example waiting:plan_limit or failed:outcome_unknown. Step logs use the same form
isolation fixture The test fixture for tenant isolation: two workspaces, the first with two projects, so both cross-project and cross-workspace access are tested
app domain The domain serving the dashboard and the API. Click tracking uses a separate tracking domain
condition A rule over a customer’s attributes and event summary in the one condition language of ADR 0045. Proposed
saved audience A named condition in a project (aud_…), referenced as { inAudience } and expanded into a workflow version at save. Proposed, ADR 0045
trigger audience The audience field of a trigger: who an occurrence reaches, or the entry filter of an event trigger. Proposed, ADR 0045
inline customers list The { customers } predicate: up to 1,000 customers, resolved to internal IDs at save. Proposed, ADR 0045
engagement record One recorded open or click, with its class (machine, proxied, direct), reason, and classifier version, without IP address or user agent. Proposed, ADR 0046
human open, machine open An open classified as likely by a person, or as made by Apple Mail Privacy Protection, a scanner, or a prefetch. Opens are estimates. Proposed, ADR 0046
message fact A first-time timestamp on the message row (sent_at, delivered_at, first_human_click_at, …), written only from null to a value. Proposed, ADR 0047
conversion A goal met within the conversion window: credited to the run’s last accepted message in reports (last touch), and to the arm from assignment in experiments (intent to treat). Proposed, ADR 0047
experiment, arm An A/B test on one send step, and one of its variants or its holdout (assigned, not sent). Proposed, ADR 0048
broadcast A one-off send of one email to a set of customers at one time, stored as a generated workflow with a once trigger. Proposed, ADR 0049
confirmation The token a sending action returns with its preview, without which the action does not commit. Proposed, ADR 0050

Decided that tenant isolation applies everywhere (ADR 0007), with physical isolation on the managed service (ADR 0008).

  • A workspace is a billing account and one SES tenant (ADR 0024). It contains users with roles, and one or more projects. Suppression is workspace-scoped: the workspace’s list is kept in the control plane and replicated to each of its project stores.
  • A project is the isolation boundary. Every customer, event, workflow, run, message, template, unsubscribe record, inbound source, and outbound destination belongs to exactly one project. On Cloudflare each project is its own DO; in Postgres every row carries project_id under row-level security. Every table carries project_id on both targets.
  • Only core/auth mints a ProjectScope, from a verified source: an API key, OAuth grant, or dashboard session (for a session, the project named in the Customer-Lite-Project header once the user’s membership in its workspace is confirmed, ADR 0041); an inbound source ID with a valid signature; a provider event’s send-time tags confirmed against the message row; a verified click token; a send approval link whose secret matches the stored approval (ADR 0033); the project named in a one-click unsubscribe link, once the control plane lists it; the unsubscribe command then verifies the link’s token against the stored message (ADR 0036); a project the control plane lists under the workspace whose sender setup is being replicated (ADR 0035); or a queue message produced by core. Repository methods take no project ID.
  • Exception: provider delivery events, click redirects, send approval links, and unsubscribe links. They arrive without project authentication. The handler resolves the project from the send-time tags (project_id, message_id, attempt_id) or the signed click token, then verifies it against the stored message row before any write. An approval link names its project in the path: the project is resolved through ControlStore first (unknown projects never reach a project store), and the link’s secret is checked against the stored link row before anything is read or written. An unsubscribe link likewise names its project in the path: the scope comes from that project as the control plane lists it, and nothing else (unknown projects never reach a project store); the unsubscribeByLink command then verifies the token against the stored message row before the customer is read or written. Unmatched events are dropped and counted, never written.
  • Proposed exception: the sending-domain claim check (ADR 0039). Claiming a sending domain reads across workspaces, because a domain has one owner per installation: SendingDomainClaims.isHeldElsewhere(scope, domain) answers only yes or no (another workspace holds a claim on the domain, or a verified claim on a parent or subdomain), and the claim is taken by a unique index. Neither returns another workspace’s ID or row. Every other sending-domain read and write goes through a WorkspaceScope, which core/auth mints as ADR 0041 decides (a project key or MCP grant acts on its project’s workspace; a session names it in the Customer-Lite-Workspace header, with its membership and role) or from a provisioning job written by core. The operator endpoints’ PUT uses the same check.
  • Exception: the installation admins of a self-hosted installation (ADR 0041), users whose verified address ADMIN_EMAILS lists. At each of their sign-ins, WorkspaceStore.ensureInstallationAdminMemberships makes them admin of every workspace, and workspaces.create adds them to the new workspace; removeInstallationAdminMemberships undoes the sign-in step for a bootstrap user whose session failed. These writes span workspaces by design, touch only that user’s rows, read nothing back, and never run in cloud mode, which refuses the variable.
  • Roles, API keys, and MCP grants are in Authentication and access.

Main entities: customer (external ID, email, attributes, timezone), event, workflow definition and its immutable versions, send approval, workflow entry, workflow run, step log, message and send attempt, trigger fire and schedule slot, tracked link and click, template, workspace suppression record, unsubscribe record, inbound source with mapping, outbound destination with signing secret, usage ledger row, tombstone. Proposed: saved audience, customer event summary, engagement record, experiment and its assignments, send confirmation.

Decided (ADR 0010).

Store Holds
ProjectDO (SQLite), or Postgres in containers definitions and versions (with their definition hash), send approvals and their links, templates, customers, a hot window of events and step logs, deduplication keys, runs, entries, messages, trigger fires and slots, a replica of the workspace suppression list, provider tenant, and sending domains, unsubscribes, sources and destinations (encrypted), usage ledger, outbox, tombstones
D1 control plane, or the Postgres control schema workspaces (with their provider tenant), approver addresses until users exist, sending domains, users, sessions, roles, API-key hashes, OAuth grants, routing (key, source, tracking host → project), audit log, usage ledger exports, next-wake index, restore generations, deletion log, workspace suppression lists (HMAC of the address), admin search roll-ups
R2, or S3 archived raw events, step logs, and clicks; audit log archives; exports; encrypted buffered-ingest payloads
Analytics Engine sampled operational metrics only: DO health, abuse and deliverability signals. Never quotas or billing
Queues, or the jobs table IDs, blob references, and versioned payloads only, no personal data
Server logs no secrets and no personal data: every line goes through logError, which masks credentials, email addresses, and IP addresses (ADR 0032)
  • Repositories use Kysely, take a Kysely<DB>, and never call db.transaction(); a per-target transaction runner wraps every command (ctx.storage.transaction(async …) on a DO, db.transaction() elsewhere). We maintain our own small DO dialect. Types are normalized at the repository boundary. Migrations are per dialect.
  • The DO keeps a hot window; older raw events, step logs, and raw clicks are archived. At the largest tier, 90 days of raw events (about 12 GB) would exceed the 10 GB DO limit. Storage alerts fire at 70%; the largest tier is load-tested before it is sold.
  • Ingest for hot projects is buffered through Queues. The edge writes the payload as an encrypted blob in R2 before acknowledging, keyed by project and HMAC(external_id); the queue carries only the reference; the consumer deletes the blob after applying it; customer deletion deletes unconsumed blobs (ADR 0023).
  • Point-in-time restore of a DO: sending disabled; the restore generation in the ledger export watermark is incremented and D1 reconciles exports on (message_id, kind); deletions after the restore point are replayed from the D1 deletion log; rollback-window messages are quarantined and reconciled against SES events and an attempt journal outside the DO. The full runbook is an open item.
  • Proposed retention, to be fixed by the load test: deduplication hashes and tombstones 13 months; runs, step logs, and messages 13 months (archived beyond the hot window). Click aggregates were planned indefinitely; ADR 0047 (Proposed) replaces them in the first release with reports computed from message facts kept 90 days, and long-term aggregates wait for the load test.
  • Proposed (ADR 0045 to ADR 0050), pending the load test: message rows with their facts stay in the project store for MESSAGE_FACT_RETENTION (90 days in the first release, the maintainer’s decision of 2026-11-20), then are archived; late engagement after that is dropped and counted. Engagement records stay for their hot window, then are archived with raw clicks. The store also holds saved audiences, customer_event_stats (at most 200 event names, the maintainer’s decision of 2026-11-20; rows only for pairs actually performed), experiments and experiment_assignments (kept until the experiment is concluded or ended plus EXPERIMENT_ASSIGNMENT_RETENTION), and send_confirmations. The estimated budget at the largest tier is about 6 GB typical and about 7 GB heavy, at the 70% alert, so the load test must measure it (ADR 0047). No user-facing number comes from Analytics Engine or D1; tracker queue messages carry a classification, never an IP address or user agent.

Decided step types: trigger, delay, condition, send email, send outbound webhook, exit (ADR 0015). Triggers are events or time-based (ADR 0016).

sequenceDiagram
participant E as Event, API call, or time trigger
participant D as Project store (DO or Postgres)
participant Q as Delivery queue
participant C as Delivery consumer
participant B as WorkspaceBudget
participant P as Amazon SES
E->>D: execute(ingestEvent): dedupe, store, match triggers, create run, wakeAt(now)
D->>D: tick: delay sets wake_at, condition reads current state
D->>D: send step: eligibility check, message queued, outbox job
D->>Q: drain outbox
Q->>C: job (IDs only)
B-->>D: chunked lease (obtained outside transactions)
C->>D: claimSend: reserve budget, recheck eligibility, persist attempt_id, lease
C->>P: send, tagged project_id, message_id, attempt_id (no automatic retries)
P-->>C: message ID / error response / timeout
C->>D: recordOutcome: accepted, retry later, failed, or unknown
P-->>D: Send, Delivery, Bounce, Complaint events (EventBridge API destination, applied synchronously)
  • A run executes saved rules. It never calls an LLM.
  • A run pins the definition version it started on. Editing a workflow creates a new version (ADR 0007).
  • Decided (ADR 0033): a workflow has a latest version and a live version. Saving never changes the live version; triggers start runs on the live version only. Activation (draft or stopped → active) makes the latest version live and increments the activation epoch; publishing makes the latest version of an active workflow live without changing the epoch, so runs on the previous version keep running and sending. workflows.activate does whichever applies, and a sending version goes live only when a person approves it (where required, below).
  • Built (optimistic concurrency on save): workflows.upsert takes an optional expectedLatestVersion. A save that would write is refused with conflict and the latest version in error.latestVersion unless the stored latest version (0 when the workflow does not exist) is that one; the check runs in the project-store transaction that writes, so of two saves on one version one wins. A save that writes nothing is never refused, and only a changed definition makes a version, so a rename alone is not guarded. Without the field, saving is unchanged.
  • Decided (ADR 0044, by the maintainer): that approval is required only in workspaces whose sendApprovalRequired setting is on; it is off by default, on the managed service and self-hosted alike. Where it is off, workflows.activate makes a sending version live at once, after the sender check.
  • Decided (ADR 0044, by the maintainer): pause and rollback exist; a rollback needs an approval where approval is on and none where it is off; there is no send cap after an unapproved change, and no notification when approval is turned off.
  • Proposed (ADR 0044): each change of the live version is an append-only live change with its principal (liveChanges.list), kept while its epoch is current. A workflow or a whole project can be paused: claimSend holds a send as waiting:paused after its final skips and before any budget is reserved, and skips it 72 hours after it first waited. workflows.rollback makes the previous live version of the epoch live again and adds the current one to the workflow’s withdrawnVersions, whose runs stop (exited:version_withdrawn) while the restored version’s runs continue.
  • Run state is plain rows interpreted by core, so a code deploy does not replay steps; new code reads old rows. Changing the meaning of a step type is a new step type or a migration.
  • Each step has a stable step ID. Side-effect idempotency keys derive from (project, run, step).
  • Every step writes a log entry with an outcome and a machine-readable reason, for example skipped:suppressed, skipped:unsubscribed, skipped:plan_limit, waiting:plan_limit, exited:goal_met, exited:workflow_stopped, failed:provider_rejected, failed:outcome_unknown; Proposed: skipped:holdout and skipped:condition_unknown (ADR 0045, ADR 0048) and waiting:conversion_window (ADR 0047). “Why was this not sent?” must be answerable from step logs alone.

Decided (ADR 0017):

  • The server assigns every ingested event an event ID; an optional client idempotency key deduplicates ingestion within the project. A replay means the same idempotency key or the same inbound source event ID; a resubmission without either is a new event.
  • An event-triggered run’s ID is hash(project, workflow_id, event_id); the version is recorded on the run, not in the ID. Time-triggered run IDs use the fire key from ADR 0016.
  • Re-entry policy per workflow: once, no-while-active (default), restart, or always. Invariant: except under always, a customer has at most one active run per workflow, and under once at most one run ever. The policy belongs to the workflow and changes only while it is stopped. Enforced in the run-creating transaction by a partial unique index on workflow_entries(workflow_id, customer_id) WHERE active AND policy <> 'always', plus an entry marker unique on (workflow_id, customer_id) for once that outlives the run.
  • Stopping a workflow cancels its waiting runs (exited:workflow_stopped), skips its queued and waiting:plan_limit messages (skipped:workflow_stopped), and removes pending fires. Each activation increments the workflow’s activation epoch; claimSend and tick treat runs of an earlier epoch as stopped, so a quick reactivation cannot release them.

Decided (ADR 0016): attribute_date, schedule (constrained RRULE, at most one occurrence per local day), and once. A per-customer fire index and per-timezone schedule slots avoid scanning all customers; the audience is snapshotted at the occurrence time; a per-occurrence recipient cap applies; catch-up windows decide late fires; DST gaps shift forward and repeated hours use the first instant; timezone changes invalidate that customer’s fire rows; rows carry a generation tag. Times are computed with runtime Intl; a golden-file test runs on both targets and weekly on the latest runtimes. workflows.preview_triggers previews the fires; its activation confirmation token is superseded by the send approval of ADR 0033. Proposed: a trigger’s audience uses the condition language of ADR 0045 and may be set on every trigger type; a confirmation returns on the committing action (ADR 0050); the per-occurrence recipient cap stays what bounds each occurrence.

Decided (ADR 0015): a workflow may define a goal, a workflow-level exit condition, rechecked before each send; a run whose goal is met exits with exited:goal_met. Proposed: the goal is also evaluated when a relevant event arrives, so waiting runs exit early. Proposed (ADR 0047): a workflow with a goal has a conversionWindow (default 7 days, at most 30, the maintainer’s decision); after its last send step the run waits in waiting:conversion_window, no longer holding the re-entry index (the maintainer’s decision of 2026-11-20), and ends completed or exited:goal_met.

Proposed (ADR 0045):

  • One condition language (all, any, not; attribute predicates with defined type-mismatch and date semantics; performed and not_performed with within, or since: "run_start" in goals, over customer_event_stats for a capped set of referenced event names; { inAudience }; { customers } resolved to internal IDs) for trigger audiences, condition steps, goals, saved audiences, and broadcasts. A newly summarised event name is backfilled from the raw event hot window; a predicate whose window starts before the name’s summarised_since is unknown, and an unknown condition resolves toward sending less: audiences and trigger audiences do not select the customer, a condition step exits the run, and an unknown goal at the pre-send check skips the send (skipped:condition_unknown), counts no conversion, and skips experiment assignment. Previews report condition_unknown exclusions and fullyKnownFrom. ADR 0016’s snapshot rule is amended: the drain considers customers created by the occurrence time and evaluates each on their data when the cursor reaches them. One pure evaluator in core checks one customer and each row of a scan batch. Email-shaped literals are refused.
  • Saved audiences are dynamic only. A workflow version keeps an expanded copy of each referenced audience with its conditionHash; the copy is authoritative. Deleting an audience referenced by the latest, live, or a rollback-reachable version of the current epoch is refused, and a version referencing a missing audience cannot go live (audience_missing).
  • audiences.preview counts matching and eligible with excluded counts and samples: within the request up to AUDIENCE_SYNC_COUNT_LIMIT customers, otherwise as a bounded count job, at most AUDIENCE_MAX_CONCURRENT_COUNTS per project.
  • Audience entry and exit triggers are deferred (the maintainer’s decision).

Proposed (ADR 0049): broadcasts.create takes content, recipients (customers, audience, or condition), sendAt (now or a local time in a zone), and an optional goal, and generates a live workflow of kind: "broadcast" (its ID is the broadcast’s) with a once trigger, one send step, and re-entry once. Status is derived (awaiting_approval, scheduled, sending, sent, missed, cancelled, terminal). Editing, activating, and rolling back a broadcast answer conflict; broadcasts.cancel is the stop.

Proposed (ADR 0048; A/B and a holdout in the first release, a winner chosen by a person or their AI, and fixed-horizon statistics are the maintainer’s decisions): a send step’s experiment has one or two variants and an optional holdout (which needs a goal). Assignment is a sticky hash of project, workflow, experiment, and customer, made after the eligibility check and written to experiment_assignments, one row per customer. Arms, metric, minimum sample, the goal’s condition hash, and the conversion window freeze when the experiment first goes live, and outcomes use the frozen goal. After a conclusion, every customer who reaches the step gets the winner; a live version with an ended experiment sends its first variant to everyone. Conversion is counted from assignment for every arm (intent to treat), and only matured assignments count. The verdict (leader or no_difference) is computed once, when every arm reaches its required sample (adjusted for unequal weights), with Wilson intervals, Newcombe difference intervals, z-tests, and Bonferroni over a defined family of at most three comparisons; later data is shown as post-horizon. experiments.conclude is a live change of kind concluded; one that ends a holdout is confirmed and, where approval is required, approved (conclusion). Rollback does not revert a conclusion.

Decided (ADR 0015): test runs use the same engine, skip delays, are marked as tests, and can simulate the current time for time-based triggers. Proposed side-effect rules:

  • Emails go only to an explicitly given test recipient, who must be a verified test recipient; how a recipient is verified is decided with test runs (ADR 0033).
  • Outbound webhooks fire only if the test run opts in, with a test marker header.
  • Test runs are not metered. Open: abuse limits on test sends.

Decided (ADR 0011; the Send event window of accepted, ADR 0038): the project store owns every retry. States: queued (with a deadline; overdue jobs are re-enqueued) → sending (with attempt_id and a lease) → accepted, or back to queued after a definite retryable error, or failed, or unknown; queued can also become waiting:plan_limit or skipped. An expired lease becomes unknown, never a resend. claimSend reserves budget before the final eligibility check. The dead-letter queue drains back through claimSend.

Every state with a deadline (queued claim deadline, sending lease expiry, unknown 72 hours after the attempt, accepted without its Send event first at the end of the one-hour Send event window that alerts the operator, then 72 hours after the attempt, waiting:plan_limit 72 hours after first entering it) registers wakeAt(deadline) in the transaction that enters it, and tick applies the due transition.

Wake recovery: setAlarm inside the transaction callback; the alarm handler catches errors per item, quarantines poison items, and re-arms in finally; a cron sweeper over the D1 next-wake index is the backstop.

Decided (ADR 0007, ADR 0011, ADR 0017): immediately before every send, including jobs that waited, claimSend rechecks unsubscribe and workspace suppression, the workflow goal, that the workflow is active in the run’s activation epoch and the run has not exited, and the global and per-workspace kill switches. Templates support variable substitution and a working unsubscribe link.

Decided (ADR 0012):

  • AWS client retries are disabled. Timeouts and lost responses are unknown; only definite pre-acceptance errors are retried, by the store.
  • attempt_id is persisted before sending; sends are tagged; both configuration sets publish Send, Reject, Bounce, Complaint, Delivery, DeliveryDelay, and RenderingFailure events; the provider message ID binds on the first event.
  • An unknown message resolves from a Send event within 72 hours of the attempt, otherwise becomes failed:outcome_unknown: never resent, not billed, alerted.
  • Billing has one rule: a message is billable when its SES Send event arrives. A successful send response moves the message to accepted but writes no ledger row. Bounces count, except a send SES drops because the address is on a suppression list, and a Reject, which write a reversal. Pre-send blocks and unresolved unknowns are not billed; a Send event after 72 hours is not billed, is recorded as a late acceptance on the message and in its step log, updates suppression, and alerts.
  • The ledger holds at most one charge and one reversal per message in the project store, and is exported to D1 with a (restore_generation, sequence) watermark; D1 deduplicates on (message_id, kind). A reversal counts only once its message has a charge (ADR 0034).

Decided (ADR 0013): a WorkspaceBudget DO per workspace hands out chunked leases (overshoot at most 100 emails), with a separate transactional grace pool. Grants carry the billing period, are idempotent per request, expire, and are reclaimed after their reservations settle; a reservation is consumed by the Send event (the same rule as billing), released on skipped, failed (including failed:outcome_unknown), requeue, or no Send event within 72 hours, held while unknown or awaiting the Send event, and returned on a suppression-drop reversal; leases of the old period are void at period reset. At the limit, workflow and marketing sends wait as waiting:plan_limit and resume within 72 hours of first entering it or become skipped:plan_limit; after an upgrade or period reset, WorkspaceBudget wakes the workspace’s waiting projects; transactional sends get a small grace, then a synchronous error. Admins are notified at 80% and 100% (ADR 0041). Events are capped at about 8× emails, accepted up to 1.5× with a notification, then rejected. Only cloud mode enforces limits.

Decided in the MVP (ADR 0015). Events and customer updates arrive through REST or MCP with a project API key, or with a publishable key under its restrictions (ADR 0026). Writing to the project store before replying makes acceptance durable. For hot projects whose ingest is buffered through Queues, acceptance means the payload is stored as an encrypted blob and its reference durably enqueued, and deduplication happens when the project store consumes the event. When a client idempotency key is present, the edge derives the event ID deterministically from (project, key), so a replay gets the same ID on either path. Proposed: concurrent attribute updates resolve last-write-wins by client timestamp.

Decided in the MVP. Proposed design:

  • Each inbound source has its own endpoint URL under /in/ and its own secret.
  • The endpoint verifies the signature using the source’s scheme (for example Stripe’s scheme or generic HMAC) before parsing. Unverified requests are rejected and not stored.
  • A mapping turns the JSON payload into an event and optional customer updates. Mappings are declarative data (field paths, constants, simple transforms), never executable code.
  • The user’s AI assistant drafts the mapping through MCP from a sample payload. A test endpoint applies a mapping to a sample and returns the resulting event without storing it.
  • The source’s own event ID is the deduplication key.
  • Customer.lite never configures the external service. The AI gives the user instructions, such as where to register the endpoint URL in Stripe.

Decided as a workflow step in the MVP with these requirements; proposed details:

  • Signing: HMAC-SHA256 over timestamp and body with a per-destination secret (cl_whsec_), sent in a signature header. Receivers can reject old timestamps.
  • Idempotency: each delivery carries an idempotency key header derived from (project, run, step). Retries reuse it.
  • Retries: exponential backoff with a cap on attempts, decided by the project store. Retry on network errors, timeouts, 429, and 5xx; do not retry other 4xx.
  • Timeouts: a short per-attempt timeout.
  • SSRF protection: validate the URL before each fetch: HTTPS only, no IP-literal hosts in private, loopback, link-local, or metadata ranges, and none of the service’s own hostnames. Fetch with redirect: "manual" and re-validate every hop with a hop limit. On Workers, DNS resolution happens inside fetch, so protection against hostnames that resolve to private ranges relies on Workers’ egress restrictions; apps/node uses a resolver-pinned check (resolve, validate the address, connect to that address).
  • Secrets: a signing secret is returned in plaintext only in the response that creates or rotates it. Signing secrets and destination credentials never appear in logs, step logs, or any other API or MCP response.
  • Approval page: the send approval view (sendApprovals.view, ADR 0033) returns the whole workflow definition. When the webhook step is built, any credential or secret header it can hold must be redacted or left out of that view, as of every other response (ADR 0007, ADR 0032).

Decided (ADR 0024): Amazon SES on à la carte pricing; one SES tenant per workspace with tenant-level SES suppression, and our own suppression scoped to the workspace to match; global transactional and marketing configuration sets (per-workspace sets only for dedicated IPs); provider_account_id stored per workspace; our own DNS checks, calling the SES management API (1 request/second) only on change.

Decided shape (ADR 0009, ADR 0012, ADR 0034):

Operation Responsibility
send(message, tags, context) Takes a provider-neutral send context (stream, providerTenant). Returns accepted with a provider message ID; rejected (permanent or retryable) for a definite error about this message; unavailable for a definite refusal that is not about this message (sending paused, credentials, configuration); or unknown (5xx, timeout, reset, unparseable response). Provider detail goes in providerReason. No automatic retries
verifyWebhook(request) Verifies the provider’s event delivery before parsing
normalizeEvents(payload) Maps provider events to send, delivered, delayed, hard bounce, soft bounce, complaint, reject, and rendering failure, with the provider event ID for deduplication and the send-time tags
capabilities Declares idempotency-key support, status lookup, and rate limits. SES has neither idempotency keys nor status lookup. Unused today and listed for removal under the YAGNI follow-ups

Hard bounces and complaints update suppression; late and out-of-order events never regress state. Self-hosting does not require SES (ADR 0003). Open: bring-your-own provider credentials on the managed service.

Decided (ADR 0034):

  • EmailProvider.send takes a provider-neutral send context (stream, providerTenant); the SES adapter maps them to the configuration set and TenantName. The provider tenant and sending domains are replicated from the control plane to each project store, like suppression, so the send path never reads the control plane.
  • adapters/email-ses calls SESv2 SendEmail with fetch and aws4fetch SigV4 (retries: 0, 10-second timeout), tagged project_id, message_id, attempt_id.
  • Outcomes: 200 with a MessageId is accepted; throttling is a retryable rejection; paused sending (including a MessageRejected “Sending disabled for” a paused tenant), an exhausted daily quota, credential, and configuration errors are unavailable (requeued without using up attempts, failed after 24 hours, alerted); any other MessageRejected, an unverified MAIL FROM domain, and other 4xx are permanent; every 5xx, timeout, and connection error is unknown. The adapter’s code goes in providerReason, apart from the closed state reason.
  • A workspace sends only from its own verified sending domains: checked when an approval is requested, and in claimSend against the replica (skipped:sender_not_verified; a store without a replica sends nothing); SES tenant association is a third guard.
  • Decided (ADR 0035): the operator writes sending domains (normalized: lower case, no trailing dot, IDNs as A-labels) and the provider tenant through /operator/* endpoints authenticated by OPERATOR_TOKEN; each write increments the workspace’s sender_version and replicates the whole setup to each project of the workspace, and a project store keeps only a newer version, so a delayed write cannot bring back a removed domain. A resync backfills every store; pnpm dev:setup runs it.
  • Decided (ADR 0037): the provider tenant is recorded with its Region, one of the allowlist SES_REGIONS (default SES_REGION), and the send context carries it; the SES adapter sends through that Region with its configuration set ({region} in the name) and sends nothing through a Region outside the allowlist; every control-plane write records the default Region for a workspace without one, so a later default does not move it; message events are matched whatever their Region, tenant status events by tenant and Region.
  • Proposed (ADR 0039): sending domains and provider tenants are provisioned at runtime. A ProviderProvisioning port (SES management over fetch with its own IAM credential, a fake, and manual for provisioning by hand) is called only by one paced runner per Region, which runs jobs from the control plane at most one call per interval, one job per domain, and settles unknown outcomes by repeating name-keyed calls (already_exists is resolved by lookup, never adopting an identity of another workspace). A workspace proves control of a domain with its own TXT record before anything is claimed or created at SES; the domain is then claimed by one workspace per installation and moves pending_ownership → provisioning → pending_dns → verified (or to failed before its identity exists, or through removing, which deletes the identity, to expired or failed), with SES polled behind our DoH check within SES’s 72-hour window; every change into or out of verified replicates as a job, and a removed verified domain is disassociated only after its replicas change. SES lets a verified domain send from its subdomains, so the exact-match replica check is the subdomain guard. Users manage domains with sendingDomains.add, list, get, verify, and remove (target: "workspace", principal: "any" as in ADR 0041: reads for members and project keys, writes for admins by session or an MCP grant with admin), screened through an AbuseScreening extension point that fails closed on add only; the operator endpoints remain for repair.
  • Account-level SES suppression is disabled and tenants use tenant-level suppression; an OnAccountSuppressionList bounce, or a complaint with that subtype (SES’s report of the same drop), is a misconfiguration alert, reverses the charge, and does not suppress in the workspace.
  • Events: configuration sets publish to the EventBridge default bus; a rule forwards aws.ses events to an API destination at /provider-events/ses, authenticated by a header secret, with a dead-letter queue and depth alarm. providerEvents.receive applies them synchronously. Delivery statuses in order: delayed < soft_bounced < delivered < content_rejected < bounced < complained. Permanent bounces and complaints suppress; transient bounces do not.
  • Configuration: EMAIL_PROVIDER (fake or ses) and SES_* variables and secrets only; a missing value fails every request with an error naming the variable and sends nothing.
  • Built (B4): apps/workers wires the provider EMAIL_PROVIDER names, parsing its settings once per request; with any provider but fake, an APP_ORIGIN that is not https: is refused. The operator endpoints take their Regions from the same parsed SesSendConfig.regions the adapter sends through. In cloud mode, the delivery consumer makes no provider call for a send context without a provider tenant and records it unavailable with provider_tenant_missing, so it is retried for 24 hours and alerted. While a provider the Worker can wire is not the selected one, its /provider-events/:provider answers 503, which EventBridge retries, instead of the 404 of an unknown provider, which it dead-letters at once. In cloud mode, an unset or fake EMAIL_PROVIDER sends nothing: each send is unavailable with fake_in_cloud_mode, and fake webhooks are refused. The 503 lives in the Cloudflare composition root (apps/workers/src/worker.ts), which alone knows which providers it can wire; apps/node must copy it when it wires providers. Setup: Setting up Amazon SES; the deploy gate’s runbook: Turning on real mail.

Decided (ADR 0029): operator system mail (sign-in codes, account mail, notifications) goes through a SystemMailer port, sent on the managed service by Cloudflare Email Service (3,000/month included on Workers Paid, then $0.35 per 1,000, checked 2026-11-07), so an SES pause cannot lock users out. Send failures alert. The service is in beta; a separate SES account can be added as a failover adapter. Cloudflare self-hosts can use the same; container self-hosts configure their own SMTP or SES; the first-boot sign-in path still applies.

  • The port takes to, subject, text, and an optional html, and returns accepted, rejected, or unknown, in the terms of SendResult; one attempt, never retried. The sender is the installation’s SYSTEM_MAIL_FROM; on Cloudflare the mail goes through the send_email binding SYSTEM_MAIL. There is no no-op default: without system mail configured, what needs it fails with a configuration error (amendment of 2026-11-13 in ADR 0029).
  • Operations: keep the Email Service account’s “Drop suppressed recipients” setting off (its default). With it on, a suppressed approver is dropped silently and the send is reported as accepted; with it off, the send is rejected with recipient_suppressed.

Decided (ADR 0024):

  • Our auto-pause acts before SES’s tenant pause: warn at 2% bounces or 0.05% complaints, pause at 4% or 0.08%, per stream, above a minimum sample size. SES tenant status events from EventBridge are reflected immediately.
  • Marketing mail carries RFC 8058 one-click unsubscribe: POST with a token unsubscribes, GET never does. DKIM must cover the List-Unsubscribe headers.
  • Decided (ADR 0036): the link is {APP_ORIGIN}/u/{projectId}/{messageId}/{token}; each attempt of a marketing message gets a random cl_unsub_ token, of which only the SHA-256 hash is stored on the message; the headers reach the provider through OutgoingEmail.headers (SES Content.Simple.Headers, not ListManagementOptions); every refusal is the same 404 not_found.

Decided (ADR 0020); open tracking is deferred because image proxies and automatic loading make opens unreliable.

  • Links are rewritten to /c/<token> on a tracking domain separate from the app domain (one shared tracking domain in the MVP; an optional per-workspace custom tracking subdomain later); the token is self-contained and signed ({kid, project_id, message_id, link_index, url}, HMAC-SHA256, rotatable keys).
  • The separately deployed tracker verifies, re-checks the URL rules, and redirects to the URL in the token. It never takes a destination from the request.
  • Clicks are recorded after the redirect through the tracking queue. Bot and scanner clicks are flagged and excluded; unique human clicks are aggregated per message, template, and workflow step.

Proposed (ADR 0046), amending the deferral above; the defaults are the maintainer’s decision of 2026-11-19:

  • Tracked HTML mail ends with a pixel /o/<token> on the tracking domain. Tokens carry their type (t: "o" or "c") and each route accepts only its own; /o always answers the GIF with no-store; HEAD is not recorded.
  • Two pure core functions used by each target’s tracker: deriveNetworkSignals turns the IP address and ASN into network flags in memory, never logged or stored, and classifyEngagement classifies requests as machine (Apple MPP by Apple-owned network plus proxy user agent, a heuristic; scanners, never by datacenter network alone; an optional hidden decoy link, tracking.decoyLink, off by default because hidden links can cost deliverability), proxied (Gmail, Yahoo, and other image proxies), or direct (iCloud Private Relay included). Lists are versioned data files updated by pull request, and each record keeps its classifier_version.
  • The tracker dedupes per message, kind, and class within a short window at the edge and enqueues a tracker-minted event ID and the classification, never the IP address or user agent. The store dedupes by event ID and adds prefetch (relative to our accepted_at or the provider’s delivery time), burst (only for clicks recorded after an earlier click or a decoy click), and opens on bounced messages as machine, from what it knows at that time; nothing is reclassified retroactively.
  • Reports give opens, humanOpens, and machineOpenShare together with the caveat opens_unreliable. Conditions cannot test opens or clicks.
  • tracking.opens and tracking.clicks per project are on by default for marketing mail; transactional mail is never tracked; a send step or a customer’s trackingOptOut turns tracking off. The tracking choice is shown at project creation, and the docs name the user as controller.

Proposed (ADR 0047):

  • Message facts. Dimensions (workflow, version, step, variant, template, saved audiences; a broadcast is a workflow), a cohort_at from our first claim or creation (not the provider’s Send event), first-time timestamps written only from null to a value, capped open and click counts, the final state and reason, and whether the message was tracked. Counts derived from facts are idempotent against duplicate events and redeliveries.
  • Reports are GROUP BY queries over message rows by cohort_at and dimensions; counters and rollups wait for the load test. Days are built exactly in the report’s timezone (the project’s by default). Reports are per project only.
  • Conversions use the run’s waiting:conversion_window after its last send step; reports attribute them to the last accepted message (last touch), and experiments to the arm from assignment (intent to treat).
  • Actions (read-only, principal: "any", scope read, role member): metrics.get extended with period, interval, timezone, grouping, filters, and caveats; metrics.workflow; messages.list extended to recipient-level rows filtered by dimension, state, and engagement within the retained window (members see them, the maintainer’s decision); messages.get with facts and engagement records; experiments.get (ADR 0048).
  • Privacy: engagement records are personal data, hold no IP address or user agent, and are deleted with the customer, as are experiment assignments; reports are recomputed from what remains.

Decided (ADR 0040, superseding ADR 0025; spike on workerd and D1 passed 2026-11-18 with better-auth 1.7.25):

  • Package: Better Auth lives in adapters/auth-better-auth. It is given a Kysely instance and sits behind the core port SessionVerifier, which never extends a session. apps/workers sets nodejs_als.
  • Routes: the mount at /api/auth/* forwards only a listed set of routes (404 otherwise), strips every token key from responses, and refuses requests without a usable client IP. surfaces/api-client has a hand-written auth module for these routes. They are exempt from parity, like endpoint actions.
  • Email codes: 6 digits, 5 minutes, 3 attempts, stored as an HMAC keyed by the auth secret, mailed through SystemMailer.
  • Google: PKCE and state; linked only when email_verified; no provider tokens kept.
  • Sessions: cookie __Host-cl_session (Secure, HttpOnly, SameSite=Lax, no Domain). Sessions last 7 days and are extended only by the dashboard’s session read. Session rows hold no IP or user agent.
  • CSRF: cookie-authenticated non-GET requests need a JSON body and an Origin equal to APP_ORIGIN. API-key requests and /mcp ignore cookies.
  • Rate limits: in D1 (auth_rate_limits, HMAC keys), per IP, and per email per 15 minutes and per day. A daily cron deletes expired auth rows.
  • Logs: Better Auth’s logger passes only fixed warn and error codes to logError.
  • Self-hosted: sign-in only for ALLOWED_EMAILS ∪ ADMIN_EMAILS, checked at every sign-in and on the next request after a removal. Neither set is a configuration error. A BOOTSTRAP_TOKEN (cl_boot_) creates the first user and session with one conditional insert.
  • Fallback: an in-house module behind the same port, routes, and users columns. The switch needs a migration and signs everyone out.
  • Deferred: the Node and Postgres check (before the open-source release).
  • MCP OAuth: no longer deferred; in the first release, by the maintainer’s decision of 2026-11-20, as Proposed in ADR 0051 (below).
  • Approvals: decided by the maintainer (2026-11-18), the dashboard shows and re-requests approvals but never approves; passkeys may later be the fresh-presence step-up.
  • Built: adapters/auth-better-auth with the 0005_auth control-plane migration; on apps/workers the /api/auth/* mount, the daily cleanup cron, and nodejs_als; and the dashboard’s sign-in screens on the auth module of surfaces/api-client. Setup: Setting up sign-in. The workspaces.* and members.* actions and every project action of ADR 0041 accept a session, with the CSRF rule above; the 8-day session test calls a project action daily (apps/workers/test/project-sessions.test.ts); the managed service’s abuse screening of user creation is not built yet.

Decided (ADR 0041), partly built:

  • Built: the memberships table and workspaces.name and created_by (0006_memberships); the principal, target, and role of every api action, with core/auth resolving a session’s Customer-Lite-Workspace header against the current membership; session authentication of REST with ADR 0040’s CSRF rule (/mcp never accepts the cookie); and workspaces.create, workspaces.list, and workspaces.get (the workspace the header selects), session-only. workspaces.create takes an optional idempotency key. Member management, session-only: members.list (any member), and members.add (a user who has signed in, by address), members.setRole, and members.remove (admins), with the last-admin rule as one conditional UPDATE or DELETE. The installation admins of a self-hosted installation (users whose address ADMIN_EMAILS lists): admin of every workspace, written by workspaces.create and at each of their sign-ins, which also backfills earlier workspaces; members.setRole and members.remove refuse to demote or remove them while listed (conflict). The any principal: every project action accepts a key or a session, and a session names its project in the Customer-Lite-Project header, which core/auth resolves in one control-plane read through the project’s workspace and the current membership and role (a key ignores the header). The role is read when a request starts, before the handler, so a call already running when its user is demoted or removed completes. A session never gets the approval link that SEND_APPROVAL_DELIVERY=response returns to a key, though its call still mints and records one, which counts against the daily link cap and replaces the link a key’s earlier call returned; the isolation fixture runs every project action as a session. Projects, session-only: projects.create (admins; one project per workspace, conflict for a second, as one conditional insert with the acting-admin check; an optional idempotency key, unique per workspace, 0007_project_idempotency_key; the new project’s store gets the workspace’s sender setup, on a replay too) and projects.list (members). API keys, session-only, for admins of the project the Customer-Lite-Project header selects: apiKeys.create (a secret key, its plaintext in that response only; an optional idempotency key whose replay answers conflict naming the key), apiKeys.list (redacted, revoked keys included), and apiKeys.revoke (effective on the next request). Keys have stored IDs, which core/auth returns as their identity, and the acting-admin check is in the statement that writes (0008_api_key_management). Not built yet: grants on any actions (ADR 0051), restricted and publishable keys, key expiry and rotation, invitations, a member leaving a workspace by themselves, admins as approvers, and the abuse screening of workspaces.create on the managed service.

  • Tables: memberships(workspace_id, user_id, role) next to users, with at least one admin kept by a conditional statement.

  • Roles: admin and member only, decided by the maintainer; admin holds every power ADR 0026 gave owner. Any admin can remove or demote another admin, accepted for small teams; a top tier can be added later from the last-admin rule and workspaces.created_by.

  • Principals: project_key and user (a session). An OAuth grant acts as its user, only on any actions.

  • Action fields: ApiAction declares principal (project_key, user, or any), target (project, workspace, or actor), and the least role. A project key reaches workspace actions only for read. Sessions get every API scope their role allows.

  • Tenant selection: a session selects the tenant with the Customer-Lite-Project or Customer-Lite-Workspace header, never an input.

  • Session-only actions: workspaces.create and workspaces.list (at most MAX_WORKSPACES_PER_USER created, default 3), projects.create and projects.list (one project per workspace until suppression is replicated across projects), and apiKeys.*. They stay MCP tools and answer forbidden to keys and grants.

  • Approvers: they become the workspace’s admin users. Installation admins (users whose address ADMIN_EMAILS lists) are admins through membership rows.

  • Send approval setting (ADR 0044): only an admin’s session changes sendApprovalRequired (workspaces.setSendApproval); no project key or MCP grant can, in either direction. Until sessions reach api actions, the operator sets it through PUT /operator/workspaces/:workspaceId/send-approval.

Decided (ADR 0026):

  • Workspace roles admin and member; ADR 0026’s owner was removed by ADR 0041 (2026-11-19), and its powers are admin’s.
  • Project API keys: cl_sk_ secret, cl_rk_ restricted, cl_pk_ publishable (restricted events only, provenance-tagged, cannot trigger sends unless the workflow opts in, rate limited), and cl_whsec_ webhook signing secrets. The operator token of the operator endpoints is cl_op_ (ADR 0035). Returned in plaintext only in the creating response (creation or rotation) and redacted to prefix and last four characters everywhere else; prefixed for secret scanning, rotatable with overlap; API keys are stored hashed, signing secrets encrypted.
  • MCP grants are bound to one project with scopes read, write, send, admin; the effective permission is scope ∩ role, computed per request.
  • A per-workspace audit log in D1, about one year, then archived to R2.

Proposed (ADR 0051); that claude.ai, ChatGPT, and Claude Code connect to /mcp by OAuth without an API key in the first release is the maintainer’s decision of 2026-11-20:

  • Rule: a grant is a delegated credential, admitted exactly where a project key is (any actions), with its user’s current role on top of its scopes. It names one user, one project, and its API scopes.
  • Flag: MCP_OAUTH, off by default, gates the metadata, the OAuth routes, and grants on /mcp.
    • Built (S1, non-production deployments only): MCP_OAUTH=true turns on, in adapters/auth-better-auth, mcp() and cimd() at 1.7.25, the two metadata documents, the mount’s OAuth routes (authorize, token, revoke, our consent POST) and the grant verifier, with their tables in migrations 0009 and 0010; the dashboard’s minimal consent page at /oauth/consent, which also signs a signed-out user in and returns (it is the plugin’s loginPage as well as its consentPage). The daily cron deletes expired and ended grants’ token rows, replay copies past their window, expired client-assertion rows, and CIMD client rows past their cache time that no token names. A refresh token’s revocation ends its whole grant. The D1 limits (L1), the prerequisite of MCP_OAUTH=true on any publicly reachable deployment, are built: authorize per client IP, and CIMD fetches per client IP and per host for clients not yet stored, with a stored client served as stored when its refetch is refused, and IPv6 keyed by its /64 in every per-IP limit. The prerequisite is met only with both of those rules in. A sustained flood of random paths on a shared host can still keep a client that is not stored from connecting; that is accepted for staging only, and its fix (#99) precedes S2 and production. Staging runs with the flag on only once L1 is deployed there, and S1’s deploy gate runs on staging after that. Claude Code over loopback is checked locally; the deployed gate is open.
  • Authorization server: Better Auth’s mcp() and cimd() plugins in adapters/auth-better-auth; their spike on workerd and D1 failed no blocking check (findings). Authorization code with PKCE S256 and rotating refresh tokens only. RFC 8414 metadata for the issuer, {APP_ORIGIN}/api/auth, and RFC 9728 metadata for the resource {APP_ORIGIN}/mcp at its path-inserted location. RFC 9207 iss is sent.
  • Clients: CIMD only at launch, fetched under the outbound-webhook SSRF rules with no redirects. DCR returns behind MCP_OAUTH_DCR, with its limits, only if a target client fails on CIMD.
  • Tokens: opaque cl_oat_ access tokens (1 hour) and cl_ort_ refresh tokens rotated by the plugin with an explicit reuse window; cl_oac_ codes (60 seconds); all stored hashed, except that a rotation’s response is kept encrypted, like sessions.token, from rotation until it is cleared lazily on the chain’s next refresh or by the daily cron (ADR 0021 amended). Grants expire 90 days after consent. Accepted on /mcp only, where a GrantVerifier is wired.
  • Grants: mcp_grants, owned by core behind ControlStore, holds identity, project, scopes, expiry, and our revocations; the plugin’s token rows hold token liveness, and a grant is usable only when both agree. Revoking sets revoked_at and deletes token rows, so a grant ID always names its user, unless the user is deleted.
  • Consent: a dashboard page with the existing session. It shows the account and the redirect host, and warns to continue only if the user started the connection. The user picks one project; read and write are preselected, admin never is. Each consent creates a new grant.
  • Principal: oauth_grant is admitted only by any actions; scope ∩ role is checked in dispatch on every request. Workspace-level and user-only actions stay session-only.
  • Challenges: core returns { caller } | { refusal }; /mcp answers 401 with resource_metadata. A missing scope is a forbidden tool result until a spike shows clients follow the 403 step-up.
  • Revocation: grants.list and grants.revoke (session-only), member removal, user deletion or disablement, and the self-hosted allowlist. The plugin’s own revocation of every token chain of a (user, client) pair on refresh-token reuse is accepted; a grant left without a live token answers invalid_token and is listed as ended, computed when read, without setting revoked_at. Dashboard sign-out ends the current access tokens, and a client holding an offline_access refresh token refreshes. A grant is never a human approval, and ADR 0050’s confirmation tokens bind its grant ID.
  • Editions: in the open-source edition too.
  • Build order: O0 spike; P1 refusal seam (built) and P2 any with projects.* (built, in two pull requests); then slices: S1 Claude Code end to end, S2 claude.ai and ChatGPT, S3 revocation, S4 only what the spike proves necessary.

Decided (ADR 0005, ADR 0019):

  • Every operation is declared once in core/actions/. kind: "api" actions generate REST routes, OpenAPI, MCP tools, the docs index, and llms.txt, and the parity test fails when one is missing. kind: "endpoint" actions (inbound webhook, SES event receiver, unsubscribe, click redirect) are HTTP-only and may not use API-key, OAuth, or session auth.
  • Tool annotations mark each tool read-only, idempotent, or destructive. Sending actions require user confirmation, enforced server-side.
  • Decided (ADR 0033): activating or publishing a sending workflow version creates a send approval bound to the version, its definition hash, and the re-entry policy. Each approver gets their own one-time link (secret in the URL fragment, re-minted on every mailing) through the ApprovalDelivery port. The decision is an endpoint action, deliberately not an MCP tool; sendApprovals.get reports its status. The approval page renders AI-written content only as text under a strict CSP. Test sends go only to verified test recipients; a direct send outside workflows would need an approved template.
    • Every change to a live sending workflow and every reactivation needs a new approval; neither reusing an approval nor hashing only the send steps.
    • SEND_APPROVAL_DELIVERY=response is the ApprovalDelivery adapter that returns the link to the caller in the optional approvalLink output field, for self-hosted installations, development, and tests only; the cloud mode refuses it.
    • During the validation phase, approvers are operator-provisioned addresses in the control plane, mailed through Cloudflare Email Service; they become admin users when users exist (ADR 0041).
  • Decided (ADR 0044, by the maintainer): the approval above is required only in workspaces that turn on sendApprovalRequired; it is off by default. Elsewhere there is no server-side confirmation; ADR 0050 (Proposed, below) changes that by the maintainer’s decision of 2026-11-19. Proposed in the same ADR: workflows.activate, workflows.rollback, and the resumes annotated destructive (a hint a client may ignore); and the actions workflows.pause, workflows.resume, sending.pause, sending.resume, sending.get, workflows.rollback, liveChanges.list, and the admin-session-only workspaces.setSendApproval, each with full parity.
  • The dashboard and MCP call only api actions.
  • Proposed (list pagination, built for customers.list and events.list; to be recorded in an ADR before another list adopts it): a list that may outgrow one page takes limit (1 to 100, 50 by default) and an optional cursor, and answers nextCursor, null on the last page. It lists newest first by a time that never changes (createdAt, receivedAt), ties by ID descending, and pages by keyset on that time and ID, so rows added meanwhile never repeat or skip a row; each order has a (project_id, time, id) index. A list ordered by a time that changes, such as workflows.list by updatedAt, is not paged this way. The cursor is opaque (core/src/actions/paging.ts): it names its list, so another list refuses it with validation_error, and it only positions the caller’s own project’s rows, so it needs no signature. Prefix filters are left out of newest-first lists, because no one index serves both; exact lookups stay with the get actions. Open: no action reads back the properties events.list omits for their size, and customers.upsert and events.track bound neither the number of attributes or properties nor their total size, so a customers.list page has no size bound.
  • Proposed (ADR 0050; confirmation in every workspace, including where approval is off, is the maintainer’s decision of 2026-11-19): actions marked startsSends (broadcasts.create, workflows.activate, workflows.rollback, workflows.resume, sending.resume, experiments.conclude) declare previewSends, and the dispatcher enforces two calls. Without confirmation, the call returns confirmation_required with a preview and a cl_conf_ token, or confirmation_pending while a count runs (a token is issued only with exact counts). With the token, the commit consumes it in the same project-store transaction. The token is single-use, expires after SEND_CONFIRMATION_TTL, is stored as a hash, and binds the credential identity, the action, the RFC 8785 canonical input (without the idempotency key), the approval setting, and the previewed bound values; a mismatch answers confirmation_invalid (409) with a fresh preview. It proves that what commits matches a fresh preview, not that a person saw it; where approval is required, the confirmed action then creates the approval. This meets the confirmation precondition of “No real mail yet” (ADR 0031); the rest of B4’s deploy gate still applies.
    • Built (G1, workflows.activate only; the other actions above do not exist yet and declare startsSends when they are built): an action declares startsSends with preview, which runs a project command (previewWorkflowActivation) and returns what the preview shows and the values the token binds. defineApiAction derives the optional confirmation input, the output { status: "confirmation_required" | "done", preview?, confirmation?, result? } (one object with the action’s own output in result, because MCP output schemas must be objects and the workflow view has its own status), and the errors confirmation_invalid (409, with preview and confirmation in the error body) and rate_limited. invokeApiAction runs it through runConfirmed. The committing command (activateWorkflow) takes the token’s claim as input, recomputes the preview’s bound values in its transaction, and refuses (confirmation_invalid, nothing written) without a valid token whenever the version sends; it uses the token only when it commits, so a refusal such as sender_not_verified leaves the token usable. The credential identity is api_key:<keyId> or session:<userId> (credentialIdentity); keyId is the key’s stored api_keys.id. A retry with a used token is answered by the action’s replay from a result reference recorded after the first call succeeded (for activation, the approval’s ID; a one-time approvalLink is not returned again); a token whose call failed after use answers confirmation_invalid with a fresh preview. Expired tokens are deleted on the next issuance once SEND_CONFIRMATION_GRACE_MS (1 hour) has passed, rather than by tick, since only issuance adds rows. The approval setting is bound as approvalRequired: true until ADR 0044’s setting exists. Configuration: SEND_CONFIRMATION_TTL (seconds, 900 by default) and SEND_CONFIRMATION_RATE_LIMIT (tokens per project per hour, 60 by default; over it, rate_limited). confirmation_pending comes with count jobs in G6. The preview of an event-triggered workflow shows the customers who had the trigger event in the last 30 days as an unbound estimate, each send step’s from, subject, and body as written, and sender_not_verified as a warning.

Built (ADR 0031): surfaces/mcp serves stateless Streamable HTTP at /mcp with one tool per api action (named resource_verb), dispatched through invokeApiAction like REST. Every api action declares an output schema, which invokeApiAction enforces. The HTTP surface serves OpenAPI 3.1 at /api/openapi.json; docs/api/reference.md, docs/llms.txt, and the typed client in surfaces/api-client are generated by pnpm docs:generate. The client’s types come from the OpenAPI document through openapi-typescript (a dev dependency), and the client has no runtime dependencies. Its fetch wrapper is hand-written and imports only the generated module. call(actionName, input) takes the action’s flat input, as MCP does, and the generated route table places each field in the path or the query string; the rest goes in the JSON body. A non-2xx response throws ApiError with the error envelope; a response without it reads as internal_error. The parity and isolation tests in apps/workers/test run every action on both surfaces, REST through this client. MCP authenticates with a project API key until MCP OAuth is built. EMAIL_PROVIDER selects the email provider (B4); fake, the default, sends no real mail, and ses waits for B4’s deploy gate.

Built (plan row A2 of ADR 0033): workflows.activate on a sending latest version leaves the workflow unchanged and returns the pending approval in sendApproval; sendApprovals.get reads it; the sendApprovals.decide endpoint action (POST /approvals/:projectId/:linkId/decision, auth: "approval_link") decides it. invokeApiAction refuses the decide command for every api action, and the handler types leave it out. Choices made while building it:

  • Its response implementation of ApprovalDelivery lives in core (responseApprovalDelivery) because it uses no platform API. apps/workers requires APP_ORIGIN (the origin the links point to), and with SEND_APPROVAL_DELIVERY=response refuses every request, with a log line naming the variable, in cloud mode, which any non-empty CUSTOMER_LITE_CLOUD selects.
  • Link secrets are cl_apsec_ followed by IdGenerator.secret(), so log redaction masks them like the other credential prefixes.
  • The daily cap counts minted links per project and UTC day (SEND_APPROVAL_DAILY_LINK_CAP, 50 by default); over it, workflows.activate answers rate_limited (429) and writes nothing.
  • A wrong secret or an unknown link or project answers not_found (404); a link whose approval is not pending, has expired, is superseded, or no longer matches the definition hash or re-entry policy answers conflict (409) with the reason.
  • Follow-ups from the A2 review, no code change yet: decidedLinkId is stored but not shown; a configuration error also makes the queue consumer retry its batch. (A4b moved the approver lookup out of ApprovalDelivery and deletes a removed approver’s link on a re-request.)
  • When workflows.stop is built, it must cancel the pending approval (ADR 0033): until then a pending approval requested before a stop can still be decided for the same version.

Built (plan row A3 of ADR 0033): GET /approvals/:projectId/:linkId serves one static page for every link from surfaces/http, with its script and stylesheet as same-origin files (/approvals/page.js, /approvals/page.css), because the CSP allows no inline script or style. The script reads the secret from the fragment and posts it to the sendApprovals.view endpoint action (POST /approvals/:projectId/:linkId/view, auth: "approval_link"), which returns the approval, the workflow’s ID and name, and the version’s definition as JSON; the page sets every value with textContent. Every response under /approvals, the view and decision endpoints and their errors included, carries the ADR 0033 headers and Cache-Control: no-store. Choices made while building it:

  • The view and the decision share one command-level check (openApprovalLink): the secret first, then the link’s approver (A4b), then every bound value. The view does not check the sender replica, so an approval whose from domain was removed since the request can still be seen and declined; approving it is refused with sender_not_verified.
  • A refused view or decision answers conflict (409) with the refusal in error.reason (one of the derived or stored non-pending statuses, reentry_policy_changed, sender_not_verified, or approver_removed), which the page maps to its own text: core exports the reasons as SEND_APPROVAL_REFUSALS, the page’s REFUSAL_TEXT is typed by them, and a reason the page does not know reads as “This approval can no longer be decided.” Endpoint actions are not in OpenAPI, so this field is not in the shared error schema.

Built (plan row A4b of ADR 0033): approvers in the control plane and approval links by mail. Choices made while building it:

  • Approvers are a table of the control plane (approvers: ID apv_…, workspace, address in normal form, trimmed and lower case), read through ControlStore.approversOf(workspaceId) and written through the ApproverStore port by PUT /operator/workspaces/:workspaceId/approvers with { "emails": [...] } (at most 100), which replaces the whole list and answers the approver IDs; an address already listed keeps its ID. The addresses are in the body, never the path. Like the other operator endpoints, it is not an action.
  • A self-hosted installation may set ADMIN_EMAILS (comma-separated addresses): those approve for every workspace, in place of the control plane’s lists, under pseudonymous IDs deriveId("adm", "approver", address). The cloud mode refuses ADMIN_EMAILS, because one list for every workspace would let one customer’s approver decide another’s approvals; response delivery with it is a configuration error; and the operator endpoint refuses with conflict while it is set.
  • The composition root pairs the recipients of approval links with their delivery (SendApprovalDeps): the caller with response, the approvers with email. pairSendApproval checks the pair by type, so caller recipients cannot be given to email delivery. ApprovalDelivery only delivers, and answers the links that reached their recipient. email delivery (emailApprovalDelivery, in core because it uses only the SystemMailer port) is the default of SEND_APPROVAL_DELIVERY; it sends one text mail per approver, 5 at a time, and counts a link delivered only when its mail is accepted; any other outcome, or a throw, is logged with the outcome, the provider’s reason code, and the link ID only. The mail puts the link and fixed instructions first and the workflow’s content, quoted line by line between framing lines, last. apps/workers builds the Cloudflare SystemMailer only with email delivery.
  • no_approvers (422) refuses a sending version, after the sender check, when the workspace has no approver; nothing is created. approval_delivery_failed (502) answers a request whose links did not all reach their approver, with the counts (delivery: { delivered, total }), after the mailed time is recorded for the links that did. The approval stays pending; the next request re-mints and mails only the links never delivered.
  • Who may view or decide is who would get a link now. The view and decision endpoints check the secret first, then read the recipients and pass their IDs to the shared openApprovalLink check, which refuses a link whose approver is not among them with conflict and the reason approver_removed; the approval stays pending. A re-request deletes a pending approval’s links of approvers no longer listed.
  • Each request mints one link per approver against the daily cap (SEND_APPROVAL_DAILY_LINK_CAP, 50 by default), so a workspace with more approvers than the cap is always rate_limited, although the operator endpoint accepts up to 100 addresses; raise the cap for such a workspace.
  • OpenAPI lists every error code of a response in x-error-codes, since two codes can share a status (sender_not_verified and no_approvers).

Decided (ADR 0002, ADR 0003, ADR 0008):

  • One codebase. The environment variable CUSTOMER_LITE_CLOUD switches between cloud (managed) and self-hosted behaviour.
  • Billing and usage metering live in core and are enforced only in cloud mode. Self-hosted has no plan limits and no billing.
  • Cloud-only marketing, analytics, and operations code plugs in through extension points with no-op defaults in core/extensions/. The cloud composition root lives in cloud/ and wraps the apps/workers factories; public code never imports cloud/. Private paths (AGENTS.cloud.md, cloud/, docs/cloud/) are excluded from the public sync.
  • Configuration comes from environment variables and platform secrets. No secrets or operator-specific values in code or history.
  • The managed service’s public site (landing page, pricing, legal pages, and the rendered docs/ under /docs) is a static, assets-only Worker on the apex domain, built with Astro and Starlight from the private cloud/site/ (ADR 0042). Staging has a noindex copy on a host of its own under dev.<domain>, with no redirect (Proposed, ADR 0052). The open-source edition has no public site.

Proposed initial extension points: product analytics events, signup and lifecycle hooks for marketing, operational alerting, and abuse screening. Operational alerting is built as OperatorAlerts (ADR 0038): alert occurrences go through the project store’s outbox with an incident key without the project, and the implementation deduplicates by that key.

flowchart TB
CloudRoot["cloud/ composition root (private)"]
Workers[apps/workers factories]
Core[core: API, workflows, billing]
Ext[core/extensions: interfaces + no-op defaults]
CloudExt["cloud/ extensions (private)"]
CloudRoot --> Workers
CloudRoot --> CloudExt
Workers --> Core
Core --> Ext
CloudExt -. implements .-> Ext

Decided (ADR 0014): one plan with every feature and unlimited profiles under fair use, priced by an emails-per-month slider from $9 (10k) to $449 (1M); events capped at about 8× emails; yearly billing gives two months free; no free tier, trial, or enterprise plan; a dedicated IP add-on at high volume. No public price comparison against competitors is published, on the public site or elsewhere (the maintainer’s amendment of ADR 0014, 2026-11-20). Proposed: audiences, broadcasts, tracking, reports, and experiments (ADR 0045 to ADR 0050) are part of the one plan and add no billable unit; opens and clicks are not events and do not count toward the event cap; a holdout message is not billed. Their limits are configuration, not plan values in code.

Proposed estimates (Cloudflare and SES pricing checked 2026-11-07); recalculate from measured prototype usage.

Item Estimate
Fixed cost of the managed service at zero users about $6/month (Workers Paid $5, domain)
Platform cost per 1,000 emails about $0.013, plus SES $0.10
Platform cost per 1M events about $6, dominated by DO rows written; events are the main cost driver
Event summary upsert (ADR 0045, Proposed; estimate 2026-11-20) one extra row write per ingested event whose name is summarised (at most 200 names), in the ingest transaction: up to about 15% more on the per-event cost above, depending on how many events are of summarised names
Weekly digest to 100k customers (about 433k emails/month) about $7 platform plus about $43 SES
Open and click tracking (ADR 0046, Proposed; estimate 2026-11-19, not measured) about 1 to 1.5 engagement records per email (Apple MPP alone makes opens close to deliveries to Apple Mail); each is a tracker request, a queue message, and a few row writes, so tracking adds roughly the per-email platform cost again

Components with a fixed monthly cost are not defaults for the managed service.

Decided (ADR 0006): the first code pull requests build this flow as a walking skeleton, before other features. Within one project: signup event → delay → condition on current state → email delivery → delivery result recorded.

These four checks are executable tests from the start:

  1. Replaying an event (same idempotency key or source event ID) does not send twice.
  2. Unsubscribing during a delay prevents the send.
  3. One project cannot read or change another project’s data, in the same workspace or another one (the isolation fixture).
  4. Duplicate provider webhooks do not inflate metrics.

Then create and validate the same workflow through MCP.

Built (ADR 0030): the skeleton runs on apps/workers (ProjectDO, Queues, D1) with adapters/email-fake, and the four checks are the tests in apps/workers/test (replay, unsubscribe-during-delay, isolation, duplicate-provider-webhooks). The ProjectExecutor contract suite runs on the Durable Object and on adapters/node-sqlite. Creating and validating the workflow through MCP is apps/workers/test/mcp-workflow.test.ts (ADR 0031).

The walking skeleton explicitly excludes: the dashboard and Better Auth (it authenticates with a project API key), MCP (built right after it, ADR 0031), real SES sending (it uses adapters/email-fake, which emits provider events, including duplicates), time-based triggers, inbound and outbound webhooks, click tracking, WorkspaceBudget and plan limits, buffered ingest, archival, workspace suppression replication beyond one project, and the Postgres adapter.

Open. The single list of open decisions and deferred work. ADRs and the sections above may mention an open point inline; every such point is tracked here.

Settle these in the design of the first code that touches them:

  • Split delivery queues (transactional and marketing) and rate buckets per workspace and global, with batched token leases.
  • Provider event ingestion: the Worker verifies the EventBridge API destination’s header secret and applies events synchronously; the provider-events queue is added only if latency approaches EventBridge’s 5-second timeout (ADR 0034).
  • DO schema migrations: a schema_version, forward-only expand and contract inside blockConcurrencyWhile, a version inventory in D1, an idle sweep that migrates idle DOs, versioned queue payloads, and migration failures that do not consume alarm retries.
  • Where the global and per-workspace kill switches are stored and how fast a change reaches every project store (the check itself is decided in ADR 0011).
  • A test per re-entry policy and for stop-then-reactivate across activation epochs (ADR 0017).
  • Event ordering: last-write-wins by client timestamp.
  • The archive format, so one customer’s records can be deleted.
  • Rate-limiter denial or a crash after claimSend turns an email that was never sent into unknown and then failed:outcome_unknown. Proposed fix: call DeliveryRateLimiter.acquire before claimSend, plus an optional release from sending back to queued, fenced by attempt_id.
  • The last-admin rule of ADR 0041 holds only where its conditional statement is the writer. members.setRole and members.remove are its only writers that demote or remove, each one conditional statement. An address removed from ADMIN_EMAILS keeps its membership rows as ordinary memberships, so a workspace’s only admin can be a user who can no longer sign in; the operator recovers it by listing another address in ADMIN_EMAILS, whose user is admin of every workspace at their next sign-in (ADR 0041’s amendment). Three cases remain open: a future user-deletion cascade would delete membership rows without the conditional statement; on Postgres every writer that removes or demotes an admin must take the workspace row lock first; and an operator path to remove a former installation admin’s rows in bulk, which today the workspaces’ admins remove one at a time.
  • members.add adds a signed-in user without their consent, and its not_found tells an admin whether an address has signed in (ADR 0041, amendments). Enforced: while anyone may sign in (SIGN_IN_OPEN), it answers forbidden. Still open: invitations that the invitee accepts, which must replace it before the managed service mails admins as approvers; until then, the listed users of an installation can find and add each other.
  • Workspace-level actions (such as creating a workspace, or ADR 0039’s sendingDomains.*) do not fit the ProjectScope and ProjectExecutor contract of ADR 0019. Decided fix, built for the workspaces.* actions: the workspace and actor targets of ADR 0041.
  • Customer deletion removes message rows, so a late provider event (such as a complaint) cannot be matched and never reaches suppression. Proposed fix: keep a minimal message correlation row with no personal data, plus the ledger rows.
  • A late provider response for an unknown attempt moves it to accepted (billing still on the Send event): implemented (ADR 0030); still to be stated in ADR 0011 and ADR 0012 by a superseding ADR.
  • An audience snapshot taken after an outage cannot reconstruct membership at the occurrence time (ADR 0016); define what is used instead.
  • The unkeyed hash(external_id) in tombstones and deduplication keys is pseudonymous personal data; use a per-project HMAC, as the deletion log already does.
  • The tracking queue needs the IP address and user agent for bot detection, which conflicts with “no personal data in queues”.
  • What the platform logs outside our code (ADR 0032): uncaught exceptions, and the request metadata and retention of Workers Logs and Logpush, set in deployment configuration; settled in B4’s deploy gate (Platform logs). Request URLs include the token of one-click unsubscribe links (ADR 0036).

Not built by the skeleton (ADR 0030); each comes with the feature that needs it:

  • The re-entry policies once, restart, and always; workflow stop; activation epochs across stop and reactivation.
  • Send approval and SES: see Plan: send approval and Amazon SES.
  • Restricted and publishable keys, key management, roles, and scope ∩ role checks.
  • The provider-events queue and SES; budget reservation in claimSend; kill switches; the cron sweeper over the next-wake index.
  • apps/node, adapters/postgres, and a background timer for adapters/node-sqlite.
  • Templates with variable substitution and the unsubscribe link in the body, with a styled confirmation page (the /u/* endpoint and the List-Unsubscribe headers are U1 of the plan below).

Follow-ups from the skeleton’s review, to do before the code they touch grows:

  • Send state machine and wakes:
    • claimSend refuses only external run exits (goal_met, workflow_stopped), not exit_step or condition_not_met (ADR 0030); build it with goals and workflow stop.
    • A definite rejection that arrives after the lease expired resolves unknown.
    • An unavailable outcome that arrives after the lease expired is dropped today; the message stays unknown. Decide it with the late rejection above.
    • Name the late Send event’s step-log outcome (accepted:late today).
    • Intention-revealing message functions in core/src/messages (claim, markUnknown, retryLater, skip, expireOutcome, recordDelivery) in place of generic transitionMessage calls, with the lease and window constants moved there.
    • A per-state deadline invariant checked in the message write (for example, sending and unknown always have a deadline; failed and skipped never do).
    • parseMessageStatus for stored rows, instead of a cast in adapters/sql.
    • A narrower ProjectTx type without message writes for code outside core/src/messages, in place of the lint rule that bans them.
    • Delivery status as its own small transition table, before SES rejected is added.
    • An eligibility result type in place of blocked ?? "no_address" in claimSend (with the discriminated ineligibility result below).
    • Quarantine semantics and an operator action that releases a quarantined item.
    • Reset wakeFailures after a success.
    • A bounded loop for the Durable Object’s outbox drain, and one alarm per outbox write instead of one per row.
    • One vocabulary for wakes and due work across code and ADRs (wake, due work, ADR 0011’s tick).
  • MCP (ADR 0031):
    • MCP OAuth, with resource_metadata in WWW-Authenticate and the /.well-known metadata: in the first release, Proposed in ADR 0051.
    • An Origin allowlist before browser-based MCP clients are supported (any Origin is refused today).
    • The server-side confirmation for sending actions, before real sending (SES) is wired (ADR 0005); designed in ADR 0033, and made optional per workspace, off by default, by ADR 0044; required in every workspace as preview-then-confirm by ADR 0050 (Proposed; the maintainer’s decision). Until it is built apps/workers refuses any provider but the fake one.
    • An authentication seam that also carries the 401 refusal ({ caller } | { refusal }, from which each surface builds its challenge), with resource_metadata for OAuth (decided in ADR 0051). Both seams select the principal with core/auth’s authenticateRequest (REST with sessions, MCP through the injected McpAuthenticator, keys only) and carry its refusal: each writes its Bearer challenge (P1). Only resource_metadata for OAuth remains. Word core’s forbidden message by grant rather than by “API key”.
    • What Claude Code does on a 401 without resource_metadata; record it in ADR 0051’s spike.
    • An interop test with the official MCP SDK client.
    • Tool titles and the openWorldHint annotation.
    • Move docs generation out of surfaces/http into a module that may depend on both surfaces, and export MCP_PATH from surfaces/mcp.
    • Replace pnpm docs:generate (vitest --update) with a writer script and a test that compares the files.
    • A behavioural parity test for REST input mapping: GET query strings and coercion.
  • Tests:
    • An in-memory ProjectTx fake for core unit tests.
    • A contract run on one shared node-sqlite database for several projects, to exercise the project_id filters.
    • Reword the replay “concurrent” test, or make it truly concurrent.
    • Pass the contract faults (contractWakeFaults, contractQueueFaults) into the harness instead of module state.
  • Simplifications:
    • YAGNI removals: EmailProvider.capabilities, occurredAt on normalized provider events.
    • as const arrays for WorkflowStatus and ReentryPolicy, shared by the record and the workflow view, as the message states already are.
    • A deliveryJobFor helper, named backoff constants, a shared slug ID schema, a discriminated ineligibility result, and splitting deferDueItem.

Pull requests that build ADR 0033 and ADR 0034. Each starts with the failing tests named, and each leaves main working: from A2 on, approval is on (where required, since ADR 0044) and tests approve through the response adapter. Rows marked Built are merged, and their nodes are filled in the graph. The suggested order of the rest: A3 ∥ A4b ∥ B3 → B2 (with I1 in parallel), then B4. The first real SES mail waits for B4 and everything before it, including one-click unsubscribe (U1), which ADR 0024 requires on marketing mail.

flowchart LR
A1[A1 live version] --> A2[A2 approval slice]
A2 --> A3[A3 approval page]
A2 --> A4b
A4a[A4a SystemMailer] --> A4b[A4b approvers and approval mail]
A5[A5 sending domains] --> C1[C1 sender replica and claimSend skip]
B1[B1 SES send and send context] --> C1
A2 --> A6[A6 sender check at approval]
A5 --> A6
C1 --> A6
B1 --> B3[B3 operator alerts]
B3 --> B2[B2 SES events]
A3 --> B4[B4 EMAIL_PROVIDER=ses]
A4b --> B4
A6 --> B4
U1[U1 one-click unsubscribe] --> B4
B2 --> B4
C1 --> B4
I1[I1 managed-service infrastructure] --> B4
classDef built fill:#dcfce7,stroke:#15803d
class A1,A2,A3,A4a,A4b,A5,A6,B1,B2,B3,B4,C1,U1 built
PR Change Failing tests first
A1 feat(core): separate the live workflow version from the latest saved version Built (#9). liveVersion on workflows; the definition hash (RFC 8785 canonical JSON, SHA-256) computed once when a version is saved; triggers start runs on the live version; workflows.activate activates (epoch + 1) or publishes (epoch unchanged); migration saving v2 of an active workflow does not change the version new runs pin; activating a draft makes the latest version live and increments the epoch; publishing v2 leaves in-flight runs on v1 running and sending; activating an active workflow whose live version is the latest is a no-op; migration: active workflows get live = current, drafts get null; the definition hash matches RFC 8785 test vectors and is identical on the Durable Object and node-sqlite (contract); workflows.upsert and workflows.activate inputs reject status, liveVersion, and approval fields
A2 feat: send approvals with the response delivery and the decision endpoint Built (#12). send_approvals and send_approval_links tables; workflows.activate creates a pending approval for a sending version; the ApprovalDelivery port and its response adapter (approvalLink in the output); POST /approvals/:projectId/:linkId/decision; sendApprovals.get; IdGenerator.secret() (WebCrypto adapter); the handler order: approvers, secrets, commit hashes, deliver, record mailed time; the caller pseudo-approver, so no control-plane approvers are needed yet; derived expired and superseded; a per-project daily cap; decider and time on the approval row; test helper approveLatestVersion in core/testing, used by the existing replay, unsubscribe, MCP workflow, parity, and isolation tests activating a sending workflow over REST and MCP leaves it unchanged and returns the same pending approval; while v2 awaits approval, events keep starting runs on live v1; approving activates or publishes exactly the approved version; a decline, an expired approval, a superseded approval, a wrong secret, and a reused link cannot activate; re-requesting re-mints the secret and the old link stops working; saving v3 while v2 is pending and activating creates one new pending approval and v2 reads as superseded; a change of re-entry policy refuses the decision; a link of project A cannot decide project B’s approval, and an unknown project never reaches a project store (isolation fixture); no api action reaches the approve or decline command (registry test); no output schema has a secret field except approvalLink; over the daily cap, rate_limited and nothing created
A3 feat(http): approval page Built (#20). GET /approvals/:projectId/:linkId static page; POST …/view; secret read from the fragment; CSP, frame-ancestors 'none', no-referrer, nosniff a GET returns no approval content and decides nothing; view needs the secret; content containing markup is returned as JSON and the page script never assigns HTML (static check); every response carries the security headers; the secret never appears in a request URL the server sees
A4a feat: SystemMailer port with the Cloudflare Email Service adapter Built (#15). The SystemMailer port, a recording fake, and the Cloudflare Email Service adapter (ADR 0029); its configuration; no caller yet a mail the service takes is reported as accepted, one that definitely did not reach the recipient as rejected, and one that may have as unknown, on the fake and on the adapter with a stubbed binding (contract); a failure is returned to the caller and never retried silently; a missing configuration value fails with an error naming the variable, not its value; no address, subject, or body appears in an error or log (ADR 0032)
A4b feat: approvers in the control plane, and approval links by mail Built (#21). Approver addresses in the control plane, written by the operator through an /operator/* endpoint like those of ADR 0035, and taken from ADMIN_EMAILS on self-hosted installations; read through ControlStore, so the approver lookup moves out of ApprovalDelivery.approvers() and the port only delivers; the email adapter of ApprovalDelivery (default), one link per approver, through A4a’s SystemMailer; the decision endpoint’s check, through ControlStore, that the link’s approver is still an approver; no_approvers; approval_delivery_failed; a re-request deletes the links of approvers who were removed; on a partial delivery failure, the mailed time is recorded only for the links that were delivered, and a retry re-mints and mails only the links never delivered (so one permanently refused address does not re-mail everyone, invalidate their links, and use up the daily cap); the cloud mode refuses response (built in A2). Notes from A4a: mail the approvers in parallel, so a request waits about one send timeout (10 s) at worst, not one per approver; build the SystemMailer only when SEND_APPROVAL_DELIVERY=email, so a self-host using response without system mail still starts; a sender display name is a possible follow-up each approver gets one mail with their own link and no customer data; a link’s mailed time is set only after a successful delivery; approver removal: a link of an approver removed after it was minted cannot decide or view, while another approver’s link works; a stale link: after a re-request, the earlier link of every approver, removed ones included, cannot decide; partial failure: when one of two mails fails, the request returns approval_delivery_failed with the counts, only the delivered link has a mailed time, and a retry mails a new link to the approver who got none, while the other’s link keeps working; a workspace without approvers gets no_approvers; in email mode the secret is in no API or MCP response and no log; the cloud mode with response fails every request with a configuration error
A5 feat: sending domains per workspace Built (#13). sending_domains in the control plane, provisioned by the operator through the operator endpoints of ADR 0035; replicated with the provider tenant to each project store of the workspace through C1’s replaceSenderReplica on every control-plane write (domains and tenant), with an order between writes so an older replica cannot bring back a removed domain (this changes the replace port’s signature; C1 leaves it out on purpose), and domains normalized (lower case, no trailing dot, IDNs as A-labels) at the source; a resync entry point that writes the replica of every existing project store, run before or with C1’s deploy, because every project store that exists before the deploy reaches schema version 5 (C1’s replica tables, after A2’s send approvals at 4) with no replica, and projects inserted into D1 by SQL (the development seed) get none from project creation either, and skipped is terminal, so messages queued before their replica arrives are never sent; the development setup runs the resync, so the dev flow sends. The approval-time sender_not_verified check is A6. No code creates projects yet, so replication on project creation is deferred to the change that builds it, and until then the operator resyncs the workspace after inserting a project a stale replica write cannot bring back a removed domain; an existing project and a seeded project get their replica from the resync; the development flow (pnpm dev:setup, pnpm dev) sends
C1 feat: replicate the provider tenant and sending domains, and skip unverified senders Built (#11). Replica in each project store, like suppression; claimSend fills the send context’s providerTenant from the replica and skips sender_not_verified; merged together with A5 or right after it, because a store without a replica sends nothing a message whose from domain was removed after approval becomes skipped:sender_not_verified without a provider call; the send context carries the replica’s provider tenant; the delivery path makes no ControlStore read
A6 feat: refuse unverified senders when an approval is requested Built (#16). workflows.activate refuses a sending version with sender_not_verified when a send step’s from domain is not a verified sending domain in the project’s replica (no control-plane read), before any approval or link is created; the from domain is normalized with normalizeSendingDomain when a version is saved and in isVerifiedSender, so an IDN from written with U-labels matches its A-label row instead of reading as unverified activating a version whose from domain is not verified returns sender_not_verified over REST and MCP, and creates no approval and sends no mail; a project store without a replica refuses; an IDN from in U-labels is verified at activation and in claimSend; a from domain with upper case or a trailing dot matches
U1 feat: one-click unsubscribe for marketing mail Built (#17, ADR 0036). The minimal RFC 8058 one-click unsubscribe of ADR 0024 for the marketing stream (every workflow message today): List-Unsubscribe with an HTTPS /u/* URL holding a token, and List-Unsubscribe-Post: List-Unsubscribe=One-Click, passed to the provider as message headers; POST /u/* with a valid token unsubscribes the customer in its project; GET /u/* shows a page and never unsubscribes. The unsubscribe link in the body comes with templates every marketing message carries both headers, on the fake and in the SES request; a POST with a valid token unsubscribes, and the pre-send recheck then skips the customer’s queued messages; a repeated POST changes nothing; a GET never unsubscribes; a wrong or tampered token is refused and reveals nothing; a token of project A cannot unsubscribe in project B (isolation fixture); the token and URL hold no address or other personal data
B1 feat(email-ses): send through SESv2 Built (#10). EmailProvider.send(email, tags, context) with providerTenant null until C1, and the fake adapter updated; adapters/email-ses send; the classification table; the unavailable outcome, decided in recordOutcome with the new firstAttemptedAt field; providerReason; the closed unknown reasons and the updated UnknownReason comment; an EmailProvider contract suite in testing/contracts on the fake and SES; setup notes for a manual mailbox-simulator smoke test that records fixtures accepted then reset is unknown after exactly one fetch; 503 is unknown after exactly one fetch; 429 is a retryable rejection after exactly one fetch; each other row of the table; an unavailable result returns the message to queued:provider_unavailable without counting toward the retry limit, and fails it as failed:provider_unavailable once its first attempt is more than 24 hours old; an adapter that throws gives unknown:adapter_error, and a 5xx gives unknown:provider; the request is signed and carries the tags, configuration set, and tenant; no credential in any result or error
B2 feat(email-ses): verify and normalize SES events from EventBridge Built (#24). verifyWebhook (header secret, source, optional account) and normalizeEvents; the secret arrives in the header x-ses-events-secret; events of a type it does not use (SES tenant status events, until the auto-pause) are answered 2xx and ignored, because EventBridge dead-letters a 4xx other than 401 without retrying; delivery statuses soft_bounced and content_rejected; recorded anonymized fixtures (written from the AWS documentation’s example events until the smoke test records real ones). A suppression-list bounce writes the reversal ledger row, which counts only once the message has a charge; an OnAccountSuppressionList bounce raises bounced:account_suppression_list through B3’s outbox. A Send event after 72 hours raises accepted:late. Tenant status events are ignored until the auto-pause. Amended by the maintainer after review (ADR 0034, 2026-11-15): soft_bounced ranks below delivered; a Reject and a Suppressed bounce reverse the charge too; an OnAccountSuppressionList complaint is the account-list bounce. Before SES is enabled, B4’s deploy gate replaces the fixtures with recorded events a wrong or missing secret is refused before parsing; each SES event maps as in ADR 0034; an OnTenantSuppressionList bounce suppresses and reverses the charge; an OnAccountSuppressionList bounce reverses the charge, alerts, and does not suppress; a transient bounce does not suppress; delivery status never moves backwards in the stated order; the duplicate-provider-webhooks check passes with SES fixtures; message events are matched by their tags and provider message ID whatever their region; when tenant status events are applied (the auto-pause), their key is the tenant and the event’s region (ADR 0037)
B3 feat: operator alerts through an extension point Built (#22, and the cloud implementation in #23; ADR 0038). A core alerting port with a no-op default (the Proposed “operational alerting” extension point). An alert occurrence is written to the outbox in the transaction that records the outcome, never emitted as a side effect inside the Durable Object transaction, and the drain hands it to the port. Each occurrence carries an incident key (provider, condition, providerReason, time window) with no project in it; deduplication lives in the implementation (the cloud one, or one shared store), so an account-wide SES outage raises one alert, not one per project. Conditions: queued:provider_unavailable; failed:provider_rejected with bad_request; unknown outcomes (SES 5xx or timeout); failed:retries_exhausted after throttled rejections (a missed daily-quota match would otherwise fail messages silently); accepted sends whose Send event never arrives within a window (an EventBridge misconfiguration). B2 reuses the port for OnAccountSuppressionList bounces and late Send events. The cloud implementation lives in cloud/ the same incident in two projects raises one alert (cross-project deduplication); an occurrence is written to the outbox with the outcome and reaches the port only through the drain, and a rolled-back outcome raises nothing; an unavailable outcome raises one alert per incident, not one per message; a bad_request rejection alerts; an unknown outcome alerts; an accepted send with no Send event within the window alerts; a message failed as retries_exhausted after throttled rejections alerts; the default implementation does nothing and public code never imports cloud/; an alert carries IDs and codes only, no address or provider text (ADR 0032)
I1 feat(cloud): managed-service infrastructure The managed service’s static, account-level SES and EventBridge setup as infrastructure as code, kept in a private path: both configuration sets, event publishing, the rule, connection, API destination, dead-letter queue and alarm, and the split IAM for sending and management. Per-workspace tenants and sending domains stay out of it and are set up at runtime. Self-hosters use B4’s setup docs. Applied by the maintainer, never in CI. Note from B2’s review: B2 answers Sending Status Disabled 200 and ignores it until the auto-pause, so nothing tells the operator that SES paused a workspace’s tenant; a second rule should route that detail-type to the operator’s alarm topic (not a 4xx from the Worker, which would also dead-letter Enabled) none in the test suite (no code path changes); the configuration validates without AWS credentials, and B4’s deploy gate checks the applied result
B4 feat(workers): select the email provider by configuration Built (#25; code built; gate items pending the maintainer). EMAIL_PROVIDER and SES_* configuration; assertEmailProviderAllowed removed; with any provider but fake, an APP_ORIGIN that is not https: is refused, because RFC 8058 needs an HTTPS unsubscribe link (ADR 0036); in cloud mode, a workspace without a provider tenant cannot send; setup docs with placeholders: IAM, configuration sets with account-level suppression disabled (SuppressionScope TENANT with reasons BOUNCE and COMPLAINT, never an empty reason list, see ADR 0034’s 2026-11-14 clarification), tenant-level suppression, EventBridge rule, connection, API destination, dead-letter queue alarm and replay; the deploy gate below; the operator endpoints take their provider Regions from the same parsed SesSendConfig.regions as the SES adapter, so the two allowlists cannot differ (ADR 0037). Note from B2’s review: while EMAIL_PROVIDER is not ses, /provider-events/ses answers 404 (unknown provider), which EventBridge dead-letters at once, so during the rollout or a rollback every SES event goes to the dead-letter queue; consider a 503, which it retries. Built as a 503 for a provider the Worker can wire but has not selected; an unknown provider stays 404. Setup docs: Setting up Amazon SES; runbook and checklist of the gate: Turning on real mail a missing SES variable fails every request with an error naming the variable, not its value, and sends nothing; fake stays the default; with ses and a stubbed fetch, the milestone flow sends only after approval; in cloud mode, a message of a workspace whose replica has no provider tenant makes no provider call

B4’s deploy gate, checked before real mail is turned on (nothing is deployed yet). Open: code built; gate items pending the maintainer. Each item is a step of Turning on real mail:

  • B3’s alerts are built and wired, so an account-wide SES failure is visible, and a 5xx notification or an external health check watches the Worker, because a refused configuration raises no alert.
  • With tenants, IAM accepts the send policy’s ses:TenantName condition key (setup step 1), and a send without TenantName is refused (what such a send returns): IAM answers AccessDeniedException without a configuration set, and SES answers BadRequestException first through a TENANT-scope one. Also, put-configuration-set-suppression-options --suppression-scope TENANT took effect on both configuration sets.
  • No active sending workflow exists without an approval in a workspace that requires approval (ADR 0044). Nothing was deployed before A2, so no migration is planned for workflows activated before it.
  • On the managed service, no workspace with send approval off sends real mail until pause and rollback (ADR 0044 rows P3 and P4), the workspace send budget of plan limits (ADR 0013), and the per-tenant sender protection of ADR 0024 (auto-pause on bounce and complaint rates) are built. With approval off, a leaked admin key can send any content to any address from the verified domains, and these bound it.
  • The deliveries queue’s max_concurrency, a rate limit, or both match the SES sending rate.
  • A runbook for removing a sending domain, including what to do when a resync returns 503 (retry, then alert). A replication of a removal that fails leaves the domain sendable in that store until a resync succeeds.
  • The interim emergency stop is documented: the operator deletes the workspace’s sending domains, so every send becomes skipped:sender_not_verified. It holds until kill switches exist. (The user’s own pause of ADR 0044 does not replace the operator’s kill switches.)
  • The manual SES smoke test has confirmed the daily-quota message text the adapter matches, the error codes for a missing, paused, or unassociated tenant, and that the DKIM signature covers List-Unsubscribe and List-Unsubscribe-Post.
  • A real round trip: an SES send, its event through EventBridge, and the event stored against the message.
  • B2’s SES event fixtures are replaced with recorded ones, anonymized as the fixtures’ README says, because they are written from the AWS documentation and a wrong detail-type or subtype string drops its events silently or changes billing. Recorded through the SES mailbox simulator: Send, Delivery, Bounce (Permanent, Transient, OnTenantSuppressionList with the simulator address on the tenant’s suppression list, OnAccountSuppressionList, Suppressed), Complaint, and the tenant status events. For the events the simulator probably cannot produce (Email Rejected, Email Delivery Delayed, Email Rendering Failed, and the Complaint with complaintSubType OnAccountSuppressionList), the detail-type and subtype strings are confirmed against a real event or the EventBridge schema registry. The adapter’s tests pass on them before SES is enabled.
  • On a deployed Durable Object, setAlarm inside the transaction callback is atomic with it.
  • The platform log settings of ADR 0032 (Workers Logs, Logpush, and their retention) are settled in the deployment configuration.

Later, not needed for the first real mail: workflows.stop with ADR 0017’s stop. Its required failing tests: a stop cancels the workflow’s pending approvals, and deciding an approval of a workflow that is neither active nor draft is refused (sendApprovalRefusal does not check the workflow status today); reactivating the previously live version needs a new approval. Also later: the audit log entry for decisions, through the outbox; the provider-events queue if latency requires it; SES tenant status events and the auto-pause (ADR 0024), later only for self-hosted installations and for managed workspaces with send approval on; for a managed workspace with approval off, the auto-pause is part of B4’s deploy gate (above); split streams; the domain management API with DNS checks; verified test recipients with runs.test.

Optional send approval, pause, and rollback: ADR 0044 plans rows P1 to P5. P2 (who made each version live), P3 (pause), and P4 (rollback) come before P1, which turns approval off by default; P5 (the admin’s session-only action) waits for ADR 0041’s session principal.

Known limitation: suppression is kept per project, not per workspace as ADR 0024 decides, because the skeleton does not replicate suppression across a workspace’s projects. This is acceptable only while each workspace has one project; revisit it in the change that lets a workspace have a second project.

Plan: audiences, broadcasts, analytics, and experiments

Section titled “Plan: audiences, broadcasts, analytics, and experiments”

Proposed in ADR 0045 to ADR 0050. Pull requests in order, prefixed G so they do not collide with the plan rows above; each builds and passes tests, and each depends only on rows before it:

Pull request Builds Depends on
G1 feat: confirm sending actions on the server startsSends, previewSends, the derived input, output union, and confirmation_invalid; send_confirmations with its sweep and rate limit; confirmation on workflows.activate (and on rollback and the resumes as ADR 0044 builds them). Unblocks real mail with the rest of B4’s gate —
G2 feat: condition language and evaluator the grammar, comparison semantics, the pure evaluator with mixed-type tests, unknown predicates resolving toward sending less, with tests for each use: audience, trigger audience, condition step, goal at the pre-send check (skipped:condition_unknown), goal on an event, and experiment eligibility; { customers } resolution, email-literal refusal, condition steps and goals on it —
G3 feat: message facts and reports claimed_at, cohort_at, the fact columns, metrics.get and messages.list extended, metrics.workflow, messages.get, fact retention —
G4 feat: broadcasts to explicit customers now broadcasts.create, list, get, cancel with customers and sendAt: "now", no goal; derived status; the workflow-action table; content_hash G1, G2
G5 feat: conversions customer_event_stats with the name cap and backfill, goal evaluation on events, waiting:conversion_window releasing re-entry, last-touch attribution with one run credited per event G2, G3
G6 feat: saved audiences and scheduled broadcasts audiences.*, expansion and conditionHash, the deletion guard, count jobs and confirmation_pending, later sendAt, broadcasts with a goal G2, G4, G5
G7 feat: classify clicks deriveNetworkSignals and classifyEngagement with versioned lists, typed tokens, edge dedupe, event IDs, store heuristics, tracking settings, the optional decoy link G3
G8 feat: track opens the pixel, humanOpens, caveats G7
G9 feat: A/B experiments on send steps the experiment record with its frozen goal and window, assignment, experiment_assignments and their retention, the verdict, experiments.*, conclusion approvals G1, G3, G5, G7

Audiences, analytics, experiments, and broadcasts

Section titled “Audiences, analytics, experiments, and broadcasts”

Open points left by ADRs 0045 to 0050 (the maintainer’s decisions of 2026-11-19 are recorded in those ADRs):

  • Counters and rollups for report history beyond MESSAGE_FACT_RETENTION, the retention values, and indexed attributes for audience scans: after the load test.
  • Three or more variants, automatic promotion, experiments on paths and from, sequential tests.
  • Audience entry and exit triggers (deferred), static lists, event counts and windows beyond within, conditions on engagement.
  • Per-link click reports, recipient exports beyond the retained window, a workspace-wide report view.
  • MCP OAuth, so claude.ai, ChatGPT, and Claude Code connect without an API key, is in the first release (the maintainer’s decision of 2026-11-20), Proposed in ADR 0051. Still open: a published Customer.lite skill or instructions for Claude Code, with llms.txt and tool descriptions, that steer the assistant to broadcasts, saved audiences, and reports, and to showing previews before confirming.
  • MCP elicitation, where a client supports it, as a way to ask the person directly before a send.
  • Per-DO health metrics to Analytics Engine: wake lag, outbox depth, unknown count, storage bytes.
  • Runtime sending-domain and provider-tenant provisioning, so users add and verify their own domains (maintainer decision of 2026-11-18; ADR 0039, Proposed, phased into its implementation pull requests there).
  • An AWS-side dead-letter queue alarm for SES event delivery, and a replay tool.
  • The DO point-in-time restore runbook, and the store for its attempt journal (chosen before the delivery code is written).
  • Consent handling: recording recipients’ consent and the prerequisites for marketing sends.
  • CI checks once code exists: gitleaks in pre-commit and CI, a docs link check, and a check-tenant-safety checkbox in the pull request template.
  • A load test of the largest tier.
  • An optional per-workspace custom tracking subdomain, and send-time URL screening.
  • Recurrences more frequent than daily.
  • External identity providers and SSO.
  • Spreading workspaces over several SES accounts.
  • Moving events into their own DOs if a project outgrows the hot window.
  • Make this document a map of the ADRs rather than a copy of them.
  • Write the invariants as an acceptance-test catalogue with exact numbers.
  • Add fitness functions for the rules that have no automated check yet.
  • Split the ADRs that bundle several decisions.
  • List the deliberate YAGNI deferrals.
  • State the bound on the replay window, and note the GDPR concern with the tombstone hash.
  • Refund policy.
  • Whether the public site carries a sign-up flow or waitlist form, which would need a backend (ADR 0042).
  • Better Auth on Node with Postgres, before the open-source release; claude.ai and ChatGPT against Better Auth’s mcp() and cimd() over a public HTTPS origin, before ADR 0051’s S2 (the workerd and D1 spike and Claude Code over loopback are done); and, at the deploy gate of sign-in, the CPU time of a sign-in, __Host- cookies on localhost in Safari, and the logger mapping (ADR 0040).
  • Deployed DO verification: whether setAlarm inside the transaction callback is atomic with it (checked in B4’s deploy gate), and whether serialization on a deployed DO matches the Miniflare results.
  • Price steps above 1M emails, and whether workflow runs need their own fair-use limit.
  • Auto-pause minimum sample size.
  • Hot-window lengths and retention periods, from the load test.
  • Bring-your-own provider credentials on the managed service.
  • The value of the per-project daily approval-mail cap, and a workspace-wide cap once a workspace may have several projects (ADR 0033).
  • Revisited only on evidence or request: whether a pause should also stop new runs, and a deployment-wide send approval default for self-hosters (ADR 0044).
  • Resolving an SES 5xx unknown sooner than 72 hours; a conditional resend needs its own ADR (ADR 0034).
  • Which messages count as transactional, whether a transactional send API is in the MVP, and abuse limits on the transactional stream and on test sends. Until this is decided, workflow messages are sent on the marketing stream.
  • OSS sync tooling and the public repository creation date.
  • API conventions such as action naming (resource.verb is proposed) and the error returned for cross-project access (not found is proposed).
  • Accepted values of CUSTOMER_LITE_CLOUD. Until decided, apps/workers treats any non-empty value as cloud mode, which fails safe for the refusal of response approval delivery.
  • Deduplication key for generic inbound sources whose payloads have no event ID.
  • Whether the draft skills add-api-action, add-email-adapter, and add-workflow-step are rewritten after their first real use.