solid-objects 0.17.1 → 0.17.3

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # Changelog
 
+## 0.17.3 - 2026-10-08
+
+- `docs/agents.md` has a new step 12 for the browser runtime. It covers when
+  the browser runtime fits, the install with `@sqlite.org/sqlite-wasm`, the
+  entry points, a module worker example, authorization in the browser, the
+  platform limits, transmit to a Node.js or Rails server, and the checks.
+- `examples/browser/draft-worker.js` and `examples/browser/page.js` are the
+  guide example. The Chromium suite runs them: state survives a reload, two
+  tabs share one draft, and the second tab continues after the holder tab
+  closes. `pnpm run check:documentation` fails when the guide does not embed
+  the current files.
+- The example keeps short lease settings. With the default settings, a call
+  from the remaining tab timed out while it waited for the lease of the closed
+  tab.
+- The documentation link check skips fenced code blocks, so code such as
+  `ref[operation](value)` is not read as a link.
+- Correct the transmit docs: `registerTransmit` never reads the HTTP response,
+  so a server 422 stops retries only when the `deliver` callback throws
+  `NonRetryableError`. The agent guide shows that callback, `docs/api.md` says
+  so, and a new test proves that `NonRetryableError` from `deliver`
+  dead-letters the effect after one attempt, where a plain `Error` retries.
+- The page example rejects every waiting and later call when the worker fails
+  to load. Before, a call waited with no end.
+
+## 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

package/README.md

@@ -49,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

package/dist/version.d.ts

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

package/dist/version.js

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

package/docs/agents.md

@@ -55,6 +55,9 @@ with Cloudflare.
 - Redis is optional. It only shortens wake-up latency and holds no durable
   state.
 
