solid_objects 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 654720ae19caa970f403b5cded61287e1f6a9eb9d731ff90fd9f4f103d55fa53
-  data.tar.gz: 256712423dd88685643a0345de44eb774efbca12188c78c9e89571ef884b59fc
+  metadata.gz: 48689af6e9b4f08415ddfd549a99d4e7e667e67db5aa4e92bc0052a6d97f51af
+  data.tar.gz: 82dc95dc346daf7260356996bfadc99c9c8dd713f2c0fa8c5d8f5efe7859021a
 SHA512:
-  metadata.gz: f1e43da5f13c33558bdb187b52c55b55093786d3ec8af9f49d4ffc123ade274d2f5483dd8975c6a638152dfc9ae1c4cf416d8b1ea94cb1383ac30b33ef7548aa
-  data.tar.gz: f8cb10850b5b3748450ffaf741417866ed360437657c5d21836312018f0d6b27109cd69c4035f770f6cf643227ab086ae7eedc1b0a14245103cfe517a008f49c
+  metadata.gz: d3a4ce2860cca8656919193b2a9bb6b2c2367552653af106db5fd065bd2bf3c7339a543c5b1bc1fdf1bb7d322e88639a6f20cdba2b5cf551b406e629e6d31598
+  data.tar.gz: '086652b090e80b0c6830b269e8857ef6de1944b2c2ab145340eeb4a8ba97a26875b9a612c5105ae46bff7362477fe20c3abde837aa4b87d27f5fb91bf19e316e'

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # 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

data/README.md

@@ -24,6 +24,7 @@ end
 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)
@@ -41,13 +42,21 @@ The invocation model is the first adoption decision:
 | --- | --- | --- |
 | `counter.increment(amount: 5)` | Committed handler result | No |
 | `counter.sync(:increment, amount: 5)` | Committed handler result | No |
-| `counter.value` | Deeply frozen state snapshot | 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).
@@ -56,8 +65,8 @@ 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
@@ -69,6 +78,7 @@ but the project does not yet claim production readiness. See
 - [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)
@@ -194,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
@@ -273,6 +283,7 @@ the runtime when the feature introduces asynchronous delivery or outboxes:
 | --- | --- |
 | 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 |
@@ -346,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
@@ -451,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
@@ -492,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
@@ -555,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:
@@ -631,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 |
@@ -664,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
@@ -814,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
@@ -831,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:
@@ -844,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/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.

data/docs/authorization.md

@@ -10,12 +10,14 @@ 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, 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, 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.
 
 ## A tenant-aware policy
@@ -80,6 +82,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,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:

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