solid_objects 0.17.3 → 0.17.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 218b1090ca466db8385017c23f98120d78b605b1db03a7ad69e82156c7669fe5
-  data.tar.gz: f0deae94f1fa479882d3d47bc5205c30d30b30c3aadfee663959ad7e787ff265
+  metadata.gz: 0ba9bcffaef380dc24ebcb6b4da8893e467e5501fe71ed77f6f1e6d95520f516
+  data.tar.gz: ed791f24f434f52efb3a5080f37d47c5778e0f5b60be605ef9cf6aed2ac14471
 SHA512:
-  metadata.gz: 97c597751ea4330ec9857faec8bc4ef8d3449891f29abd6d99fe13709e785971c42e6d3faf24ab02835685857104ad82e20df42088a0b84a32573a8519177368
-  data.tar.gz: db9450e6f7657b630cf6d6c2eb191a57614690ef7f34d3d47fea079a5bd388d1b7bc31b84ac22667b6cdd296f0a426e29f00acb20b3473fe53af0e656d146b28
+  metadata.gz: e116a5c98d6e5dfcb6ff6b4a3cf37993b7e6ea320b2b87d1fe91f080ffc11b169c97ef5381746a193f2d5d89782eefe147542a9f0f53c597e49c622956f15ff1
+  data.tar.gz: 51bf5f1a8f3c87e72ce86cfcf8cd9cf08e3fd24854dce7446e3ef3e723e02a7b74efa9c2f2ea2a2a3bf73cf14ae1716b29687c5fdff734103dc05b391b6df4ad

data/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 0.17.5 - 2026-10-12
+
+- Back off repeated interrupted-message recovery using `retry_delay`.
+  The first claimed attempt recovers immediately; after attempts 2, 3, 4,
+  and onward, the delay callback receives 1, 2, 3, and onward (defaults:
+  1, 2, 4 seconds, capped at 60 seconds). Total persisted claim attempts,
+  including earlier handler failures, determine the delay. The ready timestamp
+  survives worker replacement and preserves mailbox order while other actors
+  can proceed. Lease loss alone still does not dead-letter a message; handler
+  failure attempt limits, setting names, defaults, and schema stay unchanged.
+- Emit `activation.lost` with the message ID and total attempt count when a
+  turn loses its fence, including while saving a handler failure or rejection,
+  matching JavaScript instrumentation. Shutdown requested
+  by that callback stops the worker before another pass. Skip a cached actor
+  whose first message is delayed so later ready messages cannot starve peers.
+
+- Preserve caller lifecycle guarantees with regression tests for concurrent
+  synchronous calls retaining their staged effects and for caller process
+  re-registration after stale-process cleanup and retention. Both cases
+  already work in Ruby; no runtime behavior or configuration changes.
+  The concurrency test waits for the second caller's busy-actor wait before
+  allowing the first caller to commit its staged effect.
+
+## 0.17.4 - 2026-10-12
+
+- Renew activations between turns in a drain pass when renewal is due,
+  including when the renewal thread has not run.
+- Keep the activation fence and expiry while an outstanding message claim
+  remains. The next worker pass recovers an expired turn in mailbox order,
+  including with `max_attempts: 1`. Reclaiming increments `attempt_count`;
+  lease loss alone does not create a dead letter.
+
 ## 0.17.3 - 2026-10-09
 
 - Add four problem guides in `docs/guides/`: preventing race conditions in

data/docs/agents.md

@@ -173,6 +173,9 @@ Obey these rules in actor code:
   write in the same database.
 - Do not call an external API in a handler. Use `emit` and an effect handler.
 - Write each handler so that it can run again. Delivery is at least once.
+- Repeated lease losses back off but do not become dead letters. Observe
+  `activation.lost` and set an application stopping policy if a hard bound is
+  required; increasing the handler-failure attempt limit does not bound lease loss.
 - A reminder changes state only when it runs, and it runs only while
   `solid_objects start` runs. Do not compute expiry from the clock in a query;
   read the state that the reminder committed.

data/docs/observability.md

@@ -45,6 +45,7 @@ JavaScript does not await exporters. Telemetry is not a durable audit trail.
 | ------------------------------------------- | ---------------------------------------------------------------------------- |
 | `activation.started/completed/failed`       | Local actor activation hook lifecycle                                        |
 | `message.started/completed/failed/rejected` | One attempt's execution outcome                                              |
+| `activation.lost`                         | A message turn lost its activation fence; includes message ID and total attempt count |
 | `message.retry`                             | Failed attempt durably queued for another attempt                            |
 | `dead_letter.created`                       | Message exhausted retries or failed permanently                              |
 | `commit_action.started/completed/failed`    | One registered commit action inside the commit transaction                   |

data/docs/operations.md

@@ -606,3 +606,24 @@ 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
 violate application expectations.
