OverviewArchitecture

Architecture

Notation Durable separates contracts, workflow execution, HTTP serving, worker isolation, SQLite storage, Cloudflare hosting, and conformance suites into ten private @durable/* workspace packages. At publish time, tsup bundles those packages into @notation/durable and @notation/durable-conformance so applications and workers share one runtime identity.

Workspace packages

Dependencies flow downward to @durable/core, which defines client contracts, codecs, errors, and state transitions with no workspace dependencies:

PackageResponsibility
@durable/coreClient contracts, WorkflowRunner, ExecutionDispatcher, value codec, and state transitions
@durable/sdkWorkflow generator driver, step runners, local SDK, HTTP SDK, and step record codec
@durable/http-serverFramework-agnostic trigger, poll, wait, list, and cancel HTTP handlers
@durable/worker-invokerChild-process worker launcher, IPC protocol, and orphan exit handling
@durable/sqlite-runtimeSQLite schema, runtime clients, and bun:sqlite or node:sqlite drivers
@durable/cloudflareDurable Object SQLite driver and the alarm-driven workflow object
@durable/test-runtimeIn-memory Runtime implementation with a controllable clock
@durable/test-invokerIn-process WorkflowInvoker driving WorkflowRunner without spawning workers
@durable/test-utilsTest harness combining MemoryRuntime, in-process invoker, and createTestSdk
@durable/runtime-conformanceVitest conformance suites for execution, heap, store, effect, join, and cancellation

Published entrypoints

The @notation/durable package compiles ten ESM entrypoints with code splitting enabled so internal workspace packages share common chunks inside one distribution. External dependencies such as Standard Schema, Pino, Vitest, and host SQLite bindings remain external imports.

EntrypointResponsibility
@notation/durableWorkflow authoring, local SDK, router, dispatcher, runner, and error classes
@notation/durable/clientBrowser-safe HTTP SDK factory and client request errors
@notation/durable/runtimeRuntime client contracts, state transitions, value codec, and runner primitives
@notation/durable/httpHTTP route handlers and observation middleware
@notation/durable/workerChild-process worker invoker and worker entrypoint helpers
@notation/durable/sqliteSqliteRuntime and SQLite client implementations for custom drivers
@notation/durable/sqlite/bunSQLite runtime and createSqliteDb backed by bun:sqlite
@notation/durable/sqlite/nodeSQLite runtime and createSqliteDb backed by node:sqlite
@notation/durable/cloudflarecreateWorkflowObject and the SQLite driver for Durable Object storage
@notation/durable/testingMemoryRuntime, in-process invoker, and createTestSdk
@notation/durable-conformancePublished Vitest runtime conformance suites

Single-copy class instance invariant

WorkflowRunner, the workflow generator driver, and the step record codec rely on instanceof checks across step response subclasses and core workflow errors. Loading two copies of the core package in one process breaks those boundary checks and causes WorkflowRunner to reject with a version-mismatch error.

To keep one class hierarchy in consumer test suites, @notation/durable-conformance maps its core imports onto @notation/durable/runtime at build time. Published conformance tests therefore instantiate and inspect the exact classes from the caller's installed @notation/durable package.

App, server, and worker roles

Deployments split responsibilities across three process roles using focused subpaths:

RoleImports and responsibility
AppImports @notation/durable/client or @notation/durable to trigger, poll, wait on, list, and cancel executions
ServerImports @notation/durable, @notation/durable/http, @notation/durable/worker, and a runtime to serve routes and dispatch leases
WorkerImports @notation/durable, @notation/durable/worker, and a runtime to run workflow generators in an isolated process