solid_objects 0.2.1 → 0.4.0

data/docs/operations.md

@@ -34,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
 ```
@@ -56,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
@@ -126,49 +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. Every actor call creates a durable message-history row, including
-queries and attribute reads. Choose a retention period from measured call
-volume, storage budget, audit needs, and the longest promised synchronous-result
-lookup window.
+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:
 
-An application-owned pruning job can start from this conservative relation:
+`reference.snapshot` is the explicit exception: it performs an authorized
+current-state read without mailbox ordering or a message row.
 
 ```ruby
-cutoff = 30.days.ago
-
-prunable_messages = SolidObjects::Message
-  .where(completed_at: ...cutoff)
-  .where.not(id: SolidObjects::ReadyMessage.select(:message_id))
-  .where.not(id: SolidObjects::ClaimedMessage.select(:message_id))
-  .where.not(id: SolidObjects::DeadLetter.select(:message_id))
-  .where.not(
-    id: SolidObjects::DeadLetter
-      .where.not(retried_message_id: nil)
-      .select(:retried_message_id)
-  )
-  .where.not(
-    id: SolidObjects::Effect
-      .where.not(status: "completed")
-      .select(:message_id)
-  )
-  .where.not(
-    id: SolidObjects::Broadcast
-      .where.not(status: "delivered")
-      .select(:message_id)
-  )
-
-prunable_messages.in_batches(of: 1_000).delete_all
+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
 ```
 
-Deleting a message cascades to its completed effects, delivered broadcasts, and
-other message-owned records. Test the exact relation against a restored
-production snapshot before scheduling it. Keep source and retried messages for
-dead letters under investigation, and never prune pending, processing, ready, or
-claimed work. Choose a cutoff longer than every `sync` timeout because a caller
-whose result row disappears can no longer observe that result.
+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

data/docs/realtime.md

@@ -1,13 +1,15 @@
 # Realtime integration
 
-## Rendering
+## Scalars and components
 
 `solid_object` performs initial server rendering and emits one
 `turbo-cable-stream-source` for the actor:
 
 ```erb
-<%= solid_object ShoppingCartActor.ref(current_user.id) do |cart| %>
+<%= solid_object ShoppingCartActor.ref(current_user.id),
+  authorization_context: current_user do |cart| %>
   Items: <%= cart.items_count %>
