solid-objects 0.12.1 → 0.13.1

package/docs/dashboard.md

@@ -0,0 +1,196 @@
+# Operator dashboard
+
+`solid-objects/web` is an optional operator interface over the same relational
+tables used by the runtime. It exposes instances and committed state, ready and
+claimed messages, reminders, effects, broadcasts, dead letters, and processes.
+It needs no separate store or agent.
+
+The root `solid-objects` entry point does not import the dashboard. A worker
+process that never mounts it does not load its HTTP adapter, renderer, or
+assets.
+
+## Fetch mounting
+
+`createDashboard()` returns an immutable Fetch handler. Give every request its
+fresh server-side authentication context and the host session that should own
+the CSRF token:
+
+```typescript
+import { createDashboard } from "solid-objects/web"
+
+const dashboard = createDashboard({
+  runtime,
+  mountPath: "/solid-objects/dashboard",
+})
+
+const response = await dashboard.fetch(request, {
+  authorizationContext: currentOperator,
+  session: {
+    read: (key) => session.get(key),
+    write: (key, value) => session.set(key, value),
+  },
+})
+```
+
+`mountPath` defaults to `/solid-objects/dashboard`. Pass `/` only when the
+dashboard owns the whole origin.
+
+## Access modes
+
+`access` defaults to `authorized`. Every route uses the runtime administration
+policy, pages include mutation controls, and the request context must supply a
+session for CSRF state.
+
+Use `authorized-read-only` to retain the policy while removing mutation forms
+and rejecting every dashboard POST with 405. Use `public-read-only` for an
+explicitly public demo mount:
+
+```typescript
+const demo = createDashboard({
+  runtime,
+  mountPath: "/solid-objects/demo",
+  access: "public-read-only",
+})
+
+await demo.fetch(request, {})
+```
+
+Public read-only mode skips `authorizeAdministration` and requires neither an
+authorization context nor a session. It still exposes committed state,
+arguments, results, errors, actor identifiers, and operational metadata. Only
+use it with synthetic or otherwise public demo data. All extension GET routes
+are public in this mode, while extension POST routes are also rejected.
+
+## Node and Connect mounting
+
+`createNodeDashboardHandler()` converts `IncomingMessage` and `ServerResponse`
+to the Fetch contract. Register it after the application's authentication and
+session middleware. A Connect-compatible host may pass `next`; paths outside
+the mount and unknown dashboard paths cascade. Requests outside the mount
+cascade before context resolution or body consumption, so downstream POST
+handlers receive the original stream.
+
+```typescript
+import { createDashboard, createNodeDashboardHandler } from "solid-objects/web"
+
+const dashboard = createDashboard({ runtime })
+const handler = createNodeDashboardHandler({
+  dashboard,
+  resolveContext: async (request) => ({
+    authorizationContext: await currentOperator(request),
+    session: sessionFor(request),
+  }),
+})
+
+app.use(handler)
+```
+
+The adapter caps request bodies at 64 KiB by default. Set
+`maximumBodyBytes` to another positive bound when the host requires one.
+
+## Authorization
+
+In the default and authorized read-only modes, every data route declares an
+`authorizeAdministration` action and resource. Authorization runs before the
+route reads a record, so a denied caller cannot probe identifiers.
+
+| Page or action                             | Action                     | Resource                      |
+| ------------------------------------------ | -------------------------- | ----------------------------- |
+| Dashboard, statistics, health              | `index`                    | `dashboard`                   |
+| Instance list/detail                       | `index` / `show`           | `instances`                   |
+| Instance pause/resume                      | `pause` / `resume`         | `instances`                   |
+| Mailbox/message detail                     | `index` / `show`           | `messages`                    |
+| Reminder, effect, broadcast, process lists | `index`                    | corresponding plural resource |
+| Dead-letter list/detail/retry              | `index` / `show` / `retry` | `dead_letters`                |
+
+The policy receives the route ID as `resourceId` when one exists and receives
+the exact `authorizationContext` supplied by the host. The default policy
+denies every route. Dashboard authorization does not authenticate requests;
+resolve the operator before calling the dashboard.
+
+## Security
+
+The host session persists one random CSRF secret. Every rendered page masks it
+with fresh random bytes, so tokens differ between requests while every form
+already open in the same session remains valid. POST requests without a valid
+token receive 403 and do not perform the action.
+
+Every stored or request-derived string is escaped before entering HTML,
+including JSON placed in chart attributes. HTML and statistics responses are
+private and not cached. The dashboard sends a nonce-backed content security
+policy, denies framing, disables MIME sniffing, and limits referrers to the
+same origin.
+
+Page size defaults to 25 and is clamped to 200. Actor ID substring filtering is
+parameterized with an adapter-specific SQL expression rather than interpolated
+into a query.
+
+## Pages and actions
+
+The dashboard page shows totals, instances per actor type, mailbox depth,
+outbox/reminder status, recent processes, and recent dead letters. The summary
+bar can poll `/stats` every five seconds when the operator enables Live. Lists
+do not reload underneath an operator reading them.
+
+Instance detail shows committed state and recent related messages, reminders,
+effects, broadcasts, and dead letters. Pause prevents workers from claiming
+new turns for that identity; a turn already executing may still commit. Resume
+clears the brake and normal polling resumes delivery.
+
+Dead-letter retry calls `runtime.deadLetters.retry()`, retaining its durable
+idempotency and actor-operation validation. A retry refused by the runtime is
+shown on the detail page with status 422.
+
+`HEAD /` performs only a schema reachability query and creates no CSRF session
+state. Use it for liveness checks instead of polling the full dashboard.
+
+## Charts
+
+The dashboard defaults to Chart.js 4.5.0 from jsDelivr with subresource
+integrity. Only that exact origin is added to `script-src`.
+
+Use a self-hosted script without widening the policy:
+
+```typescript
+createDashboard({
+  runtime,
+  chartLibrary: { url: "/assets/chart.umd.min.js", integrity: null },
+})
+```
+
+Set `chartLibrary: { url: null }` to render without charts. The dedicated chart
+containers have fixed height so responsive redraws cannot grow the page.
+
+## Extensions
+
+Extensions are supplied when the dashboard is created. Configuration is copied
+and frozen; there is no global registry and no first-request mutation boundary.
+
+```typescript
+const dashboard = createDashboard({
+  runtime,
+  extensions: [
+    {
+      tab: { label: "Tenants", path: "/tenants" },
+      routes: [
+        {
+          method: "GET",
+          path: "/tenants",
+          policy: { action: "index", resource: "tenants" },
+          handle: ({ render }) =>
+            render({
+              title: "Tenants",
+              content: renderTenants(),
+            }),
+        },
+      ],
+    },
+  ],
+})
+```
+
+Every extension route must carry a nonempty policy. Missing policies and
+method/path collisions fail when the dashboard is created. Renderer callbacks
+may replace named built-in views, and Fetch middleware may wrap the whole
+dashboard. Extension HTML is trusted application code; escape dynamic values
+with the route context's `escape()` helper.

