solid_objects 0.2.0 → 0.3.0

data/docs/authorization.md

@@ -0,0 +1,98 @@
+# Authorization policies
+
+Solid Objects treats actor identities as identifiers, never capabilities.
+Knowing an actor ID, message ID, or signed stream token grants no permission.
+All five policies deny by default, so a generated installation is
+intentionally inert until the host application defines its trust boundary.
+
+## Policy reference
+
+| Policy | Gates | Caller context | Risk if opened globally |
+| --- | --- | --- | --- |
+| `authorize_message` | Direct actor methods, explicit `sync` messages, and public `async` enqueue | Value passed as `authorization_context:`; often a user, service principal, or trusted internal marker | Anyone reaching the call site can mutate any known actor identity |
+| `authorize_query` | Attribute reads, declared queries, committed snapshots, observable reads, and component reads | Explicit call context or the Rails view context supplied by `solid_object` | Actor state 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, process inspection/cleanup/pruning, message pruning, and dead-letter inspection/retry | Rails controller 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
+actor-to-actor deliveries come from
+already committed runtime rows and do not re-enter the public client policy.
+
+## A tenant-aware policy
+
+Pass the authenticated user as the call context:
+
+```ruby
+cart = ShoppingCart.ref(Current.user.id)
+cart.add_item(
+  product_id: "shirt-123",
+  authorization_context: Current.user
+)
+```
+
+Authorize only the matching user and actor type:
+
+```ruby
+SolidObjects.configure do |configuration|
+  owns_actor = lambda do |actor_type:, actor_id:, authorization_context:, **|
+    user = authorization_context
+
+    actor_type == "ShoppingCart" &&
+      user.present? &&
+      actor_id == user.id.to_s
+  end
+
+  configuration.authorize_message = owns_actor
+  configuration.authorize_query = owns_actor
+  configuration.authorize_destroy = owns_actor
+
+  configuration.authorize_subscription = lambda do |actor_type:, actor_id:, authorization_context:|
+    connection = authorization_context
+
+    actor_type == "ShoppingCart" &&
+      connection.current_user.present? &&
+      actor_id == connection.current_user.id.to_s
+  end
+
+  configuration.authorize_administration = lambda do |authorization_context:, **|
+    context = authorization_context
+    user = context.respond_to?(:current_user) ? context.current_user : nil
+
+    user&.administrator?
+  end
+end
+```
+
+The policy receives normalized actor type and ID strings, message name and
+arguments where relevant, and the context supplied by the caller. Avoid
+authorizing from arguments alone; bind the actor identity to the authenticated
+principal and tenant.
+
+## Server-side-only pilots
+
+Allowing `authorize_message` and `authorize_query` unconditionally can be a
+reasonable short-lived pilot only when every call site is trusted server code,
+actor IDs cannot come from an unauthorized request, and the feature is not
+exposed through Action Cable or administration routes.
+
+Keep `authorize_destroy`, `authorize_subscription`, and
+`authorize_administration` denied until each feature has an explicit policy.
+Replace unconditional policies before exposing actor IDs to controllers, API
+clients, MCP tools, jobs carrying user input, or browser subscriptions.
+
+For commands executed only on hosts where shell access is already the
+authenticated administration boundary, the generated initializer shows an
+optional CLI-scoped policy:
+
+```ruby
+configuration.authorize_administration = lambda do |authorization_context:, **|
+  authorization_context.is_a?(Hash) &&
+    authorization_context[:source] == "cli"
+end
+```
+
+Run `bin/rails solid_objects:doctor` after configuration. Its neutral policy
+probe is deliberately conservative: a context-aware policy may correctly warn
+because it denies a `nil` context.

data/docs/benchmarks.md

@@ -1,10 +1,31 @@
-# Local benchmarks
+# Performance and storage costs
 
 These numbers are development measurements, not universal capacity guarantees.
 They include the runtime's Active Record and database query overhead and will
 vary with hardware, schema size, connection pools, durability settings, and
 contention.
 