+  <%= cart.component :summary, observes: %i[items checkout_status] %>
 <% end %>
 ```
 
@@ -15,9 +17,39 @@ Every observable gets a stable opaque DOM ID. Multiple values share the one
 actor subscription and Action Cable multiplexes actor subscriptions over the
 browser's physical WebSocket.
 
-`actor.component(:summary)` renders a host partial by convention at
-`actors/<actor_class>/_summary`. Initial component rendering is implemented;
-durable background component replacement is not yet implemented.
+Scalar observable calls such as `cart.items_count` render stable `<span>`
+targets. Their broadcast remains a direct escaped text replacement.
+
+A reactive component declares one or more explicit observable dependencies.
+`actor.component(:summary, observes: ...)` resolves the host partial by
+convention at `actors/<actor_class>/_summary` and wraps it in a stable Turbo
+Frame. Reactive components do not accept `partial:` because a client must
+never influence partial resolution. The older
+`actor.component(:summary, partial: "server/chosen/path")` form remains
+available for initial-only static rendering.
+
+The partial receives exactly two component locals:
+
+- `actor`, which exposes the declared observables as deeply frozen ordinary
+  Ruby values plus `actor_id` and `reference`; and
+- `authorization_context`, the context for this initial render or refresh.
+
+`actor.state` is unavailable in reactive components. Reading an observable not
+listed in `observes:` raises `UnknownComponentDependency`. This keeps
+invalidation correct and prevents a partial from silently depending on state
+that cannot wake it.
+
+```erb
+<ul>
+  <% actor.recent_messages.each do |message| %>
+    <li><%= message.fetch("body") %></li>
+  <% end %>
+</ul>
+```
+
+Arrays, hashes, loops, conditionals, nested markup, and host helper output are
+normal ERB. Escaping remains Action View's responsibility; Solid Objects never
+marks actor strings as HTML safe.
 
 ## Authorization
 
@@ -26,18 +58,69 @@ it does not grant access. `ActorChannel` verifies the token, resolves the actor
 through the registry, calls `authorize_subscription`, and streams only after
 approval.
 
-Initial observable method reads separately call `authorize_query`. Never
-authorize solely from actor ID, token possession, stream name, or DOM ID.
+Initial scalar and component reads call `authorize_query` with the context
+passed to `solid_object`. The refresh controller resolves a new request context
+through `component_authorization_context`, then calls `authorize_query` again
+for the component name and every declared dependency. The default resolver
+supplies the engine controller; applications commonly resolve it to
+`Current.user`:
+
+```ruby
+configuration.component_authorization_context = ->(controller:) { Current.user }
+```
+
+The three contexts are intentionally different:
+
+| Boundary | Authorization context |
+| --- | --- |
+| Initial Action View render | Explicit `authorization_context:` passed to `solid_object` |
+| Action Cable subscription | The authenticated Cable connection |
+| Component refresh | Value returned by `component_authorization_context` for the engine controller request |
+
+Do not substitute a signed token for any of them. Never authorize solely from
+actor ID, token possession, stream name, component name, or DOM ID.
 
 ## Broadcast durability
 
 The actor's fenced commit compares observables before and after the turn and
-inserts one broadcast row per changed value. A broadcast process later sends a
-Turbo replacement and records delivery. No direct broadcast occurs inside the
-actor transaction.
+inserts one broadcast row per changed value. The actor state, monotonic
+`state_revision`, message completion, and broadcast rows commit atomically. A
+rolled-back or fenced-out turn therefore cannot invalidate a component.
+
+A broadcast process later sends small invalidation metadata and records
+delivery. Its scalar Turbo replacement is transmitted only when that observable
+target was rendered and signed into the scope's stream token. Component-only
+dependencies therefore do not expose their serialized values over Cable. The
+runtime never stores or broadcasts personalized component HTML. Each
+authorized browser requests affected components through the engine endpoint
+with its normal cookies. Responses are `private, no-store`.
+
+Several changed dependencies from one message sequence produce one logical
+refresh for a component. An unrelated observable does not refresh it. If a
+newer invalidation arrives while a Turbo Frame request is in flight, the new
+frame replaces the old frame element; the detached older response has no
+current target.
 
 If Cable delivery is lost, reconnecting `ActorChannel` transmits replacements
-from current actor state. The durable state row remains source of truth.
+from current actor state. It compares the signed component revision with the
+latest `(instance_id, state_revision)` pair and refreshes stale components.
+The incarnation ID handles destroy-and-recreate; the state revision handles
+ordered commits within one incarnation. Out-of-order invalidations at or below
+the last transmitted pair are ignored. The durable state row remains source of
+truth.
+
+The component endpoint rejects a requested revision newer than the committed
+snapshot. This is a final server-side guard; browser safety primarily comes
+from monotonic channel filtering and replacing the entire Turbo Frame
+generation.
+
+## Cost model
+
+The durable row cost is unchanged: one broadcast row per changed observable,
+containing its JSON value and the message/instance references needed to derive
+invalidation metadata. No rendered document is stored. Each affected component
+adds one authorized GET and one partial render per non-coalesced state
+revision. Scalar observables remain the cheaper path for one text value.
 
 ## Deployment
 
@@ -48,4 +131,15 @@ require Redis.
 
 Changing or removing observable names during a rolling deploy can strand old
 broadcast rows or old DOM targets. Keep old names compatible until the outbox
-and old pages have drained.
+and old pages have drained. Keep component partial names and dependency
+observables compatible across a rolling deploy for the same reason.
+
+Reactive components require the engine mount because their signed refresh path
+is generated from that mount. Applications with more than one engine mount can
+set `component_path_resolver` to return the intended same-origin
+`components_path`.
+
+```ruby
+# config/routes.rb
+mount SolidObjects::Engine => "/solid_objects"
+```

data/docs/roadmap.md

@@ -15,10 +15,17 @@
 - Transactional effects with success/failure actor messages
 - Actor-to-actor asynchronous outbox delivery
 - One-shot and recurring reminders with `:latest` or `:all` catch-up
-- Durable observable broadcast outbox and authorized Action Cable refresh
+- Durable observable invalidations, scalar Turbo replacement, and authorized
+  request-time ERB component refresh
 - Reconciliation read APIs
 - Installation doctor, authorization reference, fit guide, and legacy-state
   migration cookbook
+- Handler Active Record write isolation, same-database commit actions, ambient
+  transaction rejection, adapter lock/query deadlines, structured sync timeout
+  diagnostics, and result recovery
+- Bounded message/process pruning, actor-type opt-in instance expiration,
+  graceful caller shutdown, committed state snapshots, and an opt-in Minitest
+  helper
 - SQLite, PostgreSQL, and MySQL integration suites
 - Inline RBS generation/validation, Steep, Standard Ruby, Solid Queue's exact
   RuboCop policy, and a warning-free Brakeman scan
@@ -29,8 +36,9 @@
   role or run periodic maintenance automatically.
 - Wake-up strategy: in-process signaling plus durable polling and injection are
   implemented; PostgreSQL `LISTEN/NOTIFY` and optional Redis adapters are not.
-- Realtime: observable replacement and reconnect refresh are implemented;
-  durable component replacement and Turbo append actions are not.
+- Realtime: scalar and dependency-driven ERB component replacement,
+  personalized refresh authorization, revision fencing, coalescing, and
+  reconnect convergence are implemented; Turbo append actions are not.
 - Backpressure: mailbox/payload/state/result caps and fair yields exist;
   distributed per-actor rate limits and global admission control do not.
 - Administration: actor and dead-letter views plus policy hooks exist; richer
@@ -43,11 +51,10 @@
 1. Add automatic supervisor role replacement and periodic dead-process cleanup.
 2. Add PostgreSQL notification and optional Redis wake-up adapters with latency
    benchmarks and polling-race tests.
-3. Add bounded retention/pruning commands and result lookup by request ID.
-4. Add deadlock, lock-timeout, and SQLite-busy retry classification.
+3. Add result lookup by request ID and broader deadlock retry classification.
+4. Add scheduled retention and stale-process maintenance.
 5. Add database/server-version checks and MySQL InnoDB verification at boot.
-6. Add component broadcast rendering, Turbo append intents, and reconnect tests
-   in a full browser.
+6. Add Turbo append intents and expand reconnect coverage in a full browser.
 7. Add distributed rate limits, global admission hooks, and cache-capacity
    eviction.
 8. Expand security scanning and run compatibility CI across supported Rails and

data/docs/security.md

@@ -13,9 +13,11 @@ risk for every hook and includes a tenant-aware policy example.
 Method-style reference calls do not bypass these hooks. Public instance methods
 declared on an actor are part of its remotely addressable message surface and
 delegate to the authorized synchronous invocation path. Keep implementation
-helpers private or protected. Query and attribute methods use the separate
-query authorization policy. Explicit `async` message delivery uses the same
-message authorization policy as direct calls.
+helpers private or protected. Query, attribute, observable, and committed
+`snapshot` reads use the separate query authorization policy. Explicit `async`
+message delivery uses the same message authorization policy as direct calls.
+Recovering a timed-out result through `MessageReference#wait` reauthorizes the
+stored operation.
 `reference.destroy` delegates to `authorize_destroy` before checking whether
 the actor exists, so denial does not reveal actor existence.
 
