solid-objects 0.12.1 → 0.13.0

package/README.md

@@ -1,997 +1,272 @@
-# Solid Objects JS
+# Durable Objects for Node, backed by your existing SQL database
 
-**Stateful virtual actors for Node.js, powered entirely by your relational database.**
+[![CI](https://github.com/cardmagic/solid-objects-js/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/cardmagic/solid-objects-js/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/solid-objects)](https://www.npmjs.com/package/solid-objects)
 
-Get the programming model of Cloudflare Durable Objects without moving your
-state into custom cloud isolates. Write ordinary TypeScript classes; Solid
-Objects gives each instance a durable identity, persisted state, an ordered
-mailbox, and safe one-at-a-time execution.
+Build addressable TypeScript objects with serialized calls and durable state
+using SQLite, PostgreSQL, or MySQL, without deploying to Cloudflare.
 
-No Redis locks. No separate message broker for actor mailboxes. No proprietary
-state service. The database you already understand provides the transaction,
-lease, fencing, retry, timer, and outbox primitives.
+Concurrent calls for one identity cannot overwrite each other. Calls for
+different identities can run at the same time.
 
-> SQLite uses Node's built-in `node:sqlite` module. PostgreSQL 14 or newer and
-> MySQL 8.0 or newer use optional driver peer dependencies.
+Define ordinary TypeScript classes and run them in ordinary Node.js processes.
+State, queued operations, retries, reminders, effects, and realtime
+invalidations are stored in the database the application already operates.
 
-## The boring stack, with an actor model
+> **Early release:** the correctness core has automated coverage across the
+> supported databases, the Chromium browser client, process recovery, and
+> packaged artifacts, but the TypeScript implementation is new. Read the
+> [delivery boundaries](#delivery-boundaries) before using it for important data.
 
-Most stateful features eventually need the same machinery: load one entity,
-serialize concurrent changes, persist the result, schedule follow-up work, and
-recover after a process dies. Applications often assemble that machinery from
-a database, Redis, a queue, distributed locks, and a pile of retry code.
-
-Solid Objects keeps that coordination in one place: the relational database.
-
-- An actor is addressed by its TypeScript class and ID.
-- Public fields are JSON state.
-- Public methods are durable operations.
-- Public getters are ordered, read-only queries.
-- Every actor has a durable, sequential mailbox.
-- State, results, actor-to-actor delivery, effects, reminders, and observable
-  invalidations commit together.
-- Renewable leases and fencing prevent stale workers from committing.
-
-## What you stop building
-
-For workloads organized around durable identities—accounts, carts, game rooms,
-workflows, devices, collaborative documents, or agent sessions—Solid Objects
-replaces a recurring layer of infrastructure and application code:
-
-- per-entity locking and race-condition handling;
-- bespoke queue consumers that must preserve ordering;
-- retry bookkeeping and poison-message handling;
-- timer tables and scheduler claim logic;
-- transactional outboxes for follow-up work; and
-- durable invalidation bookkeeping.
-
-This is not an in-memory actor library. A call is complete only after its state
-and durable consequences commit to the database.
-
-Solid Objects JS ports the programming model of the Ruby
-[`solid_objects`](https://github.com/cardmagic/solid_objects) gem to idiomatic
-TypeScript. The runtimes do not share a database schema or wire protocol.
-
-## Requirements
-
-- Node.js 24.15 or newer
-- TypeScript 5.9 or newer for TypeScript applications
-- SQLite, PostgreSQL 14 or newer, or MySQL 8.0 or newer with InnoDB
-
-## Installation
-
-```bash
-pnpm add solid-objects
-```
-
-## Write an ordinary TypeScript class
+## The programming model
 
 ```typescript
 import { Actor } from "solid-objects"
 
-export class Counter extends Actor {
-  static override readonly actorType = "Counter"
+class Cart extends Actor {
+  static override readonly actorType = "Cart"
 
-  count = 0
-
-  get doubled(): number {
-    return this.count * 2
-  }
-
-  increment({ amount = 1 }: { amount?: number } = {}): number {
-    this.count += amount
-    return this.count
-  }
+  items: string[] = []
 
-  override observables(): Record<string, unknown> {
-    return { count: this.count }
+  add({ sku }: { sku: string }): number {
+    this.items.push(sku)
+    return this.items.length
   }
 }
-```
-
-No wrapper, state interface, decorator, or operation union is required. Native
-`#private` fields remain private and are not persisted. Persisted fields,
-operation arguments, results, and observable values must be JSON-compatible.
 
-`observables()` is deliberately explicit. State fields and getters do not
-become realtime data automatically.
-
-## Evolve state with explicit migrations
-
-Increase `stateVersion` and retain every adjacent migration when persisted
-state changes shape:
-
-```typescript
-import { Actor, type JsonObject } from "solid-objects"
-
-export class ShoppingCart extends Actor {
-  static override readonly actorType = "ShoppingCart"
-  static override readonly stateVersion = 2
-  static override readonly migrations = [
-    {
-      from: 1,
-      to: 2,
-      migrate: (state: JsonObject): JsonObject => ({
-        ...state,
-        currency: "USD",
-      }),
-    },
-  ]
-
-  items: string[] = []
-  currency = "USD"
-}
+const cart = Cart.ref("cart-123")
+await Promise.all([cart.add({ sku: "blue-shirt" }), cart.add({ sku: "green-hat" })])
 ```
 
-Migrations run in order when an actor is next hydrated. They must be
-deterministic, synchronous, JSON-compatible transformations and cannot write
-through a guarded application database. New field defaults are filled from a
-fresh actor after migration. Do not run application processes with different
-`stateVersion` values at the same time: once new code persists a newer state,
-old code rejects it.
+Both calls enter the durable mailbox for `cart-123`. They execute in order and
+commit one state transition at a time, even when different requests or Node.js
+processes submit them concurrently.
 
-See [`docs/state-and-lifecycle.md`](docs/state-and-lifecycle.md) for field
-discovery, rolling deployment, activation hooks, snapshots, rejection, and
-destruction.
+## Run it now with SQLite
 
-## Point it at SQLite, PostgreSQL, or MySQL
-
-SQLite needs no database driver package:
-
-```typescript
-import { configure } from "solid-objects"
-import { sqlite } from "solid-objects/database/sqlite"
-import { Counter } from "./counter.js"
-
-const runtime = configure({
-  database: sqlite({
-    path: "storage/solid-objects.sqlite3",
-    timeoutMilliseconds: 5_000,
-    lockRetryAttempts: 10,
-  }),
-  authorizeMessage: ({ authorizationContext }) => authorizationContext !== undefined,
-  authorizeQuery: ({ authorizationContext }) => authorizationContext !== undefined,
-  authorizeDestroy: ({ authorizationContext }) => authorizationContext !== undefined,
-  authorizeAdministration: ({ authorizationContext }) => isOperator(authorizationContext),
-  authorizeSubscription: ({ actorId, authorizationContext }) =>
-    authorizationContext?.canViewCounter(actorId) === true,
-})
-
-runtime.register(Counter)
-await runtime.install()
-
-const shutdown = new AbortController()
-process.once("SIGTERM", () => shutdown.abort())
-process.once("SIGINT", () => shutdown.abort())
-await runtime.run(shutdown.signal)
-```
-
-SQLite serializes access inside one Node process. Across processes, it uses the
-native busy timeout and retries transient `BEGIN IMMEDIATE` contention with
-short capped backoff. `lockRetryAttempts` bounds those retries; synchronous
-invocations remain bounded by their end-to-end `timeoutMilliseconds` deadline.
-
-`configure()` installs this runtime as the default used by `Actor.ref()`. Use
-`createRuntime()` when an application needs an isolated runtime and address its
-actors through `runtime.ref(ActorClass, actorId)`. Actor code executing in that
-runtime resolves its own actor references without changing the global default.
-
-For PostgreSQL, install the optional driver and replace the database value:
-
-```bash
-pnpm add pg
-```
-
-```typescript
-import { postgresql } from "solid-objects/database/postgresql"
-
-const connectionString = process.env.DATABASE_URL
-if (!connectionString) throw new Error("DATABASE_URL is required")
-
-const database = postgresql({
-  connectionString,
-  maximumConnections: 10,
-})
-
-const runtime = configure({
-  database,
-  wakeUp: database.wakeUp(),
-})
-```
-
-PostgreSQL uses a bounded `pg` pool, 64-bit database timestamps and sequences,
-row-locked sequence allocation, and the same durable polling contract as
-SQLite. Keep `pg` at 8.23 or newer within the supported major. Portable
-`DatabaseConnection` SQL uses `?` parameters; write `??` when a PostgreSQL query
-needs the literal JSON existence operator.
-
-`database.wakeUp()` is opt-in. It uses one event-driven PostgreSQL client per
-runtime to listen on role-specific channels and wake every matching local
-waiter. Create it in every process that should send or receive notifications.
-Polling remains the fallback if a notification is missed or the listener
-reconnects. Because `LISTEN` is session-scoped, use a direct connection or
-session pooling rather than transaction pooling for this client.
-
-For MySQL, install `mysql2` and configure its bounded promise pool:
+Node.js 24.15 or newer is required. The `0.13.0` release includes a
+packaged quickstart:
 
 ```bash
-pnpm add mysql2
-```
-
-```typescript
-import { mysql } from "solid-objects/database/mysql"
-
-const connectionString = process.env.DATABASE_URL
-if (!connectionString) throw new Error("DATABASE_URL is required")
-
-const database = mysql({
-  connectionString,
-  maximumConnections: 10,
-})
-```
-
-MySQL uses InnoDB tables, 64-bit database timestamps and sequences, row-locked
-sequence allocation, and bounded retries around the side-effect-free enqueue
-transaction when InnoDB selects it as a deadlock victim. Use the Redis wake-up
-adapter when a MySQL deployment wants cross-process notification latency;
-durable polling remains sufficient for correctness.
-
-Authorization is deny-by-default. Actor IDs identify actors; they are not
-capabilities.
-
-`runtime.run()` supervises every built-in role and registered component. An
-unexpected exit is cleaned up and rebuilt through its original factory with
-capped exponential backoff. Shutdown stops replacement before asking the live
-instances to finish, so no replacement can outlive the runtime. The shared
-shutdown budget defaults to 15 seconds and can be changed with
-`shutdownTimeoutMilliseconds`. Components and actor operations must cooperate
-with cancellation where they receive an `AbortSignal`; actor operations and
-other JavaScript code already running cannot be forcibly terminated.
-
-The default in-process wake-up adapter interrupts role polling as soon as this
-runtime commits new work. Polling remains the correctness fallback, so a missed
-or failed signal costs latency rather than losing work. Multi-process hosts not
-using PostgreSQL notifications can provide a `WakeUpAdapter` backed by their
-existing notification system without adding a required broker to the default
-SQLite stack.
-
-Applications that already operate Redis can use its optional Pub/Sub adapter:
-
-```bash
-pnpm add redis
-```
-
-```typescript
-import { redisWakeUp } from "solid-objects/wake-up/redis"
-
-const runtime = configure({
-  database,
-  wakeUp: redisWakeUp({ url: process.env.REDIS_URL ?? "redis://127.0.0.1:6379" }),
-})
-```
-
-The adapter lazily opens separate publisher and subscriber connections because
-a subscribed Redis client cannot issue ordinary commands. Role-specific
-channels wake every matching waiter in the process. Redis Pub/Sub is transient;
-the relational database remains durable truth and bounded polling covers a
-missed notification or unavailable Redis server.
-
-## Call it like a local object
-
-`await` is the committed call boundary.
-
-```typescript
-const counter = Counter.ref("primary")
-
-const count = await counter.increment({ amount: 2 })
-const doubled = await counter.doubled
-```
-
-The method call is still a durable database operation: it enters the actor's
-mailbox, waits its turn, and resolves with the committed, deeply frozen result.
-If the enqueue transaction commits, a later wait timeout does not cancel the
-durable message. If enqueue itself cannot commit within the timeout,
-`SyncEnqueueTimeout` is raised and no message exists to recover.
-
-Use `with()` when invocation behavior needs configuration:
+npm exec --yes --package=solid-objects@0.13.0 -- solid-objects quickstart
+```
+
+The command needs no repository checkout, database server, Redis, container, or
+application configuration. It uses Node's built-in SQLite module and removes
+its scoped temporary database before exiting.
+
+The executable asserts rather than merely printing a plausible result. In one
+local run, it verifies that:
+
+- 25 concurrent calls to one identity produce the exact committed state `25`;
+- their return values are the complete sequence from `1` through `25`;
+- operations for two different identities overlap in time; and
+- the runtime closes and temporary state is removed.
+
+## What Solid Objects is for
+
+Use Solid Objects when more than one request, job, or process can act on the
+same logical thing and the next action must use its latest committed state.
+These are the stateful coordination patterns for which people often reach for
+Durable Objects:
+
+| Pattern                                 | One identity per              | What the object coordinates                                                                 |
+| --------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------- |
+| Multiplayer, presence, or collaboration | Room, session, or document    | Joins, moves, and edits commit in order; subscribers refresh from committed state           |
+| Reservations and expiring holds         | Show, resource, or stock item | Availability checks and holds cannot interleave; a durable reminder can release an old hold |
+| Checkout and account workflows          | Cart, order, account, device  | The current step, retries, and effect results return to the same ordered mailbox            |
+| Per-key rate limits                     | API key, account, or device   | Token checks and decrements are serialized; a reminder can refill the bucket                |
+| Stateful agent sessions                 | Agent session                 | Messages and tool results apply in order and pending work survives a worker exit            |
+
+The common shape is one durable coordination boundary with an application
+defined identity. Work for that identity is serialized, while unrelated rooms,
+carts, accounts, or sessions can progress concurrently. A single global rate
+limiter or another very hot identity is a poor fit because it becomes an
+intentional bottleneck. If one ordinary row transaction solves the problem,
+prefer that. See [Choosing Solid Objects](docs/fit.md) for the longer guide.
+
+## How it works
+
+An object is addressed by its TypeScript class and application-defined ID.
+Public fields are JSON state, public methods are durable operations, and public
+getters are ordered queries.
+
+For each identity, Solid Objects:
+
+1. commits calls to a durable per-ID mailbox;
+2. claims one activation with a renewable lease;
+3. executes one operation at a time outside the database transaction;
+4. commits state, completion, and staged work in a short fenced transaction;
+5. retries recoverable failures and exposes terminal failures as dead letters;
+6. publishes committed realtime invalidations in revision order.
+
+The fence includes the activation owner, token, generation, expiration, and
+claimed message. A worker that finishes JavaScript after losing its lease
+cannot commit. See the executable [failure-recovery demonstration](examples/failure-recovery/demo.ts)
+and the full [architecture](docs/architecture.md).
+
+Redis is optional wake-up infrastructure. It can reduce notification latency
+for a multi-process MySQL deployment, but the relational database remains the
+durable source of truth and polling remains the recovery path.
+
+## Good and poor fits
+
+| Good fit                                                  | Poor fit                                                  |
+| --------------------------------------------------------- | --------------------------------------------------------- |
+| Multiplayer rooms and collaborative sessions              | A single-row update already solved by one SQL transaction |
+| Shopping carts, accounts, devices, and per-user workflows | Bulk ingestion and data-parallel pipelines                |
+| Stateful agent sessions with ordered tool results         | Very high-throughput global counters                      |
+| Per-document or per-device reminders                      | Large JSON documents that should remain normalized rows   |
+| Realtime projections of committed state                   | Globally placed edge state or managed elastic placement   |
+
+One hot identity is intentionally serialized. Split an identity only when the
+domain can tolerate independent ordering and transactions. Solid Objects does
+not provide a transaction across object identities.
+
+The longer decision guide is in [Choosing Solid Objects](docs/fit.md).
+
+## Delivery boundaries
+
+- Operations are ordered per identity and execute **at least once**.
+- A crash after arbitrary external I/O but before the database commit can cause
+  that I/O to repeat. Use the stable effect ID or another durable idempotency
+  key at the external system.
+- Fencing protects the Solid Objects database commit. It cannot undo an HTTP
+  request, email, payment, file write, or other external side effect.
+- Different identities can execute concurrently; one hot identity cannot.
+- State, result, actor-to-actor delivery, reminders, effects, commit actions,
+  and realtime invalidations commit together for one operation.
+- Cross-object transactions are not provided.
+- Application processes with incompatible `stateVersion` values must not run
+  together. Older code rejects state written by a newer version.
+- Direct application-database writes are guarded only when the application
+  uses the supplied database facade. Unwrapped clients cannot be intercepted.
+- Realtime sessions are process-local. A multi-process application must bridge
+  committed broadcast events to the processes holding live connections.
+
+See [Correctness and delivery semantics](docs/correctness.md) and
+[Errors and recovery](docs/errors-and-recovery.md) for the complete contract.
+
+## Realtime committed state
+
+Actors opt into browser-visible dependencies. In `0.13`, an unwrapped
+observable triggers invalidation without storing or sending its value. Use
+`broadcastValue()` only for a scalar that every authorized subscriber may see:
 
 ```typescript
-await counter
-  .with({
-    authorizationContext: currentUser,
-    timeoutMilliseconds: 2_000,
-    idempotencyKey: "increment-123",
-  })
-  .increment({ amount: 2 })
-```
-
-Invocation options stay separate from actor arguments, so an actor may safely
-use argument names such as `timeoutMilliseconds` or `authorizationContext`.
-Every invocation receives a generated `requestId`; `idempotencyKey` remains the
-caller's deduplication key and is never reused as request identity. During an
-operation, `this.currentMessage` exposes both values along with `id`,
-`enqueuedAt`, `actorType`, `actorId`, `sequence`, and `attempt`.
+import { Actor, broadcastValue } from "solid-objects"
 
-Use `this.reject()` for an expected domain refusal that should roll back the
-turn without retrying or blocking later mailbox work:
-
-```typescript
-class Reservation extends Actor {
-  static override readonly actorType = "Reservation"
+class Room extends Actor {
+  static override readonly actorType = "Room"
 
-  available = 0
+  version = 0
+  privateHands: Record<string, string[]> = {}
 
-  reserve({ quantity }: { quantity: number }): void {
-    if (quantity > this.available) {
-      this.reject("insufficientInventory", {
-        message: "Not enough inventory is available",
-        details: { available: this.available },
-      })
+  override observables(): Record<string, unknown> {
+    return {
+      version: broadcastValue(this.version),
+      hands: this.privateHands,
     }
-    this.available -= quantity
   }
 }
 ```
 
-Callers receive `Rejected` with `code`, frozen `details`, and the durable
-`messageId`. Unexpected exceptions are retried and eventually surface as
-`MessageFailed`. Rejection codes follow the same identifier rule as actor
-members: a letter or underscore followed by letters, digits, or underscores.
-
-Do not make a committed actor call or wait on a message from inside
-`database.transaction(...)` on the Solid Objects database. The runtime raises
-`SyncInsideTransaction` before enqueue or waiting, avoiding a self-deadlock on
-the transaction's checked-out connection. Send background work outside the
-transaction, or let the actor coordinate same-database changes through a commit
-action.
-
-## Read snapshots and destroy actors
-
-An authorized snapshot reads all persisted fields and getters from one
-committed state image without entering the mailbox:
+`version` crosses the shared invalidation channel. `hands` contributes only its
+name when its real value changes, allowing a reauthorized component endpoint to
+render subscriber-specific state without a manual revision counter.
 
-```typescript
-const snapshot = await Counter.ref("primary").snapshot({
-  authorizationContext: currentUser,
-})
-
-console.log(snapshot.count, snapshot.doubled)
-```
+The browser package handles replay, reconnection, incarnation/revision fences,
+personalized payloads, and framework-neutral component refresh. Applications
+provide authentication, WebSocket transport, and rendering. See the
+[browser protocol](docs/browser-protocol.md) and [authorization guide](docs/authorization.md).
 
-Snapshots are deeply frozen. Getters must not mutate state or stage durable
-work. Because snapshots do not enter the mailbox, use an ordinary query when
-the read must be ordered behind earlier messages.
+## Comparison
 
-Destroy an actor through its separate deny-by-default policy:
+These systems solve different coordination problems. The table describes their
+default unit and deployment model, not a quality ranking.
 
-```typescript
-const destroyed = await Counter.ref("primary").destroy({
-  authorizationContext: currentUser,
-})
-```
-
-Destruction is idempotent and cascades through the current incarnation's
-state, mailbox history, effects, reminders, broadcasts, and dead letters. A
-later message creates a new incarnation, and an authorized waiter on the old
-one receives `ActorDestroyed`.
-
-## Send background work without a queue service
-
-Use the typed `send` dispatcher when the caller should not wait for execution:
-
-```typescript
-const message = await counter.send.increment({ amount: 2 })
-
-const delayed = await counter.send
-  .with({
-    availableAt: new Date(Date.now() + 60_000),
-    idempotencyKey: "increment-later",
-    authorizationContext: currentUser,
-  })
-  .increment({ amount: 2 })
-
-await message.status()
-await message.result()
-await message.wait({ timeoutMilliseconds: 2_000 })
-```
+| Approach                    | Serialization and state unit                          | Durable substrate                     | Additional runtime                                      | Recovery model                                 | Placement                    |
+| --------------------------- | ----------------------------------------------------- | ------------------------------------- | ------------------------------------------------------- | ---------------------------------------------- | ---------------------------- |
+| SQL transaction or row lock | Selected rows in one transaction                      | Application database                  | None                                                    | Application retries the transaction            | Application deployment       |
+| Traditional job queue       | Job or queue; ordering depends on queue configuration | Broker or queue database              | Queue workers and usually a broker                      | Retry the job                                  | Application deployment       |
+| Solid Objects               | TypeScript class plus object ID                       | Existing SQLite, PostgreSQL, or MySQL | Library in application processes                        | Retry the per-ID operation from durable state  | Application deployment       |
+| Cloudflare Durable Objects  | Object class plus globally unique ID                  | Per-object managed storage            | Cloudflare Workers platform                             | Managed object activation                      | Cloudflare-selected location |
+| Rivet Actors                | Addressable actor                                     | Actor state, KV, or per-actor SQLite  | Rivet Engine or managed compute                         | Actor sleep, wake, and persistence             | Configured Rivet deployment  |
+| DBOS                        | Workflow ID and checkpointed steps                    | PostgreSQL system database            | Library; Conductor recommended for distributed recovery | Deterministic workflow replay from checkpoints | Application deployment       |
+| Restate                     | Service handler or keyed virtual object               | Restate log and state store           | Restate server or cloud service                         | Durable handler execution and journal replay   | Restate deployment           |
 
-`MessageReference` stores durable identity, not authorization context. Pass
-`authorizationContext` again to `status()`, `result()`, or `wait()`; every read
-reauthorizes the stored operation. Operations that return `undefined`,
-including ordinary `void` methods, are normalized to JSON `null` when their
-durable result is read or awaited.
+The sourced, dimension-by-dimension comparison—including realtime projections,
+edge placement, cross-identity transactions, and operational data access—is in
+[docs/comparisons.md](docs/comparisons.md).
 
-Actor code must not call another reference directly or through `send`. Use
-`sendTo()` so outbound delivery commits atomically with the source actor turn—no
-separate broker or hand-built transactional outbox required:
+## Requirements and supported systems
 
-```typescript
-class Account extends Actor {
-  static override readonly actorType = "Account"
-
-  disable({ auditLogId }: { auditLogId: string }): void {
-    this.sendTo(AuditLog.ref(auditLogId)).record({
-      eventName: "account_disabled",
-    })
-  }
-}
-```
-
-If `disable` fails or is rejected, the staged audit message is discarded.
-
-## Use database-backed timers
-
-Reminders are actor-owned durable alarms. The operation name is also the
-reminder identity, so scheduling it again moves the existing reminder.
-
-```typescript
-class Trial extends Actor {
-  static override readonly actorType = "Trial"
-
-  expired = false
-
-  armExpiration(): void {
-    this.schedule({ at: new Date(Date.now() + 86_400_000) }).expire!()
-  }
-
-  reconcile(): void {
-    if (!this.expired) this.armExpiration()
-  }
-
-  expire(): void {
-    this.expired = true
-  }
-}
-```
-
-The non-null assertion is only needed by projects using
-`noUncheckedIndexedAccess`; runtime registration still rejects unknown reminder
-operations before persistence. Recurring reminders accept `everyMilliseconds`
-and a `missed` policy of `"latest"` or `"all"`.
-
-Authorized operators can inspect alarm metadata and resume a reminder that was
-paused after a scheduler error:
-
-```typescript
-const paused = await runtime.reminders.all({
-  status: "paused",
-  authorizationContext: currentUser,
-})
-
-const reminder = paused.items[0]
-if (reminder) {
-  await runtime.reminders.resume(reminder.id, {
-    runAt: new Date(Date.now() + 60_000),
-    authorizationContext: currentUser,
-  })
-}
-```
-
-Inspection omits reminder arguments and error messages. Resume is idempotent;
-completed reminders must be scheduled again by their owning actor.
-
-## Keep external I/O outside the transaction
-
-Effects run outside the actor turn through a transactional outbox. Handlers
-must deduplicate external work using `context.id` because delivery is at least
-once.
-
-```typescript
-class Checkout extends Actor {
-  static override readonly actorType = "Checkout"
-
-  status = "open"
-
-  checkout({ paymentId }: { paymentId: string }): void {
-    this.status = "pending"
-    this.emit("chargePayment", {
-      arguments: { paymentId },
-      onSuccess: "paymentSucceeded",
-      onFailure: "paymentFailed",
-    })
-  }
-
-  paymentSucceeded(options: {
-    arguments: { paymentId: string }
-    result: { receiptId: string }
-  }): void {
-    this.status = "paid"
-  }
-
-  paymentFailed(options: { arguments: { paymentId: string }; error: JsonObject }): void {
-    this.status = "failed"
-  }
-}
-
-runtime.registerEffect("chargePayment", async ({ paymentId }, context) => {
-  return payments.charge({ paymentId, idempotencyKey: context.id })
-})
-```
-
-Effect context also exposes `attempt`, `sourceMessageId`, `actorType`, and
-`actorId`. The effect `id` is stable across retries and remains the external
-idempotency key.
-
-Success callbacks receive `{ effectId, arguments, result }`. Failure callbacks
-receive `{ effectId, arguments, error }`. The JSON `arguments` are the
-values originally staged by `emit()`, so actors can correlate concurrent
-effects without coupling the external handler to actor state.
-
-## Commit actions
-
-Commit actions make a short database-only write in the same fenced transaction
-as actor state:
-
-```typescript
-runtime.registerCommitAction("completeAttempt", async ({ attemptId }, context) => {
-  await context.connection.run("UPDATE attempts SET completed = 1 WHERE id = ?", [attemptId])
-})
-```
-
-Database row generics are assertions, not runtime conversions. In particular,
-SQLite integer columns are returned as `bigint`; type rows accordingly or
-convert deliberately. See the [adapter value mapping](docs/configuration.md#database-value-mapping).
-
-Commit-action context includes the source message and request IDs, actor
-identity, mailbox sequence, activation generation, and the active transaction
-connection.
-
-Do not perform network I/O in a commit action. Use an effect when work cannot
-share the Solid Objects database transaction.
-
-When actors also read an application database, wrap that database with the
-guarded facade and use the same facade everywhere:
-
-```typescript
-import { guardApplicationDatabase } from "solid-objects"
-import { sqlite } from "solid-objects/database/sqlite"
-
-const applicationDatabase = guardApplicationDatabase(sqlite({ path: "application.sqlite3" }))
-```
-
-During actor execution, observable and payload projection, and state migration,
-the facade permits `SELECT` through `get()` and `all()` and rejects `run()` or
-row-returning write statements. A commit action stays inside the same read-only
-context and writes only through its supplied fenced `context.connection`. This
-boundary is opt-in: Solid Objects cannot intercept a separate ORM pool or an
-unwrapped database client.
-
-## Inspect and retry terminal failures
-
-A committed invocation that exhausts its attempts raises `MessageFailed`.
-The exception carries the durable `messageId` and the persisted error record in
-`details`, so callers can correlate the failure without parsing its message.
-If an already-authorized actor is destroyed while a caller is waiting,
-`ActorDestroyed` is raised instead.
-
-Messages that exhaust their attempts remain available as dead letters. Access
-is deny-by-default and goes through the administration policy:
-
-```typescript
-const deadLetters = await runtime.deadLetters.all({
-  authorizationContext: currentUser,
-})
-
-const deadLetter = deadLetters[0]
-if (deadLetter) {
-  await runtime.deadLetters.retry(deadLetter.id, {
-    authorizationContext: currentUser,
-  })
-}
-```
-
-Retry creates one durable replacement message and records that link. Repeating
-the retry returns the same `MessageReference` instead of enqueueing duplicate
-work.
-
-## Reconcile application-owned actors
-
-Self-scheduling actors should have a low-frequency application reconciler for
-lost alarms and lifecycle drift. The read side is bounded, immutable, and
-administration-authorized:
-
-```typescript
-const page = await runtime.reconciliation.withoutPendingWork({
-  actorType: Trial.actorType,
-  quietForMilliseconds: 24 * 60 * 60 * 1_000,
-  authorizationContext: currentUser,
-})
-
-for (const instance of page.items) {
-  await Trial.ref(instance.actorId).send.reconcile()
-}
-```
-
-`active()`, `statesFor()`, and `orphaned()` cover the other reconciliation
-views. State batches are migrated to the registered actor's current version
-before they are returned. Reconciliation never writes actor state directly;
-repairs enter the ordinary durable mailbox.
-
-## Retain history deliberately
-
-Message history defaults to 30 days, stopped process history to 7 days, and
-actor instances never expire unless their actor type opts in:
-
-```typescript
-const runtime = configure({
-  database,
-  messageRetentionMilliseconds: 30 * 24 * 60 * 60 * 1_000,
-  messageRetentionByActorType: {
-    [AuditEvent.actorType]: 365 * 24 * 60 * 60 * 1_000,
-  },
-  instanceRetentionByActorType: {
-    [EphemeralSession.actorType]: 7 * 24 * 60 * 60 * 1_000,
-  },
-})
-```
-
-Preview each resource before pruning it:
-
-```typescript
-const preview = await runtime.retention.preview({
-  target: "messages",
-  authorizationContext: currentUser,
-})
-
-const pruned = await runtime.retention.prune({
-  target: "messages",
-  authorizationContext: currentUser,
-})
-```
-
-`preview.count` is the number of rows currently eligible; `pruned.count` is the
-number actually deleted after candidates are rechecked.
-
-Pruning rechecks every candidate in bounded transactions. Live mailbox work,
-unfinished outboxes, scheduled reminders, dead letters, retry links, active
-leases, and running processes are retained.
-
-## Verify an installation
-
-The doctor returns a structured report for startup checks, deployment probes,
-or an application-owned CLI:
-
-```typescript
-const report = await runtime.doctor.run()
-
-for (const check of report.checks) {
-  console.log(check.status, check.name, check.message)
-}
-
-if (!report.healthy) process.exitCode = 1
-```
-
-It checks configuration, schema migrations and required columns, the database
-server version and MySQL table engines, authorization-policy configuration and
-neutral-context posture, live runtime roles, and a targeted durable actor round
-trip. Pass `{ roundTrip: "skip" }` for a read-only report.
-
-Inspect role liveness with `runtime.processes.all()`. Each record exposes
-`shutdownState` (`"running"`, `"draining"`, or `"stopped"`) plus a current
-`stale` calculation based on the configured heartbeat threshold, hostname,
-host process ID, Node version, and Solid Objects version.
-`runtime.processes.cleanup()` atomically marks stale owners stopped, releases
-their actor activations, returns claimed messages to ready membership, and
-releases their effect, reminder, and broadcast claims.
-
-For application-owned long-running roles, call `runtime.registerComponent()`
-before `run()`. Each factory-created component implements `run(signal)`,
-`requestShutdown()`, `stopped()`, and `stop()`. The runtime supervises and
-replaces failed components just like built-in roles. See
-[`docs/api.md`](docs/api.md#runtime-extensions-and-manual-workers) for the full
-contract.
-
-## Operate it from the command line
-
-Export the configured runtime from an application module:
-
-```javascript
-import { configure } from "solid-objects"
-import { sqlite } from "solid-objects/database/sqlite"
-import { Counter } from "./dist/counter.js"
-
-const runtime = configure({
-  database: sqlite({ path: "storage/solid-objects.sqlite3" }),
-  authorizeAdministration: ({ authorizationContext }) => authorizationContext?.source === "cli",
-})
-
-runtime.register(Counter)
-export default runtime
-```
-
-The CLI loads `solid-objects.config.js` by default; use `--config` for another
-compiled module:
-
-```bash
-pnpm exec solid-objects start
-pnpm exec solid-objects doctor
-pnpm exec solid-objects status
-pnpm exec solid-objects cleanup
-pnpm exec solid-objects dead-letters
-pnpm exec solid-objects retry-dead-letter DEAD_LETTER_ID
-pnpm exec solid-objects reminders --status paused
-pnpm exec solid-objects resume-reminder REMINDER_ID
-pnpm exec solid-objects prune messages
-pnpm exec solid-objects prune messages --execute
-```
-
-Pruning is preview-only unless `--execute` is present. Administrative commands
-use `{ source: "cli" }` as their authorization context and emit JSON for shell
-automation.
-
-Every command accepts `--config PATH` or `-c PATH`. `doctor` accepts
-`--skip-round-trip`; `reminders` accepts `--actor-type TYPE` and `--status
-scheduled|paused|completed`; `resume-reminder` accepts an ISO `--run-at DATE`;
-and `prune` accepts `--execute`. Run `solid-objects --help` for the command
-summary.
-
-## Test durable workflows without sleeps
-
-`runtime.testing.drain()` runs configured roles in deterministic passes until
-they are idle. It does not advance reminder schedules or effect retry backoff;
-retryable effects rescheduled into the future remain pending. Throw
-`NonRetryableError` in a test handler when the scenario is terminal failure.
-Select roles when a test needs a narrower boundary:
-
-```typescript
-const message = await Counter.ref("test").send.increment()
-
-await runtime.testing.drain({ roles: ["actors"] })
-
-expect(await message.status()).toBe("completed")
-```
-
-Run reminders against an explicit future instant without changing their stored
-schedules or sleeping:
-
-```typescript
-await runtime.testing.runDueReminders({ now: fiveMinutesFromNow })
-await runtime.testing.drain({ roles: ["actors"] })
-```
-
-`runtime.testing.reset()` stops and discards the cached caller worker, then
-deletes every actor-owned table and process row in dependency order. Use it in
-test setup and teardown; it does not rely on transactional tests or foreign-key
-cascades.
-
-## Connect observability without coupling the runtime
-
-Provide a synchronous instrumentation sink and forward events to the
-observability system already used by the application:
-
-```typescript
-const runtime = configure({
-  database,
-  instrumentation: (event) => diagnosticsChannel.publish(event),
-})
-```
-
-Events use names such as `solid_objects.message.enqueued`,
-`solid_objects.message.completed`, `solid_objects.effect.failed`,
-`solid_objects.dead_letter.created`, and `solid_objects.actor.destroyed`.
-Records are immutable and contain operational metadata only. Arguments, actor
-state, results, rejection messages and details, error messages, and broadcast
-payloads never enter the instrumentation API. A sink failure is logged and
-cannot fail durable work.
-
-Moving an existing alarm to another time emits
-`solid_objects.reminder.replaced` only after the actor turn commits. The event
-contains the actor identity, operation, reminder ID, and previous and next run
-times without reminder arguments.
-
-## Add realtime updates without exposing all state
-
-Connect an authenticated socket to the transport-neutral subscription manager.
-The application owns the WebSocket server and decides what object represents
-the authenticated connection:
-
-```typescript
-server.on("connection", (socket, request) => {
-  const session = runtime.realtime.connect({
-    authorizationContext: request.user,
-    send: (envelope) => socket.send(JSON.stringify(envelope)),
-  })
-
-  socket.on("message", (data) => {
-    session.receive(data).catch(() => socket.close(1008, "subscription rejected"))
-  })
-  socket.on("close", () => session.close())
-})
-```
-
-Every subscribe request calls `authorizeSubscription` before actor lookup. An
-accepted subscription immediately receives the latest committed observable
-projection with its actor incarnation and revision, without adding a mailbox
-message. Later invalidations come from the durable outbox in actor revision
-order. Duplicate and stale revisions are fenced, and one broken connection
-cannot interrupt delivery to another.
-
-Invalidation envelopes contain the actual `observables()` values and deliver
-the same projection to every authorized subscriber. Never put credentials,
-session identifiers, private cards, or other subscriber-specific data there;
-use a typed payload projection or a reauthorized component endpoint instead.
-
-Direct session delivery is process-local. When WebSocket connections and
-workers run in several Node processes, configure `broadcast` to publish each
-durable event through the application's shared transport, and have every
-process feed received events to `runtime.realtime.publish(event)`. Polling and
-the durable outbox remain the correctness fallback; the shared transport fans
-a committed event out to the processes that own live connections.
-
-The browser entry contains no Node imports. It validates versioned invalidation
-envelopes, tracks actor incarnations and revisions, and ignores stale delivery:
-
-```typescript
-import { SolidObjectsBrowserClient } from "solid-objects/browser"
-
-const client = new SolidObjectsBrowserClient({
-  url: new URL("/solid-objects", window.location.href),
-  onInvalidation: ({ observables }) => render(observables),
-})
-
-client.subscribe({ actorType: "Counter", actorId: "primary" })
-client.connect()
-```
-
-For server-rendered or framework-owned UI fragments, register their observable
-dependencies and let one invalidation refresh only the affected targets:
-
-```typescript
-import { SolidObjectsBrowserClient, SolidObjectsComponentRegistry } from "solid-objects/browser"
-
-const componentRegistry = new SolidObjectsComponentRegistry<string>({
-  refresh: async ({ actorType, actorId, instanceId, revision, batch, components, signal }) => {
-    const response = await fetch("/components/refresh", {
-      method: "POST",
-      signal,
-      headers: { "content-type": "application/json" },
-      body: JSON.stringify({ actorType, actorId, instanceId, revision, batch, components }),
-    })
-    if (!response.ok) throw new Error(`component refresh failed with ${response.status}`)
-    return response.json()
-  },
-  apply: ({ component, rendered }) => {
-    updateComponent(component.target, rendered, { strategy: component.strategy })
-  },
-})
-
-componentRegistry.register({
-  actorType: "GameRoom",
-  actorId: "table-1",
-  target: "player-one",
-  name: "player",
-  key: 1,
-  observes: ["playerOne"],
-  batch: "playmat",
-  strategy: "morph",
-})
-
-const client = new SolidObjectsBrowserClient({
-  url: new URL("/solid-objects", window.location.href),
-  onInvalidation: (envelope) => componentRegistry.invalidate(envelope),
-})
-```
-
-Registrations sharing a batch are refreshed in one request. Same-revision
-invalidations merge in a microtask, a strictly newer request aborts the older
-one, and per-target incarnation/revision fences prevent a late response from
-overwriting current UI. `replace` and `morph` are strategies passed to the
-application's synchronous `apply` callback; the library does not assume a DOM
-framework. The refresh endpoint must authenticate the request and reauthorize
-every requested component and dependency.
-
-Run `pnpm run test:browser` after installing Playwright's Chromium build to
-exercise the browser entry through native WebSocket and browser APIs.
-
-For subscriber-specific views, declare a static payload map with a TypeScript
-`satisfies` check:
-
-```typescript
-import { Actor, type PayloadBroadcasts } from "solid-objects"
-
-type Viewer = {
-  accountId: string
-}
-
-class GameRoom extends Actor {
-  static override readonly actorType = "GameRoom"
-  static override readonly payloads = {
-    playmat: (room, viewer) => ({
-      turn: room.turn,
-      hand: room.hands[viewer.accountId] ?? [],
-    }),
-  } satisfies PayloadBroadcasts<GameRoom, Viewer>
-
-  turn = 1
-  hands: Record<string, string[]> = {}
-}
-```
-
-Declare named payload return shapes with `type`, not `interface`.
-`PayloadBroadcastValue` is a JSON object or array, and TypeScript interfaces do
-not implicitly provide the JSON object's string index signature.
-
-Request payloads by name and render them separately from observable
-invalidations:
-
-```typescript
-const client = new SolidObjectsBrowserClient({
-  url: new URL("/solid-objects", window.location.href),
-  onInvalidation: ({ observables }) => renderScalars(observables),
-  onPayload: ({ name, payload }) => renderPayload(name, payload),
-})
-
-client.subscribe({
-  actorType: "GameRoom",
-  actorId: "primary",
-  payloads: ["playmat"],
-})
-```
-
-Each payload runs against committed state and the subscribing session's fresh
-authorization context. `authorizeQuery` is called with the payload name before
-projection. A denied or failing payload is omitted without stopping sibling
-payloads or observable invalidations.
-
-`broadcast` remains available when an application also needs to forward the
-same durable events through another transport or broker. Browser-visible actor
-IDs and observable values are not authorization.
-
-## Delivery contract
-
-- Messages are ordered per actor identity and delivered at least once.
-- Different actor identities may execute concurrently.
-- A worker drains at most `maxMessagesPerActivationPass` turns from one actor,
-  then yields its still-due work behind actors that were already waiting.
-- A global claim scans at most `claimScanLimit` ordered candidates, continuing
-  to another ready actor after a lost lease race.
-- Long-running workers reuse hydrated actors for
-  `idleDeactivationTimeoutMilliseconds` while renewing the same fenced lease.
-- State, completion, staged messages, effects, reminders, commit actions, and
-  observable broadcasts share one fenced commit.
-- A lost or expired activation lease cannot commit.
-- Failed turns roll state and staged intents back and block later work until
-  retry or dead-letter completion.
-- Effects can execute more than once.
-- Results and snapshots are deeply frozen copies. A snapshot contains every
-  persisted field and getter from one committed state image; snapshot getters
-  must not mutate state or stage durable work.
-
-Override protected `onActivate()` and `onDeactivate()` methods when an actor
-needs a process-local resource during that window. Hooks may be asynchronous,
-cannot write through a guarded application database, and are nondurable;
-`onDeactivate()` is best effort and must not carry correctness work.
-
-## Current scope
-
-The current runtime supports Node.js 24, SQLite through built-in `node:sqlite`,
-PostgreSQL 14 or newer through `pg` 8.23, and MySQL 8.0 or newer through
-`mysql2` 3.23 with InnoDB. HTTP/WebSocket server adapters and Ruby schema
-interoperability are not part of the compatibility contract.
+- Node.js 24.15 or newer
+- TypeScript 5.9 or newer for TypeScript applications
+- SQLite through `node:sqlite`, PostgreSQL 14 or newer, or MySQL 8.0 or newer
+  with InnoDB
+- optional `pg`, `mysql2`, or `redis` peer dependency only for the selected
+  adapter
+
+The exact CI matrix and boundaries are documented in
+[Supported versions](docs/support.md).
+
+## Operations
+
+`runtime.run(signal)` supervises actor, effect, reminder, broadcast, retention,
+and stale-process recovery roles. The database-backed operator dashboard is an
+optional `solid-objects/web` export with deny-by-default administration policy,
+session-backed CSRF protection, and Fetch or Node/Connect mounting.
+
+The dashboard defaults to authorized read/write access. An authorized
+read-only mode removes mutations, while an explicitly public read-only mode is
+appropriate only for synthetic demo data because it exposes stored arguments,
+results, errors, identifiers, and operational metadata.
+
+Administration remains available through the JSON CLI and typed runtime
+managers. See [Operations](docs/operations.md), the [dashboard guide](docs/dashboard.md),
+and [Configuration](docs/configuration.md).
+
+## Design provenance
+
+Solid Objects JS is a Node.js and TypeScript implementation informed by the
+Ruby [`solid_objects`](https://github.com/cardmagic/solid_objects) design. It
+began at the `0.12` capability generation because the initial implementation
+targeted the Ruby `0.12` contract; the number does not represent twelve earlier
+JavaScript release generations.
+
+The TypeScript implementation is not a source translation. It redesigned the
+API around inferred TypeScript references, Node runtime supervision,
+`node:sqlite`/`pg`/`mysql2` adapters, transport-neutral realtime sessions,
+Web Components, and browser-safe package exports. The
+[parity ledger](docs/parity.md) records capability relationships and deliberate
+runtime differences.
+
+The Ruby project first appeared publicly on August 6, 2026, and this TypeScript
+repository on August 13, 2026. Both remain early releases. The
+[`mtg-playmat`](https://github.com/cardmagic/mtg-playmat) application uses the
+Ruby actor and realtime design as current dogfood; that is not evidence of a
+TypeScript deployment.
 
 ## Documentation
 
-- [`docs/state-and-lifecycle.md`](docs/state-and-lifecycle.md) covers actor
-  discovery, migrations, lifecycle hooks, rejection, snapshots, and
-  destruction.
-- [`docs/configuration.md`](docs/configuration.md) lists every runtime and
-  adapter option with its default and constraint.
-- [`docs/errors-and-recovery.md`](docs/errors-and-recovery.md) maps public
-  errors to retry and recovery behavior.
-- [`docs/api.md`](docs/api.md) indexes every supported public export and runtime
-  manager.
-- [`docs/operations.md`](docs/operations.md),
-  [`docs/architecture.md`](docs/architecture.md), and
-  [`docs/correctness.md`](docs/correctness.md) define the operating and delivery
-  contracts.
-- [`docs/authorization.md`](docs/authorization.md) and
-  [`docs/browser-protocol.md`](docs/browser-protocol.md) cover security and the
-  transport-neutral realtime protocol.
-- The [`Ruby parity ledger`](docs/parity.md) tracks native equivalents and
-  explicit scope boundaries against Ruby Solid Objects 0.12.0.
-- [`docs/releasing.md`](docs/releasing.md) documents the tag-driven npm release
-  workflow for maintainers.
+- [Getting the architecture right](docs/architecture.md)
+- [Correctness and delivery semantics](docs/correctness.md)
+- [Choosing Solid Objects](docs/fit.md)
+- [Benchmarks and methodology](docs/benchmarks.md)
+- [Supported versions and test matrix](docs/support.md)
+- [Public API](docs/api.md)
+- [State and lifecycle](docs/state-and-lifecycle.md)
+- [Operations](docs/operations.md)
+- [Configuration](docs/configuration.md)
+- [Authorization](docs/authorization.md)
+- [Browser protocol](docs/browser-protocol.md)
+- [Operator dashboard](docs/dashboard.md)
+- [Errors and recovery](docs/errors-and-recovery.md)
+- [Design parity](docs/parity.md)
+- [Contributing](CONTRIBUTING.md)
+- [Security policy](SECURITY.md)
 
 ## License
 
-Solid Objects is released under the MIT License.
+Solid Objects is released under the [MIT License](MIT-LICENSE).