solid-objects 0.17.7 → 1.0.0

package/docs/parity.md

@@ -4,7 +4,7 @@ This ledger tracks capability parity with the Ruby `solid_objects` gem.
 Parity preserves a capability and its correctness or security boundary. It does
 not copy a Rails API into Node.
 
-Reference: Ruby `solid_objects` 0.17.4. The JavaScript package began at the Ruby
+Reference: Ruby `solid_objects` 1.0.0. The JavaScript package began at the Ruby
 design's `0.12` capability generation; that version number did not imply earlier
 JavaScript releases.
 
@@ -48,28 +48,29 @@ SQL waiters read results and status from one statement. Ruby already checks
 completion and returns the result from the same loaded message; no Ruby change
 is needed for the JavaScript stale-result race fix.
 
-| 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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| Query and projection purity                                                                                   | Native  | Both runtimes reject state mutation and staged effects, recovery checks, commit actions, reminders, or outbound messages in queries, observable projections, and personalized payloads. Projection guards compare the complete staged work, including same-count replacements. Query and observable violations fail terminally with `QueryMutatedState`; payload violations fail only that payload. Snapshot projection reads enforce the same rule.                                                                                                                                                                                                                                                                  |
-| JSON property preservation                                                                                    | Native  | Reserved property names such as `__proto__`, `constructor`, and `prototype` remain ordinary data, including through size checks and immutable copies. Both suites consume `compatibility/json-values.json`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| 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  | Both runtimes renew between turns when due and retain the fence while a claim remains, allowing expired-turn recovery in mailbox order even with one allowed attempt. Reclaiming increments the attempt count; lease loss alone does not dead-letter a message. Relational ready/claimed membership tables, distinct generated request IDs and caller idempotency keys, durable history, adapter-appropriate sequence locking, and PostgreSQL/MySQL row locks held from fence validation through commit.                                                                                                                                                                                                              |
-| Domain rejection and strict poison ordering                                                                   | Native  | Rejections accept JavaScript identifier-style codes and roll back without retry; invalid codes fail terminally, while 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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| Backpressure and payload caps                                                                                 | Partial | Serialization enforces a shared maximum JSON nesting depth, raising `InvalidPayload`, and an optional caller-supplied `maxBytes` limit, raising `PayloadTooLarge`; keyed reminder names are bounded to 255 characters in JS and 191 in Ruby. These existing database limits remain runtime-specific; use at most 191 ASCII characters for a name shared across runtimes. Distributed per-actor rate limits, global admission control, and cache-capacity eviction are not planned in either runtime. They are hot, request-path, and loss-tolerant, so one durable ordered message per check is the wrong shape. Solid Objects Pro answers them with grouped and ephemeral operations, which [fit](fit.md) describes. |
-| 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 operations also receive the originally staged arguments for correlation. Typed callback envelopes are exported.                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| Actor-to-actor delivery                                                                                       | Native  | `sendTo(reference).operation()` stages delivery in the source actor commit.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| One-shot and recurring reminders                                                                              | Native  | Scheduling, cancellation by name/key/handle, read-your-writes inspection, catch-up policy, stale-claim recovery, pausing, and authorized resume. Cancellation cannot recall an already-enqueued occurrence.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| 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, outcome, and wait reauthorize the original stored operation and arguments. All delivery modes retain immutable JSON results under the result-size cap. Result reads raise terminal rejection/failure errors; outcome returns them as data. Whole-call deadlines distinguish enqueue, wait, database, activation, and mailbox blockers.                                                                                                                                                                                                                                                                                                                                                                |
-| Result lookup by request ID and idempotency key                                                               | Native  | `runtime.findBy({ requestId })` and `reference.findBy({ idempotencyKey })` rebuild a `MessageReference`, authorized with the hook the original call ran. An actor remembers the keys of its own finished turns, so a key lookup separates a pruned message from one that never existed.                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| 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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| Query and projection purity                                                                                   | Native  | Both runtimes reject state mutation and staged effects, recovery checks, commit actions, reminders, or outbound messages in queries, observable projections, and personalized payloads. Projection guards compare the complete staged work, including same-count replacements. Query and observable violations fail terminally with `QueryMutatedState`; payload violations fail only that payload. Snapshot projection reads enforce the same rule.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| JSON property preservation                                                                                    | Native  | Reserved property names such as `__proto__`, `constructor`, and `prototype` remain ordinary data, including through size checks and immutable copies. Both suites consume `compatibility/json-values.json`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| 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  | Both runtimes renew between turns when due and retain the fence while a claim remains, allowing expired-turn recovery in mailbox order even with one allowed attempt. Reclaiming increments the attempt count; lease loss alone does not dead-letter a message. Recovery after attempt one is immediate; subsequent interruptions use the existing retry delay with total attempts minus one, stored in ready membership. Mailbox order and other-actor progress are preserved. Both runtimes emit `activation.lost` with the message ID and attempt, including losses while saving a handler failure or rejection. JS busy workers and drains yield to timers and input between passes; Ruby uses threads and waits after lost turns. Relational ready/claimed membership tables, distinct generated request IDs and caller idempotency keys, durable history, adapter-appropriate sequence locking, and PostgreSQL/MySQL row locks held from fence validation through commit. |
+| Domain rejection and strict poison ordering                                                                   | Native  | Rejections accept JavaScript identifier-style codes and roll back without retry; invalid codes fail terminally, while 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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| Backpressure and payload caps                                                                                 | Partial | Serialization enforces a shared maximum JSON nesting depth, raising `InvalidPayload`, and an optional caller-supplied `maxBytes` limit, raising `PayloadTooLarge`; keyed reminder names are bounded to 255 characters in JS and 191 in Ruby. These existing database limits remain runtime-specific; use at most 191 ASCII characters for a name shared across runtimes. Distributed per-actor rate limits, global admission control, and cache-capacity eviction are not planned in either runtime. They are hot, request-path, and loss-tolerant, so one durable ordered message per check is the wrong shape. Solid Objects Pro answers them with grouped and ephemeral operations, which [fit](fit.md) describes.                                                                                                                                                                                                                                                           |
+| 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. Overlapping synchronous caller passes own separate workers, preserving staged intents and concurrent execution across actors; Ruby already isolates each invocation's activation.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| Transactional effects and outcome operations                                                                  | Native  | At-least-once handlers receive immutable stable effect, attempt, source-message, and actor identity; success and failure operations also receive the originally staged arguments for correlation. Typed callback envelopes are exported.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| Actor-to-actor delivery                                                                                       | Native  | `sendTo(reference).operation()` stages delivery in the source actor commit.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| One-shot and recurring reminders                                                                              | Native  | Scheduling, cancellation by name/key/handle, read-your-writes inspection, catch-up policy, stale-claim recovery, pausing, and authorized resume. Cancellation cannot recall an already-enqueued occurrence.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| Schedule call without an operation                                                                            | Native  | Both runtimes fail a turn that calls `schedule()` and then calls no operation on the result. The error is `ScheduleWithoutOperation`, which is not retried: the message becomes a dead letter, and the turn commits no state and no reminder. The turn can keep the result and call the operation later in the same turn. The projection guard counts such a call in an observable as staged work, so that turn fails with `QueryMutatedState`. The Cloudflare backend applies the same rules.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| 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, outcome, and wait reauthorize the original stored operation and arguments. All delivery modes retain immutable JSON results under the result-size cap. Result reads raise terminal rejection/failure errors; outcome returns them as data. Whole-call deadlines distinguish enqueue, wait, database, activation, and mailbox blockers.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| Result lookup by request ID and idempotency key                                                               | Native  | `runtime.findBy({ requestId })` and `reference.findBy({ idempotencyKey })` rebuild a `MessageReference`, authorized with the hook the original call ran. An actor remembers the keys of its own finished turns, so a key lookup separates a pruned message from one that never existed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 
 Effect callback envelopes are typed with `EffectFailurePayload`,
 `EffectSuccessPayload`, and `SerializedError` in both SQL and Cloudflare.
