solid_objects 0.10.2 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1cd348d089d12af0c4ea20a5f163d58b69f4796e7741ed12038301139396baae
-  data.tar.gz: e31ad3836b5782ee13f3669eef3645114498e7133dd5f8c561105310f4452867
+  metadata.gz: 530d40a11cbf715cc3657191124d336798d4e8efdccb129d8ee0431400ec36ff
+  data.tar.gz: 39abe950312fa41ab57aa55e7e01a088a01eb63dcfd535e0ada712ae75c03b01
 SHA512:
-  metadata.gz: 470ca38a3faacd28a05a8f3cd020a353a1a20a9717aad29ec7c0f6cb9be6efbb6e44ef96abcc5a12c2b151b112cdbda47df73da361a94a26ff275bb0dd7d966b
-  data.tar.gz: 874fa30b34175212a24ecdc115e4fd187c40f46c0e55ff62def214f5b350a54997b738f37a86991a9c032f7e1b7ec017613aa0cebaa6378c90aa0c02d6457fb5
+  metadata.gz: edd288ba3cc57f8ac7c241eda9e3e320385f26071a5dc1e11e3676af1106dc1ddadddfa520ff08f4ce61a0b2f73c23d1a2418199c8f6f98ebe85fe2b51b07426
+  data.tar.gz: 38e5561275048f00dcbd5e363b0d3da6a00242348094776c63da44df7e2ca694292e7bc0546d44ac5da7a8883eb70d3e237d7495c888d6d3e2dd9d286d1754f0

data/CHANGELOG.md

@@ -1,5 +1,58 @@
 # Changelog
 
+## 0.11.0 - 2026-08-11
+
+- Add `SolidObjects.configuration.register_component`. An extension gem can now
+  register a long running component, and the supervisor runs it beside the
+  workers, the effect executors, the broadcast executors, and the reminder
+  schedulers. The component joins the same supervision, replacement, and
+  shutdown timeout. Without it, an extension has to ask an operator to run and
+  monitor a second process for work that belongs to the same runtime. A
+  registered component must answer `run`, `request_shutdown`, `stopped?`, and
+  `stop`. The supervisor checks that contract when it builds the component and
+  raises `ArgumentError` when a method is missing. Registration never calls the
+  block, so a component may need a database connection that the application
+  does not have while it boots.
+
+- Stop the components already built when a later one fails. The supervisor
+  builds its components one after another, so a factory that raised, or a
+  component that failed the contract check, left the earlier ones constructed
+  and unreachable while they still held whatever their constructors took. Each
+  one now receives `stop`, and a failure inside that cleanup never replaces the
+  failure that caused it.
+
+- Replace a crashed component through the builder that made it. The supervisor
+  called `component.class.new`, which discards every constructor argument, so a
+  component built with arguments returned with its defaults after a crash. Each
+  component now keeps its builder. The built in components take no constructor
+  arguments, so their behavior does not change.
+
+## 0.10.3 - 2026-08-11
+
+- Delete every actor-owned row in `SolidObjects::TestHelper#reset_actors!`. It
+  deleted actor instances and processes and left the other seven tables to the
+  database cascade. That cascade is not enforced everywhere: SQLite has to be
+  asked for foreign keys, MySQL has to be on InnoDB, and a host application may
+  have stripped the constraints out of the copied migration. Where it does not
+  fire, messages, ready and claimed mailbox rows, reminders, effects,
+  broadcasts, and dead letters all survived into the next test with an
+  `instance_id` pointing at nothing, so a test reading any of them saw another
+  test's rows and failed depending on order. Reported as reminders leaking,
+  which is where it surfaces first because reminders outlive the message that
+  created them.
+- Document that a reminder is one named alarm per actor. `schedule` is keyed by
+  actor and reminder name, so scheduling a name that is already armed moves
+  that alarm rather than adding a second. The behaviour is deliberate and
+  matches Orleans and Durable Objects, but it was stated nowhere: an actor that
+  armed one reminder per queued item silently kept only the last, and the
+  earlier wake-ups never happened. The reminders guide now states the
+  uniqueness key and shows the one-alarm-many-items pattern to use instead.
+- Add `solid_objects.reminder.replaced`, reported when a `schedule` call moves
+  an alarm already armed under the same name to a different time. It carries
+  the actor identity, reminder name, previous run time, and next run time, and
+  no arguments. Rescheduling to the same time reports nothing. The replacement
+  was previously indistinguishable from a first schedule.
+
 ## 0.10.2 - 2026-08-10
 
 - Load the mailbox when the gem is required. `SolidObjects::Mailbox` was