package/docs/fit.md

@@ -0,0 +1,58 @@
+# Choosing Solid Objects
+
+Solid Objects is useful when an application has many independently addressed
+entities and every entity needs ordered state changes, durable work, recovery,
+or realtime projections.
+
+## Use it when
+
+- Concurrent requests can update the same room, cart, account, device,
+  document, or session.
+- Each identity needs its own ordering boundary and durable mailbox.
+- Operations must recover after a Node process exits.
+- State changes stage reminders, effects, actor-to-actor messages, or realtime
+  invalidations atomically.
+- The application already operates SQLite, PostgreSQL, or MySQL and should keep
+  durable coordination there.
+
+## Prefer a row transaction when
+
+One short transaction with an update, constraint, or row lock completely
+enforces the invariant. A direct transaction has less machinery, less stored
+history, and no actor-state migration contract.
+
+## Prefer another design when
+
+- Work is a bulk or data-parallel pipeline rather than per-identity state.
+- One global identity must sustain more writes than one sequential mailbox can
+  commit.
+- State is a large document or relational dataset that should be queried and
+  updated in smaller normalized pieces.
+- The application needs a transaction spanning several independent object
+  identities.
+- Compute and state must be automatically placed close to clients at the edge.
+- The team wants a managed control plane to place, scale, and recover workers.
+- Durable workflow replay across named steps is more important than a mutable
+  object with ordered operations.
+
+## Model identities deliberately
+
+One hot identity is intentionally serialized. An identity should correspond to
+the smallest domain boundary that requires one total order. Splitting a room by
+player or a cart by item may improve parallelism, but it also gives up atomic
+ordering across the split.
+
+Different identities can run concurrently when worker capacity and the
+database allow it. The [benchmark harness](benchmarks.md) measures both the hot
+and independent-identity cases.
+
+## Operational cost
+
+The relational database stores actor instances, ready and claimed mailbox
+membership, message history, leases, effects, reminders, broadcasts, dead
+letters, and process records. Retention policies and the operator dashboard
+make that state inspectable, but they do not remove the need to monitor and
+back up the database.
+
+Redis is optional. It is a transient notification path rather than durable
+state, so losing Redis increases polling latency without losing committed work.

