solid_objects 0.16.1 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b060638b79ca2236a6530f8c478fe28ac0453fc514a0daeeb5f0f3a400f446ee
-  data.tar.gz: 31424c65ecc34caab85a2296b3e2f7055f731b07a5db16022fc48d1fcc860ed6
+  metadata.gz: 27c3d17cf47d0d22b069ed5fbddfb948495fd1c62ef807e43d0f271511a63ea8
+  data.tar.gz: 1161d2b5f269a22f9b509e73a0cacc8f46c0a0528bb7e54be9c2fdf81ad0055b
 SHA512:
-  metadata.gz: 6fee1b678cfb18e2a0b59c1e275a079631570b7a7b44cdd9edc2e0d880ec7efc688f9ee59bc9e3afb2742f355f793939f9a263f07f9e3a7bc466c07367dcbb23
-  data.tar.gz: 5d92fe6f884c53b757c5dde1ab372afe0200a3f509ddef737f75bd8810f42e224def36ce363abf57d1e41326fe2dc5ff0985b111deed3656db960a3889b26d9c
+  metadata.gz: f9ae16fca8e08fd41806a22a9a7f27904d0492870e52a9f1b4b9d9ca3bb6f95b85d965fd9b40e82ddc3154334564067ba36d090a8379e71c111c5dc043a0ce66
+  data.tar.gz: 93e89b4878dac64ed92ebc50361720bf0c43a713ef069be0f5f4988bad29045cc6ca8c1aeb857510fe7830b6e6df0a3f4a5a2cbc503dedea56a4177b15b7af36

data/CHANGELOG.md

@@ -1,5 +1,72 @@
 # Changelog
 
+## 0.17.0 - 2026-10-03
+
+- Publish RBS types for portable events, metric samples, actor diagnostics, and
+  event observers in `sig/public/telemetry.rbs`, and a `json_value` type for
+  message results and actor state. Observer blocks, diagnostics, and results now
+  type-check against these contracts instead of `untyped`.
+- **Breaking:** `solid_objects.activation.started` now fires before the actor's
+  `activate` hook. Before, it fired after a successful hook. The new
+  `solid_objects.activation.completed` event takes that meaning, and
+  `solid_objects.activation.failed` reports a failed hook. JavaScript changes
+  the same events. Move a subscriber that reads `activation.started` as a
+  finished activation to `activation.completed`.
+- **Breaking:** Active Support payloads no longer carry `error_message`. This
+  applies to `commit_action.failed`, `activation.deactivation_failed`,
+  `supervisor.monitor_failed`, `supervisor.retention_failed`,
+  `supervisor.redrive_failed`, and `wake_up.failed`. The
+  `solid_objects.worker.error` log entry also omits it. Each keeps
+  `error_class`. Exception text can contain actor state, so JavaScript already
+  reports only the error name.
+
+- **Breaking:** rename `solid_objects.payload_broadcast_failed` to
+  `solid_objects.payload_broadcast.failed`, the dotted form that every other
+  event uses. Update Active Support subscribers to the new name. The portable
+  event names the payload `payload`.
+- Match portable event attributes to JavaScript through the shared
+  `compatibility/telemetry-events.json` contract. Message events carry
+  `operation` and `deliveryMode`, `message.failed` carries `retryable` and
+  `outcome`, commit action events carry the message fields and `commitAction`,
+  and `reminder.enqueued` carries `operation`. `outbox.age` carries the effect or
+  broadcast identity, `sync.enqueue_timeout` carries `timeoutMilliseconds`, and
+  polling intervals are integers. `realtime.connected` carries only actor fields.
+- Log `solid_objects.instrumentation.failed` when an exporter or observer raises.
+  Observers require a block, a process accepts at most 1,000 observers, and
+  `SolidObjects.reset!` removes them. Pin reserved JSON keys through actor
+  arguments, state, and retained results.
+
+- Guard personalized payload projections against state changes, staged work,
+  and application database writes. Each payload gets an isolated actor from
+  the committed snapshot and honors `max_payload_bytes`, matching JavaScript.
+- Preserve timeout wait reasons, activation owner IDs, and activation generations
+  in portable telemetry using the shared camelCase fields and reason values.
+- Use a yielding SQLite busy handler for background transactions so concurrent
+  writers can finish on Rails 7.1 and 7.2. Preserve configured wait limits and
+  synchronous deadlines; cover contention with a coordinated lock regression.
+
+- **Breaking:** reject query and observable state mutation and staged durable
+  work with terminal `QueryMutatedState` errors. Cover individual snapshot
+  projections and preserve ordinary operations' already-staged work while
+  reading projections, including replacements that leave the intent count
+  unchanged.
+- Pin reserved JSON property names with shared Ruby/JS fixtures. Document the
+  reminder-name limit difference and the authorized dead-transmit retry API.
+
+- **Breaking:** reauthorize every message-reference status, result, and outcome
+  read against the original invocation. Pass `authorization_context:` on every
+  read.
+- **Breaking:** retain immutable JSON results for background and internal
+  messages as well as synchronous calls. All operations now enforce result
+  serialization and size limits; return `nil` explicitly when an operation does
+  not need a result. `result` raises terminal rejection/failure errors;
+  `outcome` exposes them as data.
+- Preserve polling transition intervals in milliseconds and string reasons in
+  portable telemetry. Pin transmit staging order and null-argument validation
+  against the shared JavaScript contract.
+
+- Add portable telemetry, isolated observer hooks, metric definitions, and bounded authorized actor diagnostics matching JavaScript.
+
 ## 0.16.1 - 2026-10-02
 
 - Fix the SQLite join order of the claimed-message scan. The query in

