solid_objects 0.2.1 → 0.4.0

data/docs/architecture.md

@@ -120,7 +120,11 @@ instance first prevents a claimed reminder from recreating a destroyed actor.
 
 ### Broadcast worker
 
-The broadcast worker claims committed observable-change rows, renders idempotent Turbo replacements, broadcasts to a signed actor stream, and records delivery. Current actor state remains the reconnect source of truth.
+The broadcast worker claims committed observable-change rows, renders
+idempotent scalar Turbo replacements with component invalidation metadata,
+broadcasts to a signed actor stream, and records delivery. It never renders
+personalized component HTML. Current actor state remains the reconnect and
+request-time component source of truth.
 
 ### Process registry
 
@@ -150,6 +154,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 +171,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 +260,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 +272,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 +290,16 @@ 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. Advance the actor state revision to the completed message sequence.
+7. Store the completion timestamp and result on the durable message and delete claimed membership.
+8. Insert staged effects.
+9. Insert or update staged reminders.
+10. Insert staged actor-message outbox rows.
+11. Insert changed-observable broadcast rows.
+12. Update actor last-used time.
+13. Commit.
 
 Any lease or message predicate failure raises `LostActivation` and rolls back every item. The stale worker discards its in-memory activation.
 
@@ -346,11 +370,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
@@ -427,25 +465,61 @@ Large repairs use `async(..., available_at:)` to spread work over an application
 
 ## Realtime integration
 
-`solid_object` performs an authorized state read for initial rendering and emits:
+`solid_object` performs an authorized state read for initial rendering and
+emits:
 
 - A stable scope DOM ID derived from actor type and a SHA-256 digest of actor ID
 - One Turbo Cable subscription element for the actor
 - Stable child target IDs for values and components
 - A signed actor token used by the channel subscription
+- Signed component registrations containing a conventional component name,
+  explicit observable dependencies, the initial actor incarnation/revision,
+  and a same-origin engine refresh path
 
 ```erb
 <%= solid_object current_cart do |cart| %>
   Cart items: <%= cart.items_count %>
-  <%= cart.component :summary %>
+  <%= cart.component :summary, observes: %i[items checkout_status] %>
 <% end %>
 ```
 
 The signed token proves integrity, not authorization. `ActorChannel#subscribed` verifies the token, resolves the registered actor type, invokes `authorize_subscription`, and only then streams.
 
-Broadcast replacements happen after the actor transaction commits because only a committed broadcast outbox row can be delivered. Multiple values share the same Action Cable connection and one actor subscription.
-
-Each channel subscription transmits current observable replacements before streaming future broadcasts, including after reconnect. Missing a broadcast therefore creates temporary staleness, not permanent divergence.
+Scalar observable calls remain direct escaped Turbo replacements. A reactive
+component resolves only `actors/<actor_class>/_<component>`, receives its
+declared observables as frozen Ruby values, and cannot read raw state or a
+dependency it did not declare. A static initial-only component can still use a
+server-selected explicit partial; a reactive component cannot.
+
+Broadcast replacements happen after the actor transaction commits because only
+a committed broadcast outbox row can be delivered. Multiple scalar values and
+components share the same Action Cable connection and one actor subscription.
+One outbox row still exists per changed observable.
+
+The shared stream contains invalidation metadata and scalar HTML only for the
+scalar targets signed into that scope's stream token. Component-only
+dependencies do not send their values to the browser, and the stream never
+contains personalized component HTML. For each subscription, `ActorChannel`
+matches the changed observable to registered component dependencies. It
+coalesces multiple dependencies at the same message sequence and drops older
+revision pairs. A component invalidation replaces its stable target with a
+Turbo Frame whose source is the signed engine endpoint.
+
+The browser then makes an ordinary cookie-bearing HTTP request. The engine
+controller derives a request-specific context through
+`component_authorization_context`, calls `authorize_query` for the component
+name and every declared dependency, renders the host partial from a new
+committed snapshot, and returns `private, no-store` HTML. Subscribers to the
+same actor can therefore receive different HTML without sharing it through
+Cable or the database.
+
+Each channel subscription transmits current scalar replacements and compares
+each component's signed initial revision against the latest committed
+`(instance_id, state_revision)` pair, including after reconnect. Missing a
+broadcast therefore creates temporary staleness, not permanent divergence.
+The instance primary key distinguishes destroy-and-recreate incarnations.
+Replacing the full frame on each newer invalidation detaches an older in-flight
+frame, preventing its slower response from replacing the current generation.
 
 ## Authorization
 