package/docs/operations.md

@@ -1,12 +1,30 @@
 # Operations
 
-Runtime roles use durable polling as the correctness fallback. The default
-generation-based wake-up adapter interrupts waits for new actor messages,
-effects, reminders, and broadcasts in the same Node process. Notification
-errors are isolated and logged by role and error class without failing the
-committed work. Graceful shutdown stops new claims and allows active turns to
-finish within `shutdownTimeoutMilliseconds`, which defaults to 15 seconds. A
-component still running or stopping at the deadline emits
+Runtime roles use durable polling as the correctness fallback. Consecutive
+empty passes double each role's wait from `pollingIntervalMilliseconds` to
+`idlePollingIntervalMilliseconds`, which defaults to one second. Processed
+work and wake-up notifications reset the role to the fast interval. Actor
+workers clamp the ceiling to `leaseRenewalIntervalMilliseconds` while they may
+hold cached activations.
+
+The default generation-based wake-up adapter interrupts waits for new actor
+messages, effects, reminders, and broadcasts in the same Node process. It does
+not cross a process boundary. When live processes share the database without a
+configured adapter, the runtime logs
+`solid_objects.polling_only_cross_process_wake_up` once. Use PostgreSQL
+notifications or optional Redis Pub/Sub when separate processes need prompt
+delivery; without one, newly committed work can wait up to the current idle
+polling interval. Notification errors are isolated and logged by role and error
+class without failing the committed work.
+
+Each role exposes `currentPollingIntervalMilliseconds`.
+`solid_objects.polling.interval_changed` reports the role, reason, previous
+interval, and current interval. The polling-only warning is also emitted as
+`solid_objects.polling.only_cross_process_wake_up` instrumentation.
+
+Graceful shutdown stops new claims and allows active turns to finish within
+`shutdownTimeoutMilliseconds`, which defaults to 15 seconds. A component still
+running or stopping at the deadline emits
 `solid_objects.supervisor.component_shutdown_timeout`; the runtime then returns
 without pretending JavaScript code was forcibly terminated. Operators should
 monitor oldest ready work, claimed work, dead letters, effect failures,

package/docs/parity.md

@@ -1,18 +1,20 @@
-# Ruby parity ledger
+# Design parity ledger
 
-This ledger tracks spiritual feature parity with the Ruby `solid_objects` gem.
+This ledger tracks capability parity with the Ruby `solid_objects` gem.
 Parity means preserving a capability and its correctness or security boundary,
 not copying a Rails API into Node.
 
-Reference: Ruby `solid_objects` 0.12.0 at commit `a01b6f5`.
+Reference: Ruby `solid_objects` 0.13.1. The JavaScript package began at the
+Ruby design's `0.12` capability generation; that version number did not imply
+earlier JavaScript releases.
 
-The Node `0.12.1` implementation has spiritual parity with that reference. Its
+The Node `0.13.1` implementation has capability parity with that reference. Its
 relational runtime, correctness boundaries, administration, diagnostics,
-realtime projections, browser behavior, and supported adapters have native
-equivalents. Rails engine and rendering surfaces are intentionally replaced by
-transport- and framework-neutral JavaScript APIs. The partial guard row and the
-shared planned result-lookup row below are explicit scope boundaries, not
-missing Ruby capabilities.
+operator dashboard, realtime projections, browser behavior, and supported
+adapters have native equivalents. Rails-specific rendering surfaces are
+replaced by transport- and framework-neutral JavaScript APIs. The partial guard
+row and the shared planned result-lookup row below are explicit scope
+boundaries, not missing Ruby capabilities.
 
 ## Status vocabulary
 
@@ -49,18 +51,19 @@ missing Ruby capabilities.
 
 ## Operations
 