data/README.md

@@ -458,6 +458,39 @@ Deploy and monitor that process before enabling any feature marked as requiring
 a runtime role. A missing worker never makes a durable `async` message
 disappear, but it leaves the message pending indefinitely.
 
+### Running an extension in the same process
+
+An extension gem can register its own long-running component, and
+`solid_objects start` runs it beside the built-in roles. The component joins the
+same supervision, the same replacement after a crash, and the same shutdown
+timeout, so an operator deploys and monitors one process instead of two:
+
+```ruby
+SolidObjects.configure do |configuration|
+  configuration.register_component { MyExtension::FlushEngine.new }
+end
+```
+
+Pass `count:` for more than one instance. The block runs once for each instance,
+and again when the supervisor replaces a crashed one, so no two components share
+an object.
+
+A registered component answers four methods, the contract the built-in roles
+already keep:
+
+| Method | Purpose |
+| --- | --- |
+| `run` | Runs the loop. The supervisor calls it in its own thread |
+| `request_shutdown` | Asks the loop to finish. It must make `run` return |
+| `stopped?` | Reports whether the component already finished |
+| `stop` | Forces cleanup when the shutdown timeout expires first |
+
+The supervisor checks that contract when it builds the component, and a missing
+method raises `ArgumentError` as the supervisor starts, rather than hanging a
+shutdown later. Registration itself never calls the block, so a component is
+free to need a database connection that the application does not have while it
+boots.
+
 ## Defining an actor
 
 The Durable Object class becomes an ordinary Ruby class:
@@ -805,6 +838,62 @@ end
 Use `missed: :latest` to coalesce missed occurrences or `missed: :all` to
 enqueue each one.
 
+### A reminder is one named alarm per actor
+
+The uniqueness key is `(actor, reminder name)`. Scheduling a name that is
+already armed **moves the existing alarm** rather than adding a second one. The
+database enforces this with a unique index on `(instance_id, name)`.
+
+This is the same model as Orleans reminders and Durable Objects alarms, and it
+is what makes a reminder safe to re-arm from a handler that may run more than
+once. It also means this is a data-loss bug:
+
+```ruby
+# Wrong. Every entry overwrites the previous entry's alarm.
+def add(entry:)
+  self.entries = entries + [ entry ]
+  schedule :deliver, at: entry.fetch("wait_until"), arguments: {}
+end
+```
+
+Two entries leave one reminder. The earlier wake-up never happens, nothing
+raises, and nothing is logged except a `solid_objects.reminder.replaced` event.
+
+Arm one alarm for the earliest item instead, and let the handler drain
+everything now due before arming the next:
+
+```ruby
+def add(entry:)
+  self.entries = (entries + [ entry ]).sort_by { |item| item.fetch("wait_until") }
+  arm_next
+end
+
+def deliver
+  now = Time.current.to_i
+  due, pending = entries.partition { |item| item.fetch("wait_until") <= now }
+  due.each { |item| emit :send_push, **item.symbolize_keys }
+  self.entries = pending
+  arm_next
+end
+
+private
+
+def arm_next
+  earliest = entries.first
+  return unless earliest
+
+  schedule :deliver, at: Time.at(earliest.fetch("wait_until")), arguments: {}
+end
+```
+
+`deliver` drains every due item rather than one, so a single alarm serves a
+whole queue and a missed or coalesced occurrence cannot strand an entry. Use a
+distinct reminder name only when you genuinely need two independent alarms on
+one actor, such as `:deliver` and `:sweep`.
+
+Solid Objects has no `unschedule`. A reminder stops when its handler does not
+re-arm it, and destroying an actor removes its reminders.
+
 Self-scheduling actors should also have a low-frequency application reconciler.
 It may read `SolidObjects::Instance.states_for`, `.without_pending_work`, and
 `.orphaned`, but every repair must go through `async`. Never bulk-update actor

data/docs/architecture.md

