solid-objects 0.12.0

package/docs/operations.md

@@ -0,0 +1,170 @@
+# Operations
+
+Runtime roles use durable polling as the correctness fallback. The default
+generation-based wake-up adapter interrupts waits for new actor messages,
+effects, reminders, and broadcasts in the same Node process. Notification
+errors are isolated and logged by role and error class without failing the
+committed work. Graceful shutdown stops new claims and allows active turns to
+finish within `shutdownTimeoutMilliseconds`, which defaults to 15 seconds. A
+component still running or stopping at the deadline emits
+`solid_objects.supervisor.component_shutdown_timeout`; the runtime then returns
+without pretending JavaScript code was forcibly terminated. Operators should
+monitor oldest ready work, claimed work, dead letters, effect failures,
+reminder lag, lease loss, process heartbeats, and database contention.
+
+`runtime.run()` replaces built-in roles and registered application components
+that return or reject before shutdown. `supervisorRestartDelayMilliseconds`
+defaults to 100 ms and doubles after consecutive run or construction failures,
+capped by `supervisorMaximumRestartDelayMilliseconds` at 10 seconds. Replacement
+and replacement-failure events contain the role class, failure count, and error
+class only. Repeated failure messages are excluded from instrumentation.
+
+`maxMessagesPerActivationPass` defaults to 50 and
+`maxActivationDurationMilliseconds` defaults to 5 seconds. A pass yields when
+either budget is exhausted. Lower values improve fairness when a few actor
+identities stay continuously busy; higher values reduce claim overhead for
+isolated backlogs. `solid_objects.activation.yielded` reports the actor
+identity, turns processed, and remaining due membership count.
+
+`claimScanLimit` defaults to 100. Global claims inspect a bounded ordered set of
+actor identities and continue after a lost lease race, preserving worker
+parallelism without an unbounded scan.
+
+Workers retain a hydrated actor and its fenced lease for
+`idleDeactivationTimeoutMilliseconds`, which defaults to 30 seconds. Idle
+leases renew at `leaseRenewalIntervalMilliseconds`; the worker polling cadence
+is capped at that interval while any activation may be cached. Fairness yield,
+lease loss, timeout, and shutdown release the lease. `runUntilIdle()` and the
+runtime's synchronous caller release before returning because they are no
+longer polling.
+
+Actors can override protected `onActivate()` and `onDeactivate()` methods for
+nondurable, process-local resources. Either hook may be asynchronous. Hook code
+runs under the application-write guard, and `onDeactivate()` is best effort:
+it may not run after a crash, cannot establish a correctness guarantee, and a
+failure is logged without preventing lease release.
+
+`runtime.processes.all()` returns administration-authorized immutable process
+metadata with hostname, host process ID, Node and Solid Objects versions, and a
+current `stale` flag. Graceful shutdown first persists `draining` with a
+`shutdownRequestedAt` timestamp, then deactivates owned actors and atomically
+releases every role claim before persisting `stopped`. `cleanup()` reauthorizes
+separately and performs the same release for stale running or draining
+processes. The cleanup count is instrumented; application payloads are not.
+
+Committed calls and `message.wait()` apply `timeoutMilliseconds` to the entire
+durable wait, beginning before enqueue or message lookup. Adapter deadlines
+bound serialized SQLite access and lock waits, PostgreSQL pool acquisition,
+statements, and locks, and MySQL pool acquisition, queries, and transaction
+lock waits. A `SyncEnqueueTimeout` means the enqueue transaction did not commit
+and there is no durable message to recover. Once enqueue commits, a
+`SyncTimeout` includes `waitingOn`, activation and process metadata, an earlier
+blocking message when present, and the original `messageReference`. Database
+contention that prevents inspection is reported as `databaseContention`. The
+durable message continues after an ordinary wait timeout, so callers can store
+that reference or await `error.messageReference.wait()` later. Timeout
+instrumentation excludes actor arguments, results, and error messages.
+
+JavaScript promises already running in the process are cooperative and are not
+forcefully terminated. An actor operation that has started may therefore
+finish after the caller's timeout; durable leases and fenced commits remain the
+correctness boundary.
+
+Committed calls and `message.wait()` fail with `SyncInsideTransaction` when
+invoked inside `database.transaction(...)` on the configured Solid Objects
+adapter. The check happens before enqueue for direct calls. This prevents the
+caller from waiting on a pool connection or SQLite access slot that its own
+ambient transaction still holds.
+
+Authorized operators can inspect terminal actor failures with
+`runtime.deadLetters.all()` and retry one with `runtime.deadLetters.retry()`.
+Retry is idempotent per dead letter: the record retains the replacement message
+ID and later calls return a reference to that same message.
+
+Self-scheduling actors need a low-frequency reconciler because application
+alarms can still be lost. `runtime.reconciliation` provides administration-
+authorized, read-only views for active instances, quiet instances without
+ready work, claimed work, or scheduled reminders, migrated state batches, and
+orphaned actor IDs. Collection reads use a maximum page size of 1,000 and a
+stable cursor.
+
+The host application supplies its current owner IDs to `orphaned()` because
+Node applications do not share an Active Record relation abstraction. Send
+every repair through the actor's typed `send` dispatcher, optionally with a
+future `availableAt` to spread large repairs. Never update persisted actor
+state from reconciliation code.
+
+The runtime automatically prunes expired message and stopped-process history
+once at startup and every `retentionIntervalMilliseconds`, which defaults to
+one hour. Stale process ownership is recovered independently every
+`deadProcessCleanupIntervalMilliseconds`, which defaults to one minute. Set an
+interval to zero to disable its scheduler. Failed passes emit metadata-only
+events and retry with bounded exponential backoff without stopping other
+runtime roles.
+
+Operators can also use `runtime.retention.preview()` and
+`runtime.retention.prune()`. Both calls require administration authorization;
+use preview first and alert on an unexpected count before executing deletion.
+Message history defaults to 30 days with optional per-actor overrides. Stopped
+process history defaults to 7 days. Instance expiration is disabled unless an
+actor type appears in `instanceRetentionByActorType`, and remains an explicit
+operator action because it deletes the entire actor incarnation.
+
+Pruning selects and rechecks at most `pruneBatchSize` rows per transaction. It
+preserves ready and claimed messages, dead-letter originals and replacements,
+unfinished effects and broadcasts, scheduled reminders, leased or paused
+instances, and processes that still own a claim or activation. Instance
+expiration removes the entire actor incarnation and all of its retained
+history, so use it only for actor types whose state is safely disposable.
+
+`runtime.doctor.run()` returns structured configuration, schema, database,
+authorization-posture, live-role, and durable-round-trip checks. A warning does
+not make the report unhealthy; a failed check does. The round trip targets only
+its probe actor, uses the ordinary lease and fenced commit path, and removes its
+instance and process records afterward. Use `{ roundTrip: "skip" }` when the
+diagnostic must not write.
+
+The doctor reports whether each authorization callback was explicitly
+configured and probes all configured policies with a neutral context. It warns
+when every policy denies the probe, a policy needs unavailable application
+context, or destruction, subscription, or administration allows it. The probe
+does not replace application-specific authorization tests. Do not expose the
+report through an HTTP or CLI surface without applying the host application's
+own administration policy.
+
+The packaged `solid-objects` executable loads a configured runtime exported as
+default or `runtime` from `solid-objects.config.js`, or from `--config PATH`.
+It provides `start`, `doctor`, `status`, `cleanup`, `dead-letters`,
+`retry-dead-letter`, `reminders`, `resume-reminder`, and `prune`. Output is JSON,
+and destructive retention requires `prune TARGET --execute`; the unqualified
+command is a preview. Administrative commands consistently pass
+`{ source: "cli" }` through the ordinary policy boundary.
+
+Tests can use `runtime.testing.drain()` to process reminders, actor turns,
+effects, actor callbacks, and broadcasts in deterministic passes. The helper
+stops every temporary runner even when a handler raises. `reset()` must only run
+while the supervised runtime is stopped; it explicitly clears child tables,
+instances, and process records and replaces the cached synchronous caller.
+
+The optional `instrumentation` callback receives immutable events with the
+`solid_objects.` prefix. Core events cover runtime lifecycle, message
+enqueue/start/completion/rejection/failure, activation loss, commit actions,
+effects, reminders, broadcasts, dead letters, worker setup failures, actor
+destruction, and retention pruning. Failed realtime delivery emits
+`subscription.delivery_failed` and
+removes that session's actor registration without retrying application socket
+code. Event attributes are restricted to identities, operation or handler
+names, delivery mode, sequence, attempt, outcome, counts, durations, and error
+class names. The runtime catches sink exceptions and reports only the failed
+event name and sink error class through the configured logger.
+
+`runtime.reminders.all()` provides administration-authorized, cursor-paginated
+alarm metadata filtered by actor type or status. Arguments and error messages
+remain private. `resume()` moves a paused reminder back to `scheduled`, clears
+its claim and stored error, and optionally assigns a new run time. Repeating
+resume on an already scheduled reminder is a no-op; completed reminders cannot
+be resumed.
+
+Scheduling an existing actor operation for a different time emits
+`solid_objects.reminder.replaced` after the fenced actor commit. Scheduling it
+for the same time emits nothing.