+
+## Interrupted-message recovery
+
+An interrupted first claimed attempt recovers immediately. Recovery after
+persisted attempts 2, 3, 4, ... calls `retry_delay` with 1, 2, 3, ... . The
+callback returns seconds; defaults grow from 1 to 2 to 4 seconds up to 60 seconds.
+This uses total claim attempts, including earlier handler failures, not a
+separate lease-loss counter. The delay is stored in ready-message availability
+when a stale claim is recovered, survives worker replacement, and keeps later
+messages behind that message. Other actors can still run. Custom delays,
+including zero, remain authoritative.
+
+Lease loss alone does not create a dead letter, even with `max_attempts: 1`.
+Handler failures still use the full attempt count for `max_attempts` and
+`retry_delay`. An always-losing message remains pending indefinitely. Observe
+`activation.lost` (message ID and total attempt count) and impose an application
+stopping policy if a hard bound is required. Calling `request_shutdown` from
+instrumentation stops the worker before its next pass. Ruby uses a separate
+renewal thread and waits after lost turns; it does not have the JavaScript
+microtask starvation pattern. A handler must still return before its worker
+can finish shutting down.

data/docs/roadmap.md

@@ -23,8 +23,14 @@
   instead of 12. Concurrent creation causes no deadlock on SQLite, PostgreSQL,
   or MySQL. MySQL needs a shared read after a duplicate key, because it uses
   repeatable read. The tests count statements, and do not measure latency.
-- Activation leases, renewal, unique activation tokens, generations, and
-  fenced commits
+- Activation leases, renewal between turns as well as in the renewal thread,
+  unique activation tokens, generations, and
+  fenced commits. Interrupted first attempts recover immediately; repeated
+  interruptions use durable retry delays from total claim attempts minus one,
+  preserving mailbox order and progress for other actors. Lease loss emits
+  `activation.lost` with the message ID and attempt, including losses while
+  saving a handler failure or rejection. There is no hard retry cap;
+  applications needing one must impose a stopping policy.
 - Bounded activation passes, idle cache, hot-actor yield, and process records
 - At-least-once retries, terminal domain rejection, strict poison ordering,
   dead letters, and tail retry

data/docs/virtual-actors.md

@@ -170,6 +170,10 @@ again without harm.
   a crash or a lost lease.
 - Ordered turns do not cancel stale Ruby code. Fencing stops a stale activation
   from a commit, but that code can continue to run.
+- An interrupted first attempt recovers immediately. Repeated interruptions
+  use growing, durable retry delays while keeping mailbox order. Lease loss
+  alone has no attempt limit; use instrumentation and an application stopping
+  policy when a hard bound is required.
 - External effects can run more than once. Use the stable effect ID, or
   another durable key, as the idempotency key at the provider.
 - There are no transactions across actor identities, and there is no replay of

data/lib/solid_objects/activation.rb

@@ -52,7 +52,8 @@ module SolidObjects
     # @rbs () -> bool
     def ready?
       now = SolidObjects.database_adapter.database_now
-      ReadyMessage.where(instance_id: lease.instance_id, available_at: ..now).exists? ||
+      ready_message = ReadyMessage.where(instance_id: lease.instance_id).order(:sequence).first
+      (ready_message && ready_message.available_at <= now) ||
         ClaimedMessage.where(
           instance_id: lease.instance_id,
           process_id: lease.owner_id,
@@ -139,6 +140,7 @@ module SolidObjects
           break
         end
 
+        renew_lease if processed_count.positive? && lease_renewal_due?
         message = claim_next_message
         break unless message
 
@@ -226,11 +228,12 @@ module SolidObjects
       claimed_message.destroy!
       return if message.completed? || message.dead?
 
+      delay = (message.attempt_count <= 1) ? 0 : SolidObjects.configuration.retry_delay.call(message.attempt_count - 1)
       ReadyMessage.create!(
         message:,
         instance:,
         sequence: message.sequence,
-        available_at: SolidObjects.database_adapter.database_now
+        available_at: SolidObjects.database_adapter.database_now + delay
       )
     end
 

data/lib/solid_objects/executor.rb

@@ -16,6 +16,18 @@ module SolidObjects
 
     # @rbs () -> bool
     def call
+      execute
+    rescue LostActivation
+      SolidObjects.instrument(:"activation.lost", **instrumentation_payload, duration_milliseconds: elapsed_milliseconds)
+      raise
+    end
+
+    private
+
+    attr_reader :activation, :message
+
+    # @rbs () -> bool
+    def execute
       state_before = actor.state.to_h
       observables_before = actor.observable_values
       message_context = MessageContext.new(
@@ -53,10 +65,6 @@ module SolidObjects
       false
     end
 
-    private
-
-    attr_reader :activation, :message
-
     # @rbs () -> Actor
     def actor
       activation.actor

data/lib/solid_objects/lease.rb

@@ -123,6 +123,7 @@ module SolidObjects
         instance = Instance.lock.find_by(id: instance_id)
         next false unless instance
         next false unless owned_generation?(instance)
+        next false if ClaimedMessage.where(instance_id:).exists?
 
         instance.update!(
           activation_owner_id: nil,

data/lib/solid_objects/version.rb

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

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

@@ -22,6 +22,9 @@ module SolidObjects
 
     attr_reader message: untyped
 
+    # @rbs () -> bool
+    def execute: () -> bool
+
     # @rbs () -> Actor
     def actor: () -> Actor
 

metadata

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