Design

The design documents are binding. A coding agent implements what they say. When the code and a design disagree, the design wins until an ADR changes it (see AGENTS.md). When two pages disagree with each other, Precedence below decides which one wins. Each document cites requirement IDs from the PRD and rows from the edge-case register, and ends with a Tests section that maps them to named tests.

The public contracts live in the reference section and are not repeated here: REST API, Errors, Webhook events, Configuration and Limits. The storage schema is in Data model.

Precedence

When two pages disagree, one rule decides which wins:

Agents follow it as a rule: for wire behaviour, openapi.yaml wins and the design must match; for internal behaviour, the design page wins. A disagreement is a documentation bug, never a choice for the implementer: fix the losing page in the same pull request, and write an ADR only when the winning page is itself wrong (Decision records).

Index

Shared conventions

These rules apply to every design. A design may add to them but never contradict them.

1. Layering

crates/api-types   types only (serde, utoipa). No I/O.                 depends on: serde, utoipa
crates/core        pure logic. No I/O, no clock, no randomness.         depends on: api-types + pure crates
crates/platform    traits + Cloudflare implementations + fakes.        the ONLY crate that imports `worker`
crates/worker      handlers, Durable Objects, consumers, transports.   depends on: core, api-types, platform

• core functions take everything they need as arguments: the current time as now_ms: i64, random bytes as [u8; N], lookups as traits implemented by the caller (for example ThreadLookup in Threading). They return decisions and data, never perform effects. core builds for the host and for wasm32-unknown-unknown.
• platform wraps every Cloudflare API behind a trait. Native tests use the in-memory fakes in platform::fakes. No other crate names a worker:: type, enforced by cargo xtask check-layering.
• worker orchestrates: it reads, calls core to decide, writes, and schedules follow-up work. Business rules that can be expressed without I/O live in core, so they are unit-tested natively.

2. Errors and the error envelope

Every failure that reaches a client is an ApiError, serialised as the error envelope:

// crates/api-types/src/errors.rs
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize, ToSchema)]
#[serde(rename_all = "snake_case")]
pub enum ErrorCode { Unauthenticated, KeyExpired, KeyRevoked, PermissionDenied, ScopeDenied, /* …one
    variant per code in errors.md… */ InternalError, UpstreamError, Unavailable, SearchDegraded, Timeout }

impl ErrorCode {
    pub const fn http_status(self) -> u16;     // from the errors.md tables
    pub const fn retryable(self) -> bool;      // from the errors.md tables, never decided at call sites
    pub const fn default_fix(self) -> &'static str;
}

pub struct ApiError {
    pub code: ErrorCode,
    pub message: String,                       // human text; never contains message content or addresses
    pub fix: Option<String>,                   // overrides default_fix when more specific
    pub details: Option<serde_json::Value>,
}

• core returns domain errors (AddressError, PolicyError, QueryError, …). Each has one impl From<…> for ApiError in api-types, so a rule and its error code are defined together.

• platform returns PlatformError { kind, binding, detail }. detail is a short machine string and never contains content or clear-text addresses. The worker maps it:

  PlatformErrorKind	ErrorCode
  Unavailable (D1 or a Durable Object overloaded, a binding refusing)	unavailable (503, retryable)
  Timeout (an internal deadline)	timeout (504, retryable)
  Upstream (a Cloudflare or SES REST API returned an unexpected status during a synchronous call)	upstream_error (502, retryable)
  NotFound for an object the caller named	the resource’s own *_not_found code
  NotFound for an internal object, Corrupt, Internal	internal_error (500, retryable), logged with request_id

• Errors after a send was accepted are never HTTP errors. They become message statuses and reason codes (Errors › Send failures after 202).

• A 404 returned by the service always carries one of its own codes. Resources outside the key’s scope return the same *_not_found as missing ones (NFR-SEC-1).

3. Time, randomness and IDs

• Clock. All time comes from platform::Clock::now_ms() (Unix milliseconds, i64), implemented with Date.now(). In Workers, Date.now() advances only across I/O, so two reads in one synchronous block return the same value; designs rely on that only for “same transaction, same timestamp”. std::time::SystemTime::now() is never called in wasm code.
• Randomness. All randomness comes from platform::Rng (crypto.getRandomValues). core takes random bytes as arguments.
• IDs are {prefix}_{ULID} (Data model › Conventions), generated only by platform::Ids::new_id(prefix). The generator is monotonic within an isolate: if the clock has not advanced past the last ID’s millisecond, it reuses that millisecond and increments the 80-bit random part by one (moving to the next millisecond on overflow). The req_ request ID is generated at the start of every fetch, email, queue, scheduled and alarm invocation and carried through internal calls and logs.

