solid-objects 0.12.0 → 0.13.0

package/docs/architecture.md

@@ -1,8 +1,9 @@
 # Architecture
 
-Solid Objects is a database-backed virtual actor runtime. An actor is addressed
-by `(actor type, actor id)`, processes one durable mailbox turn at a time, and
-persists JSON state between activations.
+Solid Objects coordinates stateful TypeScript objects through database-backed
+mailboxes. Each object, called an actor in the API, is addressed by
+`(actor type, actor id)`, processes one durable turn at a time, and persists
+JSON state between activations.
 
 A durable message envelope selects an actor `operation` and records its
 `delivery_mode` as `async`, `sync`, or `internal`. An operation is actor code;
@@ -59,10 +60,10 @@ than waiting for a connection or serialized SQLite slot it cannot release.
 
 PostgreSQL notifications are an opt-in latency layer. One event-driven client
 per runtime listens on role-specific channels before the worker checks durable
-state, which closes the listener-startup race without Ruby's connection per
-blocking thread. A notification advances a process-local role generation and
-wakes every matching waiter. Reconnection and notification loss fall back to
-the ordinary polling interval.
+state, which closes the listener-startup race without holding a polling
+connection per worker. A notification advances a process-local role generation
+and wakes every matching waiter. Reconnection and notification loss fall back
+to the ordinary polling interval.
 
 The optional Redis adapter provides the same role generations through Pub/Sub
 for deployments that already operate Redis. It keeps commands and subscriptions
@@ -94,6 +95,12 @@ actor subscriptions, replays a committed observable projection, and follows
 the durable broadcast outbox in revision order. The browser client applies the
 same incarnation and revision fence without importing Node APIs.
 
+Each observable is compared using its computed JSON value. Value-broadcast
+observables persist that changed value in the outbox; invalidation-only
+observables persist only the changed name. This lets a component registry
+refresh a reauthorized view at the same dependency granularity without storing
+or sending private projection values.
+
 Actors may also declare static personalized payload projections. Each requested
 name is reauthorized as a query and evaluated against a fresh actor hydrated
 from committed state under that subscriber's session context. Payload names use
@@ -108,6 +115,5 @@ broadcast events through an application-owned shared transport and calls
 another broker optional for a single Node process while making the
 cross-process boundary explicit.
 
-This package ports the Solid Objects programming model. It does not share a
-database schema or runtime protocol with the Ruby gem and does not reproduce
-Cloudflare's placement or edge-runtime guarantees.
+Solid Objects provides database-backed state coordination for Node.js. It does
+not reproduce Cloudflare's placement or edge-runtime guarantees.

package/docs/authorization.md

@@ -18,9 +18,12 @@ before actor type lookup, so denied callers cannot probe the registry. A new
 connection must use a newly resolved authorization context; do not copy a user
 object from an earlier request or trust an actor ID supplied by the browser.
 
-Successful subscription authorization allows the explicit `observables()`
-projection for that actor, including the immediate committed replay. It does
-not authorize actor state, operations, queries, destruction, or administration.
+Successful subscription authorization allows the `broadcastValue()` portion
+of the explicit `observables()` projection for that actor, including the
+immediate committed replay. Unwrapped observables and values marked with
+`broadcastInvalidation()` disclose only their names, not their values.
+Subscription authorization does not
+authorize actor state, operations, queries, destruction, or administration.
 The runtime removes all registrations when the host calls `session.close()`.
 
 Requested personalized payloads cross both boundaries. The runtime first calls
@@ -29,3 +32,9 @@ the same fresh session authorization context before every projection. A false
 query decision omits that payload. Projection and authorization failures are
 confined to the payload name and emit metadata-only instrumentation; they do
 not reject observable delivery or expose exception messages.
+
+The optional operator dashboard applies `authorizeAdministration` before every
+data route. Each route supplies its own action, resource, optional resource ID,
+and the host-provided request authorization context. Dashboard authorization
+does not replace host authentication. State-changing routes additionally
+require a masked token backed by the host's `DashboardSession`.

package/docs/benchmarks.md

