solid-objects 0.12.1 → 0.13.1

package/docs/api.md

@@ -16,6 +16,11 @@ generic signatures; this index explains the supported role of every export.
 - `Actor`: base class providing `ref()`, `actorId`, `currentMessage`,
   `observables()`, `reject()`, `emit()`, `commitAction()`, `schedule()`,
   `sendTo()`, and protected lifecycle hooks.
+- `broadcastValue(value)`: mark an observable so its changed value enters the
+  durable invalidation envelope.
+- `broadcastInvalidation(value)`: compare the real observable value but put
+  only its name in the durable envelope when it changes.
+- `ObservableBroadcast`: the immutable marker type returned by either helper.
 - `VERSION`: running package version.
 - `ActorClass`, `ActorReference`, `ActorMessageSender`, `ActorSnapshot`,
   `ActorOperationNames`, `ActorQueryNames`, `StagedOperations`, and
@@ -31,6 +36,25 @@ generic signatures; this index explains the supported role of every export.
 `PayloadBroadcasts`, and `PayloadBroadcastValue` describe actor-declared
 transactional work and typed personalized projections.
 
+`observables()` returns a flat object. Unwrapped values are invalidation-only:
+their real values participate in change detection, but only their names enter
+the durable envelope. Use an explicit marker when wire behavior matters:
+
+```typescript
+override observables(): Record<string, unknown> {
+  return {
+    version: broadcastValue(this.document.version),
+    sidebar: broadcastInvalidation(this.sidebarForCurrentState()),
+  }
+}
+```
+
+Both values must be JSON-compatible and are evaluated after each successful
+turn. An invalidation-only value participates in change detection but is never
+written to the broadcast outbox or invalidation envelope. The envelope carries
+its name in `invalidations`, allowing component registries to refresh a
+reauthorized endpoint without exposing the value.
+
 `MessageReference` does not retain an invocation's authorization context.
 Supply `authorizationContext` to each `status()`, `result()`, and `wait()` call;
 the runtime reauthorizes the persisted operation every time. Durable results
@@ -90,6 +114,10 @@ The manager types are `DeadLetter`; `ReminderPage`, `ReminderPageOptions`,
 `AdministrationOptions` carries the application-owned authorization context
 for administration calls.
 
+The packaged `solid-objects quickstart` command is config-free and runs the
+SQLite example shipped in the npm artifact. Every other CLI command loads the
+application runtime configured through `--config`.
+
 `ProcessRecord.shutdownState` is `"running"`, `"draining"`, or `"stopped"`;
 there is no separate `running` field. `RetentionResult.count` means eligible
 rows for `preview()` and rows actually deleted for `prune()`.
@@ -124,6 +152,11 @@ rows for `preview()` and rows actually deleted for `prune()`.
 `DatabaseConnection`, `DatabaseFamily`, and `RunResult` support custom database
 and commit-action integration.
 
+`BroadcastEvent.observables` contains changed value-broadcast projections.
+`BroadcastEvent.invalidations` contains changed invalidation-only names. The
+runtime always supplies the array; consumers should treat its absence from an
+older or application-produced event as an empty array.
+
 ### Runtime extensions and manual workers
 
 `runtime.registerComponent(factory, { count = 1 })` adds application-owned
@@ -146,14 +179,17 @@ Factories should create fresh mutable state and `stop()` should be idempotent.
 exported for test runners and hosts that intentionally operate roles outside
 `runtime.run()`. Runtime factory methods create the same classes. Each provides
 `runOnce()`, bounded `runUntilIdle()`, `run(signal)`, `requestShutdown()`,
-`stopped()`, and `stop()`. Manual roles still register process ownership and
-must be stopped. Prefer `runtime.run()` in production and `runtime.testing` in
-tests.
+`stopped()`, `stop()`, and the inspectable
+`currentPollingIntervalMilliseconds`. Manual roles still register process
+ownership and must be stopped. Prefer `runtime.run()` in production and
+`runtime.testing` in tests.
 
 `InProcessWakeUpAdapter`, `WakeUpAdapter`, `WakeUpRole`, `WakeUpWatch`, and
 `WakeUpWaitOptions` define the notification extension. A watch must be obtained
 before checking durable state so a notification cannot fall between claim and
-wait.
+wait. `WakeUpWatch.wait()` returns `true` for a notification and `false` for a
+timeout or cancellation. A legacy `void` result remains accepted and preserves
+the fast polling cadence.
 
 ### Errors
 
@@ -225,5 +261,35 @@ and `SyncTimeoutWaitingOn` type timeout diagnostics. See
   `ComponentRefreshFailure`, and `ComponentRegistryOptions`: framework-neutral
   refresh contract types.
 
+`InvalidationEnvelope.observables` contains values and
+`InvalidationEnvelope.invalidations` contains names without values. The
+component registry reacts to names in either location.
+
 The wire format, trust boundary, revision rules, and component semantics are in
 [Browser protocol](browser-protocol.md).