4. Durable Object transactions

workers-rs 0.8.7 exposes SqlStorage::exec but not transactionSync (read 2026-10-09 from the v0.8.7 source). Cloudflare documents ctx.storage.transactionSync(callback), which rolls back if the callback throws, and forbids BEGIN/SAVEPOINT inside sql.exec() (SQLite storage API, read 2026-10-09). platform therefore provides Sql::transaction_sync, a wasm-bindgen call to ctx.storage.transactionSync (see Rust workspace). The rules:

1. One write transaction per state change. Every write path in a Durable Object runs inside one transaction_sync closure. The closure is synchronous: no .await, no subrequests.
2. Decide before, re-check inside. Reads used to decide may happen before the transaction (for example, while waiting on TenantQuota), but every precondition is re-checked inside it, because other requests can interleave at any .await.
3. Effects after commit. R2 writes, queue sends, D1 writes and calls to other Durable Objects never run inside a transaction. Those that must happen before the state change (an R2 object the row will point to) run before it; the rest run after commit and are either idempotent or repaired by an alarm.
4. Outbox in the same transaction. Every transaction that changes externally visible state appends its events to the object’s outbox table inside the transaction (section 6).
5. One alarm, many purposes. An object has a single alarm. Each object keeps its pending wake-ups in meta under alarm:{purpose} (for example alarm:outbox, alarm:check, alarm:claim, alarm:dispatch, alarm:maintenance; Data model lists each object’s keys). After each transaction it sets the alarm to the earliest pending wake-up if that is earlier than the current alarm. Every mailbox has a daily alarm:maintenance that deletes expired idempotency rows, rate_windows older than 48 hours, verifications past expires_at or 1 hour past consumed_at, outbox rows past the tenant’s events_days, unpins quiet fallback threads (Threading), and refreshes the database size in meta.size_bytes (Data model › Mailbox notes). The alarm handler runs every due purpose, then re-arms. Handlers are idempotent, because Cloudflare delivers alarms at least once and retries a failed handler with exponential backoff from 2 seconds, up to six times (Alarms, read 2026-10-09).
6. Schema on wake. Each object applies its migrations on first access in a transaction, guarded by meta.schema_version (J9).
7. Limits. Durable Object SQLite allows 100 bound parameters per statement, 100 KB statements and 2 MB per row or value (limits, read 2026-10-09). Designs that store text cap it below those limits (see Inbound › Storage caps).

5. Internal Durable Object RPC

Durable Objects are called with a typed request enum over fetch to the stub. There is no other entry point into an object.

// crates/worker/src/rpc.rs
#[derive(Serialize, Deserialize)]
pub struct RpcEnvelope<T> {
    pub v: u8,                         // 1
    pub tenant_id: Option<String>,     // None only for platform-level DomainMonitor and SesControl calls
    pub identity_id: Option<String>,   // required for IdentityMailbox
    pub request_id: String,            // req_…
    pub actor_key_id: Option<String>,  // for audit
    pub deadline_ms: i64,              // absolute; the object refuses work past it
    pub req: T,
}

#[derive(Serialize, Deserialize)]
#[serde(tag = "op", rename_all = "snake_case")]
pub enum MailboxRequest {
    Init(InitMailbox),                       // identity created: stores owner in meta, emits identity.created
    Ingest(IngestInput),                     // inbound.md
    Reparse(ReparseInput),                   // inbound.md, J3
    AttachmentTextReady(AttachmentText),     // inbound.md
    Submit(SubmitInput),                     // outbound.md
    BeginTransport(BeginTransport),          // outbound.md: claim before calling a transport
    RecordTransportOutcome(TransportOutcome),// outbound.md
    ApplyDeliveryEvent(DeliveryEvent),       // outbound.md
    Cancel(CancelInput), Resolve(ResolveInput),
    LearnMessageId(LearnMessageId),          // outbound.md: Message-ID strategy B (journal copy)
    RegisterWait(RegisterWait),              // inbound.md › The wait handler: E5 registration, every 10 s
    WaitPoll(WaitQuery),                     // inbound.md › The wait handler: one poll, every 1 s
    EmitEvent(EmitEvent),                    // identity.* events written after a D1 change
    GetEvents(GetEvents),                    // webhooks.md delivery and replay
    // Read, search, triage, label and erasure operations are added by their designs.
}
// DomainRequest, JobRequest, QuotaRequest, SesControlRequest (domain-connections.md § 4.8) and
// NotifierRequest (notifications.md § 3) follow the same pattern, and each starts with an
// `Init` variant that stores the owner in the object's `meta` (QuotaRequest: outbound.md › TenantQuota).