@@ -464,6 +538,11 @@ recognizable.
 
 No controller, channel, or administrative command treats an actor ID, message ID, request ID, or signed stream name as authorization.
 
+Initial component rendering, Cable subscription, and request-time component
+refresh deliberately use different authorization contexts. Signed component
+tokens constrain actor identity, component convention, dependencies, revision,
+and same-origin refresh path but never grant access.
+
 Actor IDs are bounded UTF-8 strings and never become constant names, SQL identifiers, file paths, or raw stream names.
 
 ## Serialization
@@ -505,6 +584,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 +653,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
 
@@ -592,7 +685,7 @@ PostgreSQL transaction-level advisory locks may be used for optional singleton m
 | Create actor and allocate message sequence | Instance insert/lock, sequence increment, durable message and ready-membership inserts |
 | Claim activation | Backend claim transaction, generation increment, owner and expiry |
 | Claim next message | Move ready membership to claimed membership conditioned on lease |
-| Successful message commit | Fenced state, durable message result, claimed-membership deletion, effects, reminders, actor outbox, broadcasts |
+| Successful message commit | Fenced state and monotonic revision, durable message result, claimed-membership deletion, effects, reminders, actor outbox, broadcasts |
 | Failed message attempt | Conditional error, claimed deletion, ready reinsertion or dead letter |
 | Renew or release lease | Conditional instance update |
 | Destroy actor | Instance identity lock and cascading delete of state, mailbox, reminders, and outboxes |
@@ -612,7 +705,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 +726,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.
+22. **How are lost broadcasts recovered?** Current-state scalar replacement and authorized component 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.

data/docs/authorization.md

@@ -10,14 +10,53 @@ intentionally inert until the host application defines its trust boundary.
 | 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, 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_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, process inspection/cleanup, and dead-letter inspection/retry | Rails controller or `{ source: "cli" }` | Operational metadata, arguments, errors, and retries become exposed or mutable |
