solid_objects 0.14.6 → 0.15.0

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

@@ -3,6 +3,8 @@
 module SolidObjects
   class Actor
     class EffectIntent < Data
+      attr_reader effect_id(): untyped
+
       attr_reader name(): untyped
 
       attr_reader arguments(): untyped
@@ -11,12 +13,31 @@ module SolidObjects
 
       attr_reader failure_operation(): untyped
 
-      def self.new: (untyped name, untyped arguments, untyped success_operation, untyped failure_operation) -> instance
-                  | (name: untyped, arguments: untyped, success_operation: untyped, failure_operation: untyped) -> instance
+      attr_reader recovery_operation(): untyped
+
+      attr_reader status_operation(): untyped
+
+      attr_reader recovery_timeout(): untyped
+
+      def self.new: (untyped effect_id, untyped name, untyped arguments, untyped success_operation, untyped failure_operation, untyped recovery_operation, untyped status_operation, untyped recovery_timeout) -> instance
+                  | (effect_id: untyped, name: untyped, arguments: untyped, success_operation: untyped, failure_operation: untyped, recovery_operation: untyped, status_operation: untyped, recovery_timeout: untyped) -> instance
 
-      def self.members: () -> [ :name, :arguments, :success_operation, :failure_operation ]
+      def self.members: () -> [ :effect_id, :name, :arguments, :success_operation, :failure_operation, :recovery_operation, :status_operation, :recovery_timeout ]
 
-      def members: () -> [ :name, :arguments, :success_operation, :failure_operation ]
+      def members: () -> [ :effect_id, :name, :arguments, :success_operation, :failure_operation, :recovery_operation, :status_operation, :recovery_timeout ]
+    end
+
+    class EffectRecoveryIntent < Data
+      attr_reader effect_id(): untyped
+
+      attr_reader request_id(): untyped
+
+      def self.new: (untyped effect_id, untyped request_id) -> instance
+                  | (effect_id: untyped, request_id: untyped) -> instance
+
+      def self.members: () -> [ :effect_id, :request_id ]
+
+      def members: () -> [ :effect_id, :request_id ]
     end
 
     class CommitActionIntent < Data
@@ -139,6 +160,8 @@ module SolidObjects
 
     @commit_action_intents: Array[CommitActionIntent]
 
+    @effect_recovery_intents: Array[EffectRecoveryIntent]
+
     @effect_intents: Array[EffectIntent]
 
     @state: State
@@ -158,8 +181,11 @@ module SolidObjects
     # @rbs (Symbol | String, String, ?details: Hash[String | Symbol, untyped]) -> bot
     def reject: (Symbol | String, String, ?details: Hash[String | Symbol, untyped]) -> bot
 
-    # @rbs (Symbol | String, ?on_success: Symbol | String?, ?on_failure: Symbol | String?, **untyped) -> nil
-    def emit: (Symbol | String, ?on_success: Symbol | String?, ?on_failure: Symbol | String?, **untyped) -> nil
+    # @rbs (Symbol | String, ?on_success: Symbol | String?, ?on_failure: Symbol | String?, ?on_recovery: Symbol | String?, ?on_status: Symbol | String?, ?recovery_timeout: Numeric?, **untyped) -> effect_handle
+    def emit: (Symbol | String, ?on_success: Symbol | String?, ?on_failure: Symbol | String?, ?on_recovery: Symbol | String?, ?on_status: Symbol | String?, ?recovery_timeout: Numeric?, **untyped) -> effect_handle
+
+    # @rbs (effect_handle) -> nil
+    def request_effect_recovery: (effect_handle) -> nil
 
     # @rbs () -> OperationDispatcher
     def transmit: () -> OperationDispatcher
@@ -216,6 +242,9 @@ module SolidObjects
     # @rbs () -> Array[EffectIntent]
     def drain_effect_intents: () -> Array[EffectIntent]
 
+    # @rbs () -> Array[EffectRecoveryIntent]
+    def drain_effect_recovery_intents: () -> Array[EffectRecoveryIntent]
+
     # @rbs () -> Array[CommitActionIntent]
     def drain_commit_action_intents: () -> Array[CommitActionIntent]
 
@@ -232,6 +261,8 @@ module SolidObjects
 
     attr_reader effect_intents: untyped
 
