solid-objects 0.17.0 → 0.17.2

package/CHANGELOG.md

@@ -1,5 +1,60 @@
 # Changelog
 
+## 0.17.2 - 2026-10-08
+
+- The README names the agent guide at the start of Installation, and the agent
+  guide says that a reminder changes state only when it runs under
+  `runtime.run(signal)`, so a query must not compute expiry from the clock.
+- Correct `docs/agents.md`: `reject` takes a code and an options object,
+  `this.reject(code, { message })`, not `this.reject(code, message)`.
+- `docs/agents.md` now says that a worker process runs only the actor classes
+  that it knows. For an unregistered class, actor setup fails with
+  `UnknownActorType`, the worker reports `solid_objects.activation.failed`,
+  and the message returns to the queue without a counted attempt. Nothing
+  prints without an `instrumentation` callback. Register each class before
+  `runtime.run(signal)`.
+  It also tells agents to install the current release, puts the
+  deny-by-default reminder beside the install step, and lists the API
+  mistakes found in agent-written code.
+- Claim the Context7 library: `context7.json` now carries the library `url` and
+  the maintainer `public_key`.
+- Add the Context7 refresh workflow. A push to `main` that changes the README,
+  `context7.json`, `docs/`, or `examples/` asks Context7 to refresh the index.
+  It uses the `CONTEXT7_API_KEY` repository secret.
+
+## 0.17.1 - 2026-10-08
+
+- Check holds with `Object.hasOwn` in the README and guide ticket sale
+  examples. The `in` operator also matched inherited names, so a buyer named
+  `constructor` could not hold a free ticket, and `expire` could add a ticket
+  that no hold had taken. `pnpm run test:package` now holds a ticket for that
+  buyer.
+- Override `sharp` with 0.35.5 and `source-map-js` with 1.2.2. Two high
+  advisories reach the repository only through the development tooling:
+  `sharp` through Miniflare and `source-map-js` through Vite and PostCSS. The
+  published package does not depend on either.
+- Name the category in the package metadata and the README: Solid Objects is
+  a SQL-backed virtual actor library for TypeScript and Node.js. The package
+  now declares `https://solidobjects.dev/js` as its homepage and adds the
+  `virtual-actors` and `actor-model` keywords.
+- Add `docs/virtual-actors.md`, a category guide with the definition, a small
+  example, fit and poor-fit criteria, comparisons, an Orleans concept map, and
+  separate compatibility statements for the Node runtime, the browser client,
+  the browser runtime, and the Cloudflare backend.
+- Add `docs/agents.md`, a consumer guide for coding agents with setup,
+  authorization, effect idempotency, verification, and troubleshooting steps.
+- Add Dapr actors, Temporal, and a comparison vocabulary to
+  `docs/comparisons.md`.
+- Add `examples/ticket-sale.ts`. `pnpm run test:package` runs it against the
+  packed tarball, and the documentation check fails when the guide no longer
+  embeds it.
+- The documentation check now reads every `docs/*.md` file instead of a fixed
+  list.
+- Add `context7.json` so that Context7 indexes the consumer documentation and
+  skips maintainer files.
+- Record the clean-install artifact proof in `docs/parity.md`. Ruby now has a
+  matching `rake quickstart` check.
+
 ## 0.17.0 - 2026-10-03
 
 - **Breaking:** `solid_objects.activation.started` now fires before the actor's

package/README.md

@@ -5,6 +5,12 @@
 
 **Open Source Durable Objects in your Node app.**
 
+Solid Objects is a SQL-backed virtual actor library for TypeScript and Node.js,
+with durable state, ordered operations, and automatic activation. Each actor
+has a stable identity, and its state lives in the SQL database that your app
+already uses. [Virtual actors in TypeScript and Node.js](docs/virtual-actors.md)
+explains the model and when to use it.
+
 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.