#[derive(Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum RpcResult<T> { Ok(T), Err(ApiErrorBody) }

• The caller addresses the object with id_from_string(<stored DO id>) (IDs are created with unique_id_with_jurisdiction and stored in D1, ADR 0002) and sends POST https://do.internal/rpc with the JSON envelope. A handled result, success or error, is HTTP 200 with RpcResult. Any other status, or a thrown exception, is a platform failure (unavailable).
• Tenant check. The handler compares tenant_id and identity_id with the owner stored in meta (written by Init). A mismatch returns internal_error, logs the security event rpc_owner_mismatch with both IDs, and increments rpc_owner_mismatch_total, which alerts at 1. The public handler has already checked scope against D1 before calling, so a mismatch is always a bug.
• An object that has no owner yet accepts only Init. An object marked erased = '1' refuses everything with identity_not_found.
• The caller’s default deadline is 10 seconds (Ingest and Submit: 30 seconds). The object checks deadline_ms before starting a transaction and returns timeout if it has passed.

6. Transactional outbox

Every object with an outbox table (IdentityMailbox, DomainMonitor, JobRunner) emits events the same way, detailed in Webhooks and events:

1. Inside the state-change transaction: increment meta.event_seq, build the full envelope (events) with sequence = event_seq, insert it into outbox with dispatched_at = NULL, and record alarm:outbox = now.
2. The alarm writes event_index rows to D1 (INSERT OR IGNORE), sends one pm-webhooks message per event, then sets dispatched_at.
3. A crash between steps repeats step 2. Consumers deduplicate on the event ID, so delivery is at least once and never lost.

7. Idempotent queue consumers

Every queue is at least once. Every consumer is written so that processing the same message twice has the same effect as once:

Rules for every consumer:

• Process messages one at a time within a batch, and ack() each one after its effect has committed.
• Retry counting never uses Message.attempts. workers-rs 0.8.7 does not expose it (its Message binding has only id, timestamp, body, retry and ack; read 2026-10-09 from the v0.8.7 source). A bounded retry schedule is implemented in one of two ways, named in each design:
  • Re-enqueue: the body carries attempt: u32. On a known transient failure the consumer sends a new message with attempt + 1 and delay_seconds from the schedule (MessageBuilder::delay_seconds), then acks the current one. Used where the Worker has a producer binding for the queue.
  • Age: the consumer computes the age of the work from a timestamp it owns (a field in the body, a provider event timestamp, or a stored row) and calls retry_with_options with the schedule’s delay until the age limit is reached.
• An unexpected error (a bug, a panic) is logged and the message is left to the queue’s own retry (retry()), up to the queue’s max_retries, then the dead-letter queue, whose consumer records and alerts (J8).
• A queue handler that returns an error fails the whole batch (and workers-rs 0.8.7’s own macros turn a returned Err into a panic). Handlers therefore ack or retry each message themselves and return Ok(()); the only deliberate error is the inbound temporary failure in Inbound, which the entry glue raises as a thrown exception (Rust workspace).
• Queue bodies are JSON with "v": 1 and a "kind" tag. They carry IDs and pointers only, never message bodies, attachment content or subjects (Queues allow 128 KB per message; designs stay under 4 KB).
• Consumers never trust a pointer’s scope blindly: they re-read the tenant and identity rows from D1 and check status before writing.

8. Logging

Logs never contain message bodies, subjects, attachment content or clear-text addresses (FR-PRV-6). Addresses that must be correlated are logged as HMAC-SHA256(PM_HASH_KEY, address) truncated to 16 hex characters. See Observability.

Spikes

The spikes run in milestone M1 of the build plan against a scratch Cloudflare account. Each result is recorded in the design it affects, under a “Spike result” note with the date. A failed spike takes the listed fallback, and the design is updated before the build continues.