solid-objects 0.12.0

package/docs/architecture.md

@@ -0,0 +1,113 @@
+# 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.
+
+A durable message envelope selects an actor `operation` and records its
+`delivery_mode` as `async`, `sync`, or `internal`. An operation is actor code;
+a message is the durable delivery record that invokes it. Each message has a
+generated request ID independent of its optional caller-supplied idempotency
+key. Matching idempotency keys are scoped to one actor and must identify the
+same operation, delivery mode, and arguments.
+
+The correctness contract is:
+
+> Messages for one actor are durably enqueued and processed sequentially, at
+> least once, by at most one valid activation lease holder at a time.
+
+Actor code runs outside the database transaction. A short transaction guarded
+by the activation owner, token, generation, expiration, and claimed-message
+membership commits state, completion, and staged outboxes together.
+
+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.
+
+Each runtime role occupies a supervised factory slot. An unexpected promise
+resolution or rejection cleans up that instance, waits with capped exponential
+backoff, and builds the replacement through the same factory. Supervision stops
+at the shutdown boundary; database leases and fencing remain the correctness
+mechanism if a failed role was still executing actor code.
+
+SQLite serializes access through one process-local connection and begins write
+transactions immediately. PostgreSQL and MySQL use bounded pools, keep each
+transaction on one checked-out client, store timestamps and sequences as
+64-bit integers, and lock an actor's instance row while allocating mailbox
+sequences. MySQL creates InnoDB tables and retries only the side-effect-free
+enqueue transaction when InnoDB chooses it as a deadlock victim. Every adapter
+uses database time and the same fencing predicates.
+
+Synchronous invocation carries a monotonic deadline into adapter operations.
+SQLite bounds its process-local access queue and busy timeout. Outside a caller
+deadline, it retries only acquisition of a failed `BEGIN IMMEDIATE`; it never
+replays a transaction callback. PostgreSQL bounds pool checkout and installs
+statement and lock timeouts. MySQL bounds pool checkout and client queries and
+installs transaction execution and lock-wait limits. A deadline before enqueue
+commit produces no durable message. After commit, timeout diagnostics retain
+the message reference for later recovery.
+Already-running JavaScript actor code is cooperative rather than forcefully
+preempted; leases and fenced commits remain authoritative if it outlives the
+caller's wait.
+
+Each database adapter also tracks its active transaction through Node's async
+context. A committed call or message wait fails before enqueue or polling when
+the same logical call stack already owns a Solid Objects transaction, rather
+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.
+
+The optional Redis adapter provides the same role generations through Pub/Sub
+for deployments that already operate Redis. It keeps commands and subscriptions
+on separate lazy connections. Connect, subscribe, and publish failures are
+bounded and isolated; durable polling continues independently.
+
+A worker claims one actor globally, then preferentially drains up to
+`maxMessagesPerActivationPass` ready turns for that instance. Reaching the cap
+moves only that actor's already-due ready memberships to current database time.
+Actors with older ready work therefore win the next global claim; delayed work
+keeps its original future availability.
+
+The global claim reads at most `claimScanLimit` ordered candidates. If another
+worker acquires the first candidate's lease, the transaction continues through
+that bounded set instead of returning idle and sacrificing parallelism across
+independent actor identities.
+
+When a pass becomes idle, a long-running worker keeps the hydrated actor and
+continues renewing the same fenced lease until its idle timeout. A later turn
+on that actor reuses both its persisted public fields and process-local private
+fields. Failed and rejected turns restore public fields to their pre-turn
+values before reuse. Fairness yield, timeout, lease loss, and shutdown run the
+best-effort deactivation hook and conditionally release the matching lease.
+One-shot drain helpers release immediately because they will not remain alive
+to renew.
+
+Realtime delivery is transport-neutral. A host-authenticated session authorizes
+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.
+
+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
+independent revision fences, so a failed projection is omitted and retried at a
+later committed revision without blocking invalidations or sibling payloads.
+Actors with payload declarations emit an empty-observable revision event for a
+state change when no scalar observable changed.
+
+Sessions are process-local. A multi-process deployment bridges committed
+broadcast events through an application-owned shared transport and calls
+`runtime.realtime.publish()` in each process that owns connections. This keeps
+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.

package/docs/authorization.md