@@ -0,0 +1,123 @@
+# Benchmarks
+
+The benchmark harness measures committed actor operations. It is intended to
+show tradeoffs and catch large regressions, not to predict application capacity.
+
+## Scenarios
+
+- `warm-hot`: all operations target one previously created identity.
+- `warm-many`: operations rotate across 100 previously created identities.
+- `cold-many`: every measured operation creates a new identity.
+- `synchronous`: the actor method mutates state without yielding.
+- `asynchronous`: the actor method yields through `setImmediate()` before the
+  same mutation.
+- `one-process`: four actor workers run in the caller's Node process.
+- `four-processes`: four Node worker processes share the database.
+
+Latency begins before durable enqueue and ends when the committed result is
+available. Throughput uses the wall time for the measured batch. Percentiles
+use nearest rank. Defaults are 25 warmup operations, 250 measured operations,
+and client concurrency 16.
+
+## Run the harness
+
+SQLite needs no service:
+
+```bash
+pnpm run benchmark -- --database sqlite
+```
+
+PostgreSQL and MySQL runs require a disposable database. The harness deletes
+benchmark rows but leaves its uniquely prefixed empty tables for inspection.
+
+```bash
+SOLID_OBJECTS_POSTGRESQL_BENCHMARK_URL=postgresql://... \
+  pnpm run benchmark -- --database postgresql
+
+SOLID_OBJECTS_MYSQL_BENCHMARK_URL=mysql://... \
+  pnpm run benchmark -- --database mysql
+```
+
+Use `--operations`, `--warmup`, and `--concurrency` to change the recorded
+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
+- 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.
+
+## Sources of bias
+
+- A developer laptop shares CPU, memory, and storage with unrelated processes.
+- 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.
+- 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
+  by adding workers.

package/docs/browser-protocol.md

@@ -5,6 +5,14 @@ subscription requests and receives JSON invalidation envelopes over WebSocket.
 The application supplies the rendering callback and authenticated WebSocket
 server; `runtime.realtime` supplies the server-side session protocol.
 
+The `observables` object contains changed values and every subscriber authorized
+for that actor receives the same projection. The `invalidations` array contains
+changed observable names whose values were deliberately withheld with
+`broadcastInvalidation()`. Use those names to refresh an application endpoint
+that reauthorizes the component request. Use personalized payloads when the
+browser needs subscriber-specific data, and keep secrets out of value-broadcast
+observables.
+
 The 0.1 subscription request is:
 
 ```json
@@ -32,10 +40,15 @@ The 0.1 envelope is:
   "actorId": "primary",
   "instanceId": "019...",
   "revision": "42",
-  "observables": { "count": 3 }
+  "observables": { "version": 3 },
+  "invalidations": ["playerOne"]
 }
 ```
 