+    attr_reader effect_recovery_intents: untyped
+
     attr_reader commit_action_intents: untyped
 
     attr_reader reminder_intents: untyped
@@ -246,5 +277,8 @@ module SolidObjects
 
     # @rbs (Symbol | String?) -> void
     def validate_effect_callback!: (Symbol | String?) -> void
+
+    # @rbs (timeout: Numeric?, operation: String | Symbol?) -> void
+    def validate_recovery_timeout!: (timeout: Numeric?, operation: String | Symbol?) -> void
   end
 end

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

@@ -0,0 +1,24 @@
+# Generated from lib/solid_objects/actor_signatures.rb with RBS::Inline
+
+module SolidObjects
+  class ActorSignatures
+    # @rbs (actors: Array[Class], signatures: Array[String]) -> String
+    def self.generate: (actors: Array[Class], signatures: Array[String]) -> String
+
+    @builder: untyped
+
+    # @rbs (signatures: Array[String]) -> void
+    def initialize: (signatures: Array[String]) -> void
+
+    # @rbs (actors: Array[Class]) -> String
+    def generate: (actors: Array[Class]) -> String
+
+    private
+
+    # @rbs (untyped) -> String
+    def actor_signature: (untyped) -> String
+
+    # @rbs (untyped, String, Symbol) -> untyped
+    def staged_type: (untyped, String, Symbol) -> untyped
+  end
+end

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

@@ -55,6 +55,9 @@ module SolidObjects
     # @rbs () -> Time
     def database_now: () -> Time
 
+    # @rbs () -> Time
+    def database_clock_now: () -> Time
+
     # @rbs () { () -> untyped } -> untyped
     def with_lock_retry: () { () -> untyped } -> untyped
 

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

@@ -0,0 +1,23 @@
+# Generated from lib/solid_objects/effect_payload.rb with RBS::Inline
+
+module SolidObjects
+  module EffectPayload
+    # @rbs [Arguments] (effect_id: String, arguments: Arguments) -> effect_retired_payload[Arguments]
+    def self.retired: [Arguments] (effect_id: String, arguments: Arguments) -> effect_retired_payload[Arguments]
+
+    # @rbs [Arguments, Result] (effect_id: String, arguments: Arguments, result: Result) -> effect_completed_recovery_payload[Arguments, Result]
+    def self.recovery_completed: [Arguments, Result] (effect_id: String, arguments: Arguments, result: Result) -> effect_completed_recovery_payload[Arguments, Result]
+
+    # @rbs (effect_id: String, outcome: effect_observation_outcome) -> effect_observation_payload
+    def self.recovery_observation: (effect_id: String, outcome: effect_observation_outcome) -> effect_observation_payload
+
+    # @rbs [Arguments, Result] (effect_id: String, arguments: Arguments, result: Result) -> effect_success_payload[Arguments, Result]
+    def self.success: [Arguments, Result] (effect_id: String, arguments: Arguments, result: Result) -> effect_success_payload[Arguments, Result]
+
+    # @rbs [Arguments] (effect_id: String, arguments: Arguments, error: effect_error) -> effect_failure_payload[Arguments]
+    def self.failure: [Arguments] (effect_id: String, arguments: Arguments, error: effect_error) -> effect_failure_payload[Arguments]
+
+    # @rbs (Exception) -> effect_error
+    def self.error: (Exception) -> effect_error
+  end
+end

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

@@ -0,0 +1,41 @@
+# Generated from lib/solid_objects/effect_recovery_coordinator.rb with RBS::Inline
+
+module SolidObjects
+  module EffectRecoveryOutcome
+    RETIRED: "retired"
+
+    DEFERRED: "deferred"
+
+    PENDING: "pending"
+
+    COMPLETED: "completed"
+
+    DEAD: "dead"
+
+    ALREADY_RETIRED: "already_retired"
+
+    MISSING: "missing"
+  end
+
+  class EffectRecoveryCoordinator
+    # @rbs (instance: Instance, intents: Array[Actor::EffectRecoveryIntent]) -> void
+    def check: (instance: Instance, intents: Array[Actor::EffectRecoveryIntent]) -> void
+
+    # @rbs () -> void
+    def recover_available: () -> void
+
+    private
+
+    # @rbs () -> ActiveRecord::Relation[EffectRecovery]
+    def recovery_candidates: () -> ActiveRecord::Relation[EffectRecovery]
+
+    # @rbs (instance: Instance, intent: Actor::EffectRecoveryIntent, recovery: EffectRecovery, effect: Effect?, owners: Hash[String, Process], now: Time) -> void
+    def check_one: (instance: Instance, intent: Actor::EffectRecoveryIntent, recovery: EffectRecovery, effect: Effect?, owners: Hash[String, Process], now: Time) -> void
+
+    # @rbs (effect: Effect?, recovery: EffectRecovery, owners: Hash[String, Process], now: Time) -> String
+    def observe: (effect: Effect?, recovery: EffectRecovery, owners: Hash[String, Process], now: Time) -> String
+
+    # @rbs (instance: Instance, effect: Effect, recovery: EffectRecovery, now: Time) -> Message
+    def retire: (instance: Instance, effect: Effect, recovery: EffectRecovery, now: Time) -> Message
+  end
+end

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