@@ -0,0 +1,31 @@
+# Authorization
+
+Actor identifiers are identifiers, not capabilities. Message, query,
+destruction, subscription, and administration policies deny by default.
+Applications must authorize the current server-side subject at every entry
+point.
+
+Dead-letter inspection and retry call `authorizeAdministration` with an action,
+resource, optional resource ID, and the caller's authorization context. Retry
+authorization happens before lookup so a denied caller cannot use record IDs as
+an existence oracle.
+
+`runtime.realtime` is transport-neutral. The host application authenticates its
+WebSocket or stream connection, passes that fresh server-side subject as the
+session's `authorizationContext`, and forwards incoming protocol messages to
+`session.receive()`. Every subscribe request calls `authorizeSubscription`
+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.
+The runtime removes all registrations when the host calls `session.close()`.
+
+Requested personalized payloads cross both boundaries. The runtime first calls
+`authorizeSubscription`, then calls `authorizeQuery` with the payload name and
+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.

package/docs/browser-protocol.md

@@ -0,0 +1,93 @@
+# Browser protocol
+
+The browser entry point contains no Node imports. It sends versioned
+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 0.1 subscription request is:
+
+```json
+{
+  "version": 1,
+  "action": "subscribe",
+  "actorType": "Counter",
+  "actorId": "primary",
+  "payloads": ["summary"]
+}
+```
+
+`unsubscribe` uses the same shape with `"action": "unsubscribe"`. The server
+authorizes every subscribe request against the session's fresh connection
+context before looking up the actor. A successful subscription immediately
+sends the latest committed projection and then follows its durable outbox.
+
+The 0.1 envelope is:
+
+```json
+{
+  "version": 1,
+  "kind": "invalidation",
+  "actorType": "Counter",
+  "actorId": "primary",
+  "instanceId": "019...",
+  "revision": "42",
+  "observables": { "count": 3 }
+}
+```
+
+Requested personalized projections use a separate envelope:
+
+```json
+{
+  "version": 1,
+  "kind": "payload",
+  "actorType": "Counter",
+  "actorId": "primary",
+  "instanceId": "019...",
+  "revision": "42",
+  "name": "summary",
+  "payload": { "label": "Your counter", "count": 3 }
+}
+```
+
+Invalidations and each payload name have independent revision fences. This
+lets the server project the latest committed subscriber view even while an
+older durable invalidation is being delivered. Payload bodies must be JSON
+objects or arrays and are deeply frozen after parsing.
+
+Revisions are non-negative integer strings so values larger than JavaScript's
+safe integer range remain exact. A new instance ID establishes a new actor
+incarnation and resets revision comparison. The runtime preserves revision
+order per actor; server sessions and browser clients also reject duplicates and
+stale revisions within an incarnation.
+
+## Component refresh registry
+
+`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.
+
+Components may share a batch name. A microtask unions affected components in
+the same actor, batch, incarnation, and revision into one refresh request.
+Unbatched components refresh independently. A strictly newer request aborts an
+older request for the same group; same-revision requests do not cancel each
+other. Results are accepted only for requested, still-registered targets, and
+each target has its own incarnation/revision fence.
+
+The registry never treats actor identity, component name, key, dependency, or
+target as authorization. The application-owned refresh endpoint authenticates
+the browser and reauthorizes every requested component before returning render
+results.
+
+`pnpm run test:browser` builds the browser entry and runs its Playwright suite
+in Chromium. It covers native WebSocket subscription replay, stale revision and
+incarnation handling, personalized payloads, component batching, and
+superseded-request cancellation.
+
+`runtime.realtime` delivers directly to sessions in its own Node process. For
+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.

package/docs/configuration.md

@@ -0,0 +1,168 @@
+# Configuration reference
+
+`configure(options)` creates a runtime and installs it as the default used by
+`Actor.ref()`. `createRuntime(options)` creates an isolated runtime addressed
+through `runtime.ref(ActorClass, actorId)`. Both validate options immediately.
+
+## Core runtime options
+
+| Option                                |                  Default | Contract                                                                      |
+| ------------------------------------- | -----------------------: | ----------------------------------------------------------------------------- |
+| `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.                                       |
+| `syncPollingIntervalMilliseconds`     |                     `50` | Positive result-wait polling interval.                                        |
+| `leaseDurationMilliseconds`           |                 `30_000` | Positive activation lease; must exceed renewal interval.                      |
+| `leaseRenewalIntervalMilliseconds`    |                 `10_000` | Positive activation renewal cadence.                                          |
+| `idleDeactivationTimeoutMilliseconds` |                 `30_000` | Non-negative hydrated activation cache lifetime; `0` disables idle retention. |
+| `maxMailboxLength`                    |                 `10_000` | Positive maximum ready and claimed messages for one actor.                    |
+| `maxPayloadBytes`                     |              `1_048_576` | Positive byte limit for operation arguments and personalized payloads.        |
+| `maxStateBytes`                       |              `5_242_880` | Positive persisted actor-state byte limit.                                    |
+| `maxResultBytes`                      |              `1_048_576` | Positive operation-result byte limit.                                         |
+| `maxAttempts`                         |                      `5` | Positive maximum operation, effect, and broadcast attempts.                   |
+| `maxMessagesPerActivationPass`        |                     `50` | Positive integer turn budget before fairness yield.                           |
+| `maxActivationDurationMilliseconds`   |                  `5_000` | Positive elapsed-time budget before fairness yield.                           |
+| `claimScanLimit`                      |                    `100` | Positive integer ready-actor candidates considered per global claim.          |
+| `retryDelayMilliseconds`              | exponential 1-60 seconds | Receives the next attempt number and returns its delay.                       |
+
+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
+non-negative finite number; an invalid application callback will fail the
+affected failure path rather than schedule an invalid timestamp.
+
+## Runtime roles and supervision
+
+| Option                                      |                  Default | Contract                                                 |
+| ------------------------------------------- | -----------------------: | -------------------------------------------------------- |
+| `workerCount`                               |                      `1` | Non-negative actor workers.                              |
+| `effectWorkerCount`                         |                      `1` | Non-negative effect workers.                             |
+| `broadcastWorkerCount`                      |                      `1` | Non-negative broadcast workers when realtime is enabled. |
+| `reminderSchedulerCount`                    |                      `1` | Non-negative reminder schedulers.                        |
+| `processHeartbeatIntervalMilliseconds`      |                 `15_000` | Positive persisted heartbeat cadence.                    |
+| `processAliveThresholdMilliseconds`         |                 `60_000` | Positive age after which an owner is stale.              |
+| `shutdownTimeoutMilliseconds`               |                 `15_000` | Positive shared graceful-shutdown budget.                |
+| `supervisorRestartDelayMilliseconds`        |                    `100` | Positive initial failed-role replacement delay.          |
+| `supervisorMaximumRestartDelayMilliseconds` |                 `10_000` | Positive cap no smaller than the initial delay.          |
+| `wakeUp`                                    | `InProcessWakeUpAdapter` | Adapter implementing `watch`, `notify`, and `close`.     |
+| `logger`                                    |          console methods | Structured `debug`, `info`, `warn`, and `error` sink.    |
+
+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.
+
+## Retention and cleanup
+
+| Option                                   |     Default | Contract                                                         |
+| ---------------------------------------- | ----------: | ---------------------------------------------------------------- |
+| `retentionIntervalMilliseconds`          | `3_600_000` | Non-negative automatic history-pruning cadence; `0` disables it. |
+| `deadProcessCleanupIntervalMilliseconds` |    `60_000` | Non-negative stale-owner recovery cadence; `0` disables it.      |
+| `messageRetentionMilliseconds`           |     30 days | Positive default completed-message retention.                    |
+| `messageRetentionByActorType`            |        `{}` | Positive per-type message-retention overrides.                   |
+| `instanceRetentionByActorType`           |        `{}` | Positive per-type instance-expiration opt-ins.                   |
+| `processRetentionMilliseconds`           |      7 days | Positive stopped-process retention.                              |
+| `pruneBatchSize`                         |     `1_000` | Positive integer maximum rows rechecked per pruning transaction. |
+
+Automatic retention prunes messages and stopped process records. Actor
+instance expiration remains an explicit administration action even when a type
+opts in.
+
+## Authorization, instrumentation, and broadcast
+
+All authorization callbacks default to `false`:
+
+- `authorizeMessage({ actorType, actorId, operation, arguments,
+authorizationContext })`
+- `authorizeQuery({ actorType, actorId, operation, arguments,
+authorizationContext })`
+- `authorizeDestroy({ actorType, actorId, authorizationContext })`
+- `authorizeAdministration({ action, resource, resourceId,
+authorizationContext })`
+- `authorizeSubscription({ actorType, actorId, authorizationContext })`
+
+Callbacks may return a boolean or promise. Authorization contexts are
+application-owned server values and are never persisted. See
+[Authorization](authorization.md) for the entry-point matrix.
+
+`instrumentation(event)` is synchronous. The runtime freezes metadata-only
+events, catches sink failures, and reports the sink error through `logger`.
+
+`broadcast(event)` forwards committed realtime invalidations through an
+application-owned shared transport. A receiving process calls
+`runtime.realtime.publish(event)`. It is unnecessary for a single-process
+server.
+
+## Database adapters
+
+### SQLite
+
+`sqlite({ path, timeoutMilliseconds = 5_000, lockRetryAttempts = 10 })` uses
+Node's built-in `node:sqlite`. `lockRetryAttempts` is a positive integer. The
+timeout controls SQLite's busy timeout; transaction acquisition retries use
+short capped backoff only when no synchronous deadline is active.
+
+### PostgreSQL
+
+`postgresql(options)` accepts:
+
+| Option                          |                    Default |
+| ------------------------------- | -------------------------: |
+| `connectionString`              |                   required |
+| `maximumConnections`            |               `pg` default |
+| `idleTimeoutMilliseconds`       |               `pg` default |
+| `connectionTimeoutMilliseconds` |               `pg` default |
+| `applicationName`               |          `"solid-objects"` |
+| `onPoolError`                   | structured `console.error` |
+
+`database.wakeUp(options)` creates a dedicated notification adapter using the
+same connection string. Its options are `channelPrefix = "solid_objects"`,
+`applicationName = "solid-objects-wake-up"`, and `onListenerError`. Use a
+direct or session-pooled connection because PostgreSQL `LISTEN` is
+session-scoped.
+
+`postgresqlWakeUp({ connectionString, ...options })` constructs that adapter
+without a database instance. The adapter translates portable `?` parameters;
+write `??` in SQL passed through `DatabaseConnection` when PostgreSQL needs the
+literal JSON existence operator.
+
+### MySQL
+
+`mysql(options)` accepts:
+
+| Option                    |                      Default |
+| ------------------------- | ---------------------------: |
+| `connectionString`        |                     required |
+| `maximumConnections`      |                         `10` |
+| `idleTimeoutMilliseconds` |                     `60_000` |
+| `queueLimit`              | `0` (unbounded driver queue) |
+
+Counts are non-negative except `maximumConnections`, which is positive. Tables
+use InnoDB. `mysqlSql(sql)` translates the limited portable conflict syntax
+used by database integrations into MySQL syntax.
+
+### Redis wake-up
+
+`redisWakeUp({ url, channelPrefix = "solid_objects",
+connectionTimeoutMilliseconds = 1_000, onError })` uses separate lazy
+publisher and subscriber clients. Connection, subscription, and publication
+failures are reported and bounded; database polling continues.
+
+## Lifecycle order
+
+Call `runtime.install()` before serving traffic or starting roles. Run the
+supervisor with an application-owned abort signal. To shut down, abort, await
+`runtime.run()`, then close adapters through `runtime.close()`:
+
+```typescript
+const controller = new AbortController()
+const running = runtime.run(controller.signal)
+
+controller.abort()
+await running
+await runtime.close()
+```
+
+Calling `close()` while `run()` is active raises an error so database and
+wake-up connections cannot disappear beneath live roles.