+## Production-shaped adoption measurement
+
+An adoption evaluation measured Solid Objects 0.2.0 from a macOS Rails process
+against Docker MySQL 8 over a published TCP port. The host used Rails 8.1, Ruby
+4.0.5, roughly 165 gems, and an approximately 2,200-line schema.
+
+| Operation | Existing key-value row | Solid Objects |
+| --- | ---: | ---: |
+| Write | median 4.7 ms | median 60 ms, minimum 33 ms, maximum 163 ms |
+| Read | median 0.2 ms | median 28 ms |
+| First call for a cold identity | approximately 5 ms | 315 ms |
+
+This is not a controlled cross-database benchmark and no sample count was
+recorded. It is still useful adoption evidence: a synchronous actor call is not
+a substitute for a direct indexed row read when single-digit-millisecond
+latency is the requirement. The first call includes actor-instance creation,
+caller-process registration, message enqueue, activation claim, handler
+execution, fenced commit, and activation release.
+
+## Project development benchmark
+
 Measured 2026-08-06 on an Apple M5 with 24 GB RAM, Ruby 4.0.5, Rails 8.1.3.1,
 and SQLite 3.51.0. Each throughput scenario used 200 operations; the concurrent
 scenario used four worker threads.
@@ -21,6 +42,59 @@ scenario used four worker threads.
 | Activation reuse | 98.0%, four activations for 200 messages |
 | Queries for one message turn | 29 |
 