+The browser runtime has different requirements. See
+[step 12](#12-use-the-browser-runtime).
+
 [Supported versions](support.md) lists the CI matrix.
 
 ## 4. Install
@@ -68,6 +71,10 @@ 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
@@ -81,7 +88,9 @@ const runtime = configure({
 await runtime.install()
 ```
 
-[Configuration](configuration.md) lists each option and database adapter.
+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
 
@@ -184,13 +193,26 @@ Obey these rules in actor code:
   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.
+- 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.
@@ -206,13 +228,25 @@ runs in the caller. These features need a process that calls
 - 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.
@@ -294,7 +328,234 @@ When you explain Solid Objects to a user, state these limits:
   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.
+- `solid-objects/browser` is a WebSocket client, not the SQL runtime. The
+  browser runtime in step 12 is tested in Chromium only. The Cloudflare backend
+  is experimental.
 
 The [correctness contract](correctness.md) is the source for each guarantee.
+
+## 12. Use the browser runtime
+
+The same `Actor` classes run in a browser module worker. The database is SQLite
+WASM. Persistent state is in the origin private file system (OPFS), so it
+survives a page reload.
+
+Use the browser runtime when one identity in the browser, such as a draft, a
+game, or a form, must keep its state across reloads and tabs. It also fits
+writes that must wait on the device until the network returns. Select a simpler
+tool in these cases:
+
+| Requirement                              | Use instead                                     |
+| ---------------------------------------- | ----------------------------------------------- |
+| A preference or another small value      | `localStorage`                                  |
+| A cache of server responses              | The Cache API or IndexedDB                      |
+| State that must be correct for all users | A server runtime. The user controls the browser |
+| Live updates from a server runtime only  | `solid-objects/browser`, the WebSocket client   |
+
+### Install
+
+```bash
+npm install solid-objects @sqlite.org/sqlite-wasm
+```
+
+`@sqlite.org/sqlite-wasm` 3.50 or newer is an optional peer dependency. The
+browser runtime needs it.
+
+### Choose the entry point
+
+| Need                                            | Use                                                                                                               |
+| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| The runtime in a worker                         | `solid-objects/browser/host`. It exports `Actor`, `configure`, `sqliteWasm`, `sharedSqliteWasm`, and the tab host |
+| One database for all tabs, a worker in each tab | `sharedSqliteWasm({ path })`. Storage is persistent by default                                                    |
+| One worker in one tab only                      | `sqliteWasm({ path, storage: "persistent" })`. The default storage is `"temporary"`                               |
+| One runtime for all tabs, with a leader tab     | `startTabHost()` and `connectTabClient()` from `solid-objects/browser/tab-host`                                   |
+| Send local writes to a server                   | `this.transmit()` and `registerTransmit()`. See [Send writes to a server](#send-writes-to-a-server)               |
+
+### Example
+
+This module worker hosts the runtime. Each tab starts one copy.
+`sharedSqliteWasm` elects one tab to hold the database. The other tabs send
+their SQL to that tab, and a new tab takes over when it closes.
+
+```javascript
+import { Actor, configure, sharedSqliteWasm } from "solid-objects/browser/host"
+
+class NoteDraft extends Actor {
+  static actorType = "NoteDraft"
+
+  text = ""
+  revision = 0
+
+  edit({ text }) {
+    this.text = text
+    this.revision += 1
+    return this.revision
+  }
+}
+
+const allowNoteDrafts = ({ actorType }) => actorType === "NoteDraft"
+
+const runtime = configure({
+  database: sharedSqliteWasm({ path: "notes.db" }),
+  authorizeMessage: allowNoteDrafts,
+  authorizeQuery: allowNoteDrafts,
+  processAliveThresholdMilliseconds: 750,
+  leaseDurationMilliseconds: 750,
+  leaseRenewalIntervalMilliseconds: 250,
+})
+runtime.register(NoteDraft)
+const installed = runtime.install()
+installed.then(() => runtime.run(new AbortController().signal))
+
+self.onmessage = async (event) => {
+  const { requestId, actorId, operation, argumentsValue } = event.data
+  try {
+    await installed
+    const value = await NoteDraft.ref(actorId)[operation](argumentsValue)
+    postMessage({ requestId, ok: true, value })
+  } catch (error) {
+    postMessage({ requestId, ok: false, message: String(error?.message ?? error) })
+  }
+}
+```
+
+The page sends messages to the worker. It does not hold actor references:
+
+```javascript
+const worker = new Worker(new URL("./draft-worker.js", import.meta.url), { type: "module" })
+const pending = new Map()
+let nextRequestId = 0
+let workerFailure
+
+worker.onmessage = (event) => {
+  const { requestId, ok, value, message } = event.data
+  const request = pending.get(requestId)
+  pending.delete(requestId)
+  if (ok) {
+    request.resolve(value)
+    return
+  }
+  request.reject(new Error(message))
+}
+
+worker.onerror = (event) => {
+  workerFailure = new Error(`The actor worker failed: ${event.message || "it did not load"}`)
+  for (const request of pending.values()) request.reject(workerFailure)
+  pending.clear()
+}
+
+export function callActor({ actorId, operation, argumentsValue }) {
+  if (workerFailure) return Promise.reject(workerFailure)
+  const requestId = nextRequestId++
+  return new Promise((resolve, reject) => {
+    pending.set(requestId, { resolve, reject })
+    worker.postMessage({ requestId, actorId, operation, argumentsValue })
+  })
+}
+```
+
+CI runs this example in Chromium. It checks that state survives a reload, that
+two tabs share one draft, and that the second tab continues after the first
+tab closes.
+
+A closed tab does not shut down its runtime. Keep the short lease settings in
+the example. With the default settings, the next tab waits for the old lease,
+and calls time out before it expires.
+
+### Authorize in the browser
+
+The page and the worker run on the user's device, and the user can change
+their code. A browser policy limits what your own page can call. It is not a
+security boundary. Authorize again on the server for each write that leaves the
+device.
+
+### Rules for browser actors
+
+- One worker hosts one runtime. Do not import `solid-objects/browser/host` in
+  a process that also imports the Node.js entry points.
+- After the first `await` in an operation, `currentActor()`,
+  `applicationWritesForbidden()`, and the database deadline read as unset. Keep
+  guarded writes in synchronous actor code or in commit actions.
+- Reminders and effects run only while a worker that calls
+  `runtime.run(signal)` is alive. When the user closes every tab, nothing runs.
+- With `sharedSqliteWasm`, a statement can fail with `SharedDatabaseFailover`
+  when the holder tab closes during the statement. Write operations so that
+  they can run again, and retry the call.
+- With `startTabHost()`, close the database in a `catch` block when
+  `startRuntime` fails. An open database blocks the next tab.
+
+### Platform limits
+
+- CI tests the browser runtime in Chromium only. Safari 16.4 and Firefox 111
+  added the OPFS API that persistent storage needs. Test on each engine that
+  you support.
+- Persistent storage needs a secure context (HTTPS or `localhost`) and a
+  dedicated worker. `storage: "persistent"` fails fast where OPFS is missing.
+- An embedded WebView, such as Cordova, WKWebView, or Android WebView, can lack
+  OPFS when the device browser has it. Test the WebView itself.
+- The browser can clear the storage of an origin. Call
+  `navigator.storage.persist()` to ask it to keep the data, and send important
+  writes to a server.
+
+### Send writes to a server
+
+An operation stages a write for the server in the same transaction as its
+state change:
+
+```javascript
+this.transmit().edit({ text })
+```
+
+`registerTransmit({ runtime, deliver })` sends each staged write to the server.
+The runtime does not read the HTTP response. Your `deliver` callback decides
+what happens:
+
+```javascript
+import { NonRetryableError } from "solid-objects/core"
+import { registerTransmit } from "solid-objects/browser/host"
+
+registerTransmit({
+  runtime,
+  deliver: async (envelope) => {
+    const response = await fetch("/sync", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(envelope),
+    })
+    if (response.status === 422) {
+      throw new NonRetryableError(`The server rejected effect ${envelope.effectId}`)
+    }
+    if (!response.ok) throw new Error(`Sync failed with HTTP ${response.status}`)
+  },
+})
+```
+
+- A normal return marks the write as delivered.
+- An `Error` makes the effect try again later. This is the offline case.
+- A `NonRetryableError` moves the effect to dead letters with no retry.
+
+Set a high `maxAttempts` in `configure()`, because the default is 5 and a long
+offline period can use all attempts. Run one effect worker for each local
+runtime to keep the order of writes for each actor.
+
+The server receives the write with `receiveTransmitEnvelope({ runtime, envelope })`
+in Node.js, or with `SolidObjects::Transmission.receive(envelope)` in Rails.
+Authenticate the device before this call, because this delivery skips
+`authorizeMessage`. Delivery is at least once. The server applies a repeated
+write once, because it uses the effect ID as the idempotency key. In Node.js,
+return HTTP 422 for `InvalidPayload` and `IdempotencyConflict`. The `deliver`
+callback above turns that status into a `NonRetryableError`, so the device
+stops the retries.
+
+The [public API](api.md#solid-objectstransmit) and the
+[browser protocol](browser-protocol.md) give the full contract.
+
+### Verify a browser implementation
+
+1. Call an operation, reload the page, and confirm that the state is the same.
+2. Send concurrent calls to one identity from two tabs. Assert the final state.
+3. Close the tab that holds the database. Confirm that the other tab continues.
+4. On each target engine, confirm that persistent storage opens, or fails with
+   a clear error.
+5. If you send writes to a server, confirm that the server rejects a device
+   that it cannot authenticate, and applies a repeated write once.

package/docs/api.md

@@ -961,11 +961,13 @@ outbox with at-least-once delivery, per-actor order, and retry backoff.
   ```
 
   The example uses a Fetch-style handler; any HTTP framework works. The 422
-  matters: it tells the sending outbox to dead-letter the effect instead of
-  retrying it. `InvalidPayload` marks a malformed envelope, and
-  `IdempotencyConflict` marks a replay whose arguments changed; both are
-  permanently unappliable, and a 500 would make the outbox retry them
-  forever.
+  matters only when the sending `deliver` callback reads it:
+  `registerTransmit` never sees the HTTP response. Throw `NonRetryableError`
+  (from `solid-objects/core` in a browser) for a 422, and the outbox
+  dead-letters the effect instead of retrying it; any other error retries.
+  `InvalidPayload` marks a malformed envelope, and `IdempotencyConflict`
+  marks a replay whose arguments changed; both are permanently unappliable,
+  and a 500 would make the outbox retry them until `maxAttempts` runs out.
 
 - Per-actor order comes from an ordered drain: a claimed transmit effect
   transmits every undelivered envelope for its actor up to its own mailbox

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.1. 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.
 

package/docs/releasing.md

@@ -38,8 +38,10 @@ npm trust github solid-objects \
 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.
+   guide no longer embeds `examples/ticket-sale.ts`, or when the agent guide
+   no longer embeds the files in `examples/browser/`. `pnpm run test:package`
+   runs the ticket sale example against the packed tarball, and
+   `pnpm run test:browser` runs the browser example in Chromium.
 4. Commit and push `main`.
 5. Create and push an annotated tag matching the package version:
 
@@ -60,5 +62,6 @@ 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. Then trigger a Context7 refresh
-for this repository.
+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

@@ -113,6 +113,10 @@ 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).

package/examples/browser/draft-worker.js

@@ -0,0 +1,39 @@
+import { Actor, configure, sharedSqliteWasm } from "solid-objects/browser/host"
+
+class NoteDraft extends Actor {
+  static actorType = "NoteDraft"
+
+  text = ""
+  revision = 0
+
+  edit({ text }) {
+    this.text = text
+    this.revision += 1
+    return this.revision
+  }
+}
+
+const allowNoteDrafts = ({ actorType }) => actorType === "NoteDraft"
+
+const runtime = configure({
+  database: sharedSqliteWasm({ path: "notes.db" }),
+  authorizeMessage: allowNoteDrafts,
+  authorizeQuery: allowNoteDrafts,
+  processAliveThresholdMilliseconds: 750,
+  leaseDurationMilliseconds: 750,
+  leaseRenewalIntervalMilliseconds: 250,
+})
+runtime.register(NoteDraft)
+const installed = runtime.install()
+installed.then(() => runtime.run(new AbortController().signal))
+
+self.onmessage = async (event) => {
+  const { requestId, actorId, operation, argumentsValue } = event.data
+  try {
+    await installed
+    const value = await NoteDraft.ref(actorId)[operation](argumentsValue)
+    postMessage({ requestId, ok: true, value })
+  } catch (error) {
+    postMessage({ requestId, ok: false, message: String(error?.message ?? error) })
+  }
+}

package/examples/browser/page.js

@@ -0,0 +1,30 @@
+const worker = new Worker(new URL("./draft-worker.js", import.meta.url), { type: "module" })
+const pending = new Map()
+let nextRequestId = 0
+let workerFailure
+
+worker.onmessage = (event) => {
+  const { requestId, ok, value, message } = event.data
+  const request = pending.get(requestId)
+  pending.delete(requestId)
+  if (ok) {
+    request.resolve(value)
+    return
+  }
+  request.reject(new Error(message))
+}
+
+worker.onerror = (event) => {
+  workerFailure = new Error(`The actor worker failed: ${event.message || "it did not load"}`)
+  for (const request of pending.values()) request.reject(workerFailure)
+  pending.clear()
+}
+
+export function callActor({ actorId, operation, argumentsValue }) {
+  if (workerFailure) return Promise.reject(workerFailure)
+  const requestId = nextRequestId++
+  return new Promise((resolve, reject) => {
+    pending.set(requestId, { resolve, reject })
+    worker.postMessage({ requestId, actorId, operation, argumentsValue })
+  })
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solid-objects",
-  "version": "0.17.1",
+  "version": "0.17.3",
   "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",