data/README.md

@@ -162,6 +162,7 @@ Exactly once is not hiding in a more advanced configuration. Read the
 - [Five-minute Rails guide](https://solidobjects.dev/5min/rails)
 - [Choosing Solid Objects](docs/fit.md)
 - [Operations and recovery](docs/operations.md)
+- [Observability and diagnostics](docs/observability.md)
 - [Reminders](docs/reminders.md)
 - [Reactive ERB](docs/realtime.md)
 - [Detailed architecture](docs/architecture.md)

data/app/models/solid_objects/message.rb

@@ -47,6 +47,21 @@ module SolidObjects
       dead_letter.present?
     end
 
+    # @rbs () -> json_value
+    def result!
+      if rejected?
+        raise Rejected.new(
+          code: rejection.fetch("code"),
+          message: rejection.fetch("message"),
+          details: rejection.fetch("details"),
+          message_id: id
+        )
+      end
+      raise MessageFailed.new("actor message failed permanently", message_id: id, details: error || {}) if dead?
+
+      Serialization.readonly_copy(result)
+    end
+
     private
 
     # @rbs () -> void

data/docs/architecture.md

@@ -167,10 +167,12 @@ creating a message or activation, applies required state migrations in memory,
 and returns deeply frozen declared attributes. It can race with an in-flight
 turn. `SolidObjects.mutable_copy` creates an independent mutable JSON value.
 
-`message` and `query` both execute as durable mailbox turns. A query may not
-mutate state. The executor detects query mutation and fails the message. An
-observable is a named projection of state used by server rendering and realtime
-updates. Its durable broadcast row stores only an empty invalidation marker by
+`message` and `query` both execute as durable mailbox turns. Queries and
+observables must not mutate state or stage effects, recovery checks, commit
+actions, reminders, or outbound messages. Violations raise `QueryMutatedState`
+and fail the message without retrying or committing its work. Individual snapshot
+projections enforce the same rule. An observable is a named projection used by
+server rendering and realtime updates. Its durable broadcast row stores only an empty invalidation marker by
 default. `broadcast: :value` explicitly opts into storing and sharing the
 projected value.
 
@@ -431,8 +433,16 @@ Each lookup runs the authorization hook the original call ran, against the
 stored operation and arguments, and answers `nil` for an absent row, an
 unregistered actor, and a refused caller alike, so it cannot be used to ask
 whether a request id exists. `MessageReference#outcome` reports the status, the
-result, the persisted error, the rejection, and the attempt count. A result is
-stored for `sync` delivery only.
+result, the persisted error, the rejection, and the attempt count. Every delivery
+mode stores its JSON result, including background messages. Result serialization
+and `max_result_bytes` apply before commit; a result that cannot be stored fails
+the turn. Return `nil` explicitly from operations that need no result.
+
+`status`, `result`, and `outcome` reauthorize the stored operation on every read.
+Pass `authorization_context:` each time; references retain identity rather than
+caller permissions. `result` raises `Rejected` or `MessageFailed` for terminal
+errors and returns a deeply frozen successful value. `outcome` reports terminal
+errors as data.
 
 An actor remembers the idempotency keys of its own finished turns. The executor
 already writes the instance row in the transaction that completes, rejects, or

data/docs/authorization.md

@@ -13,13 +13,20 @@ answers nothing until the host application defines its trust boundary.
 | `authorize_query` | Attribute reads, declared queries, committed snapshots, scalar observable reads, initial component rendering, and every component refresh dependency | Explicit call context, the context passed to `solid_object`, or the request context resolved for a component refresh | Actor state or personalized projections can leak across users or tenants |
 | `authorize_destroy` | `reference.destroy` | Value passed as `authorization_context:` | Complete actor state, mailbox, reminders, and pending outboxes can be deleted |
 | `authorize_subscription` | Action Cable subscription to one actor stream | The `ActionCable::Connection` object | Clients can receive future observable updates for other actors |
-| `authorize_administration` | Engine administration controllers, every `SolidObjects::Web` page, process inspection/cleanup/pruning, message pruning, and dead-letter inspection/retry | Rails controller, a `SolidObjects::Web` request that answers `request`/`session`/`env`, or `{ source: "cli" }` | Operational metadata, arguments, errors, deletion, and retries become exposed or mutable |
+| `authorize_administration` | Engine administration controllers, every `SolidObjects::Web` page, process inspection/cleanup/pruning, message pruning, dead-letter inspection/retry, and actor diagnostics and observers | Rails controller, a `SolidObjects::Web` request that answers `request`/`session`/`env`, or `{ source: "cli" }` | Operational metadata, arguments, errors, deletion, and retries become exposed or mutable |
 
-Waiting again through `MessageReference#wait` reauthorizes the stored
-invocation as a message or query. Internal reminder, effect-callback, and
+Every `MessageReference#status`, `#result`, `#outcome`, and `#wait` call
+reauthorizes the stored operation and arguments as a message or query. Supply
+`authorization_context:` on each call, including after `find_by`; the reference
+does not retain the original caller's context. Internal reminder, effect-callback, and
 actor-to-actor deliveries come from
 already committed runtime rows and do not re-enter the public client policy.
 
+Actor diagnostics and actor observers call `authorize_administration` with the
+resource `actor_diagnostics` and the resource ID `[actor_type, actor_id].to_json`.
+`diagnostics` uses the action `:inspect`. `observe` and `on` use the action
+`:observe`. The check runs before any queue read or observer registration.
+
 ## Realtime authorization contexts
 
 Reactive components cross three Rails execution contexts and authorize at all

data/docs/observability.md

@@ -0,0 +1,186 @@
+# Portable observability
+
+Configure `instrumentation(event)` to receive structured events. No exporter SDK
+is required. The same JSON envelope is emitted by Ruby, SQLite, PostgreSQL, MySQL,
+and the Durable Objects host. Existing JavaScript `name`, `occurredAt`, and
+`attributes` fields remain available. Ruby's Active Support notifications remain
+available with their existing snake_case payloads.
+
+```ruby
+SolidObjects.configure do |configuration|
+  configuration.instrumentation = ->(event) do
+    Rails.logger.info(JSON.generate(event))
+  end
+end
+```
+
+JavaScript passes `instrumentation` to `configure()`. Ruby sets
+`configuration.instrumentation` inside `SolidObjects.configure`.
+
+## Schema version 1
+
+Every event has `schemaVersion`, `name` (prefixed with `solid_objects.`),
+`occurredAt` (UTC ISO 8601), `adapter`, `actorType`, `actorId`, `incarnation`,
+`revision`, `messageId`, `attempt`, `attributes`, and `metrics`.
+Unavailable identifiers are null; `attempt` is zero outside a message attempt.
+Ruby publishes the RBS types `SolidObjects::portable_event`,
+`SolidObjects::actor_diagnostics`, and `SolidObjects::event_observer`. JavaScript
+exports `InstrumentationEvent`, `ActorDiagnostics`, and `EventObserver`.
+An incarnation identifies a persisted actor instance, independently of its lease
+generation. Revisions and IDs are strings. Process-wide events have null actor
+identity. A message ID or revision correlates actor work where applicable.
+
+Only known scalar metadata fields enter the portable envelope. Arguments, state,
+results, credentials, backtraces, exception text, nested provider data, and unknown
+attributes are excluded. Actor IDs remain correlation data: applications should
+use opaque actor identifiers and apply their own retention policy to event logs.
+Events and metric samples are immutable. Throwing observers, rejected observer
+promises, and a failing instrumentation error logger cannot change a turn's
+result. When an exporter or observer raises, both runtimes log
+`solid_objects.instrumentation.failed` with the event name and the error class.
+Delivery is best effort and synchronous callbacks should be short;
+JavaScript does not await exporters. Telemetry is not a durable audit trail.
+
+| Event                                       | Meaning                                                                      |
+| ------------------------------------------- | ---------------------------------------------------------------------------- |
+| `activation.started/completed/failed`       | Local actor activation hook lifecycle                                        |
+| `message.started/completed/failed/rejected` | One attempt's execution outcome                                              |
+| `message.retry`                             | Failed attempt durably queued for another attempt                            |
+| `dead_letter.created`                       | Message exhausted retries or failed permanently                              |
+| `commit_action.started/completed/failed`    | One registered commit action inside the commit transaction                   |
+| `mailbox.depth`                             | On-demand diagnostic sample; `depth` is null when the sample is truncated    |
+| `reminder.enqueued`                         | Due reminder dispatch; lateness is measured from due time                    |
+| `outbox.age`                                | Delivery observation; age is time since the item's current availability time |
+| `recovery.reclaimed`                        | A previously claimed, interrupted message begins another attempt             |
+| `recovery.completed/failed`                 | Durable effect recovery callback commits or enters the dead-letter queue     |
+| `snapshot.read`                             | Authorized snapshot constructed without exposing its contents                |
+| `realtime.connected/disconnected`           | Actor subscription added or removed                                          |
+| `payload_broadcast.failed`                  | One personalized payload failed; `payload` names it                          |
+
+Events describe local observations. Concurrent deletion, crashes, and failed
+exporters can omit events. Never infer exactly-once delivery from event counts.
+Additional existing runtime events retain their names.
+
+## Event attributes
+
+`compatibility/telemetry-events.json` holds the attribute allowlist and the exact
+attribute keys of each core event. Both test suites compare the events of the SQL
+runtimes with this file. Message events carry `operation` and `deliveryMode`.
+`message.failed` also carries a boolean `retryable` and an `outcome` of
+`retrying` or `dead`. Commit action events carry `commitAction` and
+`activationGeneration`. Activation events carry `generation` and `ownerId`.
+
+Ruby activates an actor instance before it claims a message, so its activation
+events have no message fields. JavaScript activates an actor in the turn that
+claims a message, so its activation events also carry the `messageId`,
+`requestId`, `sequence`, `attempt`, `operation`, and `deliveryMode` of that
+message. The contract file records these keys as JavaScript-only.
+
+The Durable Objects host sends the same envelope, but some of its events carry
+fewer attributes. The contract file does not apply to that host.
+
+Portable `polling.interval_changed` events carry `previousIntervalMilliseconds`,
+`currentIntervalMilliseconds`, and a string `reason`. Ruby converts its native
+second-based notification values while preserving the original notification.
+
+## Synchronous timeout diagnostics
+
+`solid_objects.sync.timeout` includes `waitingOn`, `activationOwnerId`, and
+`activationGeneration` in `attributes`. Generations are decimal strings;
+unavailable activation fields are null. Both runtimes use the same wait reasons:
+`actorPaused`, `activationHeld`, `earlierMessage`, `messageClaimed`,
+`notYetAvailable`, `readyUnclaimed`, `databaseContention`, and `unknown`.
+Ruby's exception attributes and Active Support notifications retain their native
+snake_case names and reason values. The portable instrumentation envelope uses
+the shared camelCase contract. The Durable Objects host does not send
+`sync.timeout`. A `call` timeout there reports `waitingOn: "unknown"`.
+
+## Metrics and tracing
+
+Metrics are sample descriptions. Exporting them is opt-in: the runtime does not
+register meters, allocate per-actor metric series, or install a vendor SDK.
+
+| Name                              | Kind      | Unit | Aggregation                                            |
+| --------------------------------- | --------- | ---- | ------------------------------------------------------ |
+| `solid_objects.events`            | counter   | `1`  | Sum one per event                                      |
+| `solid_objects.duration`          | histogram | `ms` | Distribution of observed attempt duration              |
+| `solid_objects.reminder.lateness` | histogram | `ms` | Distribution of reminder dispatch delay                |
+| `solid_objects.outbox.age`        | histogram | `ms` | Distribution of delivery delay since availability      |
+| `solid_objects.mailbox.depth`     | gauge     | `1`  | Last exact sampled actor depth; omit truncated samples |
+
+Labels contain only event name, adapter family, and declared actor type. Keep the
+actor type registry finite. Never add actor ID, incarnation, message ID, operation
+arguments, request IDs, or error text to metric labels. A gauge without an actor
+label represents the most recently observed actor; it is not total fleet backlog.
+For tracing, correlate start/outcome events using `adapter`, `incarnation`,
+`messageId`, and `attempt`, and close or expire spans when no outcome arrives.
+
+## Actor observers and diagnostics
+
+```ruby
+cart = ShoppingCart.ref("demo-cart")
+stop = cart.observe(authorization_context: operator) do |event|
+  logger.info(event.to_json)
+end
+summary = cart.diagnostics(authorization_context: operator, limit: 50)
+stop.call
+```
+
+Ruby uses `reference.observe(authorization_context:) { |event| ... }` and
+`reference.diagnostics(authorization_context:, limit: 50)`. Stop observing by
+calling the returned proc. `on` filters one event name, such as `message.retry`.
+Observers receive only this actor's events in the current runtime/process; they
+are not subscriptions to workers on other hosts. Dispose them when the caller's
+session ends or authorization is revoked. Each runtime or process accepts at most
+1,000 local observers. More observers raise `RangeError` in JavaScript and
+`ArgumentError` in Ruby. An observer needs a callback or a block. JavaScript
+rejects a missing `onEvent` with `TypeError`, and Ruby raises `ArgumentError`
+without a block. Both checks run before authorization.
+
+The JavaScript Durable Objects host does not support process-local reference
+observers. On that host, `observe` and `on` raise `UnsupportedCapability`, and
+remote `reference.diagnostics` works. To observe a remote actor, configure
+`instrumentation` on the actor host and filter the events by actor identity.
+Ruby has no Durable Objects host.
+
+Both APIs default to denied. Set `authorizeAdministration` / `authorize_administration`
+to allow action `observe` or `inspect`, resource `actor_diagnostics`, and resource ID
+`JSON.stringify([actorType, actorId])`. Ruby receives a symbol action. Authorization
+runs before reading summaries or registering observers; possessing an actor ID
+confers no permission.
+
+Diagnostics read at most `limit + 1` rows per queue source, with a hard limit
+of 100 rows. Each category returns `sampled`, `truncated`, and
+`oldestAgeMilliseconds`.
+The limit applies to each combined category: one effect plus one broadcast with
+`limit: 1` returns `sampled: 1, truncated: true`, even when both source queries
+returned all their rows. The extra row proves that the category exceeds its cap.
+The last value measures nonnegative time since availability (or terminal failure
+for recovery callbacks); future reminders have zero age. No payloads or row
+identifiers are returned. Samples are observations across several queries,
+not an atomic fleet snapshot. Large queues can still require database scanning;
+the bound limits materialized rows and response size, not query execution time.
+
+Categories are mailbox (ready and claimed), outbox (pending and processing effects
+and broadcasts), reminders (scheduled and paused), retries (failed messages still
+eligible to run), and recoveryFailures (dead internal effect recovery
+callback messages). Durable Objects does not implement process-heartbeat effect recovery;
+its recoveryFailures category is empty. Recovery failures are durable records,
+not a history of transient database or exporter exceptions.
+
+## A query that works across adapters
+
+Write one envelope per line to `events.jsonl`, using the same instrumentation hook
+with SQLite and PostgreSQL. This query reports completed attempts by adapter:
+
+```sh
+jq -s 'map(select(.name == "solid_objects.message.completed"))
+  | group_by(.adapter)
+  | map({adapter: .[0].adapter, completed: length,
+         mean_ms: (map(.attributes.durationMilliseconds) | add / length)})' events.jsonl
+```
+
+A dashboard can chart the event counter by adapter and outcome and the duration,
+reminder lateness, and outbox age distributions using exactly the same fields.
+Compare workloads with the same actor types and sampling policy. Counts measure
+observations and cannot replace a database query for authoritative queue state.

data/docs/realtime.md

@@ -347,8 +347,9 @@ object or array so the wire format stays inspectable.
 A payload is one subscriber's view of one name, so a failure is confined to it.
 A raising block does not reject the subscription, stop the other payload names,
 or stop component refreshes on the same connection. The failure is reported as
-`solid_objects.payload_broadcast_failed` carrying the actor type, actor id,
-payload name, and exception class. The exception message is deliberately not
+`solid_objects.payload_broadcast.failed` carrying the actor type, actor id,
+payload name, and exception class. The Active Support payload names the payload
+`payload_name`; the portable instrumentation event names it `payload`. The exception message is deliberately not
 included: a payload block reads subscriber state, so its message is the one
 place that state could leak into logs.
 
@@ -356,7 +357,7 @@ A revision with a failed payload does not advance the delivery watermark, so a
 transient failure is retried on the next broadcast rather than being recorded as
 delivered. Retries are driven by broadcasts rather than a timer, so a payload
 that fails persistently retries once per actor mutation and reports each
-attempt. A repeating stream of `payload_broadcast_failed` for one `payload_name`
+attempt. A repeating stream of `payload_broadcast.failed` for one `payload_name`
 therefore means a persistent fault in that block, not a one-off; a single event
 that does not recur was transient and has already been recovered.
 

data/docs/reminders.md

@@ -65,7 +65,9 @@ key only decides which alarm is which.
 
 A key must be non-empty, and the name it becomes must fit the 191-character
 column, which is checked on the composed name rather than the key alone so a
-long operation and a short key are caught too.
+long operation and a short key are caught too. JavaScript allows 255 UTF-16 code
+units for the same combined name. These existing schema limits remain different;
+use at most 191 ASCII characters for names shared across runtimes.
 
 The key is separated from the operation by a colon, so an operation may not hold
 one. Otherwise an unkeyed `deliver:item` and a `deliver` keyed `item` would be

data/docs/roadmap.md

@@ -2,8 +2,19 @@
 
 ## Implemented and tested
 
+- Portable telemetry with a shared JSON schema, metric samples, isolated observer
+  callbacks, bounded authorized actor diagnostics, and matching timeout wait
+  reasons and activation metadata. Both test suites check the attribute keys of
+  each core SQL event against `compatibility/telemetry-events.json`. See
+  [observability](observability.md).
+
 - Rails engine, install generator, migration, and CLI
 - Explicit actor registry, references, JSON state, and state migrations
+- Queries, observable projections, and personalized payloads reject state mutation
+  and staged durable work with `QueryMutatedState`, matching JavaScript. Query
+  and observable violations fail terminally; a payload violation is confined to
+  that payload. Shared JSON fixtures preserve reserved property names as ordinary
+  data in both runtimes.
 - Fluent direct synchronous RPC, configured `sync`, and durable `async`
 - Durable message history plus ready/claimed membership tables
 - Concurrent sequence allocation and actor creation. An enqueue finds the
@@ -55,7 +66,9 @@
   subscriber's authorization context, fenced by actor revision, resolved through
   `payload_authorization_context` so the block and `authorize_query` see the
   same subject a controller render passes, and confined so one failing payload
-  cannot reject the subscription or stop its siblings
+  cannot reject the subscription or stop its siblings. Each payload uses an
+  isolated actor from the same committed snapshot, prevents application database
+  writes, and enforces the configured `max_payload_bytes` limit
 - Reconciliation read APIs
 - Installation doctor, authorization reference, fit guide, and legacy-state
   migration cookbook. The doctor names every column that a migration after the
@@ -119,6 +132,9 @@
   batched and unbatched components, an inert replay of an applied revision,
   cancellation of the request left in flight by the drop, incarnation ordering
   after a destroy and recreate, and payload delivery exactly once per revision
+- Authorized message-reference reads recheck the original operation and arguments,
+  return immutable JSON results for every delivery mode, and raise terminal errors
+  from `result` while `outcome` exposes them as data.
 - Result lookup by request ID and by idempotency key, authorized with the hook
   the original call ran and against the stored operation and arguments. An
   actor remembers the idempotency keys of its own last `retained_idempotency_keys`

data/docs/security.md

@@ -16,8 +16,8 @@ delegate to the authorized synchronous invocation path. Keep implementation
 helpers private or protected. Query, attribute, observable, and committed
 `snapshot` reads use the separate query authorization policy. Explicit `async`
 message delivery uses the same message authorization policy as direct calls.
-Recovering a timed-out result through `MessageReference#wait` reauthorizes the
-stored operation.
+Message reference status, result, outcome, and wait reads reauthorize the stored
+operation and arguments with the context supplied to that read.
 `reference.destroy` delegates to `authorize_destroy` before checking whether
 the actor exists, so denial does not reveal actor existence.
 

data/docs/transmission.md

@@ -18,6 +18,9 @@ actor does the same with `transmit.increment(amount:)`. Either ingest
 accepts either sender, so Rails-to-Rails, Rails-to-Node, Node-to-Rails,
 and browser-to-Rails replication all ride one contract.
 
+An omitted `arguments` field defaults to `{}`. Explicit `null` and arrays are
+rejected by both runtimes. Shared fixtures cover this distinction.
+
 ## The sending side
 
 ```ruby
@@ -57,7 +60,7 @@ retries with backoff and dead-letters on exhaustion, like any other effect.
 
 The drain keeps per-actor order across failures: a claimed transmit effect
 delivers every undelivered sibling for its actor up to its own mailbox
-sequence, oldest first. The receiving side dedups on `transmit:<effectId>`,
+sequence, oldest first, preserving staging order within each turn. The receiving side dedups on `transmit:<effectId>`,
 so a redelivered envelope applies once.
 
 Delivery is at-least-once by design, and the drain accepts redundant sends
@@ -84,11 +87,19 @@ SolidObjects.configure do |configuration|
 end
 ```
 
-These settings apply to every effect, not only transmits. A dead transmit
-effect has no retry API; the dashboard lists it, and recovery means
-returning its row to `pending` with a cleared `attempt_count`. Order
-survives that recovery, because the drain orders by mailbox sequence, not
-by retry time.
+These settings apply to every effect, including transmits. Retry a dead transmit
+through the authorized administration API:
+
+```ruby
+SolidObjects.dead_letters.effects.retry(effect_id, authorization_context: operator)
+```
+
+Retry resets attempts and returns the effect to pending with its stable identity,
+so the receiver still deduplicates replays. The administration policy must allow
+`retry` on `effect_dead_letters`; the action is recorded in the audit log. Use
+`SolidObjects.dead_letters.effects.redrive(authorization_context: operator)` to
+recover a scope in bounded batches. Order survives recovery because the drain
+orders by source sequence and staging order.
 
 ## Wire contract
 

data/lib/solid_objects/activation.rb

@@ -24,15 +24,19 @@ module SolidObjects
       @actor = build_actor(instance)
       @last_used_at = monotonic_now
       @pass_exhausted = false
+      SolidObjects.instrument(:"activation.started", instance_id: instance.id, actor_type: instance.actor_type, actor_id: instance.actor_id, owner_id: lease.owner_id, generation: lease.generation)
       actor.activate
       SolidObjects.instrument(
-        :"activation.started",
+        :"activation.completed",
         instance_id: instance.id,
         actor_type: instance.actor_type,
         actor_id: instance.actor_id,
         owner_id: lease.owner_id,
         generation: lease.generation
       )
+    rescue => error
+      SolidObjects.instrument(:"activation.failed", instance_id: lease.instance_id, actor_type: instance&.actor_type, actor_id: instance&.actor_id, owner_id: lease.owner_id, generation: lease.generation, error_class: error.class.name)
+      raise
     end
 
     # @rbs () -> Integer
@@ -104,8 +108,7 @@ module SolidObjects
         actor_id: actor.actor_id,
         owner_id: lease.owner_id,
         generation: lease.generation,
-        error_class: error.class.name,
-        error_message: error.message
+        error_class: error.class.name
       )
       SolidObjects.configuration.logger.error(
         "SolidObjects activation deactivation failed " \

data/lib/solid_objects/actor.rb

@@ -459,7 +459,9 @@ module SolidObjects
 
     # @rbs () -> Hash[String, untyped]
     def observable_values
-      guard_application_writes("observables") do
+      return {} if self.class.definition.observables.empty?
+
+      read_projection("observables") do
         self.class.definition.observables.each_with_object({}) do |(name, handler), values|
           values[name.to_s] = Serialization.dump(instance_exec(&handler.block))
         end
@@ -472,7 +474,7 @@ module SolidObjects
       handler = self.class.definition.observables[observable_name]
       raise UnknownMessage, "unknown observable #{name.inspect}" unless handler
 
-      guard_application_writes("observable.#{observable_name}") do
+      read_projection("observable.#{observable_name}") do
         Serialization.dump(instance_exec(&handler.block))
       end
     end
@@ -537,6 +539,24 @@ module SolidObjects
       outbound_message_intents.clear
     end
 
+    # @rbs () -> Integer
+    def intent_count
+      effect_intents.length + effect_recovery_intents.length + commit_action_intents.length +
+        reminder_intents.length + outbound_message_intents.length
+    end
+
+    # @rbs [Result] (String) { () -> Result } -> Result
+    def read_projection(operation)
+      state_before = state.to_h
+      intents_before = intent_snapshot
+      result = guard_application_writes(operation) { yield }
+      unless state.to_h == state_before && intent_snapshot == intents_before
+        raise QueryMutatedState, "projections must not mutate actor state or stage durable work"
+      end
+
+      result
+    end
+
     private
 
     attr_reader :effect_intents,
@@ -545,6 +565,13 @@ module SolidObjects
       :reminder_intents,
       :outbound_message_intents
 
+    # @rbs () -> Array[Array[Hash[Symbol, Object]]]
+    def intent_snapshot
+      [ effect_intents, effect_recovery_intents, commit_action_intents, reminder_intents, outbound_message_intents ].map do |intents|
+        intents.map { |intent| intent.to_h.deep_dup }
+      end
+    end
+
     # @rbs (String) { () -> untyped } -> untyped
     def guard_application_writes(operation, &block)
       ApplicationWriteGuard.call(

data/lib/solid_objects/actor_channel.rb

@@ -49,6 +49,7 @@ module SolidObjects
       end
       refresh_outdated_components(snapshot)
       transmit_state_payloads(snapshot)
+      SolidObjects.instrument(:"realtime.connected", actor_type: reference.actor_type, actor_id: reference.actor_id)
     rescue KeyError,
       JSON::ParserError,
       InvalidStreamToken,
@@ -57,6 +58,13 @@ module SolidObjects
       reject_and_report(reject_reason(error), actor_type:, actor_id:, error:)
     end
 
+    # @rbs () -> void
+    def unsubscribed
+      return unless reference
+
+      SolidObjects.instrument(:"realtime.disconnected", actor_type: reference.actor_type, actor_id: reference.actor_id)
+    end
+
     private
 
     attr_reader :reference,
@@ -141,7 +149,7 @@ module SolidObjects
       true
     rescue => error
       SolidObjects.instrument(
-        :payload_broadcast_failed,
+        :"payload_broadcast.failed",
         actor_type: reference.actor_type,
         actor_id: reference.actor_id,
         payload_name: name,