-| Capability                                                                    | Status | TypeScript shape or remaining work                                                                                                                                             |
-| ----------------------------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Process registration, heartbeats, stale claim recovery, and graceful shutdown | Native | Runtime roles persist host, PID, runtime versions, draining and stopped transitions, cooperative cancellation, and a bounded shutdown deadline; cleanup recovers stale claims. |
-| Failed-role replacement                                                       | Native | Built-in and registered roles are rebuilt through their factories with capped backoff; shutdown is the terminal replacement boundary.                                          |
-| Additional supervised components                                              | Native | `registerComponent()` builds, validates, runs, and stops application components with the runtime.                                                                              |
-| Dead-letter inspection and retry                                              | Native | `runtime.deadLetters` provides deny-by-default immutable inspection and idempotent durable retry linkage.                                                                      |
-| Reconciliation reads                                                          | Native | Authorized cursor pages cover active, quiet, and orphaned instances; bounded state batches are migrated and deeply frozen.                                                     |
-| Message, process, and opt-in instance retention                               | Native | Supervised scheduling bounds message and process growth; authorized manual APIs add preview and keep destructive instance expiration explicit.                                 |
-| Doctor and schema verification                                                | Native | Structured checks cover configuration, schema/version shape, adapter server versions, neutral-context policy probes, live roles, and a targeted round trip.                    |
-| CLI                                                                           | Native | The packaged executable loads an application runtime and exposes start, diagnostics, processes, dead letters, reminders, and explicit retention pruning as JSON.               |
-| Structured instrumentation                                                    | Native | An isolated transport-neutral sink emits immutable lifecycle metadata and structurally excludes application payloads.                                                          |
-| Public test helper                                                            | Native | `runtime.testing` provides role-selective deterministic draining, explicit-time due-reminder execution, and dependency-ordered reset without relying on cascades.              |
+| Capability                                                                    | Status | TypeScript shape or remaining work                                                                                                                                                                   |
+| ----------------------------------------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Process registration, heartbeats, stale claim recovery, and graceful shutdown | Native | Runtime roles persist host, PID, runtime versions, draining and stopped transitions, cooperative cancellation, and a bounded shutdown deadline; cleanup recovers stale claims.                       |
+| Failed-role replacement                                                       | Native | Built-in and registered roles are rebuilt through their factories with capped backoff; shutdown is the terminal replacement boundary.                                                                |
+| Additional supervised components                                              | Native | `registerComponent()` builds, validates, runs, and stops application components with the runtime.                                                                                                    |
+| Dead-letter inspection and retry                                              | Native | `runtime.deadLetters` provides deny-by-default immutable inspection and idempotent durable retry linkage.                                                                                            |
+| Reconciliation reads                                                          | Native | Authorized cursor pages cover active, quiet, and orphaned instances; bounded state batches are migrated and deeply frozen.                                                                           |
+| Message, process, and opt-in instance retention                               | Native | Supervised scheduling bounds message and process growth; authorized manual APIs add preview and keep destructive instance expiration explicit.                                                       |
+| Doctor and schema verification                                                | Native | Structured checks cover configuration, schema/version shape, adapter server versions, neutral-context policy probes, live roles, and a targeted round trip.                                          |
+| CLI                                                                           | Native | The packaged executable loads an application runtime and exposes start, diagnostics, processes, dead letters, reminders, and explicit retention pruning as JSON.                                     |
+| Operator dashboard                                                            | Native | The opt-in `solid-objects/web` export provides Fetch and Node/Connect mounting, authorized runtime views and actions, session-backed CSRF, filtering, paging, charts, and immutable extension hooks. |
+| Structured instrumentation                                                    | Native | An isolated transport-neutral sink emits immutable lifecycle metadata and structurally excludes application payloads.                                                                                |
+| Public test helper                                                            | Native | `runtime.testing` provides role-selective deterministic draining, explicit-time due-reminder execution, and dependency-ordered reset without relying on cascades.                                    |
 
 ## Databases and wake-up
 
@@ -76,19 +79,19 @@ missing Ruby capabilities.
 
 ## Realtime and browser behavior
 