@@ -77,22 +78,23 @@ Ruby publishes RBS contracts with native Ruby field names; this does not change
 
 ## 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. SQL instance pruning uses an index on actor type and update time.                                                                                                                                                                                                                                                                                                                                                                                                               |
-| 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.                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| Operator dashboard                                                            | Native | Fetch and Node/Connect mounting, authorized views and actions, CSRF, filtering, paging, charts, and extensions match the Rack dashboard. Both dashboards expose individual retries and pause/resume; bulk redrive is available through the administration APIs. Pause does not interrupt an in-flight turn.                                                                                                                                                                                                                                                                                                                    |
-| Bulk redrive and administration audit                                         | Native | Message, effect, and broadcast scopes support idempotent retry and durable, bounded, cancellable redrive. Retry and task transitions persist administration identity in audit rows.                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| Structured instrumentation                                                    | Native | Versioned events, metric samples, isolated observers, and bounded authorized diagnostics match Ruby. Both test suites check SQL event attributes against `compatibility/telemetry-events.json`; only JS activation events add their turn's message fields. Both runtimes log exporter and observer failures, require observer callbacks, and cap local observers at 1,000. Timeout events share wait reasons, activation owner IDs, and string generations; see [observability](observability.md). Durable Objects uses host instrumentation and remote diagnostics, sends fewer attributes, and does not send `sync.timeout`. |
-| Large committed state warning                                                 | Native | `warnStateBytes` reports one `solid_objects.state.large` event, holding the actor type, actor ID, byte count, and threshold, when a committed image passes a 128 KB soft threshold. The event holds no application state, and it reports after the commit. The Ruby gem carries the same event and the same 5 MB hard default from `0.14.3`, as `warn_state_bytes`. Its threshold defaults to 64 KB rather than 128 KB, because its measured curve falls sooner: it keeps 55% of its empty-state throughput at 13 KB, where this package keeps 98% at 16 KB.                                                                   |
-| Public test helper                                                            | Native | `runtime.testing` provides role-selective deterministic draining, explicit-time due-reminder execution, and dependency-ordered reset without relying on cascades.                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| Clean-install artifact proof                                                  | Native | `pnpm run test:package` installs the packed tarball in a new project. It runs the packaged quickstart, which sends 25 concurrent calls to one identity, and the `examples/ticket-sale.ts` guide example. `pnpm run test:recovery` proves recovery after a worker process stops. Ruby's `rake quickstart` builds the gem, installs it in a new Rails application, and proves ordering and reminder recovery after a runtime restart.                                                                                                                                                                                            |
+| 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. Reused JS workers refresh their registration before each pass after cleanup or pruning; Ruby callers already reload and replace stale registrations. SQL instance pruning uses an index on actor type and update time.                                                                                                                                                                                                                                                          |
+| 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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `json` gem compatibility check                                                | Not applicable | The Ruby doctor and the Rails boot decode one JSON document with Active Support, to find a `json` gem release that Active Support cannot use. Node.js has `JSON` built in, so this package has no such dependency.                                                                                                                                                                                                                                                                                                                                                                                                             |
+| CLI                                                                           | Native         | The packaged executable loads an application runtime and exposes start, diagnostics, processes, dead letters, reminders, and explicit retention pruning as JSON.                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| Operator dashboard                                                            | Native         | Fetch and Node/Connect mounting, authorized views and actions, CSRF, filtering, paging, charts, and extensions match the Rack dashboard. Both dashboards expose individual retries and pause/resume; bulk redrive is available through the administration APIs. Pause does not interrupt an in-flight turn.                                                                                                                                                                                                                                                                                                                    |
+| Bulk redrive and administration audit                                         | Native         | Message, effect, and broadcast scopes support idempotent retry and durable, bounded, cancellable redrive. Retry and task transitions persist administration identity in audit rows.                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| Structured instrumentation                                                    | Native         | Versioned events, metric samples, isolated observers, and bounded authorized diagnostics match Ruby. Both test suites check SQL event attributes against `compatibility/telemetry-events.json`; only JS activation events add their turn's message fields. Both runtimes log exporter and observer failures, require observer callbacks, and cap local observers at 1,000. Timeout events share wait reasons, activation owner IDs, and string generations; see [observability](observability.md). Durable Objects uses host instrumentation and remote diagnostics, sends fewer attributes, and does not send `sync.timeout`. |
+| Large committed state warning                                                 | Native         | `warnStateBytes` reports one `solid_objects.state.large` event, holding the actor type, actor ID, byte count, and threshold, when a committed image passes a 128 KB soft threshold. The event holds no application state, and it reports after the commit. The Ruby gem carries the same event and the same 5 MB hard default from `0.14.3`, as `warn_state_bytes`. Its threshold defaults to 64 KB rather than 128 KB, because its measured curve falls sooner: it keeps 55% of its empty-state throughput at 13 KB, where this package keeps 98% at 16 KB.                                                                   |
+| Public test helper                                                            | Native         | `runtime.testing` provides role-selective deterministic draining, explicit-time due-reminder execution, and dependency-ordered reset without relying on cascades.                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| Clean-install artifact proof                                                  | Native         | `pnpm run test:package` installs the packed tarball in a new project. It runs the packaged quickstart, which sends 25 concurrent calls to one identity, and the `examples/ticket-sale.ts` guide example. `pnpm run test:recovery` proves recovery after a worker process stops. Ruby's `rake quickstart` builds the gem, installs it in a new Rails application, and proves ordering and reminder recovery after a runtime restart.                                                                                                                                                                                            |
 
 ## Databases and wake-up
 

