solid_objects 0.10.2 → 0.10.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1cd348d089d12af0c4ea20a5f163d58b69f4796e7741ed12038301139396baae
-  data.tar.gz: e31ad3836b5782ee13f3669eef3645114498e7133dd5f8c561105310f4452867
+  metadata.gz: 36d165ff933a151ee0cc9fbff1ae834333f9591d1ae71068a0127d198dc4d5d8
+  data.tar.gz: 1cfd279335dcf34f4cd2dd659412e04c5ac8d6ed98e1815cbd184bb38f67585f
 SHA512:
-  metadata.gz: 470ca38a3faacd28a05a8f3cd020a353a1a20a9717aad29ec7c0f6cb9be6efbb6e44ef96abcc5a12c2b151b112cdbda47df73da361a94a26ff275bb0dd7d966b
-  data.tar.gz: 874fa30b34175212a24ecdc115e4fd187c40f46c0e55ff62def214f5b350a54997b738f37a86991a9c032f7e1b7ec017613aa0cebaa6378c90aa0c02d6457fb5
+  metadata.gz: 9328e60fa9f4e08f17cfe4404fe117af3a2c8efef53ba379b5c824d73a71063ae7f3b8e438b177ec4fcacb1ca31fdb86686212a6ac6d0f972e4f337233d6dea2
+  data.tar.gz: b39f02c65284721d06c02eee9bbd678eb808770136847715f83525e3e43fe461f89e9837c0811c6730b50584b4c74c572dcf8e3de1cbbdae7fcfbf2dbc7f6708

data/CHANGELOG.md

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

@@ -805,6 +805,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/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/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.10.3"
 end

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/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.10.3
 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