+
+## `solid-objects/web`
+
+- `createDashboard(options)` creates an immutable `SolidObjectsDashboard` with
+  a standard `fetch(request, context)` entry point.
+- `createNodeDashboardHandler(options)` adapts the Fetch entry point to
+  `node:http` and Connect-compatible middleware.
+- `DashboardOptions` selects the runtime, mount path, `DashboardAccess`, chart library,
+  `DashboardExtension` objects, and `DashboardMiddleware` functions.
+- `DashboardRequestContext` supplies the existing administration authorization
+  context and an optional `DashboardSession`. Read/write access requires the
+  session so its `read()` and `write()` methods can hold the masked CSRF token
+  across requests; read-only modes do not create CSRF state.
+- `DashboardRoute`, `DashboardRouteContext`, `DashboardPolicy`, `DashboardPage`,
+  and `DashboardTab` define extension pages. Every route requires a policy.
+- `DashboardRenderer`, `DashboardRenderInput`, and `DashboardMiddlewareInput`
+  define immutable view overrides and middleware inputs.
+- `DashboardChartLibrary` selects the CDN, a self-hosted script, or disabled
+  charts.
+- `NodeDashboardHandler`, `NodeDashboardHandlerOptions`, and
+  `NodeDashboardRequestContextResolver` describe the Node adapter.
+- `SolidObjectsDashboardContract` is the minimal Fetch contract accepted by the
+  Node adapter.
+
+Mounting, authorization actions, CSRF behavior, pages, and extensions are in
+[Operator dashboard](dashboard.md).

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;
@@ -24,7 +25,9 @@ Each role takes a generation watch before checking for work. A post-commit
 wake-up therefore cannot fall into the gap between an empty claim and the
 worker's wait. The default adapter broadcasts within one process; polling
 remains active as the durable fallback and custom adapters can bridge process
-boundaries.
+boundaries. Empty passes double the role's wait up to the configured idle
+ceiling. Work or a notification resets it to the fast interval, and an actor
+worker's ceiling never exceeds its lease-renewal interval.
 
 Each runtime role occupies a supervised factory slot. An unexpected promise
 resolution or rejection cleans up that instance, waits with capped exponential
@@ -59,10 +62,11 @@ 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 adaptive polling, whose current wait can be as long as the configured idle
+ceiling.
 
 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 +98,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 +118,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,163 @@
+# Benchmarks
+
+The benchmark harness measures committed actor operations. It is intended to
+show tradeoffs and catch large regressions, not to predict application capacity.
+
+## Idle polling
+
+The idle harness measures process CPU and empty database passes for the four
+runtime roles:
+
+```bash
+pnpm run benchmark:idle
+```
+
+It warms each interval for three seconds, measures for ten seconds, and reports
+process user plus system CPU time divided by wall time.
+
+Measured on August 16, 2026 on an Apple M5 with Node.js 26.7.0 and in-memory
+SQLite. The before run used 0.13.0; the after run used the prepared 0.13.1 tree.
+Each run started one actor, effect, reminder, and broadcast role.
+
+| Fast interval | Before polls/s | Before CPU | After polls/s | After CPU |
+| ------------: | -------------: | ---------: | ------------: | --------: |
+|         20 ms |         188.78 |     3.254% |         4.000 |    0.129% |
+|        100 ms |         39.596 |     0.906% |         3.999 |    0.121% |
+|        500 ms |          7.999 |     0.251% |         3.999 |    0.104% |
+
+The after run reached the one-second ceiling for all four roles. These are
+developer-laptop measurements, not a CPU guarantee; timer scheduling, JIT,
+database path, and unrelated host activity affect short samples.
+
+Five SQLite samples measured durable enqueue through committed completion after
+2.5 seconds of idleness. The polling-only multi-process harness submits just
+after an empty pass, so it measures approximately the full polling wait rather
+than average arrival latency.
+
+| Topology                        | 0.13.0 p50 | Prepared 0.13.1 p50 |
+| ------------------------------- | ---------: | ------------------: |
+| One process, in-process wake-up |   2.589 ms |            2.662 ms |
+| Two processes, polling only     | 107.945 ms |        1,006.232 ms |
+
+The local wake-up keeps the one-process path prompt after backoff. The
+polling-only row is the explicit tradeoff: use PostgreSQL notifications or
+optional Redis Pub/Sub when separate processes need low-latency delivery.
+
+## 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,12 +5,13 @@ 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 values, not only invalidation names, and every
-subscriber authorized for that actor receives the same projection. This differs
-from Ruby morph components, which re-fetch a signed endpoint without putting
-observable values on the wire. Keep secrets and subscriber-specific state out
-of `observables()`; use personalized payloads or an application endpoint that
-reauthorizes the component request.
+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:
 
@@ -39,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
@@ -74,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

@@ -11,6 +11,7 @@ through `runtime.ref(ActorClass, actorId)`. Both validate options immediately.
 | `database`                            |                 required | A `Database` adapter.                                                         |
 | `tableNamePrefix`                     |       `"solid_objects_"` | Lowercase letters, digits, and underscores; must start with a letter.         |
 | `pollingIntervalMilliseconds`         |                    `100` | Positive durable-work polling interval.                                       |
+| `idlePollingIntervalMilliseconds`     |                  `1_000` | Positive ceiling after consecutive empty polling passes.                      |
 | `syncPollingIntervalMilliseconds`     |                     `50` | Positive result-wait polling interval.                                        |
 | `leaseDurationMilliseconds`           |                 `30_000` | Positive activation lease; must exceed renewal interval.                      |
 | `leaseRenewalIntervalMilliseconds`    |                 `10_000` | Positive activation renewal cadence.                                          |
@@ -28,7 +29,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.
 
@@ -50,8 +53,16 @@ affected failure path rather than schedule an invalid timestamp.
 
 Counts may be zero, but the complete configuration must leave at least one
 runtime role enabled. Broadcast workers are started only when `broadcast` or
-`authorizeSubscription` is configured. Wake-ups reduce latency; durable polling
-remains the correctness path.
+`authorizeSubscription` is configured.
+
+`pollingIntervalMilliseconds` is the fast interval after work or a wake-up.
+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
+compatible and keeps the fast cadence. Wake-ups reduce latency, while database
+polling remains the correctness path.
 
 ## Retention and cleanup
 

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.