-| Capability                                                   | Status         | TypeScript shape or remaining work                                                                                                                                                                                                                                          |
-| ------------------------------------------------------------ | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Explicit observable projection and durable invalidations     | Native         | `observables()` is opt-in; changed values enter invalidation envelopes and are visible to every authorized subscriber. Unlike Ruby morph refreshes, values cross the wire, so private or subscriber-specific state belongs in payloads or reauthorized component endpoints. |
-| Action Cable channels and signed stream names                | Not applicable | `runtime.realtime` provides authenticated transport-neutral sessions; the host owns its HTTP/WebSocket server and authentication.                                                                                                                                           |
-| Authorized subscriptions                                     | Native         | Each request is denied by default and authorized before actor lookup; sessions replay committed observables and fence ordered durable revisions. Multi-process hosts explicitly bridge their shared transport.                                                              |
-| Turbo scalar replacement                                     | Not applicable | The browser client exposes invalidations to application rendering code. Framework adapters can be separate packages.                                                                                                                                                        |
-| Keyed component refresh, morph/replace, and batch coalescing | Native         | A typed framework-neutral registry selects explicit dependencies, coalesces batch requests, aborts superseded work, fences each target, and delegates synchronous application strategy to the host.                                                                         |
-| Personalized payload broadcasts                              | Native         | Static typed projections run against committed state under each fresh subscriber context, reauthorize as queries, isolate failures, and carry independent revision fences.                                                                                                  |
-| Real-browser compatibility suite                             | Native         | Playwright exercises subscription replay over native WebSocket, incarnation/revision fences, payload delivery, component batching, and cancellation in Chromium.                                                                                                            |
+| Capability                                                   | Status         | TypeScript shape or remaining work                                                                                                                                                                                                                                                                                 |
+| ------------------------------------------------------------ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Explicit observable projection and durable invalidations     | Native         | `observables()` is opt-in and invalidation-only by default. `broadcastValue()` sends changed values; `broadcastInvalidation()` explicitly sends only changed names while comparing the real value. Private or subscriber-specific values belong behind invalidation-only component endpoints or in typed payloads. |
+| Action Cable channels and signed stream names                | Not applicable | `runtime.realtime` provides authenticated transport-neutral sessions; the host owns its HTTP/WebSocket server and authentication.                                                                                                                                                                                  |
+| Authorized subscriptions                                     | Native         | Each request is denied by default and authorized before actor lookup; sessions replay committed observables and fence ordered durable revisions. Multi-process hosts explicitly bridge their shared transport.                                                                                                     |
+| Turbo scalar replacement                                     | Not applicable | The browser client exposes invalidations to application rendering code. Framework adapters can be separate packages.                                                                                                                                                                                               |
+| Keyed component refresh, morph/replace, and batch coalescing | Native         | A typed framework-neutral registry selects explicit dependencies, coalesces batch requests, aborts superseded work, fences each target, and delegates synchronous application strategy to the host.                                                                                                                |
+| Personalized payload broadcasts                              | Native         | Static typed projections run against committed state under each fresh subscriber context, reauthorize as queries, isolate failures, and carry independent revision fences.                                                                                                                                         |
+| Real-browser compatibility suite                             | Native         | Playwright exercises subscription replay over native WebSocket, incarnation/revision fences, payload delivery, component batching, and cancellation in Chromium.                                                                                                                                                   |
 
 ## Rails-specific surfaces
 
-The Rails engine, generators, Active Record models/controllers, ERB helpers,
-Turbo renderer, and Action Cable channel are not copied into this package.
-Their underlying runtime, administration, authorization, and realtime
-capabilities are represented above by Node-native APIs and protocols.
+Rails generators, Active Record models/controllers, Turbo rendering, and
+Action Cable are not copied into this package. The Rack dashboard is represented
+by the framework-neutral Fetch and Node adapter, renderer callbacks, and the
+same authorization and CSRF boundaries.

package/docs/releasing.md

@@ -30,14 +30,16 @@ npm trust github solid-objects \
    lockfile when needed, and move the release notes out of the Unreleased
    section in `CHANGELOG.md`.
 2. Run `pnpm run format:check`, `pnpm run check`, `pnpm run test:coverage`,
-   `pnpm run build`, `pnpm run pack:check`, and
-   `pnpm audit --audit-level=high`.
+   `pnpm run build`, `pnpm run pack:check`, `pnpm run test:package`,
+   `pnpm run test:recovery`, `pnpm run test:browser`, and
+   `pnpm audit --audit-level=high`. Run the PostgreSQL, MySQL, and Redis jobs
+   against the versions in [the support matrix](support.md).
 3. Commit and push `main`.
 4. Create and push an annotated tag matching the package version:
 
    ```shell
-   git tag -a v0.12.1 -m "Version 0.12.1"
-   git push origin v0.12.1
+   git tag -a v0.13.1 -m "Version 0.13.1"
+   git push origin v0.13.1
    ```
 
 The tag runs the complete CI matrix. The publish job starts only after every

package/docs/state-and-lifecycle.md

@@ -20,6 +20,16 @@ The constructor must establish every persisted field and must not depend on
 external state. Solid Objects invokes it while validating the class, creating
 defaults, hydrating state, and projecting a snapshot.
 