+| `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 |
 
-Internal reminder, effect-callback, and actor-to-actor deliveries come from
+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.
 
+## Realtime authorization contexts
+
+Reactive components cross three Rails execution contexts and authorize at all
+three boundaries:
+
+1. `solid_object(..., authorization_context:)` uses the explicit Action View
+   render context for initial scalar and component reads.
+2. `ActorChannel` passes its authenticated `ActionCable::Connection` to
+   `authorize_subscription`.
+3. `ComponentsController` resolves a fresh context for the cookie-bearing HTTP
+   request and calls `authorize_query` for the component name and every
+   dependency.
+
+Configure the refresh resolver when the query policy expects a user or service
+principal rather than the engine controller:
+
+```ruby
+SolidObjects.configure do |configuration|
+  configuration.component_authorization_context = lambda do |controller:|
+    Current.user
+  end
+end
+```
+
+Authentication middleware must populate `Current.user` for the refresh
+request. Do not copy an Action View object or Cable connection into the signed
+token. Those objects are request-specific and the token provides integrity,
+not authorization.
+
+Component partials receive the resolved value as the
+`authorization_context` local, allowing two authorized viewers to render
+different projections. Responses use `Cache-Control: private, no-store`.
+Durable outbox rows and shared Cable messages never contain component HTML.
+The stream token also signs the scalar observable targets rendered into that
+specific scope. Component-only dependencies send invalidation metadata but not
+their state value to the browser.
+
 ## A tenant-aware policy
 
 Pass the authenticated user as the call context:
@@ -80,6 +119,17 @@ Keep `authorize_destroy`, `authorize_subscription`, and
 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

@@ -66,8 +66,8 @@ Attribute reads are therefore not free snapshots from the instance row. They
 are ordered durable query messages and grow message history exactly like
 writes.
 
-Version 0.2 has cleanup indexes but no built-in pruning command. Budget message
-growth as:
+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
@@ -76,6 +76,10 @@ daily durable messages = daily actor writes + daily actor reads + daily callback
 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

data/docs/correctness.md

@@ -101,13 +101,46 @@ 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, observable
+  broadcasts, and the monotonic actor state revision;
 - 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.
+
+## Reactive components
+
+A successful fenced turn advances `instances.state_revision` to that message's
+per-actor sequence and inserts changed-observable broadcast rows in the same
+transaction. A rollback, retryable handler failure, or lost activation advances
+neither. Component HTML is not durable and is never placed on the shared actor
+stream.
+
+Each component token signs the actor identity, conventional component name,
+explicit dependencies, initial instance ID and revision, and same-origin
+refresh path. The signature detects modification but grants no access. Initial
+rendering invokes query authorization, Cable separately invokes subscription
+authorization, and the cookie-bearing refresh request invokes query
+authorization again for the component name and every dependency.
+
+The actor stream token separately signs the scalar observable targets rendered
+into its scope. A component dependency that has no scalar target carries only
+its name and revision over Cable, not its serialized value.
+
+Cable compares `(instance_id, state_revision)` pairs, coalesces dependencies
+changed by the same turn, and ignores an older pair after a newer one. A new
+invalidation replaces the whole Turbo Frame generation. A response owned by
+the detached older frame cannot overwrite the current frame. Reconnect
+compares the component's signed initial pair with the current instance row and
+requests the latest committed snapshot when stale.
 
 ## Synchronous invocation
 
@@ -119,6 +152,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

@@ -8,9 +8,15 @@ migrations load. No partial indexes are used.
 ### `instances`
 
 One row per `(actor_type, actor_id)`. Stores JSON state, state version,
-next-message sequence, activation owner/token/expiration/generation, pause
-state, and lifecycle timestamps. The owner/token pairing is constrained so one
-process row cannot make two concurrent activations appear identical.
+monotonic state revision, next-message sequence, activation
+owner/token/expiration/generation, pause state, and lifecycle timestamps. The
+owner/token pairing is constrained so one process row cannot make two
+concurrent activations appear identical.
+
+`state_revision` advances to the successful message sequence in the same
+fenced transaction as state and outboxes. Reactive components compare
+`(instance_id, state_revision)` so pruned message history cannot make revisions
+regress and destroy-and-recreate produces a new incarnation.
 
 Deleting an instance is the actor-incarnation boundary. Foreign keys cascade
 the delete through messages, ready and claimed memberships, reminders, effects,
@@ -24,6 +30,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
@@ -80,8 +91,10 @@ Status/availability/ID drives delivery; completion/ID drives cleanup.
 ### `broadcasts`
 
 Durable observable-change outbox. The unique message/observable key prevents
-duplicate rows for one actor turn. Claim and delivery indexes support retries
-and cleanup.
+duplicate rows for one actor turn. Rows contain the observable JSON value and
+message/instance references used to derive invalidation metadata, never
+personalized rendered HTML. Claim and delivery indexes support retries and
+cleanup.
 
 ### `dead_letters`
 

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:

data/docs/fit.md

@@ -65,11 +65,19 @@ Each application process that performs synchronous calls registers one caller
 process row. Actor state is rewritten as a JSON value on each successful
 mutation.
 
-There is no built-in retention command in 0.2. Completed message history grows
-until the host application implements a reviewed retention policy. See
+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:

data/docs/migrating-existing-state.md

@@ -101,6 +101,12 @@ 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:
@@ -119,7 +125,8 @@ A typical zero-downtime sequence is:
 
 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; query the durable result or use an idempotency key before retrying.
+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