+`invalidations` was added as an optional version-1 field in 0.13.0. Clients
+must treat a missing field as an empty array. A name appears in either
+`observables` or `invalidations`, never both, in runtime-produced envelopes.
+
 Requested personalized projections use a separate envelope:
 
 ```json
@@ -67,7 +80,8 @@ 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 importing Turbo.
+results use the same coordination contract without assuming a rendering
+framework.
 
 Components may share a batch name. A microtask unions affected components in
 the same actor, batch, incarnation, and revision into one refresh request.

package/docs/comparisons.md

@@ -0,0 +1,36 @@
+# System comparisons
+
+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               |
+
+## Primary references
+
+- PostgreSQL documents row-lock behavior, transaction lifetime, and deadlock
+  handling in [Explicit Locking](https://www.postgresql.org/docs/18/explicit-locking.html).
+- BullMQ is one representative traditional queue; its
+  [worker concurrency documentation](https://docs.bullmq.io/guide/workers/concurrency)
+  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/).
+- Rivet documents addressable actors and persistence in
+  [Actors](https://rivet.dev/docs/actors/) and
+  [Persistence](https://rivet.dev/docs/actors/persistence).
+- DBOS documents its PostgreSQL checkpoints, recovery, distributed processes,
+  and optional control plane in [DBOS Architecture](https://docs.dbos.dev/architecture).
+- Restate documents per-key write serialization in
+  [Virtual Objects](https://docs.restate.dev/foundations/services#virtual-object)
+  and its storage requirements in the
+  [self-hosted server overview](https://docs.restate.dev/server/overview).
+
+External systems evolve. Recheck these primary sources before relying on one
+row as a procurement or architecture decision.

package/docs/configuration.md

@@ -28,7 +28,9 @@ through `runtime.ref(ActorClass, actorId)`. Both validate options immediately.
 The limits measure normalized JSON encoded as UTF-8. `maxResultBytes` also
 limits each computed snapshot getter and effect-handler result. Explicit
 `observables()` values are validated as JSON but do not currently have a
-separate aggregate byte limit. `retryDelayMilliseconds` should return a
+separate aggregate byte limit. This includes values wrapped in
+`broadcastInvalidation()`: they are compared in memory even though only their
+names enter the broadcast outbox. `retryDelayMilliseconds` should return a
 non-negative finite number; an invalid application callback will fail the
 affected failure path rather than schedule an invalid timestamp.
 
@@ -96,6 +98,25 @@ server.
 
 ## Database adapters
 
+### Database value mapping
+
+`DatabaseConnection.get<Row>()` and `all<Row>()` trust the caller-supplied row
+type; they do not validate or convert driver results. Type rows to the adapter's
+runtime representation or normalize them at the application boundary.
+
+| SQL value                           | SQLite (`node:sqlite`)      | PostgreSQL (`pg`)                               | MySQL (`mysql2`)                    |
+| ----------------------------------- | --------------------------- | ----------------------------------------------- | ----------------------------------- |
+| ordinary integer                    | `bigint`                    | `number` for `int2`/`int4`; `bigint` for `int8` | `number` for ordinary integer types |
+| arbitrary precision integer/decimal | `bigint` for SQLite INTEGER | `numeric` remains the driver's decimal string   | `BIGINT` and `DECIMAL` are strings  |
+| floating point                      | `number`                    | `number`                                        | `number`                            |
+| text                                | `string`                    | `string`                                        | `string`                            |
+| binary                              | `Uint8Array`                | `Buffer`                                        | `Buffer`                            |
+| null                                | `null`                      | `null`                                          | `null`                              |
+
+`RunResult.changes` is always a `number`. `lastInsertId`, when an adapter
+provides it, is a decimal `string`; SQLite and MySQL set it for nonzero generated
+IDs, while PostgreSQL callers should use `RETURNING` with `get()`.
+
 ### SQLite
 
 `sqlite({ path, timeoutMilliseconds = 5_000, lockRetryAttempts = 10 })` uses

package/docs/correctness.md

@@ -1,5 +1,7 @@
 # Correctness and delivery semantics
 
+## Guarantees
+
 - Delivery is ordered per actor identity and at least once.
 - Different identities may execute concurrently.
 - Sequence allocation and durable enqueue are one transaction.
@@ -51,3 +53,24 @@
   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.
+
+## Limitations and non-goals
+
+- At-least-once execution means actor code may begin more than once. State and
+  staged intents from a failed turn roll back, but arbitrary external work does
+  not. External systems need stable idempotency keys.
+- The activation fence protects the Solid Objects commit. It cannot revoke or
+  undo network calls, files, emails, payments, or other external effects.
+- One identity processes one write operation at a time. This is the ordering
+  guarantee and also the hot-identity throughput limit.
+- A commit is scoped to one actor turn. There is no transaction spanning two
+  actor identities.
+- Processes with incompatible `stateVersion` definitions cannot safely overlap.
+  Once newer code persists a state version, older code rejects that actor.
+- The application owns HTTP, WebSocket authentication, rendering, process
+  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.
+- 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

@@ -0,0 +1,196 @@
+# Operator dashboard
+
+`solid-objects/web` is an optional operator interface over the same relational
+tables used by the runtime. It exposes instances and committed state, ready and
+claimed messages, reminders, effects, broadcasts, dead letters, and processes.
+It needs no separate store or agent.
+
+The root `solid-objects` entry point does not import the dashboard. A worker
+process that never mounts it does not load its HTTP adapter, renderer, or
+assets.
+
+## Fetch mounting
+
+`createDashboard()` returns an immutable Fetch handler. Give every request its
+fresh server-side authentication context and the host session that should own
+the CSRF token:
+
+```typescript
+import { createDashboard } from "solid-objects/web"
+
+const dashboard = createDashboard({
+  runtime,
+  mountPath: "/solid-objects/dashboard",
+})
+
+const response = await dashboard.fetch(request, {
+  authorizationContext: currentOperator,
+  session: {
+    read: (key) => session.get(key),
+    write: (key, value) => session.set(key, value),
+  },
+})
+```
+
+`mountPath` defaults to `/solid-objects/dashboard`. Pass `/` only when the
+dashboard owns the whole origin.
+
+## Access modes
+
+`access` defaults to `authorized`. Every route uses the runtime administration
+policy, pages include mutation controls, and the request context must supply a
+session for CSRF state.
+
+Use `authorized-read-only` to retain the policy while removing mutation forms
+and rejecting every dashboard POST with 405. Use `public-read-only` for an
+explicitly public demo mount:
+
+```typescript
+const demo = createDashboard({
+  runtime,
+  mountPath: "/solid-objects/demo",
+  access: "public-read-only",
+})
+
+await demo.fetch(request, {})
+```
+
+Public read-only mode skips `authorizeAdministration` and requires neither an
+authorization context nor a session. It still exposes committed state,
+arguments, results, errors, actor identifiers, and operational metadata. Only
+use it with synthetic or otherwise public demo data. All extension GET routes
+are public in this mode, while extension POST routes are also rejected.
+
+## Node and Connect mounting
+
+`createNodeDashboardHandler()` converts `IncomingMessage` and `ServerResponse`
+to the Fetch contract. Register it after the application's authentication and
+session middleware. A Connect-compatible host may pass `next`; paths outside
+the mount and unknown dashboard paths cascade. Requests outside the mount
+cascade before context resolution or body consumption, so downstream POST
+handlers receive the original stream.
+
+```typescript
+import { createDashboard, createNodeDashboardHandler } from "solid-objects/web"
+
+const dashboard = createDashboard({ runtime })
+const handler = createNodeDashboardHandler({
+  dashboard,
+  resolveContext: async (request) => ({
+    authorizationContext: await currentOperator(request),
+    session: sessionFor(request),
+  }),
+})
+
+app.use(handler)
+```
+
+The adapter caps request bodies at 64 KiB by default. Set
+`maximumBodyBytes` to another positive bound when the host requires one.
+
+## Authorization
+
+In the default and authorized read-only modes, every data route declares an
+`authorizeAdministration` action and resource. Authorization runs before the
+route reads a record, so a denied caller cannot probe identifiers.
+
+| Page or action                             | Action                     | Resource                      |
+| ------------------------------------------ | -------------------------- | ----------------------------- |
+| Dashboard, statistics, health              | `index`                    | `dashboard`                   |
+| Instance list/detail                       | `index` / `show`           | `instances`                   |
+| Instance pause/resume                      | `pause` / `resume`         | `instances`                   |
+| Mailbox/message detail                     | `index` / `show`           | `messages`                    |
+| Reminder, effect, broadcast, process lists | `index`                    | corresponding plural resource |
+| Dead-letter list/detail/retry              | `index` / `show` / `retry` | `dead_letters`                |
+
+The policy receives the route ID as `resourceId` when one exists and receives
+the exact `authorizationContext` supplied by the host. The default policy
+denies every route. Dashboard authorization does not authenticate requests;
+resolve the operator before calling the dashboard.
+
+## Security
+
+The host session persists one random CSRF secret. Every rendered page masks it
+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
+policy, denies framing, disables MIME sniffing, and limits referrers to the
+same origin.
+
+Page size defaults to 25 and is clamped to 200. Actor ID substring filtering is
+parameterized with an adapter-specific SQL expression rather than interpolated
+into a query.
+
+## Pages and actions
+
+The dashboard page shows totals, instances per actor type, mailbox depth,
+outbox/reminder status, recent processes, and recent dead letters. The summary
+bar can poll `/stats` every five seconds when the operator enables Live. Lists
+do not reload underneath an operator reading them.
+
+Instance detail shows committed state and recent related messages, reminders,
+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.
+
+`HEAD /` performs only a schema reachability query and creates no CSRF session
+state. Use it for liveness checks instead of polling the full dashboard.
+
+## Charts
+
+The dashboard defaults to Chart.js 4.5.0 from jsDelivr with subresource
+integrity. Only that exact origin is added to `script-src`.
+
+Use a self-hosted script without widening the policy:
+
+```typescript
+createDashboard({
+  runtime,
+  chartLibrary: { url: "/assets/chart.umd.min.js", integrity: null },
+})
+```
+
+Set `chartLibrary: { url: null }` to render without charts. The dedicated chart
+containers have fixed height so responsive redraws cannot grow the page.
+
+## Extensions
+
+Extensions are supplied when the dashboard is created. Configuration is copied
+and frozen; there is no global registry and no first-request mutation boundary.
+
+```typescript
+const dashboard = createDashboard({
+  runtime,
+  extensions: [
+    {
+      tab: { label: "Tenants", path: "/tenants" },
+      routes: [
+        {
+          method: "GET",
+          path: "/tenants",
+          policy: { action: "index", resource: "tenants" },
+          handle: ({ render }) =>
+            render({
+              title: "Tenants",
+              content: renderTenants(),
+            }),
+        },
+      ],
+    },
+  ],
+})
+```
+
+Every extension route must carry a nonempty policy. Missing policies and
+method/path collisions fail when the dashboard is created. Renderer callbacks
+may replace named built-in views, and Fetch middleware may wrap the whole
+dashboard. Extension HTML is trusted application code; escape dynamic values
+with the route context's `escape()` helper.

package/docs/errors-and-recovery.md

@@ -19,11 +19,18 @@ 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.
+
 `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.