@@ -54,10 +56,30 @@ host authentication and audit their use.
 Instrumentation excludes arguments, state, results, and effect payloads by
 default. Review custom logging and effect handlers for accidental disclosure.
 
+## Handler database access
+
+Handlers, observables, lifecycle hooks, and state migrations run with Active
+Record writes prevented. They may query application records, but a direct
+write becomes
+`SolidObjects::ApplicationWriteForbidden` and dead-letters without retry.
+This prevents application data from escaping a later actor failure or stale
+fence.
+
+Registered commit actions are privileged application code. They execute inside
+the fenced actor transaction and receive stored JSON arguments, so register
+only fixed names, validate record ownership again, and keep the block to
+bounded database work. Never perform network I/O or authorize solely from a
+record ID in commit-action arguments.
+
 Actor destruction is not an administrative shortcut. Authorize tenancy and
 ownership explicitly in `authorize_destroy`; knowledge of an actor ID is never
 permission to delete its state or queued work.
 
+Instance pruning is likewise destructive and requires administration
+authorization. Only opt-in actor types are eligible, and live work is
+preserved, but the host application must decide whether dormant state and
+completed history may expire.
+
 ## Denial of service
 
 Configure mailbox and byte limits. Add host rate limiting before public actor

data/docs/state-migrations.md

