solid-objects 0.13.3 → 0.14.0

package/docs/benchmarks.md

@@ -83,72 +83,93 @@ dataset. Redirect stdout to retain the JSON result.
 
 ## Observed results
 
-Measured on August 15, 2026 with the prepared `0.13.0` source tree:
-
-- Apple M5, 10 logical CPUs, 24 GiB memory
-- macOS 26.6 (`darwin 25.6.0`)
-- Node.js 26.7.0
-- SQLite 3.53.4 on the internal SSD, PostgreSQL 18.4 and MySQL 8.4.11 in
-  Docker Desktop
+Measured on August 22, 2026 with the `0.14.0` source tree:
+
+- Apple M5 (Mac17,2), 10 logical CPUs
+- macOS 26.6
+- Node.js 24.18.0
+- SQLite 3.53.1 through `node:sqlite` on the internal SSD
+- PostgreSQL 17.11 and MySQL 9.7.1, both installed natively and started on a
+  scoped temporary data directory
 - 25 warmup operations, 250 measured operations, concurrency 16
 
-### SQLite 3.53.4
-
-| Topology       | Shape     | Handler      |  ops/s | p50 ms |  p95 ms |  p99 ms |
-| -------------- | --------- | ------------ | -----: | -----: | ------: | ------: |
-| one process    | warm hot  | synchronous  |  95.51 |  35.34 | 1159.07 | 1711.76 |
-| one process    | warm hot  | asynchronous | 448.63 |  35.96 |   38.95 |   41.47 |
-| one process    | warm many | synchronous  |  44.35 | 141.55 | 1886.35 | 2543.15 |
-| one process    | warm many | asynchronous | 240.64 |  48.62 |   75.10 |  671.64 |
-| one process    | cold many | synchronous  |  30.91 | 436.98 | 1502.26 | 1729.10 |
-| one process    | cold many | asynchronous |  57.15 | 167.36 |  967.74 | 1066.49 |
-| four processes | warm hot  | synchronous  | 453.10 |  27.24 |   72.09 |   77.88 |
-| four processes | warm hot  | asynchronous | 487.39 |  29.27 |   60.66 |   68.28 |
-| four processes | warm many | synchronous  |  78.88 |  86.33 |  890.29 | 1381.65 |
-| four processes | warm many | asynchronous |  47.56 | 220.37 | 1130.53 | 1341.86 |
-| four processes | cold many | synchronous  |  70.45 | 174.67 |  643.53 |  668.46 |
-| four processes | cold many | asynchronous |  39.92 | 221.01 | 1309.13 | 1442.30 |
-
-### PostgreSQL 18.4
-
-| Topology       | Shape     | Handler      | ops/s |  p50 ms |  p95 ms |  p99 ms |
-| -------------- | --------- | ------------ | ----: | ------: | ------: | ------: |
-| one process    | warm hot  | synchronous  | 66.99 |  232.89 |  317.94 |  375.68 |
-| one process    | warm hot  | asynchronous | 72.27 |  211.57 |  280.89 |  316.61 |
-| one process    | warm many | synchronous  | 76.69 |  129.88 |  552.01 | 1963.27 |
-| one process    | warm many | asynchronous | 25.78 |  340.96 | 2326.38 | 6917.26 |
-| one process    | cold many | synchronous  | 12.70 | 1262.08 | 1734.77 | 2199.20 |
-| one process    | cold many | asynchronous | 11.23 | 1254.46 | 2796.81 | 2905.99 |
-| four processes | warm hot  | synchronous  | 83.71 |  191.83 |  220.87 |  231.84 |
-| four processes | warm hot  | asynchronous | 86.42 |  184.56 |  210.11 |  215.48 |
-| four processes | warm many | synchronous  | 95.47 |  100.31 |  330.27 | 1663.84 |
-| four processes | warm many | asynchronous | 37.04 |  232.71 | 1601.29 | 4447.85 |
-| four processes | cold many | synchronous  | 14.79 | 1114.18 | 1263.33 | 1313.70 |
-| four processes | cold many | asynchronous | 11.68 | 1231.94 | 2555.34 | 2848.80 |
-
-### MySQL 8.4.11
-
-| Topology       | Shape     | Handler      | ops/s |  p50 ms |  p95 ms |  p99 ms |
-| -------------- | --------- | ------------ | ----: | ------: | ------: | ------: |
-| one process    | warm hot  | synchronous  | 28.11 |  504.36 | 1648.10 | 2088.05 |
-| one process    | warm hot  | asynchronous | 25.29 |  508.26 | 1750.17 | 2222.72 |
-| one process    | warm many | synchronous  | 61.79 |  165.62 |  463.59 | 2036.31 |
-| one process    | warm many | asynchronous | 22.45 |  446.17 | 2420.92 | 7818.65 |
-| one process    | cold many | synchronous  | 10.23 | 1353.37 | 3038.76 | 3185.15 |
-| one process    | cold many | asynchronous | 10.04 | 1338.31 | 3344.18 | 3477.06 |
-| four processes | warm hot  | synchronous  | 29.89 |  427.18 | 1483.88 | 1997.56 |
-| four processes | warm hot  | asynchronous | 27.59 |  448.16 | 1518.00 | 1589.57 |
-| four processes | warm many | synchronous  | 69.77 |  157.79 |  410.83 | 2263.13 |
-| four processes | warm many | asynchronous | 36.21 |  265.24 | 1579.43 | 4594.33 |
-| four processes | cold many | synchronous  | 13.68 | 1088.93 | 2186.30 | 2519.92 |
-| four processes | cold many | asynchronous | 11.38 | 1209.84 | 2532.38 | 2730.74 |
-
-The poor throughput and tail latency in cold and asynchronous cases are
-observed limitations, not capacity recommendations. The small asynchronous
-yield changed scheduling enough to improve some cases and worsen others;
-repeat runs on application-shaped payloads are required before drawing a
-general conclusion. PostgreSQL 14, MySQL 8.0, and other database versions are
-covered by integration tests but were not benchmarked.
+### SQLite 3.53.1
+
+| Topology       | Shape     | Handler      |  ops/s | p50 ms | p95 ms | p99 ms |
+| -------------- | --------- | ------------ | -----: | -----: | -----: | -----: |
+| one process    | warm hot  | synchronous  | 286.09 |  50.09 | 135.15 | 176.55 |
+| one process    | warm hot  | asynchronous | 322.53 |  48.66 |  70.59 |  75.87 |
+| one process    | warm many | synchronous  | 119.05 | 132.25 | 237.52 | 247.05 |
+| one process    | warm many | asynchronous | 288.26 |  32.64 |  70.33 | 562.42 |
+| one process    | cold many | synchronous  |  47.67 | 326.04 | 435.46 | 507.03 |
+| one process    | cold many | asynchronous |  99.39 |    148 | 236.03 | 295.26 |
+| four processes | warm hot  | synchronous  | 518.66 |  30.15 |  52.73 |  78.57 |
+| four processes | warm hot  | asynchronous |  506.8 |  26.39 |  92.26 | 102.18 |
+| four processes | warm many | synchronous  | 190.36 |  76.65 |  145.7 | 158.94 |
+| four processes | warm many | asynchronous |  77.12 |  194.6 | 399.43 |  527.1 |
+| four processes | cold many | synchronous  |  54.74 | 273.33 | 646.68 | 650.09 |
+| four processes | cold many | asynchronous |  93.85 | 145.27 | 333.78 |  426.6 |
+
+### PostgreSQL 17.11
+
+| Topology       | Shape     | Handler      |  ops/s | p50 ms | p95 ms |  p99 ms |
+| -------------- | --------- | ------------ | -----: | -----: | -----: | ------: |
+| one process    | warm hot  | synchronous  | 206.31 |  69.33 | 132.69 |  153.03 |
+| one process    | warm hot  | asynchronous | 212.07 |  72.38 |  96.75 |  106.12 |
+| one process    | warm many | synchronous  |  191.4 |  55.71 | 147.99 |   722.6 |
+| one process    | warm many | asynchronous |   66.6 | 121.61 | 920.97 | 2441.28 |
+| one process    | cold many | synchronous  |  31.38 | 500.73 | 705.15 |  722.54 |
+| one process    | cold many | asynchronous |  17.24 | 909.02 | 1192.9 | 1211.35 |
+| four processes | warm hot  | synchronous  | 265.63 |  57.94 |  82.52 |  109.46 |
+| four processes | warm hot  | asynchronous | 330.94 |  46.81 |  63.76 |   70.25 |
+| four processes | warm many | synchronous  | 161.73 |  58.67 | 237.04 |  718.55 |
+| four processes | warm many | asynchronous | 119.63 |  68.71 | 531.12 |  1372.5 |
+| four processes | cold many | synchronous  |  50.84 | 314.51 | 487.09 |  506.45 |
+| four processes | cold many | asynchronous |  29.93 |  546.7 | 615.36 |   638.1 |
+
+### MySQL 9.7.1
+
+| Topology       | Shape     | Handler      |  ops/s |  p50 ms |  p95 ms |  p99 ms |
+| -------------- | --------- | ------------ | -----: | ------: | ------: | ------: |
+| one process    | warm hot  | synchronous  |  79.59 |  208.66 |  222.86 |  225.19 |
+| one process    | warm hot  | asynchronous |  79.98 |  206.78 |  232.74 |  237.94 |
+| one process    | warm many | synchronous  |   79.7 |  129.25 |  395.52 | 1987.46 |
+| one process    | warm many | asynchronous |  28.06 |  338.85 | 1992.54 | 6004.98 |
+| one process    | cold many | synchronous  |  13.78 | 1215.91 | 1445.61 | 1470.91 |
+| one process    | cold many | asynchronous |  11.63 | 1347.74 | 1733.01 | 1820.26 |
+| four processes | warm hot  | synchronous  | 213.75 |   72.85 |   94.48 |  106.73 |
+| four processes | warm hot  | asynchronous | 228.32 |   70.45 |   84.96 |   90.39 |
+| four processes | warm many | synchronous  | 105.31 |   90.36 |  297.88 | 1064.14 |
+| four processes | warm many | asynchronous |  80.03 |  149.92 |  324.98 | 1090.95 |
+| four processes | cold many | synchronous  |  51.82 |   306.1 |  407.22 |  424.45 |
+| four processes | cold many | asynchronous |  27.35 |  554.03 |  807.18 |  868.48 |
+
+The cold and asynchronous cases keep the poorest throughput and the longest
+tail. These are observed limitations. They are not capacity recommendations.
+Repeat the runs on application-shaped payloads before you draw a general
+conclusion. Integration tests cover PostgreSQL 14, MySQL 8.0, and other database
+versions, but this harness did not measure them.
+
+### Virtualization cost
+
+The same server version ran natively and in Docker Desktop on the same machine,
+on the same day, through the same harness. Only the container boundary changes.
+
+| Database         | Topology and shape              | Native ops/s | Docker ops/s | Native gain |
+| ---------------- | ------------------------------- | -----------: | -----------: | ----------: |
+| PostgreSQL 17.11 | four processes, warm hot, async |       330.94 |        67.69 |        4.9x |
+| PostgreSQL 17.11 | one process, warm hot, sync     |       206.31 |        56.44 |        3.7x |
+| MySQL 9.7.1      | four processes, warm hot, async |       228.32 |        60.27 |        3.8x |
+| MySQL 9.7.1      | one process, warm hot, sync     |        79.59 |        44.56 |        1.8x |
+
+Across the full matrix, Docker Desktop cost between 1.0x and 7.8x of the native
+throughput. The multi-process rows lose the most, because more connections and
+more commits cross the container boundary. Measure a database on the deployment
+shape you intend to run, and state the boundary with any number you publish.
+
+Earlier releases of this document reported PostgreSQL 18.4 and MySQL 8.4.11 in
+Docker Desktop on the `0.13.0` tree. Those numbers measured the container as
+much as the database, so the tables above replace them.
 
 ## Sources of bias
 