+The difference between the SQLite development result and the MySQL adoption
+result is why Solid Objects does not publish one latency promise. Network
+topology, adapter behavior, host schema, logging, callbacks, and contention all
+matter.
+
+## Durable row growth
+
+The storage cost is deterministic even when latency is not:
+
+- the first call for one actor identity inserts one
+  `solid_objects_instances` row;
+- every direct, `sync`, query, attribute read, or `async` call inserts one
+  permanent `solid_objects_messages` row;
+- ready and claimed membership rows exist only while the call is pending or
+  executing;
+- one caller process row is registered per application process that performs
+  synchronous calls;
+- effects and observable changes add outbox rows; and
+- reminders add one row per named actor reminder.
+
+Attribute reads are therefore not free snapshots from the instance row. They
+are ordered durable query messages and grow message history exactly like
+writes.
+
+Built-in pruning previews by default and must be scheduled explicitly. Budget
+message growth before retention as:
+
+```text
+daily durable messages = daily actor writes + daily actor reads + daily callbacks
+```
+
+Review the [retention requirements](operations.md#retention-and-backups) before
+adopting a high-volume surface.
+
+Use `reference.snapshot` for an authorized current-state read when mailbox
+ordering is unnecessary. It avoids a message row but can observe state before
+an in-flight turn commits.
+
+## Measure the host application
+
+Run the adoption benchmark against a dedicated empty database with the same
+adapter and topology as production:
+
+```bash
+COUNT=25 \
+SOLID_OBJECTS_DATABASE_URL=mysql2://localhost/solid_objects_benchmark \
+bundle exec ruby -Ilib benchmark/adoption_latency.rb
+```
+
+It reports the first cold call, warm synchronous writes, ordered reads, and
+durable instance/message growth. Run it near the application process, with
+production-like TLS and network boundaries where applicable.
+
 The scripts and invocation examples are in the
 [development guide](development.md#benchmarks). PostgreSQL and MySQL should be
 benchmarked independently before selecting production capacity.

data/docs/correctness.md

@@ -101,13 +101,20 @@ The following are atomic:
 - activation owner, expiration, and generation acquisition;
 - ready-to-claimed membership move and attempt increment;
 - state, state version, message result/completion, claimed deletion, effects,
-  reminders, outbound actor messages, and observable broadcasts;
+  same-database commit actions, reminders, outbound actor messages, and
+  observable broadcasts;
 - failed-attempt record plus ready reinsertion or dead letter;
 - effect completion plus its optional actor outcome message;
 - reminder occurrence enqueue plus reminder advancement; and
 - actor destruction plus cascading removal of all actor-owned rows.
 
 Actor Ruby code and external I/O are never inside the actor-state transaction.
+Rails write prevention rejects direct Active Record writes while handlers,
+observables, lifecycle hooks, or state migrations run. A registered commit
+action is the only application-record write path inside the fenced commit, and
+it is available only when Solid Objects and `ActiveRecord::Base` share one
+connection pool. Commit actions must contain only bounded database work.
+External I/O belongs in the effect outbox.
 
 ## Synchronous invocation
 
@@ -119,6 +126,17 @@ result. A worker may win the activation instead; the caller then observes the
 durable result through wake-up hints with bounded polling as fallback.
 
 Timeout raises `SolidObjects::SyncTimeout` but does not cancel the message.
+The exception reports actor identity, message ID and sequence, durable status,
+an earlier mailbox blocker, and activation-owner metadata without exposing
+arguments. Its `message_reference` can reauthorize and wait for the eventual
+result. Adapter lock/query deadlines cover the durable enqueue and coordination
+transactions. If enqueue cannot commit, `SyncEnqueueTimeout` is raised and no
+message reference exists. MySQL lock waits have one-second InnoDB granularity.
+Ruby handlers that already started are not preempted.
+
+A synchronous call made while the Solid Objects connection already has an open
+transaction raises `SolidObjects::SyncInsideTransaction` before the message is
+enqueued.
 Destroying the actor while a synchronous caller waits removes its message,
 wakes the caller, and raises `SolidObjects::ActorDestroyed`.
 

data/docs/database-schema.md

@@ -24,6 +24,11 @@ Indexes:
 - owner: dead-process cleanup;
 - last used/ID: retention and reconciliation.
 
+Instance expiration is disabled unless its actor type has an explicit
+retention policy. The pruner uses the last-used index for candidate discovery,
+then locks and rechecks that the actor has no owner, mailbox membership,
+scheduled reminder, unresolved outbox, or dead letter before deletion.
+
 ### `messages`
 
 Durable immutable invocation identity and arguments plus sequence, attempt

data/docs/development.md

@@ -28,6 +28,46 @@ SOLID_OBJECTS_DATABASE_URL=mysql2://... bundle exec rake test
 Each database run must start from an empty dedicated test database because the
 test helper applies the engine migration.
 
+## Host application tests
+
+Rails transactional tests keep the application connection inside an outer
+transaction. Synchronous actor invocation deliberately rejects that condition
+because nested savepoints retain actor locks until the test transaction ends
+and make durable behavior unlike production.
+
+Use an actor-specific base class:
+
+```ruby
+require "solid_objects/test_helper"
+
+class SolidObjectsTestCase < ActiveSupport::TestCase
+  include SolidObjects::TestHelper
+end
+```
+
+The helper disables transactional tests for that class and removes Solid
+Objects instances and process registrations before and after each test. It
+preserves application configuration, actor registration, and effect/commit
+action registration. If actor commit actions create application records, clean
+those records with fixtures or explicit teardown because they are no longer
+covered by Rails' transaction rollback.
+
+Use `drain_solid_objects` to process actor, reminder, effect, callback, and
+broadcast work to a deterministic fixed point without arbitrary sleeps:
+
+```ruby
+message = Counter.ref("test").async(:increment)
+
+assert_equal 1, drain_solid_objects
+assert_equal "completed", message.status
+```
+
+Pass `roles: [:actors]` when a test intentionally wants to leave outboxes or
+reminders pending.
+
+`SolidObjects::TestHelper.reset_actors!` is also available for explicit suite
+boundaries.
+
 ## Inline RBS
 
 Ruby source starts with:
@@ -66,12 +106,13 @@ correct change, rerun the focused test, then the complete database matrix.
 
 ## Benchmarks
 
-Scripts in `benchmark/` cover enqueue, claim, processing, cold actors, a hot
-actor, concurrent actors, synchronous latency, cache reuse, and query counts.
-Results describe one machine and database configuration; they are not universal
-capacity guarantees.
+Scripts in `benchmark/` cover adoption latency and durable row growth, enqueue,
+claim, processing, cold actors, a hot actor, concurrent actors, synchronous
+latency, cache reuse, and query counts. Results describe one machine and
+database configuration; they are not universal capacity guarantees.
 
 ```bash
+COUNT=25 bundle exec ruby -Ilib benchmark/adoption_latency.rb
 COUNT=500 bundle exec ruby -Ilib benchmark/enqueue.rb
 COUNT=500 bundle exec ruby -Ilib benchmark/claim.rb
 COUNT=500 bundle exec ruby -Ilib benchmark/processing.rb

data/docs/fit.md

@@ -0,0 +1,98 @@
+# Is Solid Objects a good fit?
+
+Solid Objects trades database work and retained message history for one strong
+property: all committed turns for one durable identity execute in order behind
+a fenced activation. Adopt it when that coordination property removes
+application-level locking, recovery, and scheduling code that would otherwise
+be difficult to make correct.
+
+## Strong fit signals
+
+Solid Objects is a good candidate when most of these are true:
+
+- State belongs to one durable identity such as a cart, room, device, session,
+  workflow, or user-specific schedule.
+- Writes for that identity must be serialized.
+- The state is naturally a bounded JSON document.
+- The object needs per-identity reminders, transactional external effects, or
+  reactive Rails views.
+- Different identities should run concurrently while one hot identity remains
+  deliberately sequential.
+- A durable mailbox and at-least-once retry are more valuable than minimum
+  request latency.
+- The application can operate and monitor additional database tables and, for
+  asynchronous features, a Solid Objects runtime process.
+
+Typical fits include checkout state machines, collaborative rooms, device
+twins, durable assessments, approval workflows, and user-specific scheduling.
+
+## Poor fit and anti-patterns
+
+Prefer ordinary Active Record, cache storage, Active Job, or an event pipeline
+when any of these dominate:
+
+- High-QPS request-path reads. Every actor attribute read is an ordered durable
+  message, not a direct `SELECT`, and retains a message-history row.
+- Hot counters such as abuse limits, impressions, page views, or metrics. One
+  identity is a serialization point and cannot gain throughput by adding
+  workers.
+- High-volume append workloads. Actor state rewrites a JSON document and the
+  mailbox retains one durable message per call.
+- Latency budgets where tens of milliseconds are already unacceptable.
+- Large, relational, or query-heavy state. Keep that data normalized in
+  application tables.
+- CPU-heavy work or slow network I/O inside a handler.
+- Cross-actor transactions or synchronous actor-to-actor call graphs.
+- State that is clearer as a normal record with database constraints and direct
+  service methods.
+
+A rate limiter is usually a poor actor: it is hot, request-critical, and often
+expires rather than requiring permanent message history. An impressions
+pipeline is also a poor actor: its value is high-throughput append and
+aggregation, not serialized mutable state.
+
+## Cost model
+
+Every synchronous or asynchronous invocation:
+
+- inserts one permanent `solid_objects_messages` row;
+- briefly occupies one ready or claimed membership row;
+- performs several short coordination transactions; and
+- may add effect, broadcast, or reminder records.
+
+The first call for an identity also inserts one `solid_objects_instances` row.
+Each application process that performs synchronous calls registers one caller
+process row. Actor state is rewritten as a JSON value on each successful
+mutation.
+
+Built-in bounded pruning is explicit and dry-run by default. Configure global
+and per-actor-type message retention, then schedule the reviewed execute
+commands. Actor instances expire only for types explicitly listed in
+`instance_retention_by_actor_type`. See
+[performance measurements](benchmarks.md) and
+[retention guidance](operations.md#retention-and-backups).
+
+Actor handlers may read application records but may not write them directly.
+Use a same-database commit action for a short atomic database change or an
+idempotent effect for external work. If the domain needs broad relational
+updates throughout arbitrary handler code, an ordinary Active Record service
+is likely a clearer fit.
+
+## Decision checklist
+
+Before adopting an actor, answer:
+
+1. What exact race or lifecycle problem requires serialized per-identity turns?
+2. What is the canonical actor identity?
+3. How hot can one identity become?
+4. Can the request path tolerate the measured cold and warm latency?
+5. How many calls and durable rows will this surface create per day?
+6. Which calls can be asynchronous?
+7. Which effects need downstream idempotency?
+8. Which runtime roles and operational alerts will the feature require?
+9. How will completed messages and outbox history be retained?
+10. How will existing state be cut over and rolled back?
+
+Benchmark the actual host database and deployment topology before committing a
+latency-sensitive surface. Local benchmark results are evidence about query
+shape, not universal capacity guarantees.

data/docs/migrating-existing-state.md

@@ -0,0 +1,140 @@
+# Migrating existing state
+
+Moving an existing Redis, cache, or key-value state machine into Solid Objects
+is a data migration and a coordination cutover. Treat it as a staged production
+change, not a rewrite that switches storage in one deploy.
+
+## 1. Write down the existing contract
+
+Inventory:
+
+- every read and write path;
+- the current canonical and secondary keys;
+- expiration and cleanup behavior;
+- concurrency guards and idempotency keys;
+- external effects;
+- expected request latency and volume; and
+- rollback requirements.
+
+Run the [fit checklist](fit.md#decision-checklist) before migrating. A hot
+counter or append pipeline may be better left in its existing store.
+
+## 2. Choose one canonical identity
+
+Solid Objects addresses an actor with one `(actor_type, actor_id)` pair. Do not
+hide two competing identities inside actor code or reintroduce a scan.
+
+When existing state is written by `(user_id, assessment_short)` but read by
+`session_id`, create a normalized lookup record:
+
+```ruby
+class AssessmentSession < ApplicationRecord
+  validates :session_id, uniqueness: true
+  validates :assessment_short, uniqueness: { scope: :user_id }
+
+  def actor
+    Assessment.ref(id)
+  end
+end
+```
+
+The lookup row gives both old keys one stable primary key. The actor ID is the
+lookup record ID, and ordinary indexed Active Record queries resolve either
+external key. This is clearer and safer than delimiter-joining composite values
+or preserving a `LIKE` scan.
+
+Create and backfill the lookup table before actor traffic begins. Enforce every
+identity invariant with unique database indexes.
+
+## 3. Add an idempotent bootstrap message
+
+Never bulk-update `solid_objects_instances.state`. Direct writes bypass actor
+ordering, state migrations, observables, activation ownership, and fencing.
+
+Import through a normal actor message:
+
+```ruby
+class Assessment < SolidObjects::Actor
+  attribute :imported, default: false
+  attribute :answers, default: -> { [] }
+
+  def bootstrap(answers:)
+    return if imported
+
+    self.answers = answers
+    self.imported = true
+  end
+end
+```
+
+Give every bootstrap call an idempotency key derived from the legacy record:
+
+```ruby
+session.actor.async(
+  :bootstrap,
+  answers: legacy.answers,
+  idempotency_key: "legacy-assessment:#{legacy.id}",
+  available_at: jittered_time
+)
+```
+
+Spread large backfills over a dispatch window and monitor mailbox age,
+failures, and dead letters. Asynchronous backfill requires the worker runtime.
+
+## 4. Prefer shadow comparison over blind dual writes
+
+Two independent stores cannot be updated atomically without a shared
+transaction or outbox. A controller that writes Redis and an actor in sequence
+can leave them divergent after a timeout or crash.
+
+A safer rollout:
+
+1. Keep the legacy store authoritative.
+2. Bootstrap the actor from a consistent legacy snapshot.
+3. Mirror new changes to the actor with stable idempotency keys.
+4. Read both stores in a background comparison path.
+5. Record divergence counts without changing the user response.
+6. Repair through actor messages, never direct actor-state SQL.
+7. Cut reads over only after divergence remains acceptably low.
+
+If the actor becomes authoritative before the legacy system is retired, emit a
+transactional effect that updates the legacy store. The effect is at least once,
+so the legacy write still needs idempotency.
+
+When the legacy state is an application table in the same connection pool as
+Solid Objects, a registered `commit_action` can update it in the fenced actor
+transaction instead. Keep that action database-only and bounded. A separate
+actor database cannot make this atomic; use the outbox effect and reconciliation
+path there.
+
+## 5. Cut over in reversible stages
+
+A typical zero-downtime sequence is:
+
+1. Deploy the lookup table and dual-key resolution.
+2. Deploy actor code and policies with reads still on the legacy store.
+3. Start the required runtime roles.
+4. Backfill actors in bounded batches.
+5. Enable shadow comparison and reconcile drift.
+6. Move a small cohort of reads to actors.
+7. Expand the cohort while watching latency, database growth, retries, and
+   divergence.
+8. Move writes to the actor.
+9. Retain the legacy state through an explicit rollback window.
+10. Remove dual writes and legacy data only after the rollback window closes.
+
+Use a feature flag whose rollback restores legacy reads and writes without
+requiring actor deletion. Do not assume a timed-out synchronous actor call did
+not commit; use `error.message_reference.wait` to reauthorize and recover the
+durable result, or use an idempotency key before retrying.
+
+## 6. Plan for dormant state and future changes
+
+Actor state migrations and legacy-store migration solve different problems:
+
+- this cookbook moves ownership from another store into an actor;
+- `state_version` evolves actor JSON after that ownership exists.
+
+Keep every published actor migration step. A dormant actor can reactivate years
+later with an old state representation. See the
+[state migration guide](state-migrations.md) for rolling-deployment rules.

data/docs/operations.md

@@ -1,5 +1,20 @@
 # Operations guide
 
+## Installation verification
+
+Run the installation doctor after generating the initializer and migrating:
+
+```bash
+bin/rails solid_objects:doctor
+```
+
+It validates runtime configuration, required tables and columns, neutral policy
+posture, live runtime roles, and a real workerless synchronous actor round-trip.
+Engine migration timestamps are rewritten when copied into a host application,
+so the schema check compares the required shape instead of a fixed timestamp.
+Warnings such as an all-deny neutral policy do not fail the command because a
+context-aware production policy may correctly deny the probe.
+
 ## Runtime
 
 Start all configured roles:
@@ -19,6 +34,9 @@ Process inspection, cleanup, dead-letter inspection, and retry all require an
 administration policy that authorizes the CLI context:
 
 ```bash
+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
 ```
@@ -41,6 +59,9 @@ Important controls include:
 - payload, state, and result byte limits
 - retry attempts and delay
 - heartbeat interval and alive threshold
+- message retention and per-actor-type overrides
+- opt-in actor-instance retention by actor type
+- stopped-process retention and prune batch size
 
 Keep lease duration comfortably above renewal interval and expected database
 pause time. A handler can exceed the pass-duration budget because Ruby code is
@@ -111,12 +132,81 @@ Alert on:
 - reconciliation drift;
 - database lock waits, deadlocks, and SQLite busy errors.
 
+## Instrumentation and logging
+
+Active Support notifications use the `solid_objects.` prefix. Core events
+include message enqueue/start/completion/failure/rejection, activation
+claim/start/renew/release/deactivation failure, sync timeout/enqueue timeout/
+transaction rejection, commit-action start/completion/failure, effect and
+broadcast enqueue/completion, reminder enqueue, actor destruction/expiration,
+retention pruning, process cleanup, and supervisor lifecycle.
+
+Payloads contain stable runtime identifiers, actor identity, sequence,
+attempts, ownership generations, and safe exception summaries where relevant.
+Arguments, actor state, results, and outbox payloads are excluded. The bundled
+log subscriber turns the same notifications into structured logger hashes.
+
 ## Retention and backups
 
-The schema has cleanup indexes, but automatic pruning commands are still
-roadmap work. Until implemented, define application-owned bounded deletes that
-preserve unfinished messages, dead letters under investigation, and synchronous
-results for the promised lookup period.
+Every actor call creates a durable message-history row, including queries and
+attribute reads. The default retention policy keeps terminal message history
+for 30 days and stopped process records for 7 days:
+
+`reference.snapshot` is the explicit exception: it performs an authorized
+current-state read without mailbox ordering or a message row.
+
+```ruby
+SolidObjects.configure do |configuration|
+  configuration.message_retention = 30.days
+  configuration.message_retention_by_actor_type = {
+    "AuditActor" => 365.days,
+    "EphemeralCounter" => 1.day
+  }
+  configuration.instance_retention_by_actor_type = {
+    "EphemeralCounter" => 30.days
+  }
+  configuration.process_retention = 7.days
+  configuration.prune_batch_size = 1_000
+end
+```
+
+Both pruning commands are dry-run previews by default:
+
+```bash
+bundle exec solid_objects prune_messages
+bundle exec solid_objects prune_instances
+bundle exec solid_objects prune_processes
+```
+
+After reviewing the counts, execute bounded deletion:
+
+```bash
+bundle exec solid_objects prune_messages --execute
+bundle exec solid_objects prune_instances --execute
+bundle exec solid_objects prune_processes --execute
+```
+
+Message pruning keeps ready and claimed work, dead letters and their retry
+links, messages with unfinished effects, and messages with undelivered
+broadcasts. Deleting eligible history cascades to completed effects, delivered
+broadcasts, and other message-owned rows. Choose a cutoff longer than every
+`sync` timeout because a caller whose result row disappears can no longer
+observe it.
+
+Actor expiration is disabled by default. `prune_instances` considers only
+actor types listed in `instance_retention_by_actor_type`, excludes active or
+paused actors, and preserves ready/claimed mailbox work, scheduled reminders,
+unfinished or dead outboxes, and dead letters. It locks and rechecks every
+candidate before cascading deletion. Preview counts first, then schedule
+`--execute` only after the application has accepted the loss of dormant state
+and completed history.
+
+Use authorized `reference.destroy` when deletion is an explicit application
+operation rather than a retention policy.
+
+Run stale-process `cleanup` before `prune_processes`. Normal caller processes
+mark their registrations stopped at exit; hard kills remain recoverable through
+heartbeat cleanup.
 
 Back up actor tables with the same consistency guarantees as application data.
 Restoring only instances without their mailboxes/outboxes, or vice versa, can