+## Observable broadcast modes
+
+`observables()` defines the named values used for realtime change detection.
+Unwrapped values are invalidation-only: the runtime compares their real values
+but includes only each changed name in committed envelopes. Wrapping a value in
+`broadcastInvalidation()` makes that contract explicit. Wrap it in
+`broadcastValue()` only when every authorized actor subscriber may receive the
+value itself. Every mode evaluates and JSON-validates its real value after a
+successful turn.
+
 ## State migrations
 
 Every actor starts at state version 1. Increase `stateVersion` when existing

package/docs/support.md

@@ -0,0 +1,39 @@
+# Supported versions and test matrix
+
+## Runtime support
+
+| Component      | Supported or tested range                                   |
+| -------------- | ----------------------------------------------------------- |
+| Node.js        | 24.15 or newer; CI uses 24.15                               |
+| TypeScript     | 5.9 or newer for TypeScript applications                    |
+| SQLite         | Node's built-in `node:sqlite` on the supported Node runtime |
+| PostgreSQL     | 14 or newer; CI runs 14 and 18                              |
+| MySQL          | 8.0 or newer with InnoDB; CI runs 8.0 and 8.4               |
+| Redis wake-up  | Optional; CI runs Redis 7                                   |
+| Browser client | Chromium through Playwright                                 |
+
+The package is ESM-only. PostgreSQL, MySQL, and Redis require their optional
+peer dependency. SQLite has no driver dependency beyond Node.js.
+
+## What the matrix covers
+
+The default suite exercises actor definitions, mailbox ordering, state
+migrations, leases, fencing, retries, dead letters, effects, reminders,
+realtime outboxes, administration, authorization, retention, lifecycle,
+timeouts, and SQLite behavior.
+
+Database jobs run the real adapter suites against PostgreSQL and MySQL servers.
+The Redis job runs wake-up behavior against a real Redis server. The browser
+job uses native WebSocket connections and Chromium for replay, payload,
+component, dashboard, and revision-fence behavior.
+
+The quality job also builds the ESM package, inspects `npm pack`, installs the
+generated tarball in a clean temporary project, runs its packaged SQLite
+quickstart, and executes the multi-process recovery demonstration.
+
+## Boundaries
+
+CI currently runs on Ubuntu. Local validation also occurs on macOS, but the
+project does not claim a complete operating-system compatibility matrix. A
+database version being accepted by configuration is not a substitute for its
+listed integration job.

package/examples/failure-recovery/actor.ts

@@ -0,0 +1,51 @@
+import { appendFile, access, writeFile } from "node:fs/promises"
+import { join } from "node:path"
+import { Actor } from "solid-objects"
+
+export class RecoveryCounter extends Actor {
+  static override readonly actorType = "RecoveryCounter"
+
+  count = 0
+
+  async recover({ controlDirectory }: { controlDirectory: string }): Promise<number> {
+    const message = this.currentMessage
+    if (!message) throw new Error("recover requires a durable message")
+    const attempt = message.attempt
+    await appendFile(
+      join(controlDirectory, "external-effects.jsonl"),
+      `${JSON.stringify({ messageId: message.id, attempt, processId: process.pid })}\n`,
+    )
+    await writeFile(join(controlDirectory, `started-${attempt}-${process.pid}`), "")
+    process.send?.({ event: "operation.started", attempt, processId: process.pid })
+    if (attempt === 1) await waitForFile(join(controlDirectory, "release-first-attempt"))
+    this.count += 1
+    return this.count
+  }
+
+  async serialize({ controlDirectory }: { controlDirectory: string }): Promise<number> {
+    const message = this.currentMessage
+    if (!message) throw new Error("serialize requires a durable message")
+    await appendFile(
+      join(controlDirectory, "serialization.jsonl"),
+      `${JSON.stringify({ event: "start", messageId: message.id, at: Date.now() })}\n`,
+    )
+    await new Promise((resolve) => setTimeout(resolve, 100))
+    this.count += 1
+    await appendFile(
+      join(controlDirectory, "serialization.jsonl"),
+      `${JSON.stringify({ event: "finish", messageId: message.id, at: Date.now() })}\n`,
+    )
+    return this.count
+  }
+}
+
+async function waitForFile(path: string): Promise<void> {
+  for (;;) {
+    try {
+      await access(path)
+      return
+    } catch {
+      await new Promise((resolve) => setTimeout(resolve, 10))
+    }
+  }
+}