solid_objects 0.2.1 → 0.3.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/roadmap.md

@@ -19,6 +19,12 @@
 - 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
@@ -43,8 +49,8 @@
 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.

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/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,11 @@ SolidObjects.configure do |configuration|
   configuration.authorize_destroy = ->(**) { false }
   configuration.authorize_subscription = ->(**) { false }
   configuration.authorize_administration = ->(**) { false }
+
+  # 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|

data/lib/solid_objects/actor.rb

@@ -3,6 +3,7 @@
 module SolidObjects
   class Actor
     EffectIntent = Data.define(:name, :arguments, :success_message_name, :failure_message_name)
+    CommitActionIntent = Data.define(:name, :arguments)
     ReminderIntent = Data.define(:name, :at, :arguments, :interval_seconds, :missed_policy)
     OutboundMessageIntent = Data.define(:actor_type, :actor_id, :message_name, :arguments, :available_at, :idempotency_key)
 
@@ -131,6 +132,7 @@ module SolidObjects
     # @rbs @actor_id: String
     # @rbs @state: State
     # @rbs @effect_intents: Array[EffectIntent]
+    # @rbs @commit_action_intents: Array[CommitActionIntent]
     # @rbs @reminder_intents: Array[ReminderIntent]
     # @rbs @outbound_message_intents: Array[OutboundMessageIntent]
 
@@ -141,6 +143,7 @@ module SolidObjects
       @actor_id = actor_id
       @state = state
       @effect_intents = []
+      @commit_action_intents = []
       @reminder_intents = []
       @outbound_message_intents = []
     end
@@ -175,6 +178,17 @@ module SolidObjects
       nil
     end
 
+    # @rbs (Symbol | String, **untyped) -> nil
+    def commit_action(name, **arguments)
+      CommitActionIntent.new(
+        name: name.to_s,
+        arguments: Serialization.dump(arguments)
+      ).tap do |intent|
+        commit_action_intents << intent
+      end
+      nil
+    end
+
     # @rbs (Symbol | String, at: Time, ?every: Numeric?, ?missed: Symbol | String, arguments: Hash[Symbol | String, untyped]) -> nil
     def schedule(name, at:, every: nil, missed: :latest, arguments: {})
       interval_seconds = every&.to_f
@@ -210,24 +224,32 @@ module SolidObjects
         self.class.definition.queries[message_name.to_sym]
       raise UnknownMessage, "unknown message #{message_name.inspect} for #{self.class.actor_type}" unless handler
 
-      instance_exec(**keyword_arguments(arguments), &handler.block)
+      guard_application_writes(message_name.to_s) do
+        instance_exec(**keyword_arguments(arguments), &handler.block)
+      end
     end
 
     # @rbs () -> Hash[String, untyped]
     def observable_values
-      self.class.definition.observables.each_with_object({}) do |(name, handler), values|
-        values[name.to_s] = Serialization.dump(instance_exec(&handler.block))
+      guard_application_writes("observables") do
+        self.class.definition.observables.each_with_object({}) do |(name, handler), values|
+          values[name.to_s] = Serialization.dump(instance_exec(&handler.block))
+        end
       end
     end
 
     # @rbs () -> void
     def activate
-      self.class.definition.activation_hooks.each { |hook| instance_exec(&hook) }
+      guard_application_writes("on_activate") do
+        self.class.definition.activation_hooks.each { |hook| instance_exec(&hook) }
+      end
     end
 
     # @rbs () -> void
     def deactivate
-      self.class.definition.deactivation_hooks.each { |hook| instance_exec(&hook) }
+      guard_application_writes("on_deactivate") do
+        self.class.definition.deactivation_hooks.each { |hook| instance_exec(&hook) }
+      end
     end
 
     # @rbs (Reference, Symbol | String, Hash[Symbol | String, untyped], ?available_at: Time?, idempotency_key: String?) -> OutboundMessageIntent
@@ -247,6 +269,11 @@ module SolidObjects
       effect_intents.shift(effect_intents.length)
     end
 
+    # @rbs () -> Array[CommitActionIntent]
+    def drain_commit_action_intents
+      commit_action_intents.shift(commit_action_intents.length)
+    end
+
     # @rbs () -> Array[ReminderIntent]
     def drain_reminder_intents
       reminder_intents.shift(reminder_intents.length)
@@ -260,13 +287,27 @@ module SolidObjects
     # @rbs () -> void
     def discard_intents
       effect_intents.clear
+      commit_action_intents.clear
       reminder_intents.clear
       outbound_message_intents.clear
     end
 
     private
 
-    attr_reader :effect_intents, :reminder_intents, :outbound_message_intents
+    attr_reader :effect_intents,
+      :commit_action_intents,
+      :reminder_intents,
+      :outbound_message_intents
+
+    # @rbs (String) { () -> untyped } -> untyped
+    def guard_application_writes(operation, &block)
+      ApplicationWriteGuard.call(
+        actor_type: self.class.actor_type,
+        actor_id:,
+        operation:,
+        &block
+      )
+    end
 
     # @rbs (Hash[String, untyped]) -> Hash[Symbol, untyped]
     def keyword_arguments(arguments)

data/lib/solid_objects/actor_definition.rb

@@ -136,6 +136,8 @@ module SolidObjects
       migrated
     rescue StateMigrationError
       raise
+    rescue ActiveRecord::ReadOnlyError
+      raise
     rescue => error
       raise StateMigrationError, "state migration failed: #{error.message}"
     end

data/lib/solid_objects/actor_snapshot.rb

