solid_objects 0.2.0 → 0.3.0

data/docs/roadmap.md

@@ -17,6 +17,14 @@
 - One-shot and recurring reminders with `:latest` or `:all` catch-up
 - Durable observable broadcast outbox and authorized Action Cable 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
@@ -41,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.
@@ -50,7 +58,8 @@
    eviction.
 8. Expand security scanning and run compatibility CI across supported Rails and
    Ruby versions.
-9. Benchmark all workloads under documented hardware/database settings.
+9. Benchmark all workloads under documented hardware/database settings and
+   publish adapter-specific adoption measurements.
 
 No production-ready claim should be made until these hardening milestones have
 operational soak evidence.

data/docs/security.md

@@ -7,12 +7,17 @@ destroying actors, subscribing to actor streams, and administration. The host
 application supplies the authenticated request or connection as
 `authorization_context`. All five hooks deny by default.
 
+The [authorization reference](authorization.md) lists the caller context and
+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.
 
@@ -51,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
 
@@ -44,3 +46,7 @@ A safe destructive rollout normally uses:
 
 Never update actor JSON in a bulk SQL migration. Use actor messages so fencing,
 ordering, observables, and outboxes remain intact.
+
+This guide covers evolution after state belongs to Solid Objects. For moving
+existing Redis, key-value, or relational state into actors without downtime,
+use the [legacy-state migration cookbook](migrating-existing-state.md).

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

@@ -5,9 +5,54 @@ 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, 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:
+  # https://github.com/cardmagic/solid_objects/blob/main/docs/authorization.md
+  # and run:
+  #
+  #   bin/rails solid_objects:doctor
+  #
+  # after configuring the application.
   configuration.authorize_message = ->(**) { false }
   configuration.authorize_query = ->(**) { false }
   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" }
       )

data/lib/solid_objects/client.rb

@@ -50,16 +50,57 @@ module SolidObjects
         arguments,
         authorization_context:
       )
-      message_reference = mailbox.enqueue(
+      reject_sync_inside_transaction!(reference, message_name)
+      SyncDeadline.with(timeout:) do
+        message_reference = enqueue_sync(
+          reference,
+          message_name,
+          arguments,
+          idempotency_key:,
+          timeout:
+        )
+        SynchronousInvocation.new.call(message_reference, timeout:)
+      end
+    end
+
+    # @rbs (MessageReference, timeout: Numeric, ?authorization_context: untyped) -> untyped
+    def wait(message_reference, timeout:, authorization_context: nil)
+      message = Message.find(message_reference.id)
+      validate_message_reference!(message_reference, message)
+      reference = Reference.new(
+        actor_type: message.actor_type,
+        actor_id: message.actor_id
+      )
+      actor_class = SolidObjects.registry.fetch(reference.actor_type)
+      query = actor_class.definition.queries.key?(message.message_name.to_sym)
+      actor_message = actor_class.definition.messages.key?(message.message_name.to_sym)
+      unless query || actor_message
+        raise UnknownMessage, "unknown message #{message.message_name.inspect}"
+      end
+      authorize!(
+        query ? SolidObjects.configuration.authorize_query : SolidObjects.configuration.authorize_message,
         reference,
-        message_name,
-        arguments,
-        kind: "sync",
-        idempotency_key:
+        message.message_name,
+        message.arguments,
+        authorization_context:
       )
+      reject_sync_inside_transaction!(reference, message.message_name)
       SynchronousInvocation.new.call(message_reference, timeout:)
     end
 
+    # @rbs (Reference, ?authorization_context: untyped) -> StateSnapshot
+    def snapshot(reference, authorization_context: nil)
+      SolidObjects.registry.fetch(reference.actor_type)
+      authorize!(
+        SolidObjects.configuration.authorize_query,
+        reference,
+        "__snapshot__",
+        {},
+        authorization_context:
+      )
+      StateSnapshot.new(reference)
+    end
+
     # @rbs (Reference, ?authorization_context: untyped) -> bool
     def destroy(reference, authorization_context: nil)
       raise ActorCallCycle, "actors cannot synchronously destroy another actor" if Context.current_actor
@@ -93,6 +134,58 @@ module SolidObjects
 
     attr_reader :mailbox
 
+    # @rbs (Reference, Symbol | String, Hash[Symbol | String, untyped], idempotency_key: String?, timeout: Numeric) -> MessageReference
+    def enqueue_sync(reference, message_name, arguments, idempotency_key:, timeout:)
+      mailbox.enqueue(
+        reference,
+        message_name,
+        arguments,
+        kind: "sync",
+        idempotency_key:
+      )
+    rescue DatabaseDeadlineExceeded
+      SolidObjects.instrument(
+        :"sync.enqueue_timeout",
+        actor_type: reference.actor_type,
+        actor_id: reference.actor_id,
+        message_name: message_name.to_s
+      )
+      raise SyncEnqueueTimeout.new(
+        timeout:,
+        actor_type: reference.actor_type,
+        actor_id: reference.actor_id,
+        message_name: message_name.to_s
+      )
+    end
+
+    # @rbs (MessageReference, Message) -> void
+    def validate_message_reference!(message_reference, message)
+      valid = message_reference.request_id == message.request_id &&
+        message_reference.actor_type == message.actor_type &&
+        message_reference.actor_id == message.actor_id &&
+        message_reference.sequence == message.sequence
+      return if valid
+
+      raise ActorDestroyed, "message reference no longer identifies this invocation"
+    end
+
+    # @rbs (Reference, Symbol | String) -> void
+    def reject_sync_inside_transaction!(reference, message_name)
+      return unless SolidObjects::Record.connection.transaction_open?
+
+      SolidObjects.instrument(
+        :"sync.transaction_rejected",
+        actor_type: reference.actor_type,
+        actor_id: reference.actor_id,
+        message_name: message_name.to_s
+      )
+      raise SyncInsideTransaction.new(
+        actor_type: reference.actor_type,
+        actor_id: reference.actor_id,
+        message_name: message_name.to_s
+      )
+    end
+
     # @rbs (Proc, Reference, Symbol | String, Hash[Symbol | String, untyped], authorization_context: untyped) -> void
     def authorize!(hook, reference, message_name, arguments, authorization_context:)
       authorized = hook.call(