solid_objects 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4d95ae7c1b6791ce00951e73eaf535a7b0b357c6708112509544de82eb59314d
-  data.tar.gz: a6a9ef715c217e38959438d1ab549447e0814c621746967dece190ae46b3108b
+  metadata.gz: 48689af6e9b4f08415ddfd549a99d4e7e667e67db5aa4e92bc0052a6d97f51af
+  data.tar.gz: 82dc95dc346daf7260356996bfadc99c9c8dd713f2c0fa8c5d8f5efe7859021a
 SHA512:
-  metadata.gz: d604e195d678ae5f2ae24932fd0431a7076d0f8258b9e064bbc463042b911512edc7a6b613673b6731256d0b0603311708beb2158d79e421dc85b5febfb37f4d
-  data.tar.gz: cd817466462c8d0c843fa9766df1f2190ed3b477466661e32a47859f7fc63349327af7cb077d75ab5a43b621bb3ee98e321363b007ff5ad19e311123d871e040
+  metadata.gz: d3a4ce2860cca8656919193b2a9bb6b2c2367552653af106db5fd065bd2bf3c7339a543c5b1bc1fdf1bb7d322e88639a6f20cdba2b5cf551b406e629e6d31598
+  data.tar.gz: '086652b090e80b0c6830b269e8857ef6de1944b2c2ab145340eeb4a8ba97a26875b9a612c5105ae46bff7362477fe20c3abde837aa4b87d27f5fb91bf19e316e'

data/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 0.3.0 - 2026-08-06
+
+- Reject application-record writes from actor handlers and provide registered
+  same-database commit actions for fenced atomic changes.
+- Reject synchronous invocation inside an open Solid Objects transaction and
+  add adapter database deadlines, durable diagnostics, and recoverable results
+  to sync timeouts.
+- Guard handlers, observables, lifecycle hooks, and state migrations from
+  direct application-record writes.
+- Add dry-run-first bounded message, process, and opt-in actor-instance
+  pruning, configurable retention, and graceful caller-process shutdown.
+- Add authorized committed state snapshots, mutable JSON copies, commit-action
+  instrumentation, and deterministic full-runtime Minitest draining.
+
+## 0.2.1 - 2026-08-06
+
+- Add `solid_objects:doctor` for configuration, schema, policy, runtime, and
+  workerless synchronous round-trip verification.
+- Add onboarding guidance for fit decisions, worker requirements,
+  authorization, performance and row growth, retention, Sorbet, RuboCop, and
+  migrations from existing state stores.
+- Make the early-Action View engine boot regression explicit.
+
 ## 0.2.0 - 2026-08-06
 
 - Make direct actor methods synchronous Durable Object-style RPC.

data/README.md

@@ -20,8 +20,14 @@ class Counter < SolidObjects::Actor
   end
 end
 