@@ -43,7 +49,8 @@ subscriptions. Start with the [Cloudflare example](examples/cloudflare/README.md
 ## Installation
 
 Solid Objects is ESM-only and requires Node.js 24.4 or newer. TypeScript users
-need TypeScript 5.9 or newer.
+need TypeScript 5.9 or newer. Coding agents should follow the
+[agent guide](docs/agents.md), which gives each step in order.
 
 ```bash
 npm install solid-objects
@@ -70,7 +77,7 @@ class TicketSale extends Actor {
   holds = {}
 
   hold({ buyer }) {
-    if (this.available === 0 || buyer in this.holds) {
+    if (this.available === 0 || Object.hasOwn(this.holds, buyer)) {
       return { held: false, available: this.available }
     }
 
@@ -84,7 +91,7 @@ class TicketSale extends Actor {
   }
 
   expire({ buyer }) {
-    if (!(buyer in this.holds)) return this.available
+    if (!Object.hasOwn(this.holds, buyer)) return this.available
 
     const remainingHolds = { ...this.holds }
     delete remainingHolds[buyer]
@@ -254,6 +261,8 @@ There is no exactly-once delivery. Read the
 ## Read more
 
 - [Five-minute Node guide](https://solidobjects.dev/5min/node)
+- [Virtual actors in TypeScript and Node.js](docs/virtual-actors.md)
+- [Guide for coding agents](docs/agents.md)
 - [Choosing Solid Objects](docs/fit.md)
 - [Public API](docs/api.md)
 - [Operations and recovery](docs/operations.md)

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.17.0";
+export declare const VERSION = "0.17.2";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -1,2 +1,2 @@
-export const VERSION = "0.17.0";
+export const VERSION = "0.17.2";
 //# sourceMappingURL=version.js.map

package/docs/agents.md

@@ -0,0 +1,331 @@
+# Solid Objects for coding agents (TypeScript and Node.js)
+
+This guide is for a coding agent that evaluates or adds Solid Objects in a
+TypeScript or Node.js application. It gives the facts and steps in a fixed
+order. Each step links to the maintained documentation for more detail.
+
+## 1. Check the fit first
+
+Use Solid Objects only if you can answer yes to most of these questions:
+
+1. Does one identity, such as a room, cart, account, device, or document, own
+   the state?
+2. Must writes for that identity happen one at a time across requests and
+   processes?
+3. Must some work happen later or continue after a process exits?
+4. Is the state a bounded JSON document, not a large relational dataset?
+5. Can the application run `runtime.run(signal)` in at least one process for
+   reminders, effects, and realtime delivery?
+
+Select a simpler tool in these cases:
+
+| Requirement                                    | Use instead                                                                                                 |
+| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| The invariant fits in one request              | A transaction, a constraint, or `SELECT ... FOR UPDATE`                                                     |
+| CPU-intensive or parallel work                 | `worker_threads` or a worker pool. An actor serializes work                                                 |
+| Thousands of writes for each second to one key | A counter column or a cache. Solid Objects Pro covers this case for Rails; its Node build is in development |
+| One atomic change across two actor identities  | One SQL transaction on normal tables                                                                        |
+| Exactly-once calls to an external API          | Not available from any actor library. Use provider idempotency keys                                         |
+| Replay of named workflow steps from a step log | A durable execution engine, such as DBOS or Temporal                                                        |
+
+The full list is in [Choosing Solid Objects](fit.md). The category guide is
+[Virtual actors in TypeScript and Node.js](virtual-actors.md).
+
+## 2. Package identity
+
+| Item               | Value                                                                                                 |
+| ------------------ | ----------------------------------------------------------------------------------------------------- |
+| npm package        | `solid-objects`                                                                                       |
+| Repository         | <https://github.com/cardmagic/solid-objects-js>                                                       |
+| Website            | <https://solidobjects.dev/js>                                                                         |
+| Ruby on Rails gem  | `solid_objects`, a separate implementation of the same model                                          |
+| Commercial package | `@solidobjects/pro`, a separate paid package in development. The open-source package does not need it |
+
+Solid Objects is not SolidJS and has no relation to it. It is not affiliated
+with Cloudflare.
+
+## 3. Requirements
+
+- Node.js 24.4 or newer. Prefer 24.15 or newer, where `node:sqlite` is no
+  longer experimental.
+- The package is ESM only. TypeScript applications need TypeScript 5.9 or
+  newer.
+- SQLite through the `node:sqlite` module, PostgreSQL 14 or newer with the
+  `pg` package, or MySQL 8.0 or newer with InnoDB and the `mysql2` package.
+- Redis is optional. It only shortens wake-up latency and holds no durable
+  state.
+
+[Supported versions](support.md) lists the CI matrix.
+
+## 4. Install
+
+```bash
+npm install solid-objects
+npx solid-objects quickstart --yes
+```
+
+The quickstart runs 25 concurrent calls against one identity on a temporary
+SQLite database. It proves that no update is lost. Add `pg` or `mysql2` when
+you use PostgreSQL or MySQL.
+
+Install the current release. `npm install solid-objects` selects it. Do not
+pin a version that you remember from earlier work; the API changed between
+releases. The current version is on <https://www.npmjs.com/package/solid-objects>.
+
+Create the runtime and its tables at startup:
+
+```typescript
+import { configure } from "solid-objects"
+import { sqlite } from "solid-objects/database/sqlite"
+
+const runtime = configure({
+  database: sqlite({ path: "app.sqlite3" }),
+})
+
+await runtime.install()
+```
+
+Every authorization callback denies by default. Do step 5 before you call an
+actor. [Configuration](configuration.md) lists each option and database
+adapter.
+
+## 5. Authorize
+
+All authorization callbacks deny by default. A new runtime answers no actor
+call until you write a policy. Do not remove this behavior.
+
+For a local demonstration only, grant messages and queries:
+
+```typescript
+const runtime = configure({
+  database: sqlite({ path: "app.sqlite3" }),
+  authorizeMessage: () => true,
+  authorizeQuery: () => true,
+})
+```
+
+Keep `authorizeDestroy`, `authorizeSubscription`, and
+`authorizeAdministration` denied in a demonstration.
+
+A production policy must bind the actor type and ID to the authenticated user
+or tenant. An actor ID is not a permission:
+
+```typescript
+const ownsCart = ({
+  actorType,
+  actorId,
+  authorizationContext,
+}: {
+  actorType: string
+  actorId: string
+  authorizationContext: unknown
+}) => {
+  if (actorType !== "ShoppingCart") return false
+  if (typeof authorizationContext !== "object" || authorizationContext === null) return false
+  if (!("userId" in authorizationContext)) return false
+  return typeof authorizationContext.userId === "string" && actorId === authorizationContext.userId
+}
+
+const runtime = configure({
+  database: sqlite({ path: "app.sqlite3" }),
+  authorizeMessage: ownsCart,
+  authorizeQuery: ownsCart,
+})
+```
+
+Pass the context on each call:
+
+```typescript
+await ShoppingCart.ref(subject.userId)
+  .with({ authorizationContext: subject })
+  .addItem({ productId: "shirt-123" })
+```
+
+[Authorization](authorization.md) covers each entry point.
+
+## 6. Define an actor
+
+This actor is the example from the [virtual actor guide](virtual-actors.md):
+
+```typescript
+import { Actor } from "solid-objects"
+
+const HOLD_MILLISECONDS = 10 * 60 * 1000
+
+export class TicketSale extends Actor {
+  static override readonly actorType = "TicketSale"
+
+  available = 1
+  holds: Record<string, number> = {}
+
+  hold({ buyer }: { buyer: string }): { held: boolean; available: number } {
+    if (this.available === 0 || Object.hasOwn(this.holds, buyer)) {
+      return { held: false, available: this.available }
+    }
+
+    this.available -= 1
+    this.holds = { ...this.holds, [buyer]: Date.now() }
+    this.schedule({ at: new Date(Date.now() + HOLD_MILLISECONDS), key: buyer }).expire({ buyer })
+    return { held: true, available: this.available }
+  }
+
+  expire({ buyer }: { buyer: string }): number {
+    if (!Object.hasOwn(this.holds, buyer)) return this.available
+
+    const remainingHolds = { ...this.holds }
+    delete remainingHolds[buyer]
+    this.holds = remainingHolds
+    this.available += 1
+    return this.available
+  }
+}
+```
+
+Obey these rules in actor code:
+
+- Give each actor class a stable `static actorType`. The database stores it.
+- Enumerable public fields are the durable state. They must be
+  JSON-compatible.
+- Public methods are ordered operations. Each one takes no argument or one
+  object argument.
+- Use `this.schedule({ at, key })` for delayed work. A new `schedule` with the
+  same key moves the alarm.
+- Use `this.reject(code, { message })` for a business rule failure that must
+  not retry. The second argument is an object, for example
+  `this.reject("room_full", { message: "The room is full" })`.
+- Do not write application tables directly from an operation. Use
+  `this.commitAction()` for a short write in the same database.
+- Do not call an external API in an operation. Use `this.emit()` and an effect
+  handler.
+- Write each operation so that it can run again. Delivery is at least once.
+- A reminder changes state only when it runs, and it runs only while a process
+  calls `runtime.run(signal)`. Do not compute expiry from the clock in a query;
+  read the state that the reminder committed.
+
+Avoid these mistakes:
+
+| Mistake                                                    | Correct form                                                                                                                 |
+| ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `this.schedule({ at, key })` with no operation after it    | `this.schedule({ at, key }).expire({ buyer })`. `schedule()` stages a reminder only when you call an operation on its result |
+| `this.reject("room full")` or `this.reject(code, message)` | `this.reject("room_full", { message: "The room is full" })`                                                                  |
+| `registerEffect(name, (context, argumentsValue) => ...)`   | `registerEffect(name, (argumentsValue, context) => ...)`. The staged arguments come first                                    |
+| A worker process that never names the actor class          | `runtime.register(TicketSale)` before `runtime.run(signal)`. See step 7                                                      |
+
+[State and lifecycle](state-and-lifecycle.md) and the
+[public API](api.md) give the full rules.
+
+## 7. Run the background roles
+
+A direct call, such as `TicketSale.ref("event-42").hold({ buyer: "ada" })`,
+runs in the caller. These features need a process that calls
+`runtime.run(signal)`:
+
+- Reminders from `schedule()`.
+- Effects from `emit()` and their callbacks.
+- Messages to other actors.
+- Realtime broadcasts.
+
+The worker process runs only the actor classes that it knows. For a message
+whose class is not registered, actor setup fails with `UnknownActorType`. The
+worker reports `solid_objects.activation.failed` through instrumentation,
+returns the message to the queue without counting an attempt, and tries again.
+Nothing prints unless the application sets an `instrumentation` callback, so
+the message seems to wait with no error. Register each class before `run()`:
+
+```typescript
+runtime.register(TicketSale)
+
+const controller = new AbortController()
+process.once("SIGTERM", () => controller.abort())
+await runtime.run(controller.signal)
+await runtime.close()
+```
+
+`TicketSale.ref(...)` also registers the class, so a script that calls `ref()`
+before `run()`, like the direct call above, already works.
+
+The packaged `solid-objects start` command does the same for a runtime that
+`solid-objects.config.js` exports. When no process runs, committed work waits
+in SQL and runs later. [Operations](operations.md) covers roles and shutdown.
+
+## 8. Make external effects idempotent
+
+Register an effect handler at startup. Use `context.id` as the provider
+idempotency key:
+
+```typescript
+runtime.registerEffect("charge_payment", async (argumentsValue, context) => {
+  return payments.charge({
+    idempotencyKey: context.id,
+    paymentId: argumentsValue.paymentId,
+  })
+})
+```
+
+Stage it from an operation:
+
+```typescript
+this.emit("charge_payment", {
+  arguments: { paymentId: this.paymentId },
+  onSuccess: "charged",
+})
+```
+
+The effect can run more than once after a crash. The `context.id` value is the
+same each time. [Effect recovery](effect-recovery.md) explains how to retire
+abandoned work.
+
+## 9. Verify the implementation
+
+Do these checks before you report that the work is complete:
+
+1. Call `await runtime.doctor.run()`. The report must contain no failed check.
+2. Send concurrent calls to one identity with `Promise.all`, and from two
+   processes if the application runs more than one. Assert the final state.
+3. Test delayed work without sleeps. `runDueReminders({ now })` enqueues the
+   reminders that are due at the `Date` you pass. `drain()` then runs the
+   enqueued actor work:
+
+   ```typescript
+   await runtime.testing.runDueReminders({ now: new Date(Date.now() + HOLD_MILLISECONDS) })
+   await runtime.testing.drain({ roles: ["actors"] })
+   ```
+
+4. Start a process that calls `runtime.run(signal)`, schedule a short
+   reminder, and stop the process. Start it again after the deadline and
+   confirm that the reminder ran.
+5. Confirm that each effect handler deduplicates with `context.id`.
+6. Confirm that production policies do not grant access to every caller.
+
+The repository runs the same proofs. `pnpm run test:recovery` stops a worker
+process and recovers its work. `pnpm run test:at-least-once` shows a repeated
+effect and its deduplication.
+
+## 10. Troubleshooting
+
+| Symptom                                 | Cause and fix                                                                        |
+| --------------------------------------- | ------------------------------------------------------------------------------------ |
+| `Unauthorized`                          | A policy denied the call. Write the policy, and pass `authorizationContext`          |
+| A reminder or effect does not run       | No process calls `runtime.run(signal)`. Start one                                    |
+| `SyncInsideTransaction`                 | The call ran inside an open transaction. Call the actor outside the transaction      |
+| `SyncTimeout`                           | The call did not finish in time. The message is still durable. Wait on its reference |
+| `ApplicationWriteForbidden`             | An operation wrote an application table. Use `commitAction()` or `emit()`            |
+| `Rejected`                              | The actor called `reject()`. This is a business result, not a retry                  |
+| Wrong integer values or SQLite warnings | Node.js is older than 24.4, or older than 24.15 for the warning. Upgrade Node.js     |
+| `ERR_REQUIRE_ESM` or import errors      | The package is ESM only. Use `import` and an ES module file                          |
+
+## 11. Guarantees to state correctly
+
+When you explain Solid Objects to a user, state these limits:
+
+- Delivery is at least once, not exactly once.
+- Calls for one identity are ordered. Different identities run concurrently.
+- There are no transactions across actor identities.
+- Fencing stops a stale activation from a commit, but its code can continue to
+  run.
+- The package is pre-1.0. It has no measured scale and no known third-party
+  production use.
+- The browser client is not the SQL runtime. The Cloudflare backend is
+  experimental.
+
+The [correctness contract](correctness.md) is the source for each guarantee.

package/docs/comparisons.md

@@ -2,6 +2,9 @@
 
 This guide compares coordination models so an application can choose the
 smallest mechanism that meets its requirements. It does not rank the projects.
+Solid Objects is a virtual actor library; the
+[virtual actor guide](virtual-actors.md) defines the term. Facts about other
+projects were checked on October 7, 2026.
 
 | Approach                    | State and serialization unit             | Deployment and durable substrate                                                   | Separate service                                                                           | Replay versus state                                                             | Realtime and edge placement                                                                | Cross-identity transaction                                     | Data access                                                         |
 | --------------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------- | ------------------------------------------------------------------- |
@@ -12,7 +15,25 @@ smallest mechanism that meets its requirements. It does not rank the projects.
 | celld                       | Object class and object name             | celld nodes plus one object-storage bucket; each object is its own SQLite database | Yes, the celld daemon on every node                                                        | The new owner restores the object's SQLite database from the bucket and resumes | Cloudflare Workers APIs; an object runs on one node of your fleet, not at an edge location | No                                                             | Per-object SQLite through the Workers storage APIs, plus the bucket |
 | Rivet Actors                | Addressable actor                        | Rivet Engine or managed compute with actor state, KV, or per-actor SQLite          | Rivet Engine                                                                               | Actor persistence and lifecycle; workflows add recorded steps                   | Actor events and deployment-dependent placement                                            | No general transaction across actors                           | Actor APIs and selected persistence model                           |
 | DBOS                        | Workflow ID and checkpointed steps       | Application processes plus PostgreSQL system database                              | No orchestration server for the library; Conductor is recommended for distributed recovery | Deterministic workflow replay skips checkpointed steps                          | Workflow events; application placement                                                     | PostgreSQL transactions remain separate from workflow identity | PostgreSQL system database, client, CLI, and optional Conductor     |
+| Dapr actors                 | Actor type and ID, one turn at a time    | Application services plus Dapr sidecars and a transactional actor state store      | Yes: the Dapr sidecar plus the placement and Scheduler services                            | Actor state persists in the state store; actors do not replay workflow steps    | Sidecar-routed actor placement; no edge placement                                          | No transaction across actors                                   | Dapr actor APIs and the configured state store                      |
 | Restate                     | Service handler or keyed virtual object  | Application services plus Restate's durable log and state store                    | Yes                                                                                        | Durable execution journals handler progress and object state                    | Service protocol and Restate deployment                                                    | No shared SQL transaction across object keys                   | Restate APIs, state tools, snapshots, and backups                   |
+| Temporal                    | Workflow execution ID                    | Worker processes plus a Temporal Service, self-hosted or Temporal Cloud            | Yes, the Temporal Service                                                                  | Deterministic workflow code replays its event history                           | Workflow signals and queries; application placement                                        | No shared SQL transaction across workflows                     | Temporal SDK, CLI, and web UI                                       |
+
+## Comparison vocabulary
+
+Each row above differs on the same dimensions. For Solid Objects they are:
+
+| Dimension        | Solid Objects                                                                      |
+| ---------------- | ---------------------------------------------------------------------------------- |
+| Identity         | An actor class and an application-defined ID                                       |
+| Activation       | On demand, behind a fenced lease, released when idle                               |
+| State storage    | A JSON document in SQLite, PostgreSQL, or MySQL                                    |
+| Serialization    | One durable mailbox for each identity                                              |
+| Delivery         | At least once, in order for each identity                                          |
+| Reminders        | Durable and keyed for each actor                                                   |
+| Recovery         | Another process claims the work after a lease expires; committed work waits in SQL |
+| Deployment       | A library inside the application's Node.js processes                               |
+| Operational cost | One retained message row for each call, plus database load                         |
 
 ## Primary references
 
@@ -37,5 +58,20 @@ smallest mechanism that meets its requirements. It does not rank the projects.
   and its storage requirements in the
   [self-hosted server overview](https://docs.restate.dev/server/overview).
 
+- Dapr documents virtual actors, the actor state store, and Scheduler-backed
+  reminders in [Actors overview](https://docs.dapr.io/developing-applications/building-blocks/actors/actors-overview/)
+  and [Actor timers and reminders](https://docs.dapr.io/developing-applications/building-blocks/actors/actors-timers-reminders/).
+  The [JavaScript SDK](https://docs.dapr.io/developing-applications/sdks/js/js-actors/)
+  supports actors.
+- Temporal documents deterministic replay in
+  [Workflow definition](https://docs.temporal.io/workflow-definition) and its
+  service in [What is Temporal?](https://docs.temporal.io/temporal).
+- Orleans documents virtual actors, turn-based scheduling, and reminders in its
+  [overview](https://learn.microsoft.com/en-us/dotnet/orleans/overview),
+  [Request scheduling](https://learn.microsoft.com/en-us/dotnet/orleans/grains/request-scheduling),
+  and [Timers and reminders](https://learn.microsoft.com/en-us/dotnet/orleans/grains/timers-and-reminders).
+- Node.js documents CPU-bound parallelism in
+  [Worker threads](https://nodejs.org/api/worker_threads.html).
+
 External systems evolve. Recheck these primary sources before relying on one
 row as a procurement or architecture decision.

package/docs/parity.md

@@ -4,7 +4,7 @@ This ledger tracks capability parity with the Ruby `solid_objects` gem.
 Parity preserves a capability and its correctness or security boundary. It does
 not copy a Rails API into Node.
 
-Reference: Ruby `solid_objects` 0.17.0. The JavaScript package began at the Ruby
+Reference: Ruby `solid_objects` 0.17.2. The JavaScript package began at the Ruby
 design's `0.12` capability generation; that version number did not imply earlier
 JavaScript releases.
 
@@ -92,6 +92,7 @@ Ruby publishes RBS contracts with native Ruby field names; this does not change
 | Structured instrumentation                                                    | Native | Versioned events, metric samples, isolated observers, and bounded authorized diagnostics match Ruby. Both test suites check SQL event attributes against `compatibility/telemetry-events.json`; only JS activation events add their turn's message fields. Both runtimes log exporter and observer failures, require observer callbacks, and cap local observers at 1,000. Timeout events share wait reasons, activation owner IDs, and string generations; see [observability](observability.md). Durable Objects uses host instrumentation and remote diagnostics, sends fewer attributes, and does not send `sync.timeout`. |
 | Large committed state warning                                                 | Native | `warnStateBytes` reports one `solid_objects.state.large` event, holding the actor type, actor ID, byte count, and threshold, when a committed image passes a 128 KB soft threshold. The event holds no application state, and it reports after the commit. The Ruby gem carries the same event and the same 5 MB hard default from `0.14.3`, as `warn_state_bytes`. Its threshold defaults to 64 KB rather than 128 KB, because its measured curve falls sooner: it keeps 55% of its empty-state throughput at 13 KB, where this package keeps 98% at 16 KB.                                                                   |
 | Public test helper                                                            | Native | `runtime.testing` provides role-selective deterministic draining, explicit-time due-reminder execution, and dependency-ordered reset without relying on cascades.                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| Clean-install artifact proof                                                  | Native | `pnpm run test:package` installs the packed tarball in a new project. It runs the packaged quickstart, which sends 25 concurrent calls to one identity, and the `examples/ticket-sale.ts` guide example. `pnpm run test:recovery` proves recovery after a worker process stops. Ruby's `rake quickstart` builds the gem, installs it in a new Rails application, and proves ordering and reminder recovery after a runtime restart.                                                                                                                                                                                            |
 
 ## Databases and wake-up
 

package/docs/releasing.md

@@ -35,8 +35,13 @@ npm trust github solid-objects \
    `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:
+3. Read `docs/virtual-actors.md` and `docs/agents.md` against the release.
+   Correct any requirement, compatibility, or guarantee statement that the
+   release changed. `pnpm run check:documentation` fails when the category
+   guide no longer embeds `examples/ticket-sale.ts`, and `pnpm run
+test:package` runs that example against the packed tarball.
+4. Commit and push `main`.
+5. Create and push an annotated tag matching the package version:
 
    ```shell
    git tag -a v0.13.3 -m "Version 0.13.3"
@@ -52,3 +57,9 @@ The job then builds the release notes with `scripts/release-notes.mjs`. That
 script prints the `CHANGELOG.md` section for the tagged version. The job then
 creates the GitHub release for the tag. If you run the job again on a tag that
 npm already holds, it still creates a missing release.
+
+After the tag publishes, refresh the solidobjects.dev documentation snapshot
+from the tag and redeploy the site. The site's `check:release` step refuses a
+snapshot that is not the latest published tag. The Context7 refresh workflow
+refreshes the index after each push to `main` that changes the documentation.
+Confirm that its run succeeded.

package/docs/virtual-actors.md

@@ -0,0 +1,246 @@
+# Virtual actors in TypeScript and Node.js
+
+## Short answer
+
+Yes. Solid Objects is a SQL-backed virtual actor library for TypeScript and
+Node.js. The npm package is `solid-objects`. It gives each actor a stable
+identity, durable state, ordered operations, and automatic activation.
+
+The actor runtime runs in your Node.js processes. State and mailboxes live in
+SQLite, PostgreSQL, or MySQL. It needs no broker, no daemon, no Cloudflare
+account, and no new datastore. Redis is optional and only shortens wake-up
+latency.
+
+Solid Objects is a pre-1.0 release. Read
+[Compatibility and maturity](#compatibility-and-maturity) before you choose it.
+
+## What a virtual actor is
+
+A virtual actor is a logical object that always exists by name. The caller
+does not create it, start it, or stop it. The runtime loads it when a message
+arrives and releases it when it is idle. Microsoft Orleans made this model
+known as "virtual actors".
+
+Solid Objects implements four properties of that model:
+
+| Property             | What it means                                                             | How Solid Objects does it                                                                                                       |
+| -------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| Stable identity      | An actor is addressed by type and ID, for example one room for each game. | `Room.ref("room-7")` returns a reference. The reference does not load the actor.                                                |
+| Automatic activation | The first message activates the actor. An idle actor is released.         | A process claims a fenced activation lease when work arrives. A worker releases it after `idleDeactivationTimeoutMilliseconds`. |
+| Durable state        | State survives process exits and deploys.                                 | Enumerable public fields are a JSON document in SQL.                                                                            |
+| Ordered turns        | One identity runs one operation at a time, in a fixed order.              | Each call is a durable mailbox message with a per-actor sequence number.                                                        |
+
+Different identities run concurrently across processes. One identity is a
+serialization point on purpose.
+
+## A small example
+
+This program holds one ticket for a buyer and releases the hold after ten
+minutes. It uses the SQLite driver that Node.js includes. Save it as
+`ticket-sale.mts`, so that Node.js loads it as an ES module:
+
+```typescript
+import { Actor, configure } from "solid-objects"
+import { sqlite } from "solid-objects/database/sqlite"
+
+const HOLD_MILLISECONDS = 10 * 60 * 1000
+
+export class TicketSale extends Actor {
+  static override readonly actorType = "TicketSale"
+
+  available = 1
+  holds: Record<string, number> = {}
+
+  hold({ buyer }: { buyer: string }): { held: boolean; available: number } {
+    if (this.available === 0 || Object.hasOwn(this.holds, buyer)) {
+      return { held: false, available: this.available }
+    }
+
+    this.available -= 1
+    this.holds = { ...this.holds, [buyer]: Date.now() }
+    this.schedule({ at: new Date(Date.now() + HOLD_MILLISECONDS), key: buyer }).expire({ buyer })
+    return { held: true, available: this.available }
+  }
+
+  expire({ buyer }: { buyer: string }): number {
+    if (!Object.hasOwn(this.holds, buyer)) return this.available
+
+    const remainingHolds = { ...this.holds }
+    delete remainingHolds[buyer]
+    this.holds = remainingHolds
+    this.available += 1
+    return this.available
+  }
+}
+
+const runtime = configure({
+  database: sqlite({ path: process.env.TICKET_DATABASE ?? "tickets.sqlite3" }),
+  authorizeMessage: () => true,
+  authorizeQuery: () => true,
+})
+
+await runtime.install()
+
+try {
+  const sale = TicketSale.ref("event-42")
+
+  if (process.argv[2] === "work") {
+    const controller = new AbortController()
+    process.once("SIGINT", () => controller.abort())
+    process.once("SIGTERM", () => controller.abort())
+    await runtime.run(controller.signal)
+  } else {
+    const buyers = process.argv.length > 3 ? process.argv.slice(3) : ["ada", "grace"]
+    const results = await Promise.all(buyers.map((buyer) => sale.hold({ buyer })))
+    console.log(JSON.stringify(results))
+  }
+} finally {
+  await runtime.close()
+}
+```
+
+Run the background roles in one terminal. Place two concurrent holds in a
+second terminal:
+
+```bash
+npm install solid-objects
+node ticket-sale.mts work
+node ticket-sale.mts hold
+```
+
+The two holds enter the same mailbox and commit one at a time, so only one
+buyer gets the ticket. The hold and its reminder commit in one transaction. If
+the worker stops, the reminder stays in `tickets.sqlite3`. It runs when the
+worker starts again.
+
+The `work` branch can run the reminder because `TicketSale.ref(...)` registers
+the class first. A separate worker process must call
+`runtime.register(TicketSale)` before `runtime.run(signal)`.
+
+The authorization callbacks above allow every caller. Use them only for a
+local example. The package release check runs this file against the packed
+npm tarball. The source is [`examples/ticket-sale.ts`](../examples/ticket-sale.ts).
+
+For more setup, use one of these guides:
+
+- `npx solid-objects quickstart --yes` runs a packaged proof of concurrent
+  calls to one identity.
+- [The README](../README.md#installation) has the installation steps.
+- [The agent guide](agents.md) gives setup and verification steps for coding
+  agents.
+
+## When to use it
+
+Solid Objects is a good candidate when most of these conditions are true:
+
+- Concurrent requests can change the same room, cart, account, device,
+  document, or session.
+- Each identity needs its own ordering boundary and durable mailbox.
+- Work must happen later or continue after a Node.js process exits.
+- A state change must stage reminders, effects, messages to other actors, or
+  realtime updates in the same commit.
+- The application already runs SQLite, PostgreSQL, or MySQL and should keep
+  durable coordination there.
+
+## When to use something else
+
+Do not use an actor when a simpler tool enforces the invariant:
+
+- One short transaction, a constraint, or `SELECT ... FOR UPDATE` is enough.
+- The work is CPU-intensive. Use `worker_threads` or a worker pool. An actor
+  serializes work. It does not add CPU parallelism.
+- One global identity must accept more writes than one sequential mailbox can
+  commit, for example a request-path rate limiter.
+- The state is a large document or a relational dataset.
+- The operation must change two actor identities in one atomic transaction.
+  Solid Objects has no cross-actor transactions.
+- You need exactly-once calls to an external API. No actor library can promise
+  that through every network failure. Solid Objects gives at-least-once
+  delivery and stable effect IDs for idempotency keys.
+- You need replay of named workflow steps from a step log. That is a durable
+  execution engine, not an actor.
+- State must be placed automatically near clients at the network edge.
+
+[Choosing Solid Objects](fit.md) has the full list.
+
+## How it compares
+
+This table compares coordination models for a Node.js application. It does
+not rank the projects. Facts about other projects were checked on
+October 7, 2026, against the sources in [System comparisons](comparisons.md).
+
+| Approach                                   | Unit of order                    | Durable state                                     | Delayed work                                         | Extra service                                                                              |
+| ------------------------------------------ | -------------------------------- | ------------------------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| SQL transaction or row lock                | Rows in one transaction          | Application tables                                | None                                                 | No                                                                                         |
+| Job queue, such as BullMQ or pg-boss       | A job or a queue                 | Owned by the application                          | Scheduled jobs                                       | Redis for BullMQ; PostgreSQL for pg-boss                                                   |
+| `worker_threads` or a pool such as Piscina | None                             | None                                              | None                                                 | No                                                                                         |
+| Solid Objects                              | Actor class and ID               | JSON state in SQLite, PostgreSQL, or MySQL        | Durable per-actor reminders                          | No                                                                                         |
+| Cloudflare Durable Objects                 | Object class and ID              | Per-object storage                                | One alarm for each object                            | Cloudflare's network. The open-source `workerd` runtime hosts objects on one instance only |
+| Dapr actors (`@dapr/dapr`)                 | Actor type and ID                | A transactional Dapr state store                  | Durable reminders through the Dapr Scheduler service | A Dapr sidecar, plus the placement and Scheduler services                                  |
+| Rivet Actors                               | Actor key                        | Actor state, plus per-actor SQLite and KV storage | Scheduled actions                                    | The Rivet Engine, self-hosted or Rivet Cloud                                               |
+| Restate virtual objects                    | Object key, one writer at a time | Restate's state store                             | Durable timers                                       | A Restate server                                                                           |
+| DBOS                                       | A workflow and its steps         | Checkpoints in PostgreSQL                         | Durable sleeps                                       | No server; PostgreSQL is required                                                          |
+| Temporal                                   | A workflow execution             | Temporal event history                            | Durable timers                                       | A Temporal Service, self-hosted or Temporal Cloud                                          |
+
+[System comparisons](comparisons.md) has the full table, with primary
+references for each row.
+
+### Orleans concept map
+
+Orleans is the reference design for virtual actors on .NET. Solid Objects
+uses the same programming model on a SQL database. It does not copy the
+Orleans cluster, placement, or feature set.
+
+| Orleans                      | Solid Objects                                        | Difference                                                                                                                                                                                |
+| ---------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Grain class                  | `Actor` subclass with a static `actorType`           | None in concept                                                                                                                                                                           |
+| Grain identity (key)         | Actor type and actor ID                              | None in concept                                                                                                                                                                           |
+| Activation on first call     | Activation lease on first claimed message            | Solid Objects fences each activation with a database generation                                                                                                                           |
+| Turn-based execution         | Ordered mailbox, one turn at a time                  | Orleans can enable reentrancy. Solid Objects turns for one identity never interleave                                                                                                      |
+| Grain persistence            | Public fields stored as JSON in SQL                  | An Orleans grain calls `WriteStateAsync`. Solid Objects persists state with the turn that changed it                                                                                      |
+| Reminders                    | `schedule()`                                         | Both are durable. Orleans skips a tick that falls due while the cluster is down. A due Solid Objects reminder runs when a runtime process starts. Solid Objects has no non-durable timers |
+| Silos and cluster membership | Any Node.js process that calls `runtime.run(signal)` | Solid Objects has no placement, directory, or cluster membership. The database is the coordination point                                                                                  |
+| Streams                      | Observables and realtime sessions                    | Solid Objects publishes committed revisions through an application-owned transport                                                                                                        |
+
+Solid Objects delivery is at least once. Write each operation so that it can
+run again without harm.
+
+## Guarantees and boundaries
+
+- Calls are durably ordered per identity. Different identities can run
+  concurrently.
+- Delivery is at least once, not exactly once. An operation can start again
+  after a crash or a lost lease.
+- Ordered turns do not cancel stale JavaScript. Fencing stops a stale
+  activation from a commit, but that code can continue to run.
+- External effects can run more than once. Use the stable effect ID, or
+  another durable key, as the idempotency key at the provider.
+- There are no transactions across actor identities, and there is no replay of
+  durable function steps.
+- Reminders, effects, and realtime delivery need a process that calls
+  `runtime.run(signal)`. When no process runs, committed work waits in SQL.
+  The package does not supply a hosted worker.
+- One hot identity is sequential. The core package is not a high-throughput
+  request-path rate limiter.
+- The guarantees apply only to changes made through the actor APIs. Actor
+  fencing does not protect direct writes to the same data or other external
+  requests.
+
+The [correctness contract](correctness.md) states each guarantee and its
+limits.
+
+## Compatibility and maturity
+
+These runtimes have different compatibility statements:
+
+| Surface                                         | Status                                                                                                                                         |
+| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| Node.js SQL runtime                             | Node.js 24.4 or newer, ESM only, TypeScript 5.9 or newer. SQLite through `node:sqlite`, PostgreSQL 14 or newer, MySQL 8.0 or newer with InnoDB |
+| Browser client (`solid-objects/browser`)        | A subscription client for a server runtime. It is not the SQL actor runtime                                                                    |
+| Browser runtime (`solid-objects/browser/host`)  | The actor runtime in a browser module worker on SQLite WASM. Tested in Chromium                                                                |
+| Cloudflare backend (`solid-objects/cloudflare`) | Experimental. It runs the actor API on Cloudflare Durable Objects, with different capability limits                                            |
+
+The package is pre-1.0. It has one deployed first-party reference
+application, no measured scale, and no known third-party production use.
+[Supported versions](support.md) lists the CI matrix. For Ruby on Rails, use
+the [solid_objects](https://github.com/cardmagic/solid-objects-ruby) gem.

package/examples/ticket-sale.ts

@@ -0,0 +1,57 @@
+import { Actor, configure } from "solid-objects"
+import { sqlite } from "solid-objects/database/sqlite"
+
+const HOLD_MILLISECONDS = 10 * 60 * 1000
+
+export class TicketSale extends Actor {
+  static override readonly actorType = "TicketSale"
+
+  available = 1
+  holds: Record<string, number> = {}
+
+  hold({ buyer }: { buyer: string }): { held: boolean; available: number } {
+    if (this.available === 0 || Object.hasOwn(this.holds, buyer)) {
+      return { held: false, available: this.available }
+    }
+
+    this.available -= 1
+    this.holds = { ...this.holds, [buyer]: Date.now() }
+    this.schedule({ at: new Date(Date.now() + HOLD_MILLISECONDS), key: buyer }).expire({ buyer })
+    return { held: true, available: this.available }
+  }
+
+  expire({ buyer }: { buyer: string }): number {
+    if (!Object.hasOwn(this.holds, buyer)) return this.available
+
+    const remainingHolds = { ...this.holds }
+    delete remainingHolds[buyer]
+    this.holds = remainingHolds
+    this.available += 1
+    return this.available
+  }
+}
+
+const runtime = configure({
+  database: sqlite({ path: process.env.TICKET_DATABASE ?? "tickets.sqlite3" }),
+  authorizeMessage: () => true,
+  authorizeQuery: () => true,
+})
+
+await runtime.install()
+
+try {
+  const sale = TicketSale.ref("event-42")
+
+  if (process.argv[2] === "work") {
+    const controller = new AbortController()
+    process.once("SIGINT", () => controller.abort())
+    process.once("SIGTERM", () => controller.abort())
+    await runtime.run(controller.signal)
+  } else {
+    const buyers = process.argv.length > 3 ? process.argv.slice(3) : ["ada", "grace"]
+    const results = await Promise.all(buyers.map((buyer) => sale.hold({ buyer })))
+    console.log(JSON.stringify(results))
+  }
+} finally {
+  await runtime.close()
+}

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "solid-objects",
-  "version": "0.17.0",
-  "description": "Race-free realtime state per application identity, backed by your SQL database",
+  "version": "0.17.2",
+  "description": "SQL-backed virtual actor library for TypeScript and Node.js, with durable state, ordered operations, and automatic activation on SQLite, PostgreSQL, or MySQL",
   "type": "module",
   "license": "MIT",
   "author": "Lucas Carlson",
+  "homepage": "https://solidobjects.dev/js",
   "keywords": [
     "concurrency",
     "durable-state",
@@ -16,7 +17,9 @@
     "state-management",
     "typescript",
     "actors",
-    "durable-objects"
+    "durable-objects",
+    "virtual-actors",
+    "actor-model"
   ],
   "repository": {
     "type": "git",