@@ -15,6 +15,8 @@ end
 
 Migration runs in memory during activation. The new version is persisted only
 with the next successful fenced message commit.
+Migration blocks may read application records but cannot write them directly;
+the same Active Record write guard used for handlers applies before activation.
 
 ## Runtime rules
 

data/examples/application/README.md

@@ -10,7 +10,8 @@ key. The chat actor also gives every submitted chat message a caller-generated
 message ID and checks that ID in durable actor state, because actor handlers may
 be redelivered.
 
-The views demonstrate initial `solid_object` rendering and live observable
-replacement. Live cart-summary replacement and chat-message append are
-deliberately not shown as working behavior because component broadcasts and
-Turbo append intents remain roadmap items.
+The views demonstrate scalar observable replacement and a live chat-message
+ERB component. The chat component receives `recent_messages` as an ordinary
+Ruby array, rerenders its `<ol>` after committed changes, and refreshes through
+the authenticated host request context. Turbo append intents remain roadmap
+work.

data/examples/application/app/views/actors/chat_room_actor/_messages.html.erb

@@ -1,5 +1,5 @@
 <ol>
-  <% actor.state.recent_messages.each do |message| %>
+  <% actor.recent_messages.each do |message| %>
     <li id="message_<%= message.fetch("id") %>">
       <strong><%= message.fetch("user_id") %></strong>
       <%= message.fetch("body") %>

data/examples/application/app/views/chat_rooms/show.html.erb

@@ -1,8 +1,8 @@
-<%= solid_object @room do |room| %>
+<%= solid_object @room, authorization_context: current_user do |room| %>
   <p>
     Present:
     <%= room.presence %>
   </p>
 
-  <%= room.component :messages %>
+  <%= room.component :messages, observes: :recent_messages %>
 <% end %>

data/examples/application/config/initializers/solid_objects.rb

@@ -2,16 +2,22 @@
 
 SolidObjects.configure do |configuration|
   configuration.authorize_message = lambda do |actor_type:, actor_id:, authorization_context:, **|
-    next false unless authorization_context.respond_to?(:current_user)
+    user = if authorization_context.respond_to?(:current_user)
+      authorization_context.current_user
+    else
+      authorization_context
+    end
+    next false unless user
 
     if actor_type == ShoppingCartActor.actor_type
-      authorization_context.current_user.id.to_s == actor_id
+      user.id.to_s == actor_id
     else
-      ChatRoomPolicy.new(authorization_context.current_user).access?(actor_id)
+      ChatRoomPolicy.new(user).access?(actor_id)
     end
   end
   configuration.authorize_query = configuration.authorize_message
   configuration.authorize_subscription = configuration.authorize_message
+  configuration.component_authorization_context = ->(controller:) { Current.user }
 end
 
 SolidObjects.register_effect(:charge_payment) do |arguments, context|

data/lib/generators/solid_objects/templates/solid_objects.rb

