solid-objects 0.14.3 → 0.14.4

package/README.md

@@ -1,95 +1,92 @@
-# Solid Objects JS
+# Solid Objects for Node and Your Browser
 
 [![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)
 
-Open Source Durable Objects for JavaScript, in the SQL database you already run.
-No daemon, no broker, and no new datastore.
-
-Build addressable TypeScript objects with serialized calls and durable state on
-SQLite, PostgreSQL, or MySQL. You don't need Cloudflare for this.
-
-Concurrent calls for one identity cannot overwrite each other. Calls for
-different identities can run at the same time.
-
-Define ordinary TypeScript classes and run them in ordinary Node.js processes.
-Solid Objects keeps the state, the queued operations, the retries, the
-reminders, the effects, and the realtime invalidations in the database the
-application already operates.
-
-The same runtime also runs inside a browser worker on SQLite WASM, with
-durable actor state in the origin's private file system, and its offline
-writes can replay onto a Node **or Rails** backend over one shared wire
-contract. See [Solid Objects in the browser](#solid-objects-in-the-browser).
-
-> **Early release:** the correctness core has automated coverage. That coverage
-> includes the supported databases, the Chromium browser client, the browser
-> runtime, process recovery, and the packaged artifacts. The TypeScript
-> implementation is still new. There is one deployed first-party reference
-> application. There is no measured scale and no third-party production use
-> yet. Read the
-> [delivery boundaries](#delivery-boundaries) before you use it for important
-> data.
-
-> **Not a replacement for SQL transactions:** when one row update inside one
-> transaction solves the problem, use that and install nothing. Solid Objects
-> earns its cost when the critical section outlives the transaction: a hold that
-> expires in ten minutes, work that must survive a restart, or a fan-in that
-> spans many jobs. See
-> [Why not just use transactions?](#why-not-just-use-transactions).
+**Open Source Durable Objects in your Node app.**
+
+In a shopping cart, paying twice at the same time is a big problem. The payment provider might time out, and your Node site could be restarting before recovery finishes.
+
+To deal with this safely, you often need logic scattered between 7-10 files like database row locks, Redis locks, delayed jobs, retries, and cleanup code to keep that process straight. They are not all large, but they must agree about the same payment state and failure rules. That coordination is the difficult part.
+
+With Solid Objects, one actor in one file owns each shopping cart's full state and recovery work. Method calls on that object run one at a time, state lives in your existing SQL database, and scheduled recovery resume after restarts.
+
+Solid Object JavaScript Actors elegantly fit anything where one identifiable thing must remember state, handle competing requests in order, or wake up later:
+
+- Ticket holds and reservations
+- Multiplayer games and shared rooms
+- Shopping carts and checkout recovery
+- Rate limits and account quotas
+- Session expiration
+- Job leases and workflows
+- Connected devices
+- Collaborative documents
+
+And so much more.
 
 ## Contents
 
-- [The programming model](#the-programming-model)
-- [Why not just use transactions?](#why-not-just-use-transactions)
-- [Is it worth installing here?](#is-it-worth-installing-here)
-- [Run it now with SQLite](#run-it-now-with-sqlite)
-- [What Solid Objects is for](#what-solid-objects-is-for)
-- [Measured behavior](#measured-behavior)
-- [Running in a deployed application](#running-in-a-deployed-application)
-- [How it works](#how-it-works)
-- [Delivery boundaries](#delivery-boundaries)
-- [Realtime committed state](#realtime-committed-state)
+- [Installation](#installation)
+- [An expiring ticket hold](#an-expiring-ticket-hold)
+- [Why this exists](#why-this-exists)
+- [Good uses](#good-uses)
 - [Solid Objects in the browser](#solid-objects-in-the-browser)
-- [Comparison](#comparison)
-- [Requirements and supported systems](#requirements-and-supported-systems)
-- [Operations](#operations)
-- [Design provenance](#design-provenance)
-- [Documentation](#documentation)
-- [License](#license)
+- [When a transaction is better](#when-a-transaction-is-better)
+- [Guarantees and boundaries](#guarantees-and-boundaries)
+- [Read more](#read-more)
+- [Status and license](#status-and-license)
+
+## Installation
+
+Solid Objects is ESM-only and requires Node.js 24.4 or newer. TypeScript users
+need TypeScript 5.9 or newer.
+
+```bash
+npm install solid-objects
+npx solid-objects quickstart --yes
+```
 
-## The programming model
+The quickstart uses Node's built-in SQLite driver and proves that concurrent
+calls to one identity do not overwrite each other. It is an unusually formal
+introduction to addition.
 
-A ticket sale for one event, with 100 seats and a hold that expires:
+## An expiring ticket hold
 
-```typescript
-import { Actor, broadcastValue, configure } from "solid-objects"
+Save this as `ticket-sale.mjs`:
+
+```javascript
+import { Actor, configure } from "solid-objects"
 import { sqlite } from "solid-objects/database/sqlite"
 
-class TicketSale extends Actor {
-  static override readonly actorType = "TicketSale"
+const HOLD_MILLISECONDS = 10 * 60 * 1000
 
-  remaining = 100
-  holds: Record<string, number> = {}
+class TicketSale extends Actor {
+  static actorType = "TicketSale"
+  available = 1
+  holds = {}
 
-  override observables(): Record<string, unknown> {
-    return { remaining: broadcastValue(this.remaining) }
-  }
+  hold({ buyer }) {
+    if (this.available === 0 || buyer in this.holds) {
+      return { held: false, available: this.available }
+    }
 
-  reserve({ buyer }: { buyer: string }): boolean {
-    if (this.remaining === 0 || buyer in this.holds) return false
-    this.remaining -= 1
+    this.available -= 1
     this.holds = { ...this.holds, [buyer]: Date.now() }
-    this.schedule({ at: new Date(Date.now() + 600_000), key: buyer }).expire!({ buyer })
-    return true
+    this.schedule({
+      at: new Date(Date.now() + HOLD_MILLISECONDS),
+      key: buyer,
+    }).expire({ buyer })
+    return { held: true, available: this.available }
   }
 
-  expire({ buyer }: { buyer: string }): void {
-    if (!(buyer in this.holds)) return
-    const rest = { ...this.holds }
-    delete rest[buyer]
-    this.holds = rest
-    this.remaining += 1
+  expire({ buyer }) {
+    if (!(buyer in this.holds)) return this.available
+
+    const remainingHolds = { ...this.holds }
+    delete remainingHolds[buyer]
+    this.holds = remainingHolds
+    this.available += 1
+    return this.available
   }
 }
 
@@ -103,276 +100,57 @@ await runtime.install()
 
 try {
   const sale = TicketSale.ref("event-42")
-  const buyers = ["ada", "grace", "alan"]
-  await Promise.all(buyers.map((buyer) => sale.reserve({ buyer })))
+
+  if ((process.argv[2] ?? "hold") === "work") {
+    const controller = new AbortController()
+    process.once("SIGINT", () => controller.abort())
+    process.once("SIGTERM", () => controller.abort())
+    await runtime.run(controller.signal)
+  } else {
+    console.log(await Promise.all(["ada", "grace"].map((buyer) => sale.hold({ buyer }))))
+  }
 } finally {
   await runtime.close()
 }
 ```
 
-Every reserve enters the durable mailbox for `event-42`. They execute in order
-and commit one state transition at a time, even when different requests or
-Node.js processes submit them concurrently, so the guard on `remaining` cannot
-oversell.
-
-That example wants three things from the same number. It must never go below
-zero. It must give the seat back if the buyer does not pay within ten minutes.
-It must show the current count to everyone watching the page.
-
-The first is one UPDATE statement. The second is an `expiresAt` column plus a
-sweeper. The third is a push on every code path that changes the number. The
-combination is what costs, not any one of them. Here the guard, the ten-minute
-alarm, and the published count are one class, and they commit together.
-
-`install()` prepares the database and starts nothing. The example above finishes
-because the caller's own path executes each call. A process serves background
-work only after `runtime.run(signal)` starts its roles, so a process that
-installs and then waits never claims a ready message. Nothing is lost while no
-process runs. The message stays ready until one does.
-
-```typescript
-const controller = new AbortController()
-process.on("SIGTERM", () => controller.abort())
-await runtime.run(controller.signal)
-```
-
-## Why not just use transactions?
-
-Often you should. If the whole job is read a row, decide, write it back, and
-answer the request, then a transaction with `SELECT ... FOR UPDATE` does that
-and you need nothing else installed. In the browser, `navigator.locks` is the
-same answer. Reach for those first.
-
-The argument for an actor is scope, not discipline. A lock is scoped to one
-transaction, on one connection, in one process. The ticket sale above leaves
-that scope on one line: the hold expires in ten minutes, and no transaction
-stays open for ten minutes. A `setTimeout` does not cover it either, because it
-dies with the process.
-
-Any column named `expiresAt`, `scheduledAt`, or `nextRunAt` is evidence that
-the critical section already outlived the lock that was supposed to cover it.
-What follows such a column is a sweeper that looks for due rows, and then a
-race between that sweeper and the next writer of the same row. The column, the
-sweeper, and the race are what a Solid Objects actor replaces.
-
-Three cases a lock cannot reach:
-
-- work that fires at a future moment, when no transaction of yours is open;
-- work that must survive a process restart, which rules out an in-process
-  timer; and
-- a fan-in whose critical section spans many jobs over minutes, such as an
-  import that counts its own chunks as each one finishes.
-
-If it all happens inside one request, use a lock. If something has to happen
-later, or has to survive a restart, that is when this is worth installing.
-
-## Is it worth installing here?
-
-Worth it when several requests, jobs, or processes act on the same cart, room,
-device, event, or session, and each next action needs the last committed state.
-Worth it when that same thing also owns work that fires later, or a number a
-live page must show: per-document reminders and realtime projections of
-committed state are the same argument.
-
-Not worth it for a plain counter, a single-row update inside one transaction, a
-stateless job, bulk ingestion or a data-parallel pipeline, CPU-heavy work, a
-large JSON document that belongs in normalized rows, globally placed edge
-state, or a global rate-limit counter that every request touches. One hot
-identity is serialized on purpose, so making everything one identity makes a
-queue. Split an identity only when the domain can tolerate independent
-ordering and transactions.
-
-High-QPS reads and hot identities are where this runtime stops being the right
-tool on its own. [Solid Objects Pro](https://solidobjects.pro/) is a commercial
-performance layer for the family that adds grouped commits, which coalesce
-concurrent writes into fewer database commits; optional ephemeral operations,
-which take loss-tolerant calls out of the durable journal; and materialized
-projections, which build read models after commit so reads stop competing with
-mailbox work. It ships for the Rails gem today, and the Node build is in
-development.
-
-[What Solid Objects is for](#what-solid-objects-is-for) has the pattern table,
-and [Choosing Solid Objects](docs/fit.md) is the longer guide.
-
-## Run it now with SQLite
-
-The published package includes a quickstart that needs no checkout, database
-server, container, or configuration:
+Run the background roles in one terminal and place two concurrent holds in
+another:
 
 ```bash
-npm exec --yes --package=solid-objects@latest -- solid-objects quickstart
+node ticket-sale.mjs work
+node ticket-sale.mjs hold
 ```
 
-It states its plan, prints the `Counter` class it runs, and asks before doing
-anything. It asserts rather than printing a plausible result, and exits
-non-zero when a check fails. Add `--yes` to skip the question, or `--json` for
-a machine-readable summary.
-
-## What Solid Objects is for
-
-Use Solid Objects when more than one request, job, or process can act on the
-same logical thing. The next action must then use the latest committed state of
-that thing.
-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.
-
-## Measured behavior
-
-One developer machine, not a capacity promise: Apple M5, Node.js 24.18.0, 250
-operations at client concurrency 16, on August 22, 2026.
-
-| Measurement                                                   |           Result |
-| ------------------------------------------------------------- | ---------------: |
-| Committed operations per second, one hot identity, SQLite     | 286 to 323 ops/s |
-| The same identity across four processes, SQLite               | 507 to 519 ops/s |
-| Idle wake-up to committed result, one process                 |      2.66 ms p50 |
-| Idle wake-up to committed result, two processes, polling only |     1,006 ms p50 |
-
-Calls to one identity are serialized on purpose, so per-call latency includes
-the wait behind the other fifteen callers. That last row is the tradeoff to
-know before deploying: use PostgreSQL notifications or the optional Redis
-Pub/Sub when separate processes need low-latency delivery. The same databases
-in Docker Desktop reached 1.8x to 4.9x less throughput.
-
-PostgreSQL and MySQL numbers, idle CPU, sources of bias, and the full matrix
-are in [Benchmarks](docs/benchmarks.md). Measure your own deployment shape
-before planning capacity.
-
-## Running in a deployed application
-
-[Shuffle Up and Play](https://shuffleupandplay.com/) is a deployed reference
-application. Two players create a table, load decks, and move cards. Realtime
-updates reach both browsers. Its
-[source](https://github.com/cardmagic/shuffleupandplay) uses Node 24,
-TypeScript, SQLite, `node:http`, and `ws`. Each table code addresses one
-`GameRoom` actor that owns both seats, so mutations share one durable mailbox
-while each player receives a separately authorized projection.
-
-The application and its tests exercise more than a counter-shaped happy path:
-
-| Production concern        | Verifiable application evidence                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Concurrent mutations      | One [`GameRoom`](https://github.com/cardmagic/shuffleupandplay/blob/519a343e8db0bb6eed961a2ffd374dba80d67cd6/src/actors/game-room.ts#L45-L125) owns a table. [Mailbox tests](https://github.com/cardmagic/shuffleupandplay/blob/519a343e8db0bb6eed961a2ffd374dba80d67cd6/test/durability.test.ts#L39-L94) submit concurrent life, draw, and shuffle operations and assert the final committed state.                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| Controlled restarts       | [Restart tests](https://github.com/cardmagic/shuffleupandplay/blob/519a343e8db0bb6eed961a2ffd374dba80d67cd6/test/restart.test.ts#L38-L136) close and reopen the runtime against the same SQLite file, then assert recovery of committed state, an accepted asynchronous operation, an unfinished effect, and a scheduled reminder.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| Persistent deployment     | The [runtime uses SQLite](https://github.com/cardmagic/shuffleupandplay/blob/519a343e8db0bb6eed961a2ffd374dba80d67cd6/src/runtime.ts#L45-L63); the [container runs as an unprivileged user](https://github.com/cardmagic/shuffleupandplay/blob/519a343e8db0bb6eed961a2ffd374dba80d67cd6/Dockerfile#L20-L37), and [Kamal mounts a persistent volume](https://github.com/cardmagic/shuffleupandplay/blob/519a343e8db0bb6eed961a2ffd374dba80d67cd6/config/deploy.yml#L28-L43).                                                                                                                                                                                                                                                                                                                                                                  |
-| Private realtime state    | [Subscription policy](https://github.com/cardmagic/shuffleupandplay/blob/519a343e8db0bb6eed961a2ffd374dba80d67cd6/src/runtime.ts#L65-L82) and [per-seat projection](https://github.com/cardmagic/shuffleupandplay/blob/519a343e8db0bb6eed961a2ffd374dba80d67cd6/src/game/room-snapshot.ts#L92-L130) run on the server. [HTTP](https://github.com/cardmagic/shuffleupandplay/blob/519a343e8db0bb6eed961a2ffd374dba80d67cd6/test/server.test.ts#L526-L567) and [WebSocket tests](https://github.com/cardmagic/shuffleupandplay/blob/519a343e8db0bb6eed961a2ffd374dba80d67cd6/test/realtime.test.ts#L184-L235) assert that opponent card identities are absent from player payloads and shared invalidation envelopes.                                                                                                                          |
-| External work             | Deck imports run as [durable effects with success and failure callbacks](https://github.com/cardmagic/shuffleupandplay/blob/519a343e8db0bb6eed961a2ffd374dba80d67cd6/src/actors/game-room.ts#L192-L253). [Tests](https://github.com/cardmagic/shuffleupandplay/blob/519a343e8db0bb6eed961a2ffd374dba80d67cd6/test/game-room.test.ts#L209-L331) cover both outcomes and prevent a superseded callback from replacing a newer deck result.                                                                                                                                                                                                                                                                                                                                                                                                     |
-| Transactional staged work | A room operation stages an [actor-to-actor log message](https://github.com/cardmagic/shuffleupandplay/blob/519a343e8db0bb6eed961a2ffd374dba80d67cd6/src/actors/game-room.ts#L339-L349) and a [database commit action](https://github.com/cardmagic/shuffleupandplay/blob/519a343e8db0bb6eed961a2ffd374dba80d67cd6/src/runtime.ts#L96-L113). Tests cover [rollback of staged messages](https://github.com/cardmagic/shuffleupandplay/blob/519a343e8db0bb6eed961a2ffd374dba80d67cd6/test/durability.test.ts#L160-L192) and the [metrics write](https://github.com/cardmagic/shuffleupandplay/blob/519a343e8db0bb6eed961a2ffd374dba80d67cd6/test/server.test.ts#L467-L499).                                                                                                                                                                     |
-| Time and schema changes   | The actor defines [versioned state migrations](https://github.com/cardmagic/shuffleupandplay/blob/519a343e8db0bb6eed961a2ffd374dba80d67cd6/src/actors/game-room.ts#L47-L91) and a [durable reminder](https://github.com/cardmagic/shuffleupandplay/blob/519a343e8db0bb6eed961a2ffd374dba80d67cd6/src/actors/game-room.ts#L276-L310). Tests load [stored version-one state](https://github.com/cardmagic/shuffleupandplay/blob/519a343e8db0bb6eed961a2ffd374dba80d67cd6/test/operations.test.ts#L135-L201) and [run the reminder scheduler](https://github.com/cardmagic/shuffleupandplay/blob/519a343e8db0bb6eed961a2ffd374dba80d67cd6/test/durability.test.ts#L236-L257).                                                                                                                                                                   |
-| Operations and CI         | The [operations tests](https://github.com/cardmagic/shuffleupandplay/blob/519a343e8db0bb6eed961a2ffd374dba80d67cd6/test/operations.test.ts#L39-L202) exercise doctor, process, retention, and reconciliation APIs; server suites cover the [dashboard](https://github.com/cardmagic/shuffleupandplay/blob/519a343e8db0bb6eed961a2ffd374dba80d67cd6/test/server.test.ts#L297-L326), [rate limits](https://github.com/cardmagic/shuffleupandplay/blob/519a343e8db0bb6eed961a2ffd374dba80d67cd6/test/rate-limit.test.ts), and [shutdown](https://github.com/cardmagic/shuffleupandplay/blob/519a343e8db0bb6eed961a2ffd374dba80d67cd6/test/shutdown.test.ts). The [current main CI run](https://github.com/cardmagic/shuffleupandplay/actions/runs/31963000789) passed typechecking, 171 tests, the build, the doctor, and a Docker image build. |
-
-**Scope:** the checked-in deployment configuration runs one Node process with
-SQLite on one Docker host. It shows a real deployed workload. It does not show a
-measured traffic level or every supported topology. Its deck-import effect reads
-an external API. An effect that writes to an external system still needs a
-stable idempotency key, because delivery is at least once. The restart tests
-close the runtime cleanly. The library verifies abrupt termination, PostgreSQL,
-MySQL, and multi-process lease fencing separately in its
-[test matrix](docs/support.md),
-[failure-recovery demonstration](examples/failure-recovery/demo.ts), and
-[correctness contract](docs/correctness.md). Compare those guarantees and limits
-with your own workload.
-
-## How it works
-
-An actor is addressed by its class and an application-chosen ID. Fields are
-durable state, methods are operations, and getters are queries. One operation
-is one turn: the runtime claims the actor under a fenced lease, runs your
-JavaScript outside the transaction, then commits state, results, staged
-effects, reminders, and realtime invalidations together. A failure retries with
-backoff and dead-letters at the limit.
-
-The fence includes the activation owner, token, generation, expiration, and
-claimed message, so a worker that finishes its JavaScript after losing the
-lease cannot commit. The database is the source of truth. Redis is optional
-acceleration, and polling remains the recovery path.
-
-[`examples/failure-recovery/demo.ts`](examples/failure-recovery/demo.ts) kills a
-worker mid-turn and shows the survivor finish it.
-[Architecture](docs/architecture.md) and
-[Operations](docs/operations.md) cover the turn lifecycle, polling backoff, and
-wake-up adapters.
-
-## Delivery boundaries
-
-- Operations are ordered per identity and execute **at least once**.
-- Fencing protects the database commit. It cannot undo an HTTP request, email,
-  payment, or file write, so external systems need the stable effect ID or
-  another durable idempotency key.
-- Different identities run concurrently; one hot identity cannot.
-- Cross-object transactions are not provided.
-- Realtime sessions are process-local, so a multi-process application must
-  bridge committed broadcast events to the processes holding live connections.
-
-[Correctness and delivery semantics](docs/correctness.md) has the complete
-contract, including `stateVersion` compatibility and the database write guard,
-and [Errors and recovery](docs/errors-and-recovery.md) covers failure handling.
-
-## Realtime committed state
-
-For a like count or a dashboard number, write the row and then send on your own
-socket. That is less code than this library and it works.
-
-It gets harder when several people write to the same record at once. Each
-request builds its payload in its own process and sends it. The lock decided
-who wrote first, but it has no say over which of the two sends arrives last, so
-a viewer can be left looking at the older number. The second gap is that the
-send is not part of the write: if the process dies after the database commits
-and before the send goes out, the tab keeps a wrong number and nothing corrects
-it.
-
-An observable is the alternative. The change and its publication commit
-together, so no crash can leave one without the other. A worker delivers the
-publication afterwards, claiming rows in actor revision order, and subscribers
-reject a duplicate or stale revision. Delivery is still at least once, so the
-guarantee is that a subscriber cannot end up on an older value, not that a
-value is sent exactly once.
-
-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
-import { Actor, broadcastValue } from "solid-objects"
-
-class Room extends Actor {
-  static override readonly actorType = "Room"
-
-  version = 0
-  privateHands: Record<string, string[]> = {}
-
-  override observables(): Record<string, unknown> {
-    return {
-      version: broadcastValue(this.version),
-      hands: this.privateHands,
-    }
-  }
-}
-```
+Only one buyer gets the ticket. The successful call stores the hold and its
+ten-minute expiry together. Stop the worker process before the deadline and
+restart it afterwards; the reminder is still in `tickets.sqlite3` and runs when
+the process returns. We have now given `available += 1` a recovery plan.
+
+The authorization callbacks above are for this local example only. Production
+policies must bind actor IDs and operations to the authenticated user or tenant.
 
-`version` crosses the shared invalidation channel. `hands` contributes only its
-name when its real value changes. A reauthorized component endpoint can then
-render subscriber-specific state without a manual revision counter.
+## Why this exists
 
-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).
+The handwritten version usually starts with a row lock. Then it gains an
+`expiresAt` column, a sweeper, retries, per-room ordering, and a broadcast path
+that must agree with the write. The original transaction has developed a robust
+interplay with four other subsystems.
+
+Solid Objects makes the application-defined identity the coordination boundary.
+Its state, mailbox, retries, reminders, and staged consequences live in SQLite,
+PostgreSQL, or MySQL. No daemon, broker, Cloudflare account, or new datastore is
+required. Redis is optional wake-up plumbing, not durable state.
+
+## Good uses
+
+- Multiplayer rooms, collaborative sessions, and documents with ordered edits.
+- Carts, reservations, and inventory holds with durable expiry.
+- Accounts, devices, and long-lived jobs whose next action depends on committed state.
+- Realtime multi-user state where publications must follow committed revisions.
+
+Different identities can run concurrently. One global identity is merely a
+queue wearing an ambitious name.
 
 ## Solid Objects in the browser
 
@@ -410,11 +188,12 @@ holder per origin through the Web Locks API, carries the other tabs' SQL to it
 over a `BroadcastChannel`, and fails over onto the same durable state when the
 holder's tab dies. Use `sqliteWasm` for a single dedicated worker.
 
-Two companions complete the local-first story: `solid-objects/browser/tab-host`
-runs one runtime for all tabs when the application prefers request-level
-routing, and `solid-objects/transmit` drains the transactional effects outbox
-to a server with at-least-once delivery, per-actor order, and an idempotent
-server ingest, so offline writes reconcile when the network returns.
+Two more modules support local-first applications.
+`solid-objects/browser/tab-host` runs one runtime for all tabs when the
+application prefers request-level routing. `solid-objects/transmit` drains the
+transactional effects outbox to a server with at-least-once delivery, per-actor
+order, and an idempotent server ingest, so offline writes reconcile when the
+network returns.
 
 ### The backend can be Rails, not only Node
 
@@ -447,99 +226,48 @@ The wire shapes are documented in the
 [public API reference](docs/api.md), and the platform boundaries in
 [supported versions](docs/support.md).
 
-## Comparison
-
-A SQL transaction or row lock serializes selected rows for one transaction and
-needs nothing installed. A job queue retries a job but leaves ordering to queue
-configuration. Solid Objects serializes by object ID, keeps state in the
-database you already run, and adds a library rather than a service. Cloudflare
-Durable Objects, Rivet, DBOS, and Restate each add a managed runtime or server.
-
-celld and Solid Objects both self-host the Durable Objects model, and the
-difference is what you run. celld runs a daemon that embeds V8 and executes
-Wrangler bundles, gives each object its own SQLite database, replicates that
-database to an object-storage bucket you own, and moves ownership between nodes
-through compare-and-swap on that bucket. Solid Objects runs plain TypeScript
-classes inside your Node processes, adds no daemon, and keeps object state in
-the SQL database the application already operates. Choose celld to run
-Workers-format code across a fleet with bucket-based placement. Choose Solid
-Objects to keep one database, no extra process, and an ordinary Node
-deployment.
-
-[docs/comparisons.md](docs/comparisons.md) has the full table across eight
-systems, with primary sources for every dimension: realtime projections, edge
-placement, cross-identity transactions, and operational data access.
-
-## Requirements and supported systems
-
-Node.js 24.4.0 or newer, TypeScript 5.9 or newer, and SQLite through
-`node:sqlite`, PostgreSQL 14 or newer, or MySQL 8.0 or newer on InnoDB.
-`pg`, `mysql2`, `ioredis`, and `@sqlite.org/sqlite-wasm` are optional peer
-dependencies, installed only for the adapters you use.
-
-[Supported versions](docs/support.md) records the exact CI matrix, the browser
-requirements for OPFS and the Web Locks API, and the boundaries.
-
-## Operations
-
-`runtime.run(signal)` supervises the actor, effect, reminder, broadcast,
-retention, and stale-process recovery roles. An optional `solid-objects/web`
-export mounts a database-backed operator dashboard behind a deny-by-default
-administration policy, with session-backed CSRF protection and Fetch or
-Node/Connect mounting. Administration is also available through the JSON CLI
-and typed runtime managers.
-
-The dashboard has an explicitly public read-only mode. Use it only for
-synthetic demo data: it exposes stored arguments, results, errors, identifiers,
-and operational metadata. 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. The Ruby
-[`solid_objects`](https://github.com/cardmagic/solid-objects-ruby) design informed
-it. It began at the `0.12` capability generation, because the first
-implementation targeted the Ruby `0.12` contract. That 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, a
-framework-neutral component registry, 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.
-[Shuffle Up and Play](https://github.com/cardmagic/shuffleupandplay) uses the
-TypeScript package in the deployed Node and SQLite topology above.
-
-## Documentation
-
-- [Getting the architecture right](docs/architecture.md)
-- [Correctness and delivery semantics](docs/correctness.md)
+## When a transaction is better
+
+Often. If all the work happens in one request, use a transaction, constraint, or
+`SELECT ... FOR UPDATE`. It is smaller, faster, and does not need a manifesto.
+
+Use Solid Objects when the critical section outlives that transaction: work
+must happen later, survive a restart, or remain ordered across several requests
+or jobs. A plain counter is not a reason to install this package.
+
+## Guarantees and boundaries
+
+- Calls are durably ordered per identity. Different identities may run concurrently.
+- Delivery is **at least once**, not exactly once. A handler can begin again after a crash.
+- One successful turn commits state and staged reminders, messages, effects, and realtime publications together.
+- Fencing prevents a stale worker from committing, though its JavaScript may keep running. It cannot undo an HTTP request, email, payment, or file write.
+- External effects can repeat and must use the stable effect ID or another durable idempotency key.
+- One hot identity is intentionally sequential. There are no transactions across identities.
+- Background work needs `runtime.run(signal)`. If no process is running, committed work waits in SQL rather than disappearing.
+- Your application still owns authorization, database backups, failover, WebSocket transport, and capacity planning.
+
+Exactly once remains absent, despite its excellent branding. Read the
+[correctness contract](docs/correctness.md) before using important data.
+
+## Read more
+
+- [Five-minute Node guide](https://solidobjects.dev/5min/node)
 - [Choosing Solid Objects](docs/fit.md)
-- [Benchmarks and methodology](docs/benchmarks.md)
-- [Supported versions and test matrix](docs/support.md)
-- [Test suite](https://github.com/cardmagic/solid-objects-js/tree/main/test)
-- [CI workflow](https://github.com/cardmagic/solid-objects-js/actions/workflows/ci.yml)
 - [Public API](docs/api.md)
-- [State and lifecycle](docs/state-and-lifecycle.md)
-- [Operations, retention, and reconciliation](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)
-- [Changelog](CHANGELOG.md)
-- [Releases](https://github.com/cardmagic/solid-objects-js/releases)
-- [Contributing](CONTRIBUTING.md)
-- [Security policy](SECURITY.md)
-
-## License
-
-Solid Objects is released under the [MIT License](MIT-LICENSE).
+- [Operations and recovery](docs/operations.md)
+- [Detailed architecture](docs/architecture.md)
+- [Detailed documentation](docs/)
+
+The benchmarks, parity ledger, dashboard, browser setup, and exhaustive API
+notes remain in `docs/`, where long documentation can be long on purpose.
+
+## Status and license
+
+Solid Objects JS is a pre-1.0 early release. The correctness core has
+automated coverage across the supported databases, browser runtime, recovery
+paths, and packaged artifact. There is one deployed first-party reference
+application, no measured scale, and no known third-party production use yet.
+Pre-1.0 is doing actual work in that sentence.
+
+Solid Objects is released under the [MIT License](MIT-LICENSE). It is an
+independent project and is not affiliated with or endorsed by Cloudflare.