@@ -0,0 +1,38 @@
+# Generated from lib/solid_objects/process_heartbeat.rb with RBS::Inline
+
+module SolidObjects
+  class ProcessHeartbeat
+    @process_registry: ProcessRegistry
+
+    @mutex: Thread::Mutex
+
+    @condition: Thread::ConditionVariable
+
+    @stopped: bool
+
+    @thread: Thread?
+
+    # @rbs (process_registry: ProcessRegistry) -> void
+    def initialize: (process_registry: ProcessRegistry) -> void
+
+    # @rbs () -> void
+    def start: () -> void
+
+    # @rbs () -> void
+    def stop: () -> void
+
+    private
+
+    attr_reader process_registry: untyped
+
+    attr_reader mutex: untyped
+
+    attr_reader condition: untyped
+
+    # @rbs (Exception) -> void
+    def report_failure: (Exception) -> void
+
+    # @rbs () -> bool
+    def wait_for_interval: () -> bool
+  end
+end

data/sig/generated/models/solid_objects/effect_recovery.rbs

@@ -0,0 +1,6 @@
+# Generated from app/models/solid_objects/effect_recovery.rb with RBS::Inline
+
+module SolidObjects
+  class EffectRecovery < Record
+  end
+end

data/sig/public/effect_payload.rbs

@@ -0,0 +1,33 @@
+module SolidObjects
+  type effect_handle = { "effect_id" => String }
+
+  type effect_retired_payload[Arguments] = {
+    "effect_id" => String, "arguments" => Arguments, "outcome" => "retired"
+  }
+
+  type effect_completed_recovery_payload[Arguments, Result] = {
+    "effect_id" => String, "arguments" => Arguments, "outcome" => "completed", "result" => Result
+  }
+
+  type effect_observation_outcome = "deferred" | "pending" | "dead" | "already_retired" | "missing"
+  type effect_observation_payload = { "effect_id" => String, "outcome" => effect_observation_outcome }
+  type effect_recovery_payload[Arguments, Result] = effect_retired_payload[Arguments] | effect_completed_recovery_payload[Arguments, Result] | effect_observation_payload
+
+  type effect_error = {
+    "class" => String?,
+    "message" => String,
+    "backtrace" => Array[String]
+  }
+
+  type effect_failure_payload[Arguments] = {
+    "effect_id" => String,
+    "arguments" => Arguments,
+    "error" => effect_error
+  }
+
+  type effect_success_payload[Arguments, Result] = {
+    "effect_id" => String,
+    "arguments" => Arguments,
+    "result" => Result
+  }
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: solid_objects
 version: !ruby/object:Gem::Version
-  version: 0.14.6
+  version: 0.15.0
 platform: ruby
 authors:
 - Lucas Carlson
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-12 00:00:00.000000000 Z
+date: 2026-09-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actioncable
@@ -303,6 +303,7 @@ files:
 - app/models/solid_objects/claimed_message.rb
 - app/models/solid_objects/dead_letter.rb
 - app/models/solid_objects/effect.rb
+- app/models/solid_objects/effect_recovery.rb
 - app/models/solid_objects/instance.rb
 - app/models/solid_objects/message.rb
 - app/models/solid_objects/process.rb
@@ -330,6 +331,7 @@ files:
 - db/migrate/20260805000000_create_solid_objects_tables.rb
 - db/migrate/20260806000000_add_state_revision_to_solid_objects_instances.rb
 - db/migrate/20260813000000_rename_message_dispatch_columns.rb