-# from anywhere in your app — addressed by name:
-Counter.ref("global").increment(amount: 5)
+# Synchronous caller-assisted RPC. No worker fleet is required.
+counter = Counter.ref("global")
+count = counter.increment(amount: 5)
+current_count = counter.value
+current_snapshot = counter.snapshot.value
+
+# Durable fire-and-forget delivery. A worker processes it later.
+message = counter.async(:increment, amount: 5)
 ```
 
 `Counter / global` is a logical identity. Like a Durable Object named with
@@ -30,12 +36,37 @@ locating a Ruby object. Solid Objects activates it when work arrives, commits
 its ordered turns one at a time, persists its state, and deactivates it when
 idle. Different identities can run concurrently.
 
+The invocation model is the first adoption decision:
+
+| Call | Returns | Worker fleet required? |
+| --- | --- | --- |
+| `counter.increment(amount: 5)` | Committed handler result | No |
+| `counter.sync(:increment, amount: 5)` | Committed handler result | No |
+| `counter.value` | Ordered, committed query result | No |
+| `counter.snapshot.value` | Current committed state without a mailbox message | No |
+| `counter.async(:increment, amount: 5)` | `MessageReference` immediately | Yes |
+
+Direct methods and `sync` durably enqueue the call, then the Rails caller helps
+execute the actor through the same mailbox, lease, and fencing path as a
+worker. `async` only enqueues; a runtime process handles it later.
+
+Synchronous calls fail before enqueue when the Solid Objects database
+connection is already inside a transaction. Actor handlers may read application
+records, but direct Active Record writes are rejected so they cannot escape a
+later actor failure. Use a same-database
+[`commit_action`](#application-database-writes) for atomic database changes and
+[`emit`](#effects) for external I/O.
+
+Before adopting a latency-sensitive or high-volume surface, read
+[Is Solid Objects a good fit?](docs/fit.md) and the
+[measured performance and row-growth costs](docs/benchmarks.md).
+
 This is a port of the programming model, not Cloudflare's edge runtime or
 platform. Read the conceptual overview at [solidobjects.dev](https://solidobjects.dev/)
 and the exact Rails guarantees in [Correctness and delivery semantics](docs/correctness.md).
 
-Version 0.2 is an early release. Its correctness core is implemented and tested,
-but the project does not yet claim production readiness. See
+Solid Objects is an early release. Its correctness core is implemented and
+tested, but the project does not yet claim production readiness. See
 [Status](#status) and the [roadmap](docs/roadmap.md).
 
 ## Table of contents
@@ -43,9 +74,11 @@ but the project does not yet claim production readiness. See
 - [Cloudflare Durable Objects for Rails](#cloudflare-durable-objects-for-rails)
 - [Reactive ERB](#reactive-erb)
 - [Installation](#installation)
+- [Worker requirements](#worker-requirements)
 - [Defining an actor](#defining-an-actor)
 - [Actor identity](#actor-identity)
 - [Invoking an object](#invoking-an-object)
+- [Application database writes](#application-database-writes)
 - [Effects](#effects)
 - [Reminders](#reminders)
 - [Destroying an object](#destroying-an-object)
@@ -171,7 +204,7 @@ refresh from current actor state.
 `cart.component(:summary)` supports initial rendering of
 `actors/shopping_cart/_summary`. Durable live component replacement and
 Turbo append actions are roadmap work; observable replacement is the live path
-implemented in 0.2.
+implemented today.
 
 Reactive views require `turbo-rails` and a working Action Cable adapter in the
 host application. They are optional; the actor runtime itself does not depend
@@ -187,10 +220,17 @@ Add the gem, install its initializer and migration, then migrate:
 bundle add solid_objects
 bin/rails generate solid_objects:install
 bin/rails db:migrate
+bin/rails solid_objects:doctor
 ```
 
-The generated initializer denies all externally initiated operations. Replace
-the policy blocks with application-specific authorization before sending
+The doctor validates configuration and required schema shape, reports
+authorization posture and live runtime roles, and completes a real synchronous
+actor round-trip without a worker. It checks required tables and columns instead
+of a copied migration timestamp, which the host application rewrites. It exits
+unsuccessfully when configuration, schema, or the round-trip is broken.
+
+The generated initializer is intentionally inert: all five policies deny by
+default. Replace them with application-specific authorization before sending
 messages, querying state, destroying actors, subscribing to streams, or
 mounting administration routes:
 