package/docs/correctness.md

@@ -0,0 +1,53 @@
+# Correctness and delivery semantics
+
+- Delivery is ordered per actor identity and at least once.
+- Different identities may execute concurrently.
+- Sequence allocation and durable enqueue are one transaction.
+- A retryable failure rolls state and staged intents back and blocks later work.
+- A stale activation may finish JavaScript but cannot commit.
+- Effects can execute more than once and must deduplicate by their stable id.
+- Destruction creates an incarnation boundary; old leases cannot address a
+  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
+  public exception contract.
+- Operation, lifecycle, observable, and payload callbacks retain their owning
+  runtime through async context. Isolated runtimes therefore never fall back to
+  a global default while actor-owned code resolves another actor reference.
+- Observable outbox rows are claimed in actor revision order. Subscription
+  sessions and browser clients reject duplicate or stale revisions within an
+  incarnation, while a recreated actor starts a new revision sequence.
+- Wake-up notifications happen only after commit and never replace polling.
+  Workers watch before claiming, so an in-process notification between an empty
+  claim and the following wait is retained.
+- 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.
+- 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.
+- `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
+  that read-only context and may write only through their supplied fenced
+  connection. The guarantee applies only to clients passed through the facade.
+- Snapshots hydrate one committed state image and evaluate every inferred getter
+  against it. Getter mutation or staged durable work rejects the whole snapshot;
+  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.

package/docs/errors-and-recovery.md

@@ -0,0 +1,89 @@
+# Errors and recovery
+
+All library errors extend `SolidObjectsError`. Ordinary validation failures may
+also use `TypeError`. Catch the narrow class whose recovery you can perform;
+do not parse error messages.
+
+## Caller-facing control flow
+
+| Error                   | Meaning                                                                                                          | Recovery                                                                                                                      |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `Rejected`              | Actor domain refusal. The turn rolled back and will not retry.                                                   | Inspect `code`, frozen `details`, and `messageId`; correct the request or present the refusal.                                |
+| `Unauthorized`          | The relevant deny-by-default policy refused the operation.                                                       | Reauthenticate or change the application policy; actor IDs are not credentials.                                               |
+| `SyncEnqueueTimeout`    | The enqueue transaction did not commit before the call deadline.                                                 | It is safe to retry with an idempotency key; no durable message exists from this attempt.                                     |
+| `SyncTimeout`           | Enqueue committed but result waiting expired.                                                                    | Retain `messageReference`, inspect `details.waitingOn`, and call `wait()` again later.                                        |
+| `MessageFailed`         | The durable operation failed permanently.                                                                        | Correlate `messageId`, inspect persisted `details`, then inspect or retry its dead letter under administration authorization. |
+| `ActorDestroyed`        | An authorized waiter lost the actor incarnation it was waiting on.                                               | Decide whether the new incarnation should receive a new operation.                                                            |
+| `IdempotencyConflict`   | One actor reused a key for different arguments, operation, or delivery mode.                                     | Reuse a key only for the identical request.                                                                                   |
+| `MailboxFull`           | One actor reached `maxMailboxLength`.                                                                            | Apply admission control or wait for existing work; do not blindly increase the cap.                                           |
+| `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.                                               |
+
+`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.
+
+## Definition and programming errors
+
+These errors normally require a code or deployment correction:
+
+- `InvalidActor`: invalid actor type, state version, migration declaration,
+  member name, payload declaration, or duplicate registration.
+- `UnknownActorType`, `UnknownOperation`, `UnknownEffect`, and
+  `UnknownCommitAction`: deployed registration does not match durable work or
+  code attempted an undeclared operation.
+- `StateMigrationError`: migration path is missing or failed, or stored state
+  is newer than the process code.
+- `ActorCallCycle`: actor code tried to make a synchronous actor call, use a
+  reference's `send`, or destroy an actor. Stage delivery with `this.sendTo()`.
+- `QueryMutatedState`: a field/getter query, snapshot, observable, or payload
+  projection changed state or staged durable work.
+- `ApplicationWriteForbidden`: actor-owned code attempted a write through
+  `guardApplicationDatabase()` outside the fenced commit-action connection.
+- `InvalidPayload`, `InvalidPayloadBroadcast`, and
+  `UnknownPayloadBroadcast`: a value or requested personalized projection did
+  not satisfy the JSON and declaration contract.
+- `UnsupportedDatabase`: an adapter reports a database family the runtime does
+  not support.
+
+`NonRetryableError` is also the application extension point for an unexpected
+failure that retry cannot resolve:
+
+```typescript
+import { NonRetryableError } from "solid-objects"
+
+class InvalidWorkflowDefinition extends NonRetryableError {}
+```
+
+Throwing it from an operation rolls back the turn and dead-letters immediately.
+Prefer `this.reject()` for expected domain decisions because it preserves a
+stable public code and does not classify the operation as failed.
+
+## Lease, database, and administration errors
+
+- `LostActivation` means the worker no longer owns the commit fence. The
+  runtime discards the stale result; application code should not suppress it.
+- `DatabaseDeadlineExceeded` is the adapter-level deadline used to construct
+  synchronous timeout behavior.
+- `UnknownDeadLetter` and `UnknownReminder` mean an authorized administration
+  lookup found no record.
+- `ReminderNotPaused` means only a completed reminder remains; schedule it
+  again through its actor instead of resuming it.
+
+Realtime protocol validation uses `TypeError` for malformed subscription or
+browser envelopes. Server delivery failures are isolated to the session and
+reported through instrumentation; one connection cannot fail durable
+broadcast processing for the others.
+
+## Retry ownership
+
+An ordinary thrown error is retryable until `maxAttempts`. Each failure rolls
+back state and staged work and preserves strict ordering, so later messages do
+not pass the poison message. After terminal failure, the dead letter records
+the arguments, attempts, and error. `runtime.deadLetters.retry(id)` creates one
+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`.