@@ -5,14 +5,35 @@ SolidObjects.configure do |configuration|
   configuration.effect_worker_count = 1
   configuration.broadcast_worker_count = 1
   configuration.reminder_scheduler_count = 1
+  configuration.message_retention = 30.days
+  configuration.process_retention = 7.days
+  configuration.prune_batch_size = 1_000
+
+  # Override message retention only for actor types with different audit or
+  # privacy requirements:
+  #
+  # configuration.message_retention_by_actor_type = {
+  #   "AuditActor" => 365.days,
+  #   "EphemeralCounter" => 1.day
+  # }
+  #
+  # Actor instances never expire unless their type is listed here. Expiration
+  # removes idle state and completed history, so start with the preview command:
+  #
+  # configuration.instance_retention_by_actor_type = {
+  #   "EphemeralCounter" => 30.days
+  # }
+  #
+  #   bundle exec solid_objects prune_instances
 
   # Every policy denies by default, so a fresh installation is intentionally
   # inert. Replace these policies before invoking actors.
   #
   # Message and query policies gate direct calls, sync, async, and state reads.
   # Destroy removes an actor and all of its durable work. Subscription gates
-  # Action Cable streams. Administration gates engine pages and operational
-  # commands. Keep the last three denied until their callers are authenticated.
+  # Action Cable streams. Administration gates engine pages, pruning, and
+  # operational commands. Keep the last three denied until their callers are
+  # authenticated.
   #
   # Prefer policies that bind actor_type and actor_id to a trusted
   # authorization_context. See:
@@ -27,4 +48,14 @@ SolidObjects.configure do |configuration|
   configuration.authorize_destroy = ->(**) { false }
   configuration.authorize_subscription = ->(**) { false }
   configuration.authorize_administration = ->(**) { false }
+
+  # Configure component_authorization_context to return the authenticated
+  # principal used for reactive component refreshes.
+
+  # On hosts where shell access is already an authenticated administrative
+  # boundary, this enables only gem commands that pass the CLI context:
+  #
+  # configuration.authorize_administration = lambda do |authorization_context:, **|
+  #   authorization_context.is_a?(Hash) && authorization_context[:source] == "cli"
+  # end
 end

data/lib/solid_objects/activation.rb

@@ -91,9 +91,25 @@ module SolidObjects
     # @rbs () -> void
     def deactivate
       actor.deactivate
-      lease.release
-    rescue LostActivation
-      nil
+    rescue => error
+      SolidObjects.instrument(
+        :"activation.deactivation_failed",
+        instance_id: lease.instance_id,
+        actor_type: actor.class.actor_type,
+        actor_id: actor.actor_id,
+        owner_id: lease.owner_id,
+        generation: lease.generation,
+        error_class: error.class.name,
+        error_message: error.message
+      )
+      SolidObjects.configuration.logger.error(
+        "SolidObjects activation deactivation failed " \
+          "actor_type=#{actor.class.actor_type.inspect} " \
+          "actor_id=#{actor.actor_id.inspect} " \
+          "error_class=#{error.class.name}"
+      )
+    ensure
+      release_lease
     end
 
     private
@@ -129,13 +145,26 @@ module SolidObjects
 
     # @rbs (Instance) -> Actor
     def build_actor(instance)
-      state_data = actor_class.definition.migrate_state(instance.state_version, instance.state)
+      state_data = ApplicationWriteGuard.call(
+        actor_type: instance.actor_type,
+        actor_id: instance.actor_id,
+        operation: "state_migration"
+      ) do
+        actor_class.definition.migrate_state(instance.state_version, instance.state)
+      end
       actor_class.new(
         actor_id: instance.actor_id,
         state: State.new(actor_class.definition.state_definition, state_data)
       )
     end
 
+    # @rbs () -> void
+    def release_lease
+      lease.release
+    rescue LostActivation
+      nil
+    end
+
     # @rbs () -> Message?
     def claim_next_message
       lease.fenced_transaction do |instance|