package/docs/parity.md

@@ -0,0 +1,94 @@
+# Ruby parity ledger
+
+This ledger tracks spiritual feature parity with the Ruby `solid_objects` gem.
+Parity means preserving a capability and its correctness or security boundary,
+not copying a Rails API into Node.
+
+Reference: Ruby `solid_objects` 0.12.0 at commit `a01b6f5`.
+
+The Node `0.12.0` implementation has spiritual parity with that reference. Its
+relational runtime, correctness boundaries, administration, diagnostics,
+realtime projections, browser behavior, and supported adapters have native
+equivalents. Rails engine and rendering surfaces are intentionally replaced by
+transport- and framework-neutral JavaScript APIs. The partial guard row and the
+shared planned result-lookup row below are explicit scope boundaries, not
+missing Ruby capabilities.
+
+## Status vocabulary
+
+- **Native**: the TypeScript runtime provides the capability in a Node-native
+  shape.
+- **Partial**: the core exists, but an important Ruby guarantee or operational
+  surface is missing.
+- **Planned**: no defensible equivalent exists yet.
+- **Not applicable**: the Ruby feature belongs specifically to Rails, Active
+  Record, Action Cable, Turbo, or Ruby language constraints. The equivalent
+  Node capability is tracked separately when one is useful.
+
+## Runtime and correctness
+
+| Capability                                                                                                    | Status  | TypeScript shape or remaining work                                                                                                                                                                                 |
+| ------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Actor registry, durable identity, JSON state, and adjacent state migrations                                   | Native  | Ordinary classes, static actor types, inferred state, explicit migrations, and isolated runtime context across every actor-instance callback.                                                                      |
+| Fluent committed calls and background delivery                                                                | Native  | `await reference.operation()` and `reference.send.operation()`.                                                                                                                                                    |
+| Ordered mailbox, sequence allocation, idempotency, retries, dead letters, leases, renewal, and fenced commits | Native  | Relational ready/claimed membership tables, distinct generated request IDs and caller idempotency keys, durable history, and adapter-appropriate sequence locking.                                                 |
+| Domain rejection and strict poison ordering                                                                   | Native  | Rejections roll back without retry; retryable failures block later operations until completion or dead-lettering.                                                                                                  |
+| Bounded activation passes and hot-actor fairness                                                              | Native  | Configurable turn-count and elapsed-time budgets bound each pass, then move only that actor's already-due memberships behind actors already waiting.                                                               |
+| Bounded claim candidate scan                                                                                  | Native  | A configurable ordered scan continues to another ready actor when a worker loses the first candidate's lease race.                                                                                                 |
+| Idle activation cache                                                                                         | Native  | Long-running workers retain hydrated actors under renewable fenced leases, restore public state after failed turns, and release on timeout, fairness yield, lease loss, or shutdown.                               |
+| Transactional effects and outcome operations                                                                  | Native  | At-least-once handlers receive immutable stable effect, attempt, source-message, and actor identity; success and failure return through actor operations.                                                          |
+| Actor-to-actor delivery                                                                                       | Native  | `sendTo(reference).operation()` stages delivery in the source actor commit.                                                                                                                                        |
+| One-shot and recurring reminders                                                                              | Native  | Scheduling, replacement events, catch-up policy, stale-claim recovery, pausing, authorized inspection, and idempotent resume are implemented.                                                                      |
+| Same-database commit actions                                                                                  | Native  | Registered actions receive source-message identity, mailbox sequence, activation generation, and the fenced transaction connection.                                                                                |
+| Ambient transaction rejection                                                                                 | Native  | Committed calls and message waits fail before blocking when the current async context already owns a transaction on the Solid Objects adapter.                                                                     |
+| Direct application-write isolation during actor code                                                          | Partial | `guardApplicationDatabase()` fails closed for operations, projections, migrations, and commit actions; only the supplied fenced commit-action connection may write. Unwrapped clients cannot be intercepted.       |
+| Committed snapshots                                                                                           | Native  | `snapshot()` returns authorized persisted fields and inferred getters from one read-only committed state image; realtime replay reads explicit observables without mailbox history.                                |
+| Actor destruction and incarnation fencing                                                                     | Native  | Authorized cascading deletion creates a fresh instance ID on recreation; an authorized waiter receives `ActorDestroyed` when that incarnation disappears.                                                          |
+| Result recovery and sync timeout diagnostics                                                                  | Native  | Status, result, and wait reauthorize the stored operation; terminal failure raises structured `MessageFailed`; whole-call adapter deadlines distinguish enqueue, wait, database, activation, and mailbox blockers. |
+| Result lookup by request ID                                                                                   | Planned | This is also an open Ruby roadmap item and will be implemented in both runtimes when its authorization shape is settled.                                                                                           |
+
+## Operations
+
+| Capability                                                                    | Status | TypeScript shape or remaining work                                                                                                                                             |
+| ----------------------------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Process registration, heartbeats, stale claim recovery, and graceful shutdown | Native | Runtime roles persist host, PID, runtime versions, draining and stopped transitions, cooperative cancellation, and a bounded shutdown deadline; cleanup recovers stale claims. |
+| Failed-role replacement                                                       | Native | Built-in and registered roles are rebuilt through their factories with capped backoff; shutdown is the terminal replacement boundary.                                          |
+| Additional supervised components                                              | Native | `registerComponent()` builds, validates, runs, and stops application components with the runtime.                                                                              |
+| Dead-letter inspection and retry                                              | Native | `runtime.deadLetters` provides deny-by-default immutable inspection and idempotent durable retry linkage.                                                                      |
+| Reconciliation reads                                                          | Native | Authorized cursor pages cover active, quiet, and orphaned instances; bounded state batches are migrated and deeply frozen.                                                     |
+| Message, process, and opt-in instance retention                               | Native | Supervised scheduling bounds message and process growth; authorized manual APIs add preview and keep destructive instance expiration explicit.                                 |
+| Doctor and schema verification                                                | Native | Structured checks cover configuration, schema/version shape, adapter server versions, neutral-context policy probes, live roles, and a targeted round trip.                    |
+| CLI                                                                           | Native | The packaged executable loads an application runtime and exposes start, diagnostics, processes, dead letters, reminders, and explicit retention pruning as JSON.               |
+| Structured instrumentation                                                    | Native | An isolated transport-neutral sink emits immutable lifecycle metadata and structurally excludes application payloads.                                                          |
+| Public test helper                                                            | Native | `runtime.testing` provides role-selective deterministic draining and dependency-ordered reset without relying on cascades.                                                     |
+
+## Databases and wake-up
+
+| Capability               | Status | TypeScript shape or remaining work                                                                                                                                                      |
+| ------------------------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| SQLite                   | Native | Uses built-in `node:sqlite`, serialized process-local access, bounded transient writer retries, foreign keys, strict tables, database time, and deadline-bounded access and lock waits. |
+| PostgreSQL               | Native | Optional `pg` 8.23 peer, bounded pooling, 64-bit schema, row-locked sequences, server checks, and deadline-bounded pool, statement, and lock waits.                                     |
+| MySQL                    | Native | Optional `mysql2` 3.23 peer, bounded pooling, InnoDB schema, row-locked sequences, scoped deadlock retry, and deadline-bounded pool, query, and lock waits.                             |
+| Durable polling fallback | Native | Every role progresses without a notification service.                                                                                                                                   |
+| In-process wake-up       | Native | A generation-based default adapter prevents claim-to-wait signal loss; commits wake role-specific waiters and polling remains the fallback.                                             |
+| PostgreSQL wake-up       | Native | `database.wakeUp()` uses one dedicated event-driven client, role-specific `LISTEN/NOTIFY`, generation fencing, reconnectable listeners, and durable polling fallback.                   |
+| Redis wake-up            | Native | An optional `redis` peer provides role-specific Pub/Sub over separate lazy publisher/subscriber connections, with bounded failures and durable polling fallback.                        |
+
+## Realtime and browser behavior
+
+| Capability                                                   | Status         | TypeScript shape or remaining work                                                                                                                                                                             |
+| ------------------------------------------------------------ | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Explicit observable projection and durable invalidations     | Native         | `observables()` is opt-in; only changed projected values enter the broadcast outbox.                                                                                                                           |
+| Action Cable channels and signed stream names                | Not applicable | `runtime.realtime` provides authenticated transport-neutral sessions; the host owns its HTTP/WebSocket server and authentication.                                                                              |
+| Authorized subscriptions                                     | Native         | Each request is denied by default and authorized before actor lookup; sessions replay committed observables and fence ordered durable revisions. Multi-process hosts explicitly bridge their shared transport. |
+| Turbo scalar replacement                                     | Not applicable | The browser client exposes invalidations to application rendering code. Framework adapters can be separate packages.                                                                                           |
+| Keyed component refresh, morph/replace, and batch coalescing | Native         | A typed framework-neutral registry selects explicit dependencies, coalesces batch requests, aborts superseded work, fences each target, and delegates synchronous application strategy to the host.            |
+| Personalized payload broadcasts                              | Native         | Static typed projections run against committed state under each fresh subscriber context, reauthorize as queries, isolate failures, and carry independent revision fences.                                     |
+| Real-browser compatibility suite                             | Native         | Playwright exercises subscription replay over native WebSocket, incarnation/revision fences, payload delivery, component batching, and cancellation in Chromium.                                               |
+
+## Rails-specific surfaces
+
+The Rails engine, generators, Active Record models/controllers, ERB helpers,
+Turbo renderer, and Action Cable channel are not copied into this package.
+Their underlying runtime, administration, authorization, and realtime
+capabilities are represented above by Node-native APIs and protocols.

