solid-objects 0.15.2 → 0.16.1

package/docs/parity.md

@@ -51,26 +51,26 @@ 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.                                                                                                                                                                                          |
-| 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, 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`; reminder names are bounded to 255 characters. Distributed per-actor rate limits and global admission control do not exist yet, matching the open Ruby roadmap item. |
-| 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, 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.                                                                                                                                                                                                               |
+| 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, 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`; reminder names are bounded to 255 characters. 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, 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 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.
@@ -106,11 +106,86 @@ Ruby field names; this does not change runtime delivery semantics.
 | 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.                                                                                                                                                                                                                      |
 
-Every wake-up adapter above is opt-in. Neither runtime selects one
-automatically. An application that configures nothing keeps polling. Each
-runtime warns once when live processes share a database without a configured
-cross-process adapter. This limit is intentional in both runtimes. It is not a
-gap between them.
+Both runtimes select a wake-up adapter automatically. `wakeUp` takes a name or
+an adapter and defaults to `"automatic"`, which prefers a configured Redis URL,
+then PostgreSQL notifications, then polling. Selection proves the PostgreSQL
+path with a probe notification, because `LISTEN` does not survive a transaction
+pooler. Each runtime reports what it installed, whether that crosses processes,
+its measured floor, and why, and warns once when live processes share a
+database and the installed adapter cannot reach them. MySQL still polls in both
+runtimes, because MySQL has no notification channel.
+
+A requested adapter that the environment cannot provide polls instead and says
+so in both runtimes, rather than claim a cross-process wake-up that cannot
+happen. Only a name that does not exist is refused.
+
+Three details differ, and each follows from the language rather than from the
+feature. The pooled-session warning is emitted once per runtime here and once
+per process in Ruby, because this runtime supports several runtimes in one
+process. A configured adapter must implement `watch`, `notify`, and `close`
+here, while Ruby requires `signal` and `wait` and treats `watch` and `stop` as
+optional, which is each runtime's own adapter contract. A selection that a later
+edit of the settings makes impossible is reported once here and raised in Ruby;
+both runtimes refuse an unknown name when the configuration is built, so this
+only reaches code that changes the setting afterwards.
+
+## Dead letters, retry, and redrive
+
+Both runtimes scope dead letters by kind through one receiver, retry a dead
+message, effect, or broadcast, redrive a whole scope as a durable and idempotent
+task, bound that task to the rows that were dead when it started, advance it in
+bounded batches, and write one administration event per retry and per task
+transition, in the transaction that causes it. The filters, the resource names,
+the audit actions, and the configuration defaults match.
+
+Two details differ. This runtime filters on a `failed_at_ms` stamp that schema
+version 11 adds, while Ruby filters on the `updated_at` column Active Record
+already maintains. The Durable Objects engine keeps its own message and outbox
+tables inside each object, so these scopes cover the SQL backends here; its
+`deadLetters` call is unchanged.
+
+## Result lookup
+
+Both runtimes rebuild a `MessageReference` from a request id or an idempotency
+key, scope each lookup through the receiver that matches its index, authorize it
+with the hook the original call ran, and report absence, an unregistered actor,
+and a refusal the same way. `outcome` reports the status, result, error,
+rejection, and attempt count in both.
+
+Three details differ, and all come from the runtimes rather than the feature.
+This runtime stores a result for every completed message, so a lookup answers
+one for asynchronous work; Ruby stores a result only for `sync` delivery, so a
+lookup there answers the status and the error but not the result. This runtime
+needed a new unique index on `request_id`, added as schema version 12, because
+its table constrained the pair `(actor_type, actor_id, request_id)`; the Ruby
+schema has carried a global unique index since its first migration. The error
+record also differs: Ruby's `ErrorRecord` carries `class_name`, `message`, and
+`backtrace`, while this runtime persists only `name` and `message`, because
+`safeError` has never stored a stack. An `outcome` here reports what failed, not
+where.
+
+Both runtimes tell a pruned message from one that never existed the same way.
+An actor remembers the idempotency keys of its own last
+`retained_idempotency_keys` / `retainedIdempotencyKeys` finished turns, written
+in the instance row the executor updates anyway, so a key lookup raises
+`MessagePruned` for a message retention removed and answers absent for a
+message that never existed. Each remembered key carries its operation and original arguments, so the
+pruned answer runs the same authorization a lookup of the surviving row
+would. Both also bound the serialized memory, because an
+idempotency key has no length limit and the memory outlives the message row; an
+actor drops its oldest keys until the list fits. The original operation selects the message or query authorization hook in both. A request id lookup answers absent in both cases,
+because the runtime generates a request id and no actor remembers one.
+
+Remembered arguments count toward the serialized memory limit and remain until
+the entry is evicted or the instance is removed. Entries from older versions
+that lack arguments return absence after pruning because their original
+authorization cannot be reproduced.
+
+The Durable Objects backend answers a key lookup and a request id lookup
+through the actor that holds the row, and it remembers keys in the same
+instance record. It cannot answer `findBy({ requestId })` without a reference,
+because a Durable Object indexes only its own messages, so that form raises
+`UnsupportedCapability`.
 
 ## Realtime and browser behavior
 
@@ -235,3 +310,8 @@ checks. Per-effect recovery timeouts extend the runtime heartbeat threshold
 (milliseconds in JS, seconds in Ruby). Cloudflare returns emit handles but rejects
 process-heartbeat recovery options and intents before commit. See
 [the transaction protocol](effect-recovery.md).
+
+On SQLite, both runtimes mark the `status = 'processing'` test in the recovery
+candidate query with `likelihood()`. The candidate scan then starts from the
+effects poll index, also when `sqlite_stat1` shows that most effects have one
+status.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solid-objects",
-  "version": "0.15.2",
+  "version": "0.16.1",
   "description": "Race-free realtime state per application identity, backed by your SQL database",
   "type": "module",
   "license": "MIT",