package/docs/versioning.md

@@ -0,0 +1,50 @@
+# Versioning
+
+From version 1.0.0, Solid Objects follows
+[Semantic Versioning](https://semver.org/).
+
+## The promise
+
+The public API is the set of exports, commands, and configuration options that
+`README.md` and the files in `docs/` describe. [Public API](api.md) lists each
+export.
+
+| Release                  | What it can change                                            |
+| ------------------------ | ------------------------------------------------------------- |
+| Patch, for example 1.0.1 | Corrections of defects. No new behavior                       |
+| Minor, for example 1.1.0 | New behavior. Code that uses the public API continues to work |
+| Major, for example 2.0.0 | A change that breaks code that uses the public API            |
+
+## Supported versions
+
+A minor release can raise the minimum version of Node.js, TypeScript, SQLite,
+PostgreSQL, MySQL, or Redis. It does this only for a version that its own
+project no longer supports, and [CHANGELOG.md](../CHANGELOG.md) names the
+change. A patch release does not raise a minimum version.
+[Supported versions](support.md) lists the current minimum versions.
+
+## Outside the promise
+
+- The Cloudflare backend, `solid-objects/cloudflare`. It is experimental, and a
+  minor release can change it.
+- Exports that the documentation does not describe.
+- The database schema. A minor release can add tables, columns, and indexes.
+  `runtime.install()` applies each change.
+- The text of error messages and log lines. The error classes are part of the
+  public API.
+- The timing of background work, where no configuration option sets it.
+- A correction of behavior that is different from the
+  [correctness contract](correctness.md). A patch release can make such a
+  correction.
+
+## What version 1.0 does not claim
+
+Version 1.0 is a promise about the API. It is not a claim of measured scale.
+The [benchmarks](benchmarks.md) are development measurements and do not
+guarantee capacity. Longer soak tests are open work. The project has one
+maintainer, and no production use by other people is known.
+
+## Releases before 1.0
+
+The 0.x releases changed the API between minor versions.
+[CHANGELOG.md](../CHANGELOG.md) lists each change.

package/docs/virtual-actors.md

@@ -7,11 +7,13 @@ Node.js. The npm package is `solid-objects`. It gives each actor a stable
 identity, durable state, ordered operations, and automatic activation.
 
 The actor runtime runs in your Node.js processes. State and mailboxes live in
-SQLite, PostgreSQL, or MySQL. It needs no broker, no daemon, no Cloudflare
-account, and no new datastore. Redis is optional and only shortens wake-up
-latency.
+SQLite, PostgreSQL, or MySQL. It needs no separate actor service, no broker,
+no Cloudflare account, and no new datastore. A process of your application
+calls `runtime.run(signal)` to run reminders, effects, and queued messages.
+Redis is optional and only shortens wake-up latency.
 
-Solid Objects is a pre-1.0 release. Read
+Solid Objects 1.0 promises a stable public API. It makes no claim of measured
+scale. Read
 [Compatibility and maturity](#compatibility-and-maturity) before you choose it.
 
 ## What a virtual actor is
@@ -213,6 +215,10 @@ run again without harm.
   after a crash or a lost lease.
 - Ordered turns do not cancel stale JavaScript. Fencing stops a stale
   activation from a commit, but that code can continue to run.
+- An interrupted first attempt recovers immediately. Repeated interruptions
+  use growing, durable retry delays while keeping mailbox order. Lease loss
+  alone has no attempt limit; use instrumentation and an application stopping
+  policy when a hard bound is required.
 - External effects can run more than once. Use the stable effect ID, or
   another durable key, as the idempotency key at the provider.
 - There are no transactions across actor identities, and there is no replay of
@@ -240,7 +246,10 @@ These runtimes have different compatibility statements:
 | Browser runtime (`solid-objects/browser/host`)  | The actor runtime in a browser module worker on SQLite WASM. Tested in Chromium                                                                |
 | Cloudflare backend (`solid-objects/cloudflare`) | Experimental. It runs the actor API on Cloudflare Durable Objects, with different capability limits                                            |
 
-The package is pre-1.0. It has one deployed first-party reference
-application, no measured scale, and no known third-party production use.
+Version 1.0: the public API follows [semantic versioning](versioning.md). The
+Cloudflare backend is outside that promise. One first-party application with
+more than 100,000 users runs the package in production. That is a count of
+users, not a measure of load. The project makes no claim of measured scale,
+and no production use by other people is known.
 [Supported versions](support.md) lists the CI matrix. For Ruby on Rails, use
 the [solid_objects](https://github.com/cardmagic/solid-objects-ruby) gem.

package/examples/failure-recovery/demo.ts

@@ -72,7 +72,7 @@ async function proveSerialization(): Promise<SerializationProof & { finalState:
   ])
   const workers = [spawnWorker(), spawnWorker()]
   await Promise.all(workers.map(({ finished }) => finished))
-  await Promise.all(messages.map((message) => message.result()))
+  for (const message of messages) assert.equal(await message.status(), "completed")
   const events = await readJsonLines(
     join(controlDirectory, "serialization.jsonl"),
     parseSerializationEvent,
@@ -99,7 +99,7 @@ async function proveCrashRecovery(): Promise<{
   await wait(350)
   const recoveryWorker = spawnWorker()
   await recoveryWorker.finished
-  await message.result()
+  assert.equal(await message.status(), "completed")
   return recoveryResult({ reference, message, controlDirectory })
 }
 
@@ -118,7 +118,7 @@ async function proveFencing(): Promise<{
   await wait(350)
   const recoveryWorker = spawnWorker()
   await recoveryWorker.finished
-  await message.result()
+  assert.equal(await message.status(), "completed")
   staleWorker.child.kill("SIGCONT")
   await writeFile(join(controlDirectory, "release-first-attempt"), "")
   await staleWorker.waitFor((entry) => entry.event === "solid_objects.activation.lost")
@@ -138,9 +138,10 @@ async function recoveryResult(options: {
     join(options.controlDirectory, "external-effects.jsonl"),
     parseExternalEffectEvent,
   )
-  assert.equal(attempts, 2)
+  assert.ok(attempts >= 2)
   assert.equal(snapshot.count, 1)
-  assert.equal(effects.length, 2)
+  assert.ok(effects.length >= 2)
+  assert.ok(effects.length <= attempts)
   return { attempts, finalState: snapshot.count, repeatedEffects: effects.length }
 }
 

package/examples/failure-recovery/process-messages.ts

@@ -0,0 +1,10 @@
+export async function processMessages(worker: {
+  runUntilIdle(): Promise<number>
+}): Promise<number> {
+  let processed = 0
+  for (let attempt = 0; attempt < 200 && processed === 0; attempt += 1) {
+    processed = await worker.runUntilIdle()
+    if (processed === 0) await new Promise((resolve) => setTimeout(resolve, 10))
+  }
+  return processed
+}

package/examples/failure-recovery/worker.ts

@@ -1,6 +1,7 @@
 import { createRuntime } from "solid-objects"
 import { sqlite } from "solid-objects/database/sqlite"
 import { RecoverableReport, RecoveryCounter } from "./actor.ts"
+import { processMessages } from "./process-messages.ts"
 
 const databasePath = requiredArgument(2)
 const runtime = createRuntime({
@@ -36,11 +37,7 @@ if (process.argv[3] === "retire-effects") {
 const worker = runtime.worker()
 
 try {
-  let processed = 0
-  for (let attempt = 0; attempt < 200 && processed === 0; attempt += 1) {
-    processed = await worker.runOnce({ activationRetention: "release" })
-    if (processed === 0) await new Promise((resolve) => setTimeout(resolve, 10))
-  }
+  const processed = await processMessages(worker)
   process.send?.({ event: "worker.finished", processed })
 } finally {
   await worker.stop()

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "solid-objects",
-  "version": "0.17.7",
-  "description": "SQL-backed virtual actor library for TypeScript and Node.js, with durable state, ordered operations, and automatic activation on SQLite, PostgreSQL, or MySQL",
+  "version": "1.0.0",
+  "description": "Fix race conditions across Node.js processes: ordered operations, expiring holds, and state that survives a restart, in your SQL database. A SQL-backed virtual actor library for TypeScript and Node.js.",
   "type": "module",
   "license": "MIT",
   "author": "Lucas Carlson",
@@ -19,7 +19,10 @@
     "actors",
     "durable-objects",
     "virtual-actors",
-    "actor-model"
+    "actor-model",
+    "race-conditions",
+    "reservations",
+    "transactional-outbox"
   ],
   "repository": {
     "type": "git",
@@ -118,8 +121,8 @@
     "test": "vitest run",
     "test:browser": "pnpm run build && playwright test",
     "test:coverage": "vitest run --coverage",
-    "test:postgresql": "vitest run test/postgresql.test.ts test/activation-lease.test.ts test/effect-recovery.test.ts test/instance-retention.test.ts test/transmit-ordering.test.ts",
-    "test:mysql": "vitest run test/mysql.test.ts test/activation-lease.test.ts test/effect-recovery.test.ts test/instance-retention.test.ts test/transmit-ordering.test.ts",
+    "test:postgresql": "vitest run test/postgresql.test.ts test/activation-lease.test.ts test/activation-recovery-backoff.test.ts test/caller-lifecycle.test.ts test/effect-recovery.test.ts test/instance-retention.test.ts test/transmit-ordering.test.ts",
+    "test:mysql": "vitest run test/mysql.test.ts test/activation-lease.test.ts test/activation-recovery-backoff.test.ts test/caller-lifecycle.test.ts test/effect-recovery.test.ts test/instance-retention.test.ts test/transmit-ordering.test.ts",
     "test:package": "node scripts/release-artifact-smoke.mjs",
     "test:recovery": "pnpm run build && node examples/failure-recovery/demo.ts",
     "test:at-least-once": "pnpm run build && node examples/at-least-once/demo.ts",