package/docs/releasing.md

@@ -0,0 +1,45 @@
+# Releasing
+
+Publishing is driven by version tags and npm Trusted Publishing. GitHub Actions
+uses a short-lived OpenID Connect identity, so the repository does not need an
+npm token.
+
+## npm trusted publisher
+
+The `solid-objects` package must authorize this GitHub Actions identity:
+
+- Organization or user: `cardmagic`
+- Repository: `solid-objects-js`
+- Workflow filename: `ci.yml`
+- Environment: none
+- Allowed action: `npm publish`
+
+The relationship can be created while authenticated as a package owner:
+
+```shell
+npm trust github solid-objects \
+  --repo cardmagic/solid-objects-js \
+  --file ci.yml \
+  --allow-publish \
+  --yes
+```
+
+## Release procedure
+
+1. Update the version in `package.json` and `pnpm-lock.yaml` and move the
+   release notes out of the Unreleased section in `CHANGELOG.md`.
+2. Run `pnpm run format:check`, `pnpm run check`, `pnpm run test:coverage`,
+   `pnpm run build`, `pnpm run pack:check`, and
+   `pnpm audit --audit-level=high`.
+3. Commit and push `main`.
+4. Create and push an annotated tag matching the package version:
+
+   ```shell
+   git tag -a v0.13.0 -m "Version 0.13.0"
+   git push origin v0.13.0
+   ```
+
+The tag runs the complete CI matrix. The publish job starts only after every
+quality, database, Redis, and browser job succeeds. It rejects tags that do not
+match `package.json`, safely skips versions already present in npm, and
+publishes new versions with npm provenance.