+- db/migrate/20260915000000_add_solid_objects_effect_recoveries.rb
 - docs/adr/0001-postgresql-backend.md
 - docs/adr/0002-jsonb-actor-state.md
 - docs/adr/0003-mailbox-ordering.md
@@ -350,6 +352,7 @@ files:
 - docs/dashboard.md
 - docs/database-schema.md
 - docs/development.md
+- docs/effect-recovery.md
 - docs/fit.md
 - docs/implementation-plan.md
 - docs/local-testing.md
@@ -389,6 +392,7 @@ files:
 - lib/solid_objects/actor_channel.rb
 - lib/solid_objects/actor_definition.rb
 - lib/solid_objects/actor_registry.rb
+- lib/solid_objects/actor_signatures.rb
 - lib/solid_objects/actor_snapshot.rb
 - lib/solid_objects/actor_view.rb
 - lib/solid_objects/administration.rb
@@ -416,6 +420,8 @@ files:
 - lib/solid_objects/doctor.rb
 - lib/solid_objects/dom_identity.rb
 - lib/solid_objects/effect_executor.rb
+- lib/solid_objects/effect_payload.rb
+- lib/solid_objects/effect_recovery_coordinator.rb
 - lib/solid_objects/effect_registry.rb
 - lib/solid_objects/engine.rb
 - lib/solid_objects/errors.rb
@@ -431,6 +437,7 @@ files:
 - lib/solid_objects/operation_dispatcher.rb
 - lib/solid_objects/payload_broadcast.rb
 - lib/solid_objects/polling_backoff.rb
+- lib/solid_objects/process_heartbeat.rb
 - lib/solid_objects/process_pruner.rb
 - lib/solid_objects/process_registry.rb
 - lib/solid_objects/reference.rb
@@ -478,6 +485,7 @@ files:
 - sig/generated/lib/solid_objects/actor_channel.rbs
 - sig/generated/lib/solid_objects/actor_definition.rbs
 - sig/generated/lib/solid_objects/actor_registry.rbs
+- sig/generated/lib/solid_objects/actor_signatures.rbs
 - sig/generated/lib/solid_objects/actor_snapshot.rbs
 - sig/generated/lib/solid_objects/actor_view.rbs
 - sig/generated/lib/solid_objects/administration.rbs
@@ -505,6 +513,8 @@ files:
 - sig/generated/lib/solid_objects/doctor.rbs
 - sig/generated/lib/solid_objects/dom_identity.rbs
 - sig/generated/lib/solid_objects/effect_executor.rbs
+- sig/generated/lib/solid_objects/effect_payload.rbs
+- sig/generated/lib/solid_objects/effect_recovery_coordinator.rbs
 - sig/generated/lib/solid_objects/effect_registry.rbs
 - sig/generated/lib/solid_objects/engine.rbs
 - sig/generated/lib/solid_objects/errors.rbs
@@ -520,6 +530,7 @@ files:
 - sig/generated/lib/solid_objects/operation_dispatcher.rbs
 - sig/generated/lib/solid_objects/payload_broadcast.rbs
 - sig/generated/lib/solid_objects/polling_backoff.rbs
+- sig/generated/lib/solid_objects/process_heartbeat.rbs
 - sig/generated/lib/solid_objects/process_pruner.rbs
 - sig/generated/lib/solid_objects/process_registry.rbs
 - sig/generated/lib/solid_objects/reference.rbs
@@ -555,12 +566,14 @@ files:
 - sig/generated/models/solid_objects/claimed_message.rbs
 - sig/generated/models/solid_objects/dead_letter.rbs
 - sig/generated/models/solid_objects/effect.rbs
+- sig/generated/models/solid_objects/effect_recovery.rbs
 - sig/generated/models/solid_objects/instance.rbs
 - sig/generated/models/solid_objects/message.rbs
 - sig/generated/models/solid_objects/process.rbs
 - sig/generated/models/solid_objects/ready_message.rbs
 - sig/generated/models/solid_objects/record.rbs
 - sig/generated/models/solid_objects/reminder.rbs
+- sig/public/effect_payload.rbs
 - sig/support/framework.rbs
 - web/assets/javascripts/application.js
 - web/assets/javascripts/charts.js