@@ -156,7 +177,8 @@ covered by integration tests but were not benchmarked.
 - Loopback database connections exclude production network latency.
 - Filesystem cache, SQLite WAL state, Node JIT warmup, and garbage collection
   affect short runs.
-- Docker Desktop adds virtualization overhead to containerized databases.
+- Docker Desktop costs between 1.0x and 7.8x of the native throughput. The
+  tables above use native servers. See [Virtualization cost](#virtualization-cost).
 - The payload is a small counter, not a representative application state size.
 - The harness measures default durability settings and one client concurrency.
 - Hot-identity results deliberately include serialization and cannot be scaled

package/docs/browser-protocol.md

@@ -79,9 +79,9 @@ stale revisions within an incarnation.
 
 `SolidObjectsComponentRegistry` maps changed observable names to keyed UI
 registrations. The browser supplies an asynchronous `refresh` function and a
-synchronous `apply` function, so HTML, virtual DOM, and framework-native render
-results use the same coordination contract without assuming a rendering
-framework.
+synchronous `apply` function. HTML, virtual DOM, and framework-native render
+results therefore use the same coordination contract. The registry assumes no
+render framework.
 
 Components may share a batch name. A microtask unions affected components in
 the same actor, batch, incarnation, and revision into one refresh request.
@@ -105,3 +105,62 @@ several WebSocket processes, the configured `broadcast` callback publishes the
 committed envelope through a shared transport and each process passes received
 envelopes to `runtime.realtime.publish()`. The session fence safely drops the
 duplicate seen by a process that both claimed and received the same event.
+
+## Tab host channel protocol
+
+`solid-objects/browser/tab-host` uses a second, unrelated wire surface: a
+`BroadcastChannel` between tabs of one origin. Every envelope carries
+`protocol: "solid-objects-tab-host"` and `version: 1`; a listener ignores
+anything else. Three kinds exist:
+
+- `invoke`: a client request with a `requestId` (a UUID the client generates),
+  the target `actorType`, `actorId`, `operation`, and a JSON `arguments`
+  object.
+- `result`: the leader's answer for one `requestId`, with either an `ok`
+  value or a named error.
+- `leader-online`: the announcement a new leader posts on promotion. Clients
+  re-post their pending requests when they see it.
+
+The client retries an `invoke` on an interval until a `result` arrives or its
+timeout passes. The leader enqueues each request with `tab:<requestId>` as the
+idempotency key, so a retried or re-posted request applies once. The channel
+is same-origin plumbing between the application's own tabs; it carries no
+authentication, so the trust boundary is the origin.
+
+## Sync envelope
+
+`solid-objects/transmit` transmits one JSON envelope per staged transmit
+effect: `effectId`, target `actorType` and `actorId`, `operation`, and an
+optional `arguments` object that defaults to an empty object on both
+ingests. The transport belongs to the host application; the
+Playwright suite posts envelopes over `fetch`. The server calls
+`receiveTransmitEnvelope`, which enqueues an internal message with
+`transmit:<effectId>` as the idempotency key, so a replayed envelope applies once.
+Internal delivery skips `authorizeMessage`; the host must authenticate the
+sender before that call.
+
+## Shared database channel protocol
+
+`solid-objects/database/shared-sqlite-wasm` uses a third wire surface: a
+`BroadcastChannel` that carries SQL sessions from every tab to the current
+database holder. Every envelope carries
+`protocol: "solid-objects-shared-sqlite"` and `version: 1`. Seven kinds
+exist:
+
+- `ping` and `pong`: holder discovery. A new instance pings until a holder
+  answers with its `epoch`.
+- `holder-online`: the announcement a new holder posts on promotion, with a
+  fresh `epoch`.
+- `open`: start a session (`connection` or `transaction`) with a client
+  `sessionId`.
+- `statement`: one `run`, `get`, `all`, or `now` operation inside a session.
+- `close`: finish a session with `commit`, `rollback`, or `end`.
+- `result`: the holder's answer for one `requestId`.
+
+Every request carries the `epoch` it targets. A holder rejects requests from
+another epoch, so a client learns about a failover from a fast rejection
+rather than a timeout. A session that has not executed a statement retries
+against the new holder automatically; later failures surface as
+`SharedDatabaseFailover`, because a partially executed session must not
+replay. The channel is same-origin plumbing with the origin as its trust
+boundary, the same as the tab host protocol.

package/docs/comparisons.md

@@ -3,15 +3,16 @@
 This guide compares coordination models so an application can choose the
 smallest mechanism that meets its requirements. It does not rank the projects.
 
-| Approach                    | State and serialization unit             | Deployment and durable substrate                                          | Separate service                                                                           | Replay versus state                                                | Realtime and edge placement                                           | Cross-identity transaction                                     | Data access                                                     |
-| --------------------------- | ---------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ | --------------------------------------------------------------------- | -------------------------------------------------------------- | --------------------------------------------------------------- |
-| SQL transaction or row lock | Rows selected by one transaction         | Application process and SQL database                                      | No                                                                                         | The application retries a failed transaction                       | Application-owned                                                     | Yes, for rows in the same database transaction                 | Ordinary application tables and SQL tools                       |
-| Traditional job queue       | A job, queue, or configured grouping key | Workers plus broker or queue database                                     | Usually                                                                                    | The job is retried; mutable entity state remains application-owned | Application-owned                                                     | Not supplied by the queue                                      | Queue administration plus application data stores               |
-| Solid Objects               | Actor class and application-defined ID   | Node processes plus existing SQLite, PostgreSQL, or MySQL                 | No; Redis wake-up is optional                                                              | The operation retries against durable actor state                  | Committed projections; application-owned transport; no edge placement | No                                                             | Relational tables, typed administration, CLI, and dashboard     |
-| Cloudflare Durable Objects  | Object class and globally unique ID      | Cloudflare Workers plus per-object managed storage                        | Cloudflare platform                                                                        | Object activation with durable state, not workflow-step replay     | WebSockets and Cloudflare-selected object location                    | Storage transactions are scoped to one object                  | Object storage APIs and platform tooling                        |
-| 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 |
-| 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               |
+| Approach                    | State and serialization unit             | Deployment and durable substrate                                                   | Separate service                                                                           | Replay versus state                                                             | Realtime and edge placement                                                                | Cross-identity transaction                                     | Data access                                                         |
+| --------------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------- | ------------------------------------------------------------------- |
+| SQL transaction or row lock | Rows selected by one transaction         | Application process and SQL database                                               | No                                                                                         | The application retries a failed transaction                                    | Application-owned                                                                          | Yes, for rows in the same database transaction                 | Ordinary application tables and SQL tools                           |
+| Traditional job queue       | A job, queue, or configured grouping key | Workers plus broker or queue database                                              | Usually                                                                                    | The job is retried; mutable entity state remains application-owned              | Application-owned                                                                          | Not supplied by the queue                                      | Queue administration plus application data stores                   |
+| Solid Objects               | Actor class and application-defined ID   | Node processes plus existing SQLite, PostgreSQL, or MySQL                          | No; Redis wake-up is optional                                                              | The operation retries against durable actor state                               | Committed projections; application-owned transport; no edge placement                      | No                                                             | Relational tables, typed administration, CLI, and dashboard         |
+| Cloudflare Durable Objects  | Object class and globally unique ID      | Cloudflare Workers plus per-object managed storage                                 | Cloudflare platform                                                                        | Object activation with durable state, not workflow-step replay                  | WebSockets and Cloudflare-selected object location                                         | Storage transactions are scoped to one object                  | Object storage APIs and platform tooling                            |
+| 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     |
+| 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                   |
 
 ## Primary references
 
@@ -22,6 +23,10 @@ smallest mechanism that meets its requirements. It does not rank the projects.
   distinguishes local concurrency from multiple worker processes.
 - Cloudflare documents global uniqueness, per-object storage, single-threaded
   execution, and placement in [What are Durable Objects?](https://developers.cloudflare.com/durable-objects/concepts/what-are-durable-objects/).
+- celld documents per-object SQLite databases, bucket replication, and
+  object-storage compare-and-swap ownership in its
+  [repository](https://github.com/denoland/celld) and its
+  [documentation](https://celld.dev/docs).
 - Rivet documents addressable actors and persistence in
   [Actors](https://rivet.dev/docs/actors/) and
   [Persistence](https://rivet.dev/docs/actors/persistence).

package/docs/configuration.md

@@ -59,8 +59,8 @@ runtime role enabled. Broadcast workers are started only when `broadcast` or
 Consecutive empty passes double it up to
 `idlePollingIntervalMilliseconds`. Actor workers never wait longer than
 `leaseRenewalIntervalMilliseconds`. Set the fast and idle values equal for a
-fixed cadence. A custom wake-up adapter should return `true` for a notification
-and `false` for a timeout; an older adapter that returns `void` remains
+fixed cadence. A custom wake-up adapter must return `true` for a notification
+and `false` for a timeout. An older adapter that returns `void` remains
 compatible and keeps the fast cadence. Wake-ups reduce latency, while database
 polling remains the correctness path.
 

package/docs/correctness.md

@@ -12,12 +12,12 @@
   recreated actor. A caller authorized before destruction receives
   `ActorDestroyed`; an unknown or forged reference remains unauthorized.
 - Graceful process shutdown and stale-process cleanup use the same atomic
-  ownership release: claimed messages return to ready membership, activations
-  are unfenced, and processing effect, reminder, and broadcast claims become
-  available again. A stale draining process is recoverable like a stale running
-  process.
-- Permanent operation failure raises `MessageFailed` with the durable message
-  ID and persisted error details instead of treating actor code text as the
+  ownership release. Claimed messages return to ready membership. The runtime
+  unfences the activations. Effect, reminder, and broadcast claims become
+  available again. A stale process that drains is recoverable like a stale
+  process that runs.
+- Permanent operation failure raises `MessageFailed`. The error carries the
+  durable message ID and the persisted error details. Actor code text is not the
   public exception contract.
 - Operation, lifecycle, observable, and payload callbacks retain their owning
   runtime through async context. Isolated runtimes therefore never fall back to
@@ -31,14 +31,14 @@
 - Activation passes are bounded. Yielding changes ready-membership polling
   order only; it neither changes durable message sequence nor makes future work
   due early.
-- Idle hydrated actors remain fenced by the same renewable lease. Cache reuse
-  never bypasses claim membership or the commit fence, failed turns restore
-  their public fields before reuse, and conditional release cannot clear a
-  newer owner or generation.
+- Idle hydrated actors keep the same renewable lease as their fence. Cache reuse
+  never bypasses claim membership or the commit fence. A failed turn restores
+  its public fields before reuse. Conditional release cannot clear a newer owner
+  or generation.
 - Actor setup completes before an attempt begins. A hydration, migration, or
-  activation failure atomically restores ready membership, releases its
-  activation fence, and restores the attempt count; an awaiting caller receives
-  the setup error.
+  activation failure restores ready membership, releases its activation fence,
+  and restores the attempt count. All three happen in one atomic step. A caller
+  that waits receives the setup error.
 - `guardApplicationDatabase()` rejects direct application writes during actor
   operations, observable and payload projections, and state migrations. It
   permits only `SELECT` through row-returning methods. Commit actions remain in
@@ -49,10 +49,10 @@
   successful snapshots and their nested JSON values are frozen copies.
 - Personalized payloads hydrate committed state separately for every payload
   name and subscriber. Each projection is read-only, size bounded, and fenced
-  independently by actor incarnation and revision. One denied, mutating, or
-  failing projection cannot stop its siblings or observable delivery. A state
-  change on an actor declaring payloads creates a revision broadcast even when
-  the actor declares no scalar observables.
+  independently by actor incarnation and revision. One projection that is
+  denied, that mutates, or that fails cannot stop its siblings or observable
+  delivery. A state change on an actor with payloads creates a revision
+  broadcast, even when that actor declares no scalar observables.
 
 ## Limitations and non-goals
 
@@ -71,6 +71,19 @@
   placement, capacity, database backups, and database failover.
 - Redis and PostgreSQL notifications reduce wake-up latency but do not replace
   durable polling or become a source of truth.
+- The browser platform has no `AsyncLocalStorage`. Its context store covers
+  only the synchronous part of a callback. After the first `await` inside an
+  actor operation, the ambient guards (`applicationWritesForbidden()` and the
+  inside-transaction check) read as unset. Durable-state fencing, mailbox
+  ordering, and the SQLite WASM deadline enforcement do not depend on those
+  guards. The guards are best-effort in the browser and exact in Node.
+- `snapshotWithIncarnation`'s `createdAtMs` orders actor incarnations to the
+  millisecond. Every adapter stores `created_at_ms` at that same precision. If
+  you destroy and recreate the same actor identity inside one database-clock
+  millisecond, the two incarnations get an equal `createdAtMs`. In that narrow
+  case, a caller cannot tell which of the two is current, so it cannot fence a
+  derived write on that value. `instanceId` still changes and shows that a
+  recreation occurred. It is a random UUID and carries no order of its own.
 - Large documents, bulk pipelines, globally placed edge state, and global
   counters are outside the intended workload. Prefer an ordinary row
   transaction when it completely enforces the invariant.

package/docs/dashboard.md

@@ -115,9 +115,9 @@ with fresh random bytes, so tokens differ between requests while every form
 already open in the same session remains valid. POST requests without a valid
 token receive 403 and do not perform the action.
 
-Every stored or request-derived string is escaped before entering HTML,
-including JSON placed in chart attributes. HTML and statistics responses are
-private and not cached. The dashboard sends a nonce-backed content security
+The dashboard escapes every stored or request-derived string before that string
+enters the HTML. This includes the JSON in chart attributes. HTML and statistics
+responses are private, and no cache holds them. The dashboard sends a nonce-backed content security
 policy, denies framing, disables MIME sniffing, and limits referrers to the
 same origin.
 
@@ -137,9 +137,9 @@ effects, broadcasts, and dead letters. Pause prevents workers from claiming
 new turns for that identity; a turn already executing may still commit. Resume
 clears the brake and normal polling resumes delivery.
 
-Dead-letter retry calls `runtime.deadLetters.retry()`, retaining its durable
-idempotency and actor-operation validation. A retry refused by the runtime is
-shown on the detail page with status 422.
+Dead-letter retry calls `runtime.deadLetters.retry()`. It keeps the durable
+idempotency and the actor-operation validation of that method. If the runtime
+refuses a retry, the detail page shows it with status 422.
 
 `HEAD /` performs only a schema reachability query and creates no CSRF session
 state. Use it for liveness checks instead of polling the full dashboard.

package/docs/errors-and-recovery.md

@@ -19,18 +19,19 @@ do not parse error messages.
 | `PayloadTooLarge`       | Arguments, state, result, snapshot getter, effect result, or personalized payload exceeded its configured limit. | Reduce the JSON value or deliberately raise the corresponding limit.                                                          |
 | `SyncInsideTransaction` | A committed call or message wait would self-deadlock inside this adapter's transaction.                          | Finish the transaction first or stage actor-owned work through a commit action.                                               |
 
-`this.reject()` accepts codes matching `[A-Za-z_][A-Za-z0-9_]*`, including
-camelCase. An invalid code throws the non-retryable `InvalidRejectionCode`; the
-operation fails on its first attempt and a synchronous caller receives
-`MessageFailed` instead of waiting through retry backoff.
+`this.reject()` accepts any code that matches `[A-Za-z_][A-Za-z0-9_]*`.
+camelCase is valid. An invalid code throws the non-retryable
+`InvalidRejectionCode`. The operation then fails on its first attempt, and a
+synchronous caller receives `MessageFailed`. It does not wait through retry
+backoff.
 
 `MessageReference.status()`, `result()`, and `wait()` reauthorize the stored
 operation. `result()` returns `undefined` while work is nonterminal, returns the
 committed result when complete, and raises `Rejected` or `MessageFailed` for a
 terminal refusal or failure. `wait()` blocks until the same terminal outcomes
-or its deadline. A reference does not retain the authorization context used to
-send it; supply the context to each of these methods so the stored operation is
-reauthorized.
+or its deadline. A reference does not keep the authorization context of the
+original send. Supply the context to each of these methods, so that the runtime
+can reauthorize the stored operation.
 
 ## Definition and programming errors
 
@@ -97,8 +98,7 @@ linked replacement message; repeating the call returns the same replacement.
 Effects are different: they execute outside the actor transaction and are at
 least once. Deduplicate external work with the stable `EffectContext.id`.
 Success and failure callback operations receive the originally staged
-`arguments` for actor-state correlation. A retryable failure scheduled into the
-future is correctly considered idle for the present pass, so
-`runtime.testing.drain()` does not advance retry backoff; use a
-`NonRetryableError` when a test needs to exercise the exhausted failure callback
-without waiting.
+`arguments` for actor-state correlation. A retryable failure with a future
+schedule is correctly idle for the present pass, so `runtime.testing.drain()`
+does not advance retry backoff. Use a `NonRetryableError` when a test must reach
+the exhausted failure callback immediately.

package/docs/fit.md

@@ -14,6 +14,9 @@ or realtime projections.
   invalidations atomically.
 - The application already operates SQLite, PostgreSQL, or MySQL and should keep
   durable coordination there.
+- A local-first application needs the same actor model in the browser:
+  durable per-user state on SQLite WASM, one runtime shared across tabs, and
+  an outbox that syncs to a server runtime when the network allows.
 
 ## Prefer a row transaction when
 

package/docs/operations.md

@@ -13,9 +13,9 @@ not cross a process boundary. When live processes share the database without a
 configured adapter, the runtime logs
 `solid_objects.polling_only_cross_process_wake_up` once. Use PostgreSQL
 notifications or optional Redis Pub/Sub when separate processes need prompt
-delivery; without one, newly committed work can wait up to the current idle
-polling interval. Notification errors are isolated and logged by role and error
-class without failing the committed work.
+delivery. Without one of them, newly committed work can wait for the current
+idle polling interval. The runtime isolates notification errors and logs them by
+role and error class. The committed work does not fail.
 
 The warning excludes process rows with the current hostname and host process ID.
 It can therefore appear during a rolling deployment or restart overlap when an
@@ -53,8 +53,8 @@ isolated backlogs. `solid_objects.activation.yielded` reports the actor
 identity, turns processed, and remaining due membership count.
 
 `claimScanLimit` defaults to 100. Global claims inspect a bounded ordered set of
-actor identities and continue after a lost lease race, preserving worker
-parallelism without an unbounded scan.
+actor identities. They continue after a lost lease race. Worker parallelism
+stays, and the scan stays bounded.
 
 Workers retain a hydrated actor and its fenced lease for
 `idleDeactivationTimeoutMilliseconds`, which defaults to 30 seconds. Idle
@@ -66,15 +66,17 @@ longer polling.
 
 Actors can override protected `onActivate()` and `onDeactivate()` methods for
 nondurable, process-local resources. Either hook may be asynchronous. Hook code
-runs under the application-write guard, and `onDeactivate()` is best effort:
-it may not run after a crash, cannot establish a correctness guarantee, and a
-failure is logged without preventing lease release.
+runs under the application-write guard. `onDeactivate()` is best effort:
+
+- it may not run after a crash;
+- it cannot establish a correctness guarantee;
+- the runtime logs a failure and still releases the lease.
 
 `runtime.administration.processes()` returns the same administration-authorized
 immutable process metadata as `runtime.processes.all()`, with hostname, host
-process ID, Node and Solid Objects versions, and a current `stale` flag. It is
-safe to call through the runtime's database adapter while workers are running;
-the query is serialized with other database access and does not require a
+process ID, Node and Solid Objects versions, and a current `stale` flag. You can
+safely call it through the runtime's database adapter while the workers run. The
+runtime serializes the query with the other database access, and it needs no
 second SQLite connection. Graceful shutdown first persists `draining` with a
 `shutdownRequestedAt` timestamp, then deactivates owned actors and atomically
 releases every role claim before persisting `stopped`. `cleanup()` reauthorizes
@@ -82,7 +84,8 @@ separately and performs the same release for stale running or draining
 processes. The cleanup count is instrumented; application payloads are not.
 
 Committed calls and `message.wait()` apply `timeoutMilliseconds` to the entire
-durable wait, beginning before enqueue or message lookup. Adapter deadlines
+durable wait. The clock starts before enqueue or message lookup. Adapter
+deadlines
 bound serialized SQLite access and lock waits, PostgreSQL pool acquisition,
 statements, and locks, and MySQL pool acquisition, queries, and transaction
 lock waits. A `SyncEnqueueTimeout` means the enqueue transaction did not commit
@@ -112,10 +115,14 @@ ID and later calls return a reference to that same message.
 
 Self-scheduling actors need a low-frequency reconciler because application
 alarms can still be lost. `runtime.reconciliation` provides administration-
-authorized, read-only views for active instances, quiet instances without
-ready work, claimed work, or scheduled reminders, migrated state batches, and
-orphaned actor IDs. Collection reads use a maximum page size of 1,000 and a
-stable cursor.
+authorized, read-only views for:
+
+- active instances;
+- quiet instances with no ready work, claimed work, or scheduled reminder;
+- migrated state batches;
+- orphaned actor IDs.
+
+Collection reads use a maximum page size of 1,000 and a stable cursor.
 
 The host application supplies its current owner IDs to `orphaned()` because
 Node applications do not share an Active Record relation abstraction. Send
@@ -140,9 +147,16 @@ actor type appears in `instanceRetentionByActorType`, and remains an explicit
 operator action because it deletes the entire actor incarnation.
 
 Pruning selects and rechecks at most `pruneBatchSize` rows per transaction. It
-preserves ready and claimed messages, dead-letter originals and replacements,
-unfinished effects and broadcasts, scheduled reminders, leased or paused
-instances, and processes that still own a claim or activation. Instance
+keeps:
+
+- ready and claimed messages;
+- dead-letter originals and replacements;
+- unfinished effects and broadcasts;
+- scheduled reminders;
+- leased or paused instances;
+- processes that still own a claim or an activation.
+
+Instance
 expiration removes the entire actor incarnation and all of its retained
 history, so use it only for actor types whose state is safely disposable.