package/docs/state-and-lifecycle.md

@@ -0,0 +1,162 @@
+# State and lifecycle
+
+An actor class is both the persisted state definition and the typed operation
+surface. Registration constructs the class to discover its enumerable public
+fields, then walks its prototype chain to discover methods and getters.
+
+## Persisted state and operations
+
+- Enumerable public instance fields are persisted JSON state.
+- Public methods are ordered operations and accept zero arguments or one
+  object argument.
+- Public fields and getters are ordered, read-only queries on a reference.
+- `#private` fields are process-local and survive only while an activation is
+  cached.
+- Actor arguments, state, results, observables, and payloads must be
+  JSON-compatible and fit their configured byte limits.
+- Operation, field, and getter names must not collide with the reference API.
+
+The constructor must establish every persisted field and must not depend on
+external state. Solid Objects invokes it while validating the class, creating
+defaults, hydrating state, and projecting a snapshot.
+
+## State migrations
+
+Every actor starts at state version 1. Increase `stateVersion` when existing
+rows need a structural transformation and retain an adjacent migration for
+every version:
+
+```typescript
+import { Actor, type JsonObject } from "solid-objects"
+
+class Document extends Actor {
+  static override readonly actorType = "Document"
+  static override readonly stateVersion = 3
+  static override readonly migrations = [
+    {
+      from: 1,
+      to: 2,
+      migrate: (state: JsonObject): JsonObject => ({
+        title: state.name ?? "Untitled",
+      }),
+    },
+    {
+      from: 2,
+      to: 3,
+      migrate: (state: JsonObject): JsonObject => ({
+        ...state,
+        archived: false,
+      }),
+    },
+  ]
+
+  title = "Untitled"
+  archived = false
+}
+```
+
+Migrations run synchronously in ascending order when an actor is hydrated for
+an operation, snapshot, reconciliation state read, observable replay, or
+personalized payload. Each receives a detached JSON object and must return a
+JSON object. After the chain completes, any new persisted field missing from
+the result receives its constructor default. Migrated state is persisted only
+by the next successful fenced operation commit; read-only projections do not
+rewrite the row.
+
+A migration must be deterministic and side-effect free. It cannot perform
+asynchronous work or write through a database wrapped by
+`guardApplicationDatabase()`. Missing, duplicate, or non-adjacent migrations,
+a failing migration, or state newer than the running code raises
+`StateMigrationError`.
+
+For a destructive shape change, use expand/contract deployment: first deploy
+readers that understand both shapes, then deploy the migration, wait for
+operational evidence that actors have advanced, and only then remove old-shape
+support. If old code cannot understand the new shape, drain it before new code
+can persist the migration. Keep old migration steps so actors idle for several
+releases can still advance one version at a time.
+
+Actor state migration is separate from `runtime.install()`. The latter applies
+the package's relational schema migrations; it does not eagerly rewrite actor
+state.
+
+## Activation lifecycle
+
+Override `onActivate()` and `onDeactivate()` for process-local resources:
+
+```typescript
+class Device extends Actor {
+  static override readonly actorType = "Device"
+
+  #connection: DeviceConnection | undefined
+
+  protected override async onActivate(): Promise<void> {
+    this.#connection = await connectToDevice(this.actorId)
+  }
+
+  protected override async onDeactivate(): Promise<void> {
+    await this.#connection?.close()
+    this.#connection = undefined
+  }
+}
+```
+
+Activation happens after state migration and before an operation attempt
+starts. A setup failure restores the claimed message without consuming an
+attempt. A long-running worker may reuse the hydrated actor and its private
+fields until `idleDeactivationTimeoutMilliseconds`, fairness yield, lease loss,
+or shutdown.
+
+Lifecycle hooks have no `currentMessage` and run under the application-write
+guard. Intents staged by `onActivate()` join the first turn's commit; use that
+only when reactivation should repeat the intent safely. `onDeactivate()` is
+best effort, its staged intents are discarded, and it may not run after a
+crash, so it cannot establish correctness.
+
+## Domain rejection and failure
+
+Call `this.reject(code, { message, details })` when an operation is valid but
+the domain refuses it. Codes contain lowercase letters, digits, and
+underscores. The turn rolls back, staged work is discarded, the message becomes
+`rejected`, and later mailbox work remains eligible. The caller receives
+`Rejected` with the code, frozen JSON details, and durable message ID.
+
+Throwing another error rolls the turn back and schedules a retry according to
+`maxAttempts` and `retryDelayMilliseconds`. Throw a custom subclass of
+`NonRetryableError` only when retry cannot help; the message goes directly to a
+terminal dead letter. See [Errors and recovery](errors-and-recovery.md).
+
+## Queries and snapshots
+
+Reading a public field or getter through an actor reference is an ordered
+mailbox query:
+
+```typescript
+const count = await Counter.ref("primary").count
+```
+
+Use `snapshot()` when the read need not wait behind mailbox work:
+
+```typescript
+const snapshot = await Counter.ref("primary").snapshot({
+  authorizationContext: currentUser,
+})
+```
+
+Both paths call `authorizeQuery`. A snapshot hydrates one committed state
+image, returns all fields and getters as a deeply frozen value, and never adds
+a message to history. A getter that mutates state or stages work raises
+`QueryMutatedState` for the whole snapshot.
+
+## Destruction and reincarnation
+
+`reference.destroy()` calls the separate `authorizeDestroy` policy, deletes
+the current actor incarnation and every owned row, and returns `true` when an
+incarnation existed. Repeating it returns `false`.
+
+An actor cannot destroy another actor from inside a turn. A later message to
+the same actor type and ID creates a new instance ID and revision sequence.
+Old activation leases cannot commit to the new incarnation, and an authorized
+caller waiting on the deleted incarnation receives `ActorDestroyed`. An
+external effect or broadcast already executing cannot be recalled, but its
+stale completion cannot recreate or enqueue a callback to the deleted source.