+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.
 
 ## Definition and programming errors
 
@@ -31,6 +38,8 @@ These errors normally require a code or deployment correction:
 
 - `InvalidActor`: invalid actor type, state version, migration declaration,
   member name, payload declaration, or duplicate registration.
+- `InvalidRejectionCode`: `reject()` received a code outside the supported
+  identifier grammar. It is terminal because retrying cannot change actor code.
 - `UnknownActorType`, `UnknownOperation`, `UnknownEffect`, and
   `UnknownCommitAction`: deployed registration does not match durable work or
   code attempted an undeclared operation.
@@ -87,3 +96,9 @@ 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.

package/docs/fit.md

@@ -0,0 +1,58 @@
+# Choosing Solid Objects
+
+Solid Objects is useful when an application has many independently addressed
+entities and every entity needs ordered state changes, durable work, recovery,
+or realtime projections.
+
+## Use it when
+
+- Concurrent requests can update the same room, cart, account, device,
+  document, or session.
+- Each identity needs its own ordering boundary and durable mailbox.
+- Operations must recover after a Node process exits.
+- State changes stage reminders, effects, actor-to-actor messages, or realtime
+  invalidations atomically.
+- The application already operates SQLite, PostgreSQL, or MySQL and should keep
+  durable coordination there.
+
+## Prefer a row transaction when
+
+One short transaction with an update, constraint, or row lock completely
+enforces the invariant. A direct transaction has less machinery, less stored
+history, and no actor-state migration contract.
+
+## Prefer another design when
+
+- Work is a bulk or data-parallel pipeline rather than per-identity state.
+- One global identity must sustain more writes than one sequential mailbox can
+  commit.
+- State is a large document or relational dataset that should be queried and
+  updated in smaller normalized pieces.
+- The application needs a transaction spanning several independent object
+  identities.
+- Compute and state must be automatically placed close to clients at the edge.
+- The team wants a managed control plane to place, scale, and recover workers.
+- Durable workflow replay across named steps is more important than a mutable
+  object with ordered operations.
+
+## Model identities deliberately
+
+One hot identity is intentionally serialized. An identity should correspond to
+the smallest domain boundary that requires one total order. Splitting a room by
+player or a cart by item may improve parallelism, but it also gives up atomic
+ordering across the split.
+
+Different identities can run concurrently when worker capacity and the
+database allow it. The [benchmark harness](benchmarks.md) measures both the hot
+and independent-identity cases.
+
+## Operational cost
+
+The relational database stores actor instances, ready and claimed mailbox
+membership, message history, leases, effects, reminders, broadcasts, dead
+letters, and process records. Retention policies and the operator dashboard
+make that state inspectable, but they do not remove the need to monitor and
+back up the database.
+
+Redis is optional. It is a transient notification path rather than durable
+state, so losing Redis increases polling latency without losing committed work.