@@ -205,16 +245,63 @@ end
 ```
 
 Knowledge of an actor ID or signed stream token is never authorization.
+Read the [policy reference and tenant-aware example](docs/authorization.md)
+before opening a policy. Unconditionally allowing message and query calls is
+reasonable only for a controlled server-side pilot. Keep destroy,
+subscription, and administration denied until each has an authenticated
+caller.
+
+The engine uses the application's primary Active Record connection by default.
+See [Database support](#database-support) for a separate database configuration.
+
+### Host application tooling
+
+Installed engine migrations are copied as
+`db/migrate/*_create_solid_objects_tables.solid_objects.rb`. If the host enables
+`Rails/CreateTableWithTimestamps`, exclude engine-owned migrations rather than
+editing their intentionally specialized hot tables:
+
+```yaml
+Rails/CreateTableWithTimestamps:
+  Exclude:
+    - "db/migrate/*.solid_objects.rb"
+```
 
-Start the runtime for asynchronous messages, effects, reminders, and
-broadcasts:
+Solid Objects ships inline RBS signatures, not RBI files. Sorbet applications
+can generate the gem RBI with:
+
+```bash
+bundle exec tapioca gem solid_objects
+```
+
+## Worker requirements
+
+Synchronous actors can be adopted without adding a long-running process. Start
+the runtime when the feature introduces asynchronous delivery or outboxes:
+
+| Feature | Runtime roles required |
+| --- | --- |
+| Direct actor method or explicit `sync` | None; the caller executes it |
+| Attribute or declared query read | None; the caller executes it |
+| Committed `snapshot` read | None; reads the instance row directly |
+| `destroy` | None |
+| `async` including delayed delivery | Actor worker |
+| One-shot or recurring `schedule` | Reminder scheduler and actor worker |
+| `emit` without an actor callback | Effect worker |
+| `emit` with success or failure callback | Effect worker and actor worker |
+| Actor-to-actor `async` or `send_to` | Effect worker and actor worker |
+| Observable Turbo updates | Broadcast worker, Action Cable, and the actor execution path |
+| Initial `solid_object` server render | No Solid Objects worker; normal Rails rendering |
+
+One command starts every Solid Objects role:
 
 ```bash
 bundle exec solid_objects start
 ```
 
-The engine uses the application's primary Active Record connection by default.
-See [Database support](#database-support) for a separate database configuration.
+Deploy and monitor that process before enabling any feature marked as requiring
+a runtime role. A missing worker never makes a durable `async` message
+disappear, but it leaves the message pending indefinitely.
 
 ## Defining an actor
 
@@ -270,6 +357,20 @@ mailbox. State changes must go through public actor methods or explicit
 State, arguments, results, effects, and reminder arguments accept
 JSON-compatible values. Solid Objects never deserializes Ruby `Marshal` data.
 
+Attribute readers are ordered mailbox queries and retain message history. For
+a read that does not need mailbox ordering, use an authorized committed
+snapshot:
+
+```ruby
+snapshot = cart.snapshot
+items = snapshot.items
+```
+
+Snapshots and synchronous results are deeply frozen. Use
+`SolidObjects.mutable_copy(items)` before changing a returned collection.
+Snapshot reads can race with an in-flight turn; they return the most recently
+committed state and do not create or activate a missing actor.
+
 Lifecycle hooks are also available:
 
 ```ruby
@@ -375,6 +476,37 @@ and MCP request/response boundaries when the handler itself fits the
 application's latency budget. If another process owns the activation, the
 caller waits for the durable result using wake-up hints with bounded database
 polling as the fallback. A timeout never cancels the durable invocation.
+`SolidObjects::SyncTimeout` includes actor identity, message ID, sequence,
+durable status, mailbox blocker, and activation-owner diagnostics without
+including message arguments. The configured timeout also bounds adapter
+database lock waits from the enqueue attempt through result observation.
+PostgreSQL uses transaction lock and statement timeouts, SQLite uses its busy
+timeout, and MySQL uses its execution timeout plus InnoDB's one-second minimum
+lock-wait granularity.
+
+The durable call can finish after its original caller gives up. Reauthorize and
+recover its eventual result through the durable message identity:
+
+```ruby
+begin
+  order.submit(timeout: 250.milliseconds)
+rescue SolidObjects::SyncTimeout => error
+  result = error.message_reference.wait(
+    timeout: 5.seconds,
+    authorization_context: Current.user
+  )
+end
+```
+
+If the enqueue transaction itself cannot finish within the budget, Solid
+Objects raises `SyncEnqueueTimeout`; no durable message exists to recover.
+Timeouts do not preempt Ruby handler code that has already started.
+
+Do not wrap a synchronous actor call in `ApplicationRecord.transaction`.
+Solid Objects raises `SolidObjects::SyncInsideTransaction` before enqueue when
+its connection already has an open transaction. Move the actor call before the
+transaction, use `async`, or let the actor own the coordinated change through a
+commit action.
 
 Actor code cannot use direct calls or `sync` on another actor; synchronous
 actor-to-actor waits can deadlock in cycles. Use `async` or `send_to` and a
@@ -396,6 +528,10 @@ The caller receives `SolidObjects::Rejected` with a stable code, message, and
 JSON-compatible details. The rejected message remains durable for audit, actor
 state is rolled back, and no later mailbox turn is blocked.
 
+`Rejected#code` is a `String`, even when `reject` receives a symbol. Codes must
+match `\A[a-z][a-z0-9_]*\z`; invalid codes raise `ArgumentError` when the
+handler calls `reject`.
+
 ### Redelivery
 
 Sequential does not mean once. A handler can run again after a process crash or
@@ -412,6 +548,50 @@ end
 
 External systems must also deduplicate effects using the stable effect ID.
 
+## Application database writes
+
+Actor handlers execute outside the fenced commit. They may query application
+records, but Solid Objects rejects direct Active Record writes from all
+user-supplied actor code: handlers, observables, activation/deactivation hooks,
+and state migrations. Otherwise an application row could commit before the
+actor later raises or loses its activation fence.
+
+For a short database-only change that must commit atomically with actor state,
+stage a named action:
+
+```ruby
+class Assessment < SolidObjects::Actor
+  attribute :status, default: "open"
+
+  def finish(attempt_id:, score:)
+    self.status = "complete"
+    commit_action :complete_attempt, attempt_id:, score:
+  end
+end
+```
+
+Register its implementation during application boot:
+
+```ruby
+SolidObjects.register_commit_action(:complete_attempt) do |arguments, context|
+  AssessmentAttempt.find(arguments.fetch("attempt_id")).update!(
+    score: arguments.fetch("score"),
+    actor_message_id: context.message_id
+  )
+end
+```
+
+The registered block runs inside the short fenced transaction. Its database
+writes, actor state, message completion, and outboxes all commit or roll back
+together. Commit actions require Solid Objects and `ActiveRecord::Base` to
+share one connection pool. They may be invoked again after a database rollback,
+so keep them deterministic, bounded, and database-only. Never perform network
+I/O, wait for another actor, or enqueue nontransactional work from a commit
+action.
+
+When Solid Objects uses a separate actor database, use `emit` and an idempotent
+effect consumer instead; the two databases cannot share one transaction.
+
 ## Effects
 
 Cloudflare Durable Objects can call external services directly. Solid Objects
@@ -475,6 +655,10 @@ It may read `SolidObjects::Instance.states_for`, `.without_pending_work`, and
 `.orphaned`, but every repair must go through `async`. Never bulk-update actor
 state around the lease and fencing checks.
 
+Suspended actors should be reported rather than silently resumed. Spread large
+repair batches with `available_at:` so reconciliation cannot stampede one
+mailbox or the worker fleet.
+
 ## Destroying an object
 
 Destroy an actor incarnation through its reference:
@@ -551,6 +735,11 @@ Important defaults:
 | `max_attempts` | 5 |
 | `process_heartbeat_interval` | 15 seconds |
 | `process_alive_threshold` | 60 seconds |
+| `message_retention` | 30 days |
+| `message_retention_by_actor_type` | `{}` |
+| `instance_retention_by_actor_type` | `{}`; instances never expire unless listed |
+| `process_retention` | 7 days |
+| `prune_batch_size` | 1,000 |
 | `worker_count` | 1 |
 | `effect_worker_count` | 1 |
 | `broadcast_worker_count` | 1 |
@@ -584,10 +773,16 @@ Administration commands require the administration policy:
 ```bash
 bundle exec solid_objects status
 bundle exec solid_objects cleanup
+bundle exec solid_objects prune_messages
+bundle exec solid_objects prune_instances
+bundle exec solid_objects prune_processes
 bundle exec solid_objects dead_letters
 bundle exec solid_objects retry_dead_letter 123
 ```
 
+The prune commands preview counts by default. Add `--execute` only after
+reviewing the configured retention policy.
+
 The supervisor stops new claims, drains active loops, releases cached leases,
 and marks process rows stopped on graceful shutdown. A hard-killed worker's
 claimed turn is recovered after its process heartbeat or activation lease
@@ -686,6 +881,13 @@ Do not use it for stateless work, bulk pipelines, CPU-heavy computation,
 cross-actor transactions, slow network calls inside handlers, or domains that
 are clearer as normalized Active Record models and direct service objects.
 
+High-QPS request reads, rate-limit counters, impression pipelines, large JSON
+documents, and latency budgets that cannot tolerate several coordination
+transactions are explicit anti-patterns. Read the full
+[fit and anti-pattern guide](docs/fit.md) before migrating an existing
+surface, and use the [legacy-state migration cookbook](docs/migrating-existing-state.md)
+for staged cutovers.
+
 ## Comparisons
 
 | Tool | What Solid Objects adds or changes |
@@ -727,11 +929,13 @@ See the [development guide](docs/development.md) and
 
 ## Status
 
-Implemented and tested in 0.2:
+Implemented and tested in 0.3:
 
 - Rails engine, install generator, migrations, and `solid_objects` executable;
 - actor registry, references, JSON state, and state migrations;
 - direct synchronous actor RPC, explicit `sync`, and durable `async`;
+- guarded transaction boundaries, same-database commit actions, adapter lock
+  deadlines, structured synchronous timeout diagnostics, and result recovery;
 - durable message history plus ready and claimed membership tables;
 - concurrent sequence allocation and actor creation;
 - activation leases, per-activation tokens, fencing generations, and
@@ -744,7 +948,11 @@ Implemented and tested in 0.2:
 - authorized actor destruction with fenced stale-write rejection and cascading
   durable-work cleanup;
 - durable observable broadcasts and authorized Action Cable refresh;
-- process registration, heartbeats, cleanup, and graceful shutdown; and
+- process registration, heartbeats, caller shutdown, cleanup, and bounded
+  message/process retention plus opt-in actor-instance expiration;
+- an opt-in Minitest helper for actor-state isolation and deterministic async
+  actor/reminder/effect/broadcast draining;
+- authorized mailbox-free state snapshots and mutable JSON copies; and
 - SQLite, PostgreSQL, and MySQL integration tests.
 
 Partially implemented:
@@ -757,8 +965,8 @@ Partially implemented:
   Turbo append actions remain future work;
 - local admission limits exist, but distributed rate limits and global
   admission control do not; and
-- administration views exist, but retention automation and richer audit tools
-  do not.
+- administration views and pruning commands exist, but scheduled maintenance
+  and richer audit tools do not.
 
 Production readiness requires hardening and operational soak evidence. The
 [roadmap](docs/roadmap.md) tracks that work.

data/benchmark/adoption_latency.rb

@@ -0,0 +1,5 @@
+# rbs_inline: enabled
+
+require_relative "support"
+
+SolidObjectsBenchmark.adoption_latency

data/benchmark/support.rb

@@ -145,6 +145,32 @@ module SolidObjectsBenchmark
         "p99=#{milliseconds(percentile(sorted, 0.99))}ms"
     end
 
+    # @rbs () -> void
+    def adoption_latency
+      instance_count = SolidObjects::Instance.count
+      message_count = SolidObjects::Message.count
+
+      cold_elapsed = Benchmark.realtime do
+        CounterActor.ref("adoption-cold").increment
+      end
+
+      reference = CounterActor.ref("adoption-warm")
+      reference.increment
+      write_samples = Array.new(count) do
+        Benchmark.realtime { reference.increment }
+      end
+      read_samples = Array.new(count) do
+        Benchmark.realtime { reference.count }
+      end
+
+      puts "first cold call: #{milliseconds(cold_elapsed)}ms"
+      puts latency_summary("warm writes", write_samples)
+      puts latency_summary("ordered reads", read_samples)
+      puts "durable row growth: " \
+        "instances=+#{SolidObjects::Instance.count - instance_count}, " \
+        "messages=+#{SolidObjects::Message.count - message_count}"
+    end
+
     # @rbs () -> void
     def activation_cache
       reference = CounterActor.ref("cache")
@@ -255,6 +281,15 @@ module SolidObjectsBenchmark
       samples.fetch(((samples.length - 1) * fraction).ceil)
     end
 
+    # @rbs (String, Array[Float]) -> String
+    def latency_summary(name, samples)
+      sorted = samples.sort
+      "#{name} #{samples.length} calls: " \
+        "median=#{milliseconds(percentile(sorted, 0.50))}ms " \
+        "min=#{milliseconds(sorted.first)}ms " \
+        "max=#{milliseconds(sorted.last)}ms"
+    end
+
     # @rbs (Float) -> String
     def milliseconds(seconds)
       format("%.1f", seconds * 1_000)

data/docs/architecture.md

@@ -150,6 +150,12 @@ snapshots are deeply frozen. Use `async` for durable fire-and-forget delivery
 and `sync` for dynamic operation names. The explicit `message` DSL remains
 available for dynamic definitions.
 
+`reference.snapshot` is the explicit unordered read path. It invokes query
+authorization, reads the most recently committed instance state without
+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
@@ -161,6 +167,8 @@ Lifecycle hooks are deterministic local hooks:
 - `on_deactivate` runs only on graceful local deactivation. Its state changes are not persisted and it must not be used for durable work. Explicit destruction does not run lifecycle hooks.
 
 Durable application cleanup belongs in messages, reminders, or effects.
+Handlers, observable blocks, lifecycle hooks, and state migrations all execute
+with application Active Record writes prevented.
 
 ## Enqueue and sequence allocation
 
@@ -248,6 +256,8 @@ Actor code then executes with no open database transaction and no pinned connect
 
 - Read and mutate its in-memory state for a message
 - Read state for a query
+- Read application records
+- Stage same-database commit actions
 - Stage effects
 - Stage reminders
 - Stage asynchronous actor messages
@@ -258,8 +268,16 @@ It cannot:
 - Perform a synchronous actor-to-actor wait
 - Assume execution happens once
 - Commit actor state directly
+- Write application records directly
+- Perform external I/O that must be atomic with actor state
 
-After actor code, the executor validates state and staged data as JSON and computes changed observables.
+Rails write prevention turns a direct Active Record write into
+`ApplicationWriteForbidden` before it reaches the database. Handler and
+observable failures become nonretryable message failures. Activation and
+migration failures happen before the message is claimed. A deactivation-hook
+failure is instrumented and logged, but cannot replace an already committed
+result or prevent best-effort lease release. After actor code, the executor
+validates state and staged data as JSON and computes changed observables.
 
 ## Fenced commit
 
@@ -268,14 +286,15 @@ Successful completion uses one database transaction:
 1. Lock the instance row.
 2. Verify owner, activation token, generation, and an unexpired lease using database time.
 3. Lock the durable message and verify its claimed membership belongs to that owner, activation token, and generation.
-4. Update native JSON state and state version.
-5. Store the completion timestamp and result on the durable message and delete claimed membership.
-6. Insert staged effects.
-7. Insert or update staged reminders.
-8. Insert staged actor-message outbox rows.
-9. Insert changed-observable broadcast rows.
-10. Update actor last-used time.
-11. Commit.
+4. Execute registered same-database commit actions.
+5. Update native JSON state and state version.
+6. Store the completion timestamp and result on the durable message and delete claimed membership.
+7. Insert staged effects.
+8. Insert or update staged reminders.
+9. Insert staged actor-message outbox rows.
+10. Insert changed-observable broadcast rows.
+11. Update actor last-used time.
+12. Commit.
 
 Any lease or message predicate failure raises `LostActivation` and rolls back every item. The stale worker discards its in-memory activation.
 
@@ -346,11 +365,25 @@ overhead at or below 100 milliseconds; polling fallback can pay up to
 Caller timeout:
 
 - Raises `SolidObjects::SyncTimeout`.
+- Reports durable message, blocker, and activation-owner diagnostics.
+- Exposes a `message_reference` that can reauthorize and wait again.
 - Does not cancel or delete the message.
 - Does not prevent later execution.
 - Leaves the result available until retention cleanup.
 
-The durable row remains after timeout and can be inspected directly by message ID. A public request-ID lookup and bounded retention commands are not yet implemented.
+The configured timeout begins before durable enqueue. PostgreSQL transaction
+lock and statement timeouts, MySQL execution and InnoDB lock-wait timeouts, and
+SQLite busy timeout bound database contention. MySQL rounds lock waits up to
+its one-second minimum. If enqueue cannot commit, `SyncEnqueueTimeout` is
+raised and no durable result exists. Once Ruby handler code starts, it is not
+safely preempted and may outlive the caller budget.
+
+The durable row remains after a normal wait timeout and can be recovered with
+`error.message_reference.wait`. Bounded retention commands are implemented;
+public request-ID lookup is not. A sync call made with an already-open
+transaction on the Solid Objects connection raises `SyncInsideTransaction`
+before enqueue. This avoids savepoint enlistment, lock retention until the
+outer commit, and callers timing out on work they indirectly block.
 
 `async` performs the same durable enqueue without caller assistance or result
 waiting and immediately returns a `MessageReference`. Runtime workers process
@@ -505,6 +538,7 @@ end
 ```
 
 Activation applies each step in order. Missing steps, cycles, non-JSON output, or stored versions newer than code fail activation.
+Migration code is subject to the same application-write guard as handlers.
 
 Refusing newer stored state is a runtime invariant, not an operator recommendation. The worker does not invoke lifecycle hooks or message code when `stored_state_version > actor_class.state_version`.
 
@@ -573,6 +607,19 @@ An activation becomes idle when it has no due earliest message and no turn in fl
 Graceful release conditionally clears owner and expiration only if the generation still matches. Expired leases need no explicit cleanup before another worker claims them.
 
 `on_deactivate` is best effort and nondurable. It may not run on crash and cannot be the source of a correctness requirement.
+A failing hook is logged and instrumented as
+`solid_objects.activation.deactivation_failed`; lease release is still
+attempted and a committed synchronous result is preserved.
+
+## Retention
+
+Terminal messages and stopped process rows have configurable bounded pruning.
+Actor instances never expire by default. Types listed in
+`instance_retention_by_actor_type` become eligible after their idle cutoff only
+when they are unowned, unpaused, and have no ready/claimed work, scheduled
+reminder, unfinished or dead outbox, or dead letter. The pruner locks and
+rechecks each candidate before cascading deletion. All pruning commands
+preview by default and require administration authorization.
 
 ## Advisory locks
 
@@ -612,7 +659,7 @@ The semantic guarantees are common, but their coordination implementations diffe
 | JSON state | JSONB | JSON | Rails JSON type |
 | Executable-work indexes | Ready/claimed membership tables | Ready/claimed membership tables | Ready/claimed membership tables |
 | Write isolation | Row locks and MVCC | InnoDB row/next-key locks and MVCC | One writer, serializable writes |
-| Contention retry | Database/Active Record behavior; explicit classification is roadmap | Database/Active Record behavior; explicit classification is roadmap | Busy timeout; explicit busy classification is roadmap |
+| Sync contention deadline | Transaction lock and statement timeouts | Execution timeout and one-second-granularity InnoDB lock timeout | Busy timeout |
 | Lease clock | Database current time | Database current time | Database current time |
 
 All backends use unique identity and sequence constraints, short transactions, and conditional owner/generation/expiry fencing. Passing one backend's suite is not evidence for another.
@@ -633,14 +680,14 @@ All backends use unique identity and sequence constraints, short transactions, a
 12. **How are leases renewed?** Conditional database update by instance, owner, generation, and unexpired lease.
 13. **How does graceful shutdown work?** Stop claims, finish current turn within timeout, release cached leases, stop heartbeat, mark process stopped.
 14. **How does synchronous invocation work across processes?** The caller first tries to claim and execute the actor locally. If another process owns it, a wake-up adapter prompts a durable result query and bounded polling remains the fallback.
-15. **What happens after caller timeout?** The durable message continues and its eventual result remains on the message row.
-16. **How are results cleaned up?** The schema has cleanup indexes, but bounded retention tooling is not implemented yet.
+15. **What happens after caller timeout?** A committed message continues and its eventual result can be recovered with the timeout's authorized message reference. An enqueue timeout leaves no message. Running Ruby code is not preempted.
+16. **How are results cleaned up?** `prune_messages` deletes eligible terminal history in bounded batches after global or per-actor retention. It previews by default and preserves live work, dead letters, retry links, and unfinished outboxes.
 17. **How are large mailboxes managed?** The implemented controls are the per-actor mailbox cap, payload caps, and fair activation yields; rate and global admission controls remain roadmap work.
-18. **How are completed messages pruned?** Cleanup indexes support future bounded pruning; the initial release does not automatically prune them.
+18. **How are completed messages pruned?** Operators schedule the dry-run-reviewed `prune_messages --execute` command. Solid Objects does not run deletion automatically.
 19. **How are state migrations performed?** Explicit one-step actor migrations on activation, persisted only with a successful fenced commit.
 20. **What happens during rolling deploys?** Newer state can make old workers incompatible; deploys must preserve backward readability or drain old workers.
 21. **How are subscriptions authorized?** Verify signed identity, resolve registered type, invoke host authorization, then stream.
 22. **How are lost broadcasts recovered?** Current-state refresh after reconnect; durable outbox retries server delivery.
 23. **How are actor-to-actor cycles handled?** Synchronous actor waits are rejected; asynchronous request/result messages avoid call-stack cycles.
-24. **Which operations are transactional?** The transaction map above lists every atomic boundary; actor code and I/O are outside.
+24. **Which operations are transactional?** The transaction map above lists every atomic boundary. Actor code and external I/O are outside; registered same-pool commit actions execute inside the fenced state/message transaction.
 25. **Which guarantees depend on PostgreSQL?** None of the public semantics are PostgreSQL-only. PostgreSQL and MySQL depend on row-lock claiming; SQLite depends on serialized write transactions. Each backend's guarantee depends on its adapter-specific integration tests.