package/package.json

@@ -0,0 +1,100 @@
+{
+  "name": "solid-objects",
+  "version": "0.12.0",
+  "description": "Durable, addressable objects for Node.js",
+  "type": "module",
+  "license": "MIT",
+  "author": "Lucas Carlson",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cardmagic/solid-objects-js.git"
+  },
+  "engines": {
+    "node": ">=24.15.0"
+  },
+  "packageManager": "pnpm@11.11.0",
+  "bin": {
+    "solid-objects": "dist/executable.js"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "README.md",
+    "CHANGELOG.md",
+    "MIT-LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./database/sqlite": {
+      "types": "./dist/database/sqlite.d.ts",
+      "import": "./dist/database/sqlite.js"
+    },
+    "./database/postgresql": {
+      "types": "./dist/database/postgresql.d.ts",
+      "import": "./dist/database/postgresql.js"
+    },
+    "./database/mysql": {
+      "types": "./dist/database/mysql.d.ts",
+      "import": "./dist/database/mysql.js"
+    },
+    "./wake-up/redis": {
+      "types": "./dist/wake-up/redis.d.ts",
+      "import": "./dist/wake-up/redis.js"
+    },
+    "./browser": {
+      "types": "./dist/browser/index.d.ts",
+      "import": "./dist/browser/index.js"
+    }
+  },
+  "scripts": {
+    "build": "pnpm run clean && tsc -p tsconfig.build.json && node scripts/prepare-executable.mjs",
+    "check": "pnpm run check:parameters && pnpm run check:documentation && tsc -p tsconfig.json --noEmit",
+    "check:documentation": "node scripts/check-documentation.mjs",
+    "check:parameters": "node scripts/check-parameter-style.mjs",
+    "clean": "node scripts/clean.mjs",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "test": "vitest run",
+    "test:browser": "pnpm run build && playwright test",
+    "test:coverage": "vitest run --coverage",
+    "test:postgresql": "vitest run test/postgresql.test.ts",
+    "test:mysql": "vitest run test/mysql.test.ts",
+    "test:redis": "vitest run test/redis-wake-up.test.ts",
+    "test:watch": "vitest",
+    "pack:check": "pnpm pack --dry-run && node scripts/check-package.mjs",
+    "prepack": "pnpm run build"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.62.1",
+    "@types/node": "^24.0.0",
+    "@types/pg": "^8.21.0",
+    "@types/ws": "^8.18.1",
+    "@vitest/coverage-v8": "^4.1.10",
+    "mysql2": "^3.23.3",
+    "pg": "^8.23.0",
+    "prettier": "^3.9.6",
+    "redis": "^6.2.1",
+    "typescript": "^5.9.0",
+    "vitest": "^4.1.10",
+    "ws": "^8.21.3"
+  },
+  "peerDependencies": {
+    "mysql2": "^3.23.3",
+    "pg": "^8.23.0",
+    "redis": "^6.2.1"
+  },
+  "peerDependenciesMeta": {
+    "mysql2": {
+      "optional": true
+    },
+    "pg": {
+      "optional": true
+    },
+    "redis": {
+      "optional": true
+    }
+  }
+}