0030. Walking skeleton: tool versions and implementation decisions
- Status: Proposed
- Date: 2026-11-09
Context
Section titled “Context”The first code builds the walking skeleton of the first validation milestone on the managed target (Cloudflare). ADR 0022 leaves tool versions to the first code pull request. Building the skeleton showed points the accepted ADRs leave open or underspecified. This ADR records what the code does. It changes no accepted decision, but it adds one transition to the send state machine of ADR 0011 (a late provider response resolves unknown to accepted), which a superseding ADR should state there.
Decision
Section titled “Decision”Tool versions (checked 2026-11-08), pinned exactly in package.json:
| Tool | Version | Note |
|---|---|---|
| Node | 24 or later | engines; development used Node 26 |
| pnpm | 10.34.9 | packageManager |
| TypeScript | 6.0.3 | typescript-eslint 8.72 supports TypeScript below 6.1, so not TypeScript 7 |
| Kysely, Hono, zod | 0.29.8, 4.13.17, 4.6.7 | |
vitest, @cloudflare/vitest-plugin, wrangler |
4.1.12, 1.6.0, 4.158.0 | |
| ESLint, typescript-eslint, Prettier, dependency-cruiser | 9.39.5, 8.72.1, 3.9.10, 18.7.2 |
Implementation decisions:
- Deterministic IDs in core. Event IDs from an idempotency key, run IDs, and message IDs are SHA-256 derivations computed synchronously with
@noble/hashes. Core cannot use WebCrypto (no platform globals) and a command may not await anything butProjectTx. - The wake protocol.
ProjectTx.wakeAtwrites awakeupsrow; the executor arms the platform timer to the earliest row inside the transaction callback. When it fires, the executor checks the earliest wake against the injectedClock(so a wake never fires early, even when tests move the clock by hand) and calls core’srunWake.runWakelists due runs and message deadlines in bounded batches until none are left (at most eight rounds, then it reports that work remains and the executor registers a wake at the current time), processes each item in its own transaction, and backs off a failing item, quarantining it after five failures, so one poison item cannot block the rest (ADR 0011). The executor clears the due wakes only afterrunWakesucceeds. If it throws, the due wakes are replaced by one retry wake a few seconds later; if the Durable Object is interrupted, the due wakes stay and the platform’s alarm retry fires them again. Each message keeps the deadline of its current state in onedeadline_atcolumn. - Outbox drain. Outbox rows also register a wake at the current time. The executor drains them to the queue right after commit and again after every wake. If outbox rows are left after a wake’s drain, the executor registers a wake a few seconds later, so a failing queue is retried until it recovers.
- One wake protocol for every executor. The Durable Object and node-sqlite settle wakes with the same
adapters/sqlfunctions (replaceDueWakes,wakeForPendingOutbox) and retry delays, and the contract suite pins both rules: a failed handler’s due wakes become one retry wake, and a failing queue is retried until it recovers. - Durable Object RPC.
ProjectDO.executereturns a command’s failure as a value ({ ok: false, error }) and the executor rethrows it, so a rolled-back or refused command is a normal result for the Durable Object. The first scope a ProjectDO serves binds it to that project; any other scope is refused. - Retryable rejections return the message to
queuedwith a backoff (30 seconds, doubling; capped at one hour, which the retry limit below keeps it from reaching: the longest wait is 32 minutes). The backoff is kept in its ownnot_beforecolumn, apart from the state deadline indeadline_at:claimSendrefuses aqueuedmessage beforenot_before, so a duplicate or redelivered job cannot skip the backoff. The due-work pass re-enqueues the message when the backoff passes, and the next claim gets a newattempt_id. A column was chosen over a separate retry-wait state because the state machine of ADR 0011 already models the retry assending→queued. - Retry limit. A message gets at most eight attempts. A retryable rejection of the eighth fails it as
failed:retries_exhausted. Eight attempts spread the retries over about an hour in total (seven waits, about 63 minutes), which covers provider throttling and short outages without retrying a broken send for hours. - Billing on Send events follows the single rule of ADR 0012: a Send event within 72 hours of the attempt writes the charge, whatever the message state; it also moves
sendingorunknowntoaccepted. A later Send event is not billed and writes the step log outcomeaccepted:late; recording it on the message and alerting are not built yet. - A late provider response for an
unknownattempt moves it toaccepted(billing stays on the Send event), resolving that open item for ADR 0011 and ADR 0012. - Run exits in
claimSend(decided, not built). When goals and workflow stop exist,claimSendrefuses a message only for an external exit of its run (goal_met,workflow_stopped), never for the run’s own path ending (exit_step,condition_not_met) after the send step queued the message: those exits come after the send in the definition, so they must not cancel it. - Ineligible sends are recorded as messages. A send step whose customer is unsubscribed, suppressed, or has no address writes the message as
skipped:<reason>, so “why was this not sent?” is answered by the message as well as the step log. - Provider events are verified and applied synchronously by the
providerEvents.receiveendpoint, grouped per project. Theprovider-eventsqueue from the open items comes with SES. - API conventions used: action names are
resource.verb; JSON fields are camelCase; cross-project access returns404 not_found; errors are{ "error": { "code", "message", "issues"? } }. - API scopes are enforced in one dispatch path.
authenticateApiKeyreturns the caller: the project scope and the API scopes its key grants (ADR 0026); a secret key grants all of them.invokeApiActionin core checks the action’sscope, validates the input, and runs the handler, and every surface calls it, so REST and MCP cannot diverge. The grants travel besideProjectScope, not inside it: aProjectScopealso reaches the project store from delivery jobs and provider events, which have no API grants. Every API action declaresforbidden, and a registry fitness test checks unique names and routes and the declared errors. - Fitness rules added with the skeleton. Core’s npm dependencies are allowlisted to
zodand@noble/hashes;apps/workersmay not importadapters/node-sqlite; a cast toProjectScopeoutsidecore/authis a lint error; and the determinism ban also catchesDate(), computed access such asDate["now"](), and anyglobalThisaccess in core.core/test/lint-bans.test.tskeeps the lint bans from silently missing a spelling. - Control plane schema (workspaces, projects, hashed API keys) lives in
adapters/cloudflare/migrations/controland is applied with wrangler’s D1 migrations. - Test clock. Workers tests run in the same isolate as the Durable Objects, so the test entry wires a
ManualClockfrom@customer-lite/core/testingand tests fire alarms withrunDurableObjectAlarm. Durable Objects are still called only through their stubs.
Scope of the skeleton:
- Only the default re-entry policy,
no-while-active, is implemented; workflows have no stop action yet. - Only secret keys (
cl_sk_) authenticate; there is no key-management API, so keys are provisioned directly in D1. adapters/node-sqliteimplementsProjectExecutoronly, without a background timer (runDueWakesis called explicitly), and runs the same contract suite as the Durable Object.
Consequences
Section titled “Consequences”- The ProjectExecutor contract suite (
testing/contracts) runs on the Durable Object in workerd and on node-sqlite on every check. - The re-entry policies
once,restart, andalways, workflow stop and activation epochs across stop and reactivation, the activation confirmation token fromworkflows.preview_triggers, restricted and publishable keys, OpenAPI and MCP generation from the registry, budget reservation, and kill switches remain to be built; they are listed in docs/architecture.md.