solid-objects 0.12.0 → 0.13.0

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.0. 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.0` implementation has spiritual parity with that reference. Its
+The Node `0.13.0` 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
 
@@ -32,11 +34,11 @@ missing Ruby capabilities.
 | Actor registry, durable identity, JSON state, and adjacent state migrations                                   | Native  | Ordinary classes, static actor types, inferred state, explicit migrations, and isolated runtime context across every actor-instance callback.                                                                      |
 | Fluent committed calls and background delivery                                                                | Native  | `await reference.operation()` and `reference.send.operation()`.                                                                                                                                                    |
 | Ordered mailbox, sequence allocation, idempotency, retries, dead letters, leases, renewal, and fenced commits | Native  | Relational ready/claimed membership tables, distinct generated request IDs and caller idempotency keys, durable history, and adapter-appropriate sequence locking.                                                 |
-| Domain rejection and strict poison ordering                                                                   | Native  | Rejections roll back without retry; retryable failures block later operations until completion or dead-lettering.                                                                                                  |
+| Domain rejection and strict poison ordering                                                                   | Native  | Rejections accept JavaScript identifier-style codes and roll back without retry; invalid codes fail terminally, while retryable failures block later operations until completion or dead-lettering.                |
 | Bounded activation passes and hot-actor fairness                                                              | Native  | Configurable turn-count and elapsed-time budgets bound each pass, then move only that actor's already-due memberships behind actors already waiting.                                                               |
 | Bounded claim candidate scan                                                                                  | Native  | A configurable ordered scan continues to another ready actor when a worker loses the first candidate's lease race.                                                                                                 |
 | Idle activation cache                                                                                         | Native  | Long-running workers retain hydrated actors under renewable fenced leases, restore public state after failed turns, and release on timeout, fairness yield, lease loss, or shutdown.                               |
-| Transactional effects and outcome operations                                                                  | Native  | At-least-once handlers receive immutable stable effect, attempt, source-message, and actor identity; success and failure return through actor operations.                                                          |
+| Transactional effects and outcome operations                                                                  | Native  | At-least-once handlers receive immutable stable effect, attempt, source-message, and actor identity; success and failure operations also receive the originally staged arguments for correlation.                  |
 | Actor-to-actor delivery                                                                                       | Native  | `sendTo(reference).operation()` stages delivery in the source actor commit.                                                                                                                                        |
 | One-shot and recurring reminders                                                                              | Native  | Scheduling, replacement events, catch-up policy, stale-claim recovery, pausing, authorized inspection, and idempotent resume are implemented.                                                                      |
 | Same-database commit actions                                                                                  | Native  | Registered actions receive source-message identity, mailbox sequence, activation generation, and the fenced transaction connection.                                                                                |
@@ -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 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; only changed projected values enter the broadcast outbox.                                                                                                                           |
-| 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

@@ -26,11 +26,14 @@ npm trust github solid-objects \
 
 ## Release procedure
 
-1. Update the version in `package.json` and `pnpm-lock.yaml` and move the
-   release notes out of the Unreleased section in `CHANGELOG.md`.
+1. Update the version in `package.json` and `src/version.ts`, refresh the
+   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:
 

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
@@ -116,10 +126,10 @@ crash, so it cannot establish correctness.
 ## Domain rejection and failure
 
 Call `this.reject(code, { message, details })` when an operation is valid but
-the domain refuses it. Codes contain lowercase letters, digits, and
-underscores. The turn rolls back, staged work is discarded, the message becomes
-`rejected`, and later mailbox work remains eligible. The caller receives
-`Rejected` with the code, frozen JSON details, and durable message ID.
+the domain refuses it. Codes use the same identifier rule as actor members:
+`[A-Za-z_][A-Za-z0-9_]*`. The turn rolls back, staged work is discarded, the
+message becomes `rejected`, and later mailbox work remains eligible. The caller
+receives `Rejected` with the code, frozen JSON details, and durable message ID.
 
 Throwing another error rolls the turn back and schedules a retry according to
 `maxAttempts` and `retryDelayMilliseconds`. Throw a custom subclass of

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))
+    }
+  }
+}

package/examples/failure-recovery/demo.ts

@@ -0,0 +1,233 @@
+import assert from "node:assert/strict"
+import { existsSync } from "node:fs"
+import { mkdtemp, mkdir, readFile, rm, writeFile } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { fileURLToPath } from "node:url"
+import { fork, type ChildProcess } from "node:child_process"
+import { createRuntime, type ActorReference, type MessageReference } from "solid-objects"
+import { sqlite } from "solid-objects/database/sqlite"
+import { RecoveryCounter } from "./actor.ts"
+
+interface WorkerMessage {
+  event: string
+  attempt?: number
+  processed?: number
+}
+
+interface SerializationEvent {
+  event: "start" | "finish"
+  messageId: string
+  at: number
+}
+
+interface ExternalEffectEvent {
+  messageId: string
+  attempt: number
+  processId: number
+}
+
+const directory = await mkdtemp(join(tmpdir(), "solid-objects-recovery-"))
+const databasePath = join(directory, "state.sqlite3")
+const runtime = createRuntime({
+  database: sqlite({ path: databasePath, timeoutMilliseconds: 2_000, lockRetryAttempts: 20 }),
+  leaseDurationMilliseconds: 250,
+  leaseRenewalIntervalMilliseconds: 50,
+  processHeartbeatIntervalMilliseconds: 75,
+  processAliveThresholdMilliseconds: 300,
+  workerCount: 1,
+  effectWorkerCount: 0,
+  reminderSchedulerCount: 0,
+  retentionIntervalMilliseconds: 0,
+  deadProcessCleanupIntervalMilliseconds: 0,
+  authorizeMessage: () => true,
+  authorizeQuery: () => true,
+  authorizeAdministration: () => true,
+})
+
+try {
+  runtime.register(RecoveryCounter)
+  await runtime.install()
+  const serialization = await proveSerialization()
+  const crash = await proveCrashRecovery()
+  const fencing = await proveFencing()
+  process.stdout.write(`${JSON.stringify({ serialization, crash, fencing }, null, 2)}\n`)
+} finally {
+  await runtime.close()
+  await rm(directory, { recursive: true })
+}
+
+assert.equal(existsSync(directory), false)
+
+async function proveSerialization(): Promise<{ finalState: number; overlap: false }> {
+  const controlDirectory = join(directory, "serialization")
+  await mkdir(controlDirectory)
+  const reference = runtime.ref(RecoveryCounter, "serialized")
+  const messages = await Promise.all([
+    reference.send.serialize({ controlDirectory }),
+    reference.send.serialize({ controlDirectory }),
+  ])
+  const workers = [spawnWorker(), spawnWorker()]
+  await Promise.all(workers.map(({ finished }) => finished))
+  await Promise.all(messages.map((message) => message.result()))
+  const events = await readJsonLines(
+    join(controlDirectory, "serialization.jsonl"),
+    parseSerializationEvent,
+  )
+  assert.equal(events.length, 4)
+  const starts = events.filter((event) => event.event === "start")
+  const finishes = events.filter((event) => event.event === "finish")
+  assert.equal(starts.length, 2)
+  assert.equal(finishes.length, 2)
+  assert(Number(starts[1]?.at) >= Number(finishes[0]?.at))
+  const snapshot = await reference.snapshot()
+  assert.equal(snapshot.count, 2)
+  return { finalState: snapshot.count, overlap: false }
+}
+
+async function proveCrashRecovery(): Promise<{
+  attempts: number
+  finalState: number
+  repeatedEffects: number
+}> {
+  const controlDirectory = join(directory, "crash")
+  await mkdir(controlDirectory)
+  const reference = runtime.ref(RecoveryCounter, "crash")
+  const message = await reference.send.recover({ controlDirectory })
+  const firstWorker = spawnWorker()
+  await firstWorker.waitFor((entry) => entry.event === "operation.started" && entry.attempt === 1)
+  firstWorker.child.kill("SIGKILL")
+  await firstWorker.finished.catch(() => undefined)
+  await wait(350)
+  const recoveryWorker = spawnWorker()
+  await recoveryWorker.finished
+  await message.result()
+  return recoveryResult({ reference, message, controlDirectory })
+}
+
+async function proveFencing(): Promise<{
+  attempts: number
+  finalState: number
+  repeatedEffects: number
+}> {
+  const controlDirectory = join(directory, "fencing")
+  await mkdir(controlDirectory)
+  const reference = runtime.ref(RecoveryCounter, "fencing")
+  const message = await reference.send.recover({ controlDirectory })
+  const staleWorker = spawnWorker()
+  await staleWorker.waitFor((entry) => entry.event === "operation.started" && entry.attempt === 1)
+  staleWorker.child.kill("SIGSTOP")
+  await wait(350)
+  const recoveryWorker = spawnWorker()
+  await recoveryWorker.finished
+  await message.result()
+  staleWorker.child.kill("SIGCONT")
+  await writeFile(join(controlDirectory, "release-first-attempt"), "")
+  await staleWorker.waitFor((entry) => entry.event === "solid_objects.activation.lost")
+  await staleWorker.finished
+  return recoveryResult({ reference, message, controlDirectory })
+}
+
+async function recoveryResult(options: {
+  reference: ActorReference<RecoveryCounter>
+  message: MessageReference
+  controlDirectory: string
+}): Promise<{ attempts: number; finalState: number; repeatedEffects: number }> {
+  const stored = await runtime.repository.findMessage(options.message.id)
+  const attempts = Number(stored?.attempt_count)
+  const snapshot = await options.reference.snapshot()
+  const effects = await readJsonLines(
+    join(options.controlDirectory, "external-effects.jsonl"),
+    parseExternalEffectEvent,
+  )
+  assert.equal(attempts, 2)
+  assert.equal(snapshot.count, 1)
+  assert.equal(effects.length, 2)
+  return { attempts, finalState: snapshot.count, repeatedEffects: effects.length }
+}
+
+function spawnWorker(): {
+  child: ChildProcess
+  finished: Promise<void>
+  waitFor(predicate: (message: WorkerMessage) => boolean): Promise<WorkerMessage>
+} {
+  const child = fork(fileURLToPath(new URL("./worker.ts", import.meta.url)), [databasePath], {
+    cwd: fileURLToPath(new URL("../..", import.meta.url)),
+    stdio: ["ignore", "pipe", "pipe", "ipc"],
+  })
+  const messages: WorkerMessage[] = []
+  const listeners = new Set<(message: WorkerMessage) => void>()
+  let stderr = ""
+  child.stderr?.on("data", (chunk) => {
+    stderr += chunk
+  })
+  child.on("message", (message: WorkerMessage) => {
+    messages.push(message)
+    for (const listener of listeners) listener(message)
+  })
+  const finished = new Promise<void>((resolvePromise, reject) => {
+    child.once("error", reject)
+    child.once("exit", (code, signal) => {
+      if (code === 0) {
+        resolvePromise()
+        return
+      }
+      reject(new Error(`worker exited with code ${code} and signal ${signal}\n${stderr}`))
+    })
+  })
+  return {
+    child,
+    finished,
+    waitFor: (predicate) => {
+      const existing = messages.find(predicate)
+      if (existing) return Promise.resolve(existing)
+      return new Promise((resolvePromise) => {
+        const listener = (message: WorkerMessage) => {
+          if (!predicate(message)) return
+          listeners.delete(listener)
+          resolvePromise(message)
+        }
+        listeners.add(listener)
+      })
+    },
+  }
+}
+
+async function readJsonLines<Value>(
+  path: string,
+  parse: (line: string) => Value,
+): Promise<Value[]> {
+  return (await readFile(path, "utf8")).trim().split("\n").filter(Boolean).map(parse)
+}
+
+function parseSerializationEvent(line: string): SerializationEvent {
+  const event = JSON.parse(line) as Partial<SerializationEvent>
+  if (
+    (event.event !== "start" && event.event !== "finish") ||
+    typeof event.messageId !== "string" ||
+    typeof event.at !== "number"
+  ) {
+    throw new TypeError("invalid serialization event")
+  }
+  return { event: event.event, messageId: event.messageId, at: event.at }
+}
+
+function parseExternalEffectEvent(line: string): ExternalEffectEvent {
+  const event = JSON.parse(line) as Partial<ExternalEffectEvent>
+  if (
+    typeof event.messageId !== "string" ||
+    typeof event.attempt !== "number" ||
+    typeof event.processId !== "number"
+  ) {
+    throw new TypeError("invalid external effect event")
+  }
+  return {
+    messageId: event.messageId,
+    attempt: event.attempt,
+    processId: event.processId,
+  }
+}
+
+async function wait(milliseconds: number): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve, milliseconds))
+}

package/examples/failure-recovery/worker.ts

@@ -0,0 +1,46 @@
+import { createRuntime } from "solid-objects"
+import { sqlite } from "solid-objects/database/sqlite"
+import { RecoveryCounter } from "./actor.ts"
+
+const databasePath = requiredArgument(2)
+const runtime = createRuntime({
+  database: sqlite({ path: databasePath, timeoutMilliseconds: 2_000, lockRetryAttempts: 20 }),
+  pollingIntervalMilliseconds: 10,
+  leaseDurationMilliseconds: 250,
+  leaseRenewalIntervalMilliseconds: 50,
+  processHeartbeatIntervalMilliseconds: 75,
+  processAliveThresholdMilliseconds: 300,
+  workerCount: 1,
+  effectWorkerCount: 0,
+  reminderSchedulerCount: 0,
+  retentionIntervalMilliseconds: 0,
+  deadProcessCleanupIntervalMilliseconds: 0,
+  authorizeMessage: () => true,
+  authorizeQuery: () => true,
+  authorizeAdministration: () => true,
+  instrumentation: ({ name, attributes }) => {
+    process.send?.({ event: name, attributes })
+  },
+})
+
+runtime.register(RecoveryCounter)
+await runtime.install()
+const worker = runtime.worker()
+
+try {
+  let processed = 0
+  for (let attempt = 0; attempt < 200 && processed === 0; attempt += 1) {
+    processed = await worker.runOnce({ activationRetention: "release" })
+    if (processed === 0) await new Promise((resolve) => setTimeout(resolve, 10))
+  }
+  process.send?.({ event: "worker.finished", processed })
+} finally {
+  await worker.stop()
+  await runtime.close()
+}
+
+function requiredArgument(index: number): string {
+  const value = process.argv[index]
+  if (!value) throw new TypeError(`argument ${index - 1} is required`)
+  return value
+}

package/examples/sqlite-quickstart.ts

@@ -0,0 +1,109 @@
+import assert from "node:assert/strict"
+import { existsSync } from "node:fs"
+import { mkdtemp, rm } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import { join, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+import { Actor, createRuntime } from "solid-objects"
+import { sqlite } from "solid-objects/database/sqlite"
+
+class Counter extends Actor {
+  static override readonly actorType = "QuickstartCounter"
+
+  count = 0
+
+  increment(): number {
+    this.count += 1
+    return this.count
+  }
+
+  async pause({ milliseconds }: { milliseconds: number }): Promise<{
+    startedAt: number
+    finishedAt: number
+  }> {
+    const startedAt = performance.now()
+    await new Promise((resolvePromise) => setTimeout(resolvePromise, milliseconds))
+    return { startedAt, finishedAt: performance.now() }
+  }
+}
+
+export async function runQuickstart(
+  options: {
+    signal?: AbortSignal
+    write?: (value: string) => void
+  } = {},
+): Promise<void> {
+  const directory = await mkdtemp(join(tmpdir(), "solid-objects-quickstart-"))
+  const databasePath = join(directory, "state.sqlite3")
+  const runtime = createRuntime({
+    database: sqlite({ path: databasePath }),
+    workerCount: 2,
+    effectWorkerCount: 0,
+    reminderSchedulerCount: 0,
+    retentionIntervalMilliseconds: 0,
+    deadProcessCleanupIntervalMilliseconds: 0,
+    authorizeMessage: () => true,
+    authorizeQuery: () => true,
+  })
+  const shutdown = new AbortController()
+  const abort = () => shutdown.abort(options.signal?.reason)
+  options.signal?.addEventListener("abort", abort, { once: true })
+  let running: Promise<void> | undefined
+  let sameIdentityFinalState = 0
+  let independentIdentitiesOverlapped = false
+
+  try {
+    runtime.register(Counter)
+    await runtime.install()
+    running = runtime.run(shutdown.signal)
+
+    const counter = runtime.ref(Counter, "room-1")
+    const results = await Promise.all(Array.from({ length: 25 }, () => counter.increment()))
+    assert.deepEqual(
+      [...results].sort((left, right) => left - right),
+      Array.from({ length: 25 }, (_value, index) => index + 1),
+    )
+    sameIdentityFinalState = await counter.count
+    assert.equal(sameIdentityFinalState, 25)
+
+    const pauses = await Promise.all([
+      runtime.ref(Counter, "room-2").send.pause({ milliseconds: 100 }),
+      runtime.ref(Counter, "room-3").send.pause({ milliseconds: 100 }),
+    ])
+    const windows = await Promise.all(
+      pauses.map((message) => message.wait({ timeoutMilliseconds: 5_000 })),
+    )
+    const firstWindow = windows[0]
+    const secondWindow = windows[1]
+    if (!firstWindow || !secondWindow) throw new Error("two execution windows are required")
+    independentIdentitiesOverlapped =
+      firstWindow.startedAt < secondWindow.finishedAt &&
+      secondWindow.startedAt < firstWindow.finishedAt
+    assert.equal(independentIdentitiesOverlapped, true)
+  } finally {
+    shutdown.abort()
+    await running
+    await runtime.close()
+    options.signal?.removeEventListener("abort", abort)
+    await rm(directory, { recursive: true })
+  }
+
+  assert.equal(existsSync(directory), false)
+  const write = options.write ?? ((value: string) => process.stdout.write(value))
+  write(
+    `${JSON.stringify(
+      {
+        sameIdentityCalls: 25,
+        sameIdentityFinalState,
+        independentIdentitiesOverlapped,
+        temporaryStateRemoved: true,
+      },
+      null,
+      2,
+    )}\n`,
+  )
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1])) {
+  await runQuickstart()
+}