@@ -29,10 +29,16 @@ module SolidObjects
         actor_id: reference.actor_id
       )
       state_version = instance&.state_version || actor_class.state_version
-      state_data = actor_class.definition.migrate_state(
-        state_version,
-        instance&.state || {}
-      )
+      state_data = ApplicationWriteGuard.call(
+        actor_type: reference.actor_type,
+        actor_id: reference.actor_id,
+        operation: "state_migration"
+      ) do
+        actor_class.definition.migrate_state(
+          state_version,
+          instance&.state || {}
+        )
+      end
       actor_class.new(
         actor_id: reference.actor_id,
         state: State.new(actor_class.definition.state_definition, state_data)

data/lib/solid_objects/application_write_guard.rb

@@ -0,0 +1,24 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  class ApplicationWriteGuard
+    class << self
+      # @rbs (actor_type: String, actor_id: String, operation: String) { () -> untyped } -> untyped
+      def call(actor_type:, actor_id:, operation:)
+        ActiveRecord::Base.while_preventing_writes { yield }
+      rescue ActiveRecord::ReadOnlyError
+        SolidObjects.instrument(
+          :"actor_code.write_forbidden",
+          actor_type:,
+          actor_id:,
+          operation:
+        )
+        raise ApplicationWriteForbidden.new(
+          actor_type:,
+          actor_id:,
+          message_name: operation
+        )
+      end
+    end
+  end
+end

data/lib/solid_objects/caller_process.rb

@@ -5,12 +5,14 @@ module SolidObjects
     # @rbs @mutex: Thread::Mutex
     # @rbs @process_id: Integer?
     # @rbs @registry: ProcessRegistry?
+    # @rbs @shutdown_hook_installed: bool
 
     # @rbs () -> void
     def initialize
       @mutex = Thread::Mutex.new
       @process_id = nil
       @registry = nil
+      @shutdown_hook_installed = false
     end
 
     # @rbs () -> ProcessRegistry
@@ -18,11 +20,22 @@ module SolidObjects
       mutex.synchronize do
         reset_after_fork
         register unless reusable_registry?
+        install_shutdown_hook
         registry.heartbeat
         registry
       end
     end
 
+    # @rbs () -> bool
+    def stop
+      mutex.synchronize do
+        return false unless @process_id == ::Process.pid
+        return false unless registry&.process_record
+
+        registry.stop.tap { @registry = nil }
+      end
+    end
+
     private
 
     attr_reader :mutex, :registry
@@ -53,5 +66,20 @@ module SolidObjects
       )
       registry
     end
+
+    # @rbs () -> void
+    def install_shutdown_hook
+      return if @shutdown_hook_installed
+
+      @shutdown_hook_installed = true
+      at_exit { stop_after_exit }
+    end
+
+    # @rbs () -> bool
+    def stop_after_exit
+      stop
+    rescue
+      false
+    end
   end
 end

data/lib/solid_objects/cli.rb

@@ -34,7 +34,7 @@ module SolidObjects
     # @rbs () -> void
     def status
       boot_application
-      authorize_administration!(:status)
+      authorize_administration!(:status, resource: "processes")
       rows = SolidObjects::Process.order(:kind, :started_at).map do |process_record|
         {
           id: process_record.id,
@@ -54,10 +54,49 @@ module SolidObjects
     # @rbs () -> void
     def cleanup
       boot_application
-      authorize_administration!(:cleanup)
+      authorize_administration!(:cleanup, resource: "processes")
       puts JSON.generate(cleaned_processes: ProcessRegistry.cleanup_dead)
     end
 
+    desc "prune_messages", "Preview or delete expired terminal message history"
+    option :environment, type: :string, aliases: "-e"
+    option :execute, type: :boolean, default: false
+
+    # @rbs () -> void
+    def prune_messages
+      boot_application
+      authorize_administration!(:prune, resource: "messages")
+      pruner = MessagePruner.new
+      count = options[:execute] ? pruner.prune : pruner.preview
+      puts JSON.generate(mode: options[:execute] ? "execute" : "preview", messages: count)
+    end
+
+    desc "prune_instances", "Preview or delete expired idle actor instances"
+    option :environment, type: :string, aliases: "-e"
+    option :execute, type: :boolean, default: false
+
+    # @rbs () -> void
+    def prune_instances
+      boot_application
+      authorize_administration!(:prune, resource: "instances")
+      pruner = InstancePruner.new
+      count = options[:execute] ? pruner.prune : pruner.preview
+      puts JSON.generate(mode: options[:execute] ? "execute" : "preview", instances: count)
+    end
+
+    desc "prune_processes", "Preview or delete expired stopped process records"
+    option :environment, type: :string, aliases: "-e"
+    option :execute, type: :boolean, default: false
+
+    # @rbs () -> void
+    def prune_processes
+      boot_application
+      authorize_administration!(:prune, resource: "processes")
+      pruner = ProcessPruner.new
+      count = options[:execute] ? pruner.prune : pruner.preview
+      puts JSON.generate(mode: options[:execute] ? "execute" : "preview", processes: count)
+    end
+
     desc "dead_letters", "Print dead actor messages"
     option :environment, type: :string, aliases: "-e"
 
@@ -102,11 +141,11 @@ module SolidObjects
       value ? Integer(value) : default
     end
 
-    # @rbs (Symbol) -> void
-    def authorize_administration!(action)
+    # @rbs (Symbol, resource: String) -> void
+    def authorize_administration!(action, resource:)
       authorized = SolidObjects.configuration.authorize_administration.call(
         action:,
-        resource: "processes",
+        resource:,
         resource_id: nil,
         authorization_context: { source: "cli" }
       )