@@ -439,6 +439,8 @@ A reminder record contains actor identity, a reminder name, target message, JSON
 schedule :expire, at: 30.minutes.from_now, arguments: {}
 ```
 
+Reminders are keyed by `(actor, reminder name)`, enforced by a unique index on `(instance_id, name)`. `schedule` is therefore an upsert: scheduling a name that is already armed moves that alarm instead of adding another, which is what makes re-arming safe from a handler that may run more than once. An actor needing several pending items should arm one alarm for the earliest and drain everything due when it fires, rather than one alarm per item; the [reminders guide](../README.md#a-reminder-is-one-named-alarm-per-actor) shows that pattern. A move that changes `next_run_at` emits `solid_objects.reminder.replaced`, because the replacement is otherwise indistinguishable from a first schedule.
+
 When due, the scheduler locks the source instance and creates a normal mailbox
 row with an idempotency key derived from reminder ID and occurrence. The
 mailbox insert and reminder advancement commit atomically. The mailbox provides

data/docs/database-schema.md

@@ -77,7 +77,8 @@ Indexes:
 ### `reminders`
 
 Durable one-shot or recurring alarm definitions. Unique instance/name makes
-rescheduling an actor-owned reminder deterministic. Status/next-run/ID drives
+rescheduling an actor-owned reminder deterministic, which also means a second
+`schedule` under the same name moves that alarm rather than adding one. Status/next-run/ID drives
 the due scan. Claim ownership references the process registry, and constraints
 limit recurrence intervals, missed-work policies, and statuses.
 

data/docs/development.md

@@ -66,7 +66,13 @@ 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.
+boundaries. It deletes every actor-owned row itself rather than deleting actor
+instances and letting the database cascade remove the rest: SQLite has to be
+asked for foreign keys, MySQL has to be on InnoDB, and a host application may
+have stripped the constraints out of the copied migration. Where the cascade
+does not fire, a row that survives a reset carries an `instance_id` pointing at
+nothing, and the next test that reads reminders or dead letters sees another
+test's data.
 
 ## Inline RBS
 

data/docs/operations.md

@@ -155,6 +155,15 @@ transaction rejection, commit-action start/completion/failure, effect and
 broadcast enqueue/completion, reminder enqueue, actor destruction/expiration,
 retention pruning, process cleanup, and supervisor lifecycle.
 
+`solid_objects.reminder.replaced` reports a `schedule` call that moved an alarm
+already armed under the same name on the same actor, carrying the actor
+identity, reminder `name`, `previous_run_at`, and `next_run_at`. Reminders are
+keyed by actor and name, so re-arming a name is an update rather than a second
+alarm. That is deliberate, and it is silent: an actor that arms one reminder
+per queued item keeps only the last, and the earlier wake-up never happens.
+Watch this event if your actors schedule from a loop or from a handler that can
+run more than once. Rescheduling to the same time reports nothing.
+
 `solid_objects.component.refreshed` covers every authorized component refresh
 request. Its payload carries the actor identity, `component_name`,
 `component_key`, declared `dependencies`, `refresh_method`, the rendered

data/docs/roadmap.md

@@ -44,7 +44,8 @@
   result recovery
 - Bounded message/process pruning, actor-type opt-in instance expiration,
   graceful caller shutdown, committed state snapshots, and an opt-in Minitest
-  helper
+  helper that clears every actor-owned table itself rather than relying on the
+  database cascade, which a host application may not enforce
 - Supervisor role replacement: a role whose thread dies is restarted until
   shutdown is requested, and dead process records plus expired message and
   process history are pruned on their own intervals without an application

data/lib/solid_objects/configuration.rb

@@ -92,6 +92,9 @@ module SolidObjects
       :authorize_subscription,
       :authorize_administration
 
+    # @rbs @additional_components: Array[untyped]
+    attr_reader :additional_components
+
     # @rbs () -> void
     def initialize
       @table_name_prefix = "solid_objects_"
@@ -142,6 +145,45 @@ module SolidObjects
       @authorize_destroy = ->(**) { false }
       @authorize_subscription = ->(**) { false }
       @authorize_administration = ->(**) { false }
+      @additional_components = []
+    end
+
+    # Registers a long running component that the supervisor runs beside its own
+    # workers. An extension gem uses this to share one process, rather than ask
+    # an operator to run and monitor a second one.
+    #
+    # The block must return an object that answers `run`, `request_shutdown`,
+    # `stopped?`, and `stop`, which is the contract the built in components
+    # already keep. The supervisor calls the block once for each supervisor it
+    # builds, and again when it replaces a crashed component, so two
+    # supervisors never share one component instance.
+    #
+    # @rbs (?count: Integer) { () -> untyped } -> void
+    def register_component(count: 1, &factory)
+      raise ArgumentError, "register_component requires a block" unless factory
+      raise ArgumentError, "count must be positive" unless count.positive?
+
+      count.times { @additional_components << factory }
+    end
+
+    # The supervisor checks the contract here rather than at registration,
+    # because a component often needs a database connection to exist, and
+    # registration happens while the application boots.
+    # @rbs () -> Array[untyped]
+    def build_additional_components
+      additional_components.map { |factory| factory.call.tap { |component| validate_component!(component) } }
+    end
+
+    # A component that misses part of the contract would hang the supervisor at
+    # shutdown, or crash the moment it starts. The build fails instead, where
+    # the caller can read the reason.
+    # @rbs (untyped) -> void
+    def validate_component!(component)
+      %i[run request_shutdown stopped? stop].each do |method_name|
+        next if component.respond_to?(method_name)
+
+        raise ArgumentError, "a registered component must respond to #{method_name}"
+      end
     end
 
     # @rbs () -> self

data/lib/solid_objects/executor.rb

@@ -90,8 +90,14 @@ module SolidObjects
       reminder_intents = actor.drain_reminder_intents
       outbound_message_intents = actor.drain_outbound_message_intents
       enqueued_effects = []
+      moved_reminders = []
 
       activation.lease.fenced_transaction do |instance|
+        # A busy database makes the adapter retry this whole block, so an
+        # attempt that was rolled back must not leave its work in the lists the
+        # reporting below reads. Each attempt starts from empty.
+        enqueued_effects.clear
+        moved_reminders.clear
         claimed_message = matching_claim!
         locked_message = Message.lock.find(message.id)
         execute_commit_actions(commit_action_intents)
@@ -107,7 +113,7 @@ module SolidObjects
           completed_at: SolidObjects.database_adapter.database_now
         )
         enqueued_effects.concat(enqueue_effects(locked_message, instance, effect_intents))
-        schedule_reminders(instance, reminder_intents)
+        moved_reminders.concat(schedule_reminders(instance, reminder_intents))
         enqueued_effects.concat(
           enqueue_actor_messages(locked_message, instance, outbound_message_intents)
         )
@@ -127,6 +133,9 @@ module SolidObjects
           observable_name:
         )
       end
+      moved_reminders.each do |moved|
+        SolidObjects.instrument(:"reminder.replaced", **moved)
+      end
       enqueued_effects.each do |effect|
         SolidObjects.instrument(
           :"effect.enqueued",
@@ -211,10 +220,20 @@ module SolidObjects
       end
     end
 
-    # @rbs (Instance, Array[Actor::ReminderIntent]) -> void
+    # A reminder is one named alarm per actor, so scheduling a name that is
+    # already armed moves it rather than adding a second. An actor that arms a
+    # reminder per queued item therefore keeps only the last, and nothing else
+    # about that is visible: the write succeeds and the earlier wake-up simply
+    # never happens.
+    # Moves are returned rather than reported here, so the report happens after
+    # the turn commits. A rolled back turn would otherwise announce an alarm
+    # that never moved, which is the opposite of the visibility this event
+    # exists to provide.
+    # @rbs (Instance, Array[Actor::ReminderIntent]) -> Array[Hash[Symbol, untyped]]
     def schedule_reminders(instance, intents)
-      intents.each do |intent|
+      intents.filter_map do |intent|
         reminder = Reminder.find_or_initialize_by(instance:, name: intent.name)
+        previous_run_at = reminder.next_run_at
         reminder.assign_attributes(
           actor_type: instance.actor_type,
           actor_id: instance.actor_id,
@@ -227,10 +246,28 @@ module SolidObjects
           claimed_by: nil,
           claimed_at: nil
         )
+        moved = moved_reminder_payload(reminder, previous_run_at)
         reminder.save!
+        moved
       end
     end
 
+    # Arguments are omitted deliberately: a reminder carries application data
+    # and this event exists to be logged.
+    # @rbs (Reminder, Time?) -> Hash[Symbol, untyped]?
+    def moved_reminder_payload(reminder, previous_run_at)
+      return nil unless previous_run_at
+      return nil if previous_run_at == reminder.next_run_at
+
+      {
+        actor_type: reminder.actor_type,
+        actor_id: reminder.actor_id,
+        name: reminder.name,
+        previous_run_at:,
+        next_run_at: reminder.next_run_at
+      }
+    end
+
     # @rbs (Message, Instance, Array[Actor::OutboundMessageIntent]) -> Array[Effect]
     def enqueue_actor_messages(locked_message, instance, intents)
       intents.map do |intent|

data/lib/solid_objects/supervisor.rb

@@ -19,12 +19,13 @@ module SolidObjects
       broadcast_worker_count: SolidObjects.configuration.broadcast_worker_count,
       reminder_scheduler_count: SolidObjects.configuration.reminder_scheduler_count
     )
-      @components = build_components(
+      @builders = component_builders(
         worker_count:,
         effect_worker_count:,
         broadcast_worker_count:,
         reminder_scheduler_count:
       )
+      @components = build_all(@builders)
       @threads = []
       @monitor = nil
       @started = false
@@ -77,7 +78,7 @@ module SolidObjects
 
     private
 
-    attr_reader :components, :threads
+    attr_reader :components, :threads, :builders
 
     # A role that raises leaves its thread dead. Without replacement the
     # process keeps running while quietly doing less work, so the supervisor
@@ -116,7 +117,11 @@ module SolidObjects
         replaced = @lifecycle.synchronize do
           next false unless @started
 
-          replacement = component.class.new
+          # A component built by this supervisor has a builder, which carries
+          # whatever the constructor was given. A component put in place by
+          # other means has none, so the class is the only thing left to go on.
+          builder = builders[index] || -> { component.class.new }
+          replacement = builder.call
           components[index] = replacement
           threads[index] = supervise(replacement)
           replacement
@@ -250,17 +255,53 @@ module SolidObjects
       nil
     end
 
-    # @rbs (worker_count: Integer, effect_worker_count: Integer, broadcast_worker_count: Integer, reminder_scheduler_count: Integer) -> Array[Worker | EffectExecutor | ReminderScheduler | BroadcastExecutor]
-    def build_components(
+    # A constructor can take a resource, and a later builder can raise. Without
+    # this, the components built first would be dropped while still holding
+    # whatever they took, and nothing would ever give it back.
+    # @rbs (Array[^() -> untyped]) -> Array[untyped]
+    def build_all(builders)
+      built = []
+      builders.each do |builder|
+        # The component joins the list before the contract check, so a
+        # component that fails the check is stopped along with the rest.
+        built << (component = builder.call)
+        SolidObjects.configuration.validate_component!(component)
+      end
+      built
+    rescue Exception # rubocop:disable Lint/RescueException
+      built.each { |component| stop_after_failed_build(component) }
+      raise
+    end
+
+    # The failure that stopped the build is the one worth reporting, so a
+    # failure inside the cleanup never replaces it.
+    # @rbs (untyped) -> void
+    def stop_after_failed_build(component)
+      component.stop if component.respond_to?(:stop)
+    rescue Exception => error # rubocop:disable Lint/RescueException
+      SolidObjects.instrument(
+        :"supervisor.component_cleanup_failed",
+        role: component.class.name,
+        error_class: error.class.name
+      )
+    end
+
+    # Each component keeps the builder that made it, so a replacement after a
+    # crash is built the same way as the original. Components registered
+    # through the configuration run beside the built in ones, under the same
+    # supervision, restart, and shutdown timeout.
+    # @rbs (worker_count: Integer, effect_worker_count: Integer, broadcast_worker_count: Integer, reminder_scheduler_count: Integer) -> Array[^() -> untyped]
+    def component_builders(
       worker_count:,
       effect_worker_count:,
       broadcast_worker_count:,
       reminder_scheduler_count:
     )
-      Array.new(worker_count) { Worker.new } +
-        Array.new(effect_worker_count) { EffectExecutor.new } +
-        Array.new(broadcast_worker_count) { BroadcastExecutor.new } +
-        Array.new(reminder_scheduler_count) { ReminderScheduler.new }
+      Array.new(worker_count) { -> { Worker.new } } +
+        Array.new(effect_worker_count) { -> { EffectExecutor.new } } +
+        Array.new(broadcast_worker_count) { -> { BroadcastExecutor.new } } +
+        Array.new(reminder_scheduler_count) { -> { ReminderScheduler.new } } +
+        SolidObjects.configuration.additional_components
     end
 
     # @rbs () -> void

data/lib/solid_objects/test_helper.rb

@@ -12,12 +12,35 @@ module SolidObjects
         test_case.teardown { reset_actors! }
       end
 
+      # Deleting instances alone left every other actor-owned row to the
+      # database cascade. That cascade is not enforced everywhere: SQLite has
+      # to be asked for foreign keys, MySQL has to be on InnoDB, and a host
+      # application may have stripped the constraints out of the copied
+      # migration. Where it does not fire, rows survive into the next test with
+      # an instance_id pointing at nothing, and a test that reads them sees
+      # another test's data. Deleting each table costs nothing and does not
+      # depend on referential integrity.
       # @rbs () -> void
       def reset_actors!
         SolidObjects.reset_caller_process!
-        Instance.delete_all
+        actor_owned_models.each(&:delete_all)
         Process.delete_all
       end
+
+      # Children first, so the order is safe whether or not the cascade fires.
+      # @rbs () -> Array[Class]
+      def actor_owned_models
+        [
+          DeadLetter,
+          ClaimedMessage,
+          ReadyMessage,
+          Broadcast,
+          Effect,
+          Reminder,
+          Message,
+          Instance
+        ]
+      end
     end
 
     # @rbs () -> void

data/lib/solid_objects/version.rb

@@ -1,5 +1,5 @@
 # rbs_inline: enabled
 
 module SolidObjects
-  VERSION = "0.10.2"
+  VERSION = "0.11.0"
 end

data/sig/generated/lib/solid_objects/configuration.rbs

@@ -2,6 +2,10 @@
 
 module SolidObjects
   class Configuration
+    @process_alive_threshold: Float
+
+    @shutdown_timeout: Float
+
     @supervisor_monitor_interval: Float
 
     @retention_interval: Float
@@ -86,10 +90,6 @@ module SolidObjects
 
     @process_heartbeat_interval: Float
 
-    @process_alive_threshold: Float
-
-    @shutdown_timeout: Float
-
     attr_accessor table_name_prefix: untyped
 
     attr_accessor polling_interval: untyped
@@ -178,9 +178,37 @@ module SolidObjects
 
     attr_accessor authorize_administration: untyped
 
+    # @rbs @additional_components: Array[untyped]
+    attr_reader additional_components: untyped
+
     # @rbs () -> void
     def initialize: () -> void
 
+    # Registers a long running component that the supervisor runs beside its own
+    # workers. An extension gem uses this to share one process, rather than ask
+    # an operator to run and monitor a second one.
+    #
+    # The block must return an object that answers `run`, `request_shutdown`,
+    # `stopped?`, and `stop`, which is the contract the built in components
+    # already keep. The supervisor calls the block once for each supervisor it
+    # builds, and again when it replaces a crashed component, so two
+    # supervisors never share one component instance.
+    #
+    # @rbs (?count: Integer) { () -> untyped } -> void
+    def register_component: (?count: Integer) { () -> untyped } -> void
+
+    # The supervisor checks the contract here rather than at registration,
+    # because a component often needs a database connection to exist, and
+    # registration happens while the application boots.
+    # @rbs () -> Array[untyped]
+    def build_additional_components: () -> Array[untyped]
+
+    # A component that misses part of the contract would hang the supervisor at
+    # shutdown, or crash the moment it starts. The build fails instead, where
+    # the caller can read the reason.
+    # @rbs (untyped) -> void
+    def validate_component!: (untyped) -> void
+
     # @rbs () -> self
     def validate!: () -> self
 

data/sig/generated/lib/solid_objects/executor.rbs

@@ -45,8 +45,22 @@ module SolidObjects
     # @rbs (Message, Instance, Array[Actor::EffectIntent]) -> Array[Effect]
     def enqueue_effects: (Message, Instance, Array[Actor::EffectIntent]) -> Array[Effect]
 
-    # @rbs (Instance, Array[Actor::ReminderIntent]) -> void
-    def schedule_reminders: (Instance, Array[Actor::ReminderIntent]) -> void
+    # A reminder is one named alarm per actor, so scheduling a name that is
+    # already armed moves it rather than adding a second. An actor that arms a
+    # reminder per queued item therefore keeps only the last, and nothing else
+    # about that is visible: the write succeeds and the earlier wake-up simply
+    # never happens.
+    # Moves are returned rather than reported here, so the report happens after
+    # the turn commits. A rolled back turn would otherwise announce an alarm
+    # that never moved, which is the opposite of the visibility this event
+    # exists to provide.
+    # @rbs (Instance, Array[Actor::ReminderIntent]) -> Array[Hash[Symbol, untyped]]
+    def schedule_reminders: (Instance, Array[Actor::ReminderIntent]) -> Array[Hash[Symbol, untyped]]
+
+    # Arguments are omitted deliberately: a reminder carries application data
+    # and this event exists to be logged.
+    # @rbs (Reminder, Time?) -> Hash[Symbol, untyped]?
+    def moved_reminder_payload: (Reminder, Time?) -> Hash[Symbol, untyped]?
 
     # @rbs (Message, Instance, Array[Actor::OutboundMessageIntent]) -> Array[Effect]
     def enqueue_actor_messages: (Message, Instance, Array[Actor::OutboundMessageIntent]) -> Array[Effect]

data/sig/generated/lib/solid_objects/supervisor.rbs

@@ -36,6 +36,8 @@ module SolidObjects
 
     attr_reader threads: untyped
 
+    attr_reader builders: untyped
+
     # A role that raises leaves its thread dead. Without replacement the
     # process keeps running while quietly doing less work, so the supervisor
     # watches its threads and restarts any that stopped before shutdown.
@@ -101,8 +103,23 @@ module SolidObjects
     # @rbs () -> void
     def release_wake_up: () -> void
 
-    # @rbs (worker_count: Integer, effect_worker_count: Integer, broadcast_worker_count: Integer, reminder_scheduler_count: Integer) -> Array[Worker | EffectExecutor | ReminderScheduler | BroadcastExecutor]
-    def build_components: (worker_count: Integer, effect_worker_count: Integer, broadcast_worker_count: Integer, reminder_scheduler_count: Integer) -> Array[Worker | EffectExecutor | ReminderScheduler | BroadcastExecutor]
+    # A constructor can take a resource, and a later builder can raise. Without
+    # this, the components built first would be dropped while still holding
+    # whatever they took, and nothing would ever give it back.
+    # @rbs (Array[^() -> untyped]) -> Array[untyped]
+    def build_all: (Array[^() -> untyped]) -> Array[untyped]
+
+    # The failure that stopped the build is the one worth reporting, so a
+    # failure inside the cleanup never replaces it.
+    # @rbs (untyped) -> void
+    def stop_after_failed_build: (untyped) -> void
+
+    # Each component keeps the builder that made it, so a replacement after a
+    # crash is built the same way as the original. Components registered
+    # through the configuration run beside the built in ones, under the same
+    # supervision, restart, and shutdown timeout.
+    # @rbs (worker_count: Integer, effect_worker_count: Integer, broadcast_worker_count: Integer, reminder_scheduler_count: Integer) -> Array[^() -> untyped]
+    def component_builders: (worker_count: Integer, effect_worker_count: Integer, broadcast_worker_count: Integer, reminder_scheduler_count: Integer) -> Array[^() -> untyped]
 
     # @rbs () -> void
     def join_until_timeout: () -> void

data/sig/generated/lib/solid_objects/test_helper.rbs

@@ -5,9 +5,21 @@ module SolidObjects
     # @rbs (Class) -> void
     def self.included: (Class) -> void
 
+    # Deleting instances alone left every other actor-owned row to the
+    # database cascade. That cascade is not enforced everywhere: SQLite has
+    # to be asked for foreign keys, MySQL has to be on InnoDB, and a host
+    # application may have stripped the constraints out of the copied
+    # migration. Where it does not fire, rows survive into the next test with
+    # an instance_id pointing at nothing, and a test that reads them sees
+    # another test's data. Deleting each table costs nothing and does not
+    # depend on referential integrity.
     # @rbs () -> void
     def self.reset_actors!: () -> void
 
+    # Children first, so the order is safe whether or not the cascade fires.
+    # @rbs () -> Array[Class]
+    def self.actor_owned_models: () -> Array[Class]
+
     # @rbs () -> void
     def reset_actors!: () -> void
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: solid_objects
 version: !ruby/object:Gem::Version
-  version: 0.10.2
+  version: 0.11.0
 platform: ruby
 authors:
 - Lucas Carlson
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-10 00:00:00.000000000 Z
+date: 2026-08-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actioncable