solid_objects 0.14.6 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0616851aa1c44a26313dac95fa3f868324910a64a7023435d2c2b6aed83b7610'
-  data.tar.gz: b54b99a40ee18b68f7d6b7f21eb9879c92a867b0715a52647f4f58b4f35997d9
+  metadata.gz: 30a65b9701ec2d566a8d62c2ee428ec61cbfb5bc24d1390905a46943594b78cf
+  data.tar.gz: 39daa8fe6b2586902eee4e9bd6fbdeef4e2666651e707d647a91e5644243bb79
 SHA512:
-  metadata.gz: 5a1a03e584ad3305114993f1898294ebcc719330d2ea6466aa29b38b218bae50fca92394cc57dac95dd8f584da6c506a57f7c145d4238ed2c06e0411a93fa4a8
-  data.tar.gz: 45b4818bc0beb1de4697155bd438c58bc3432e2d40e93c1deb6ff6db5c295d54fe9994e021ff5f7167564a3444fd2b8918b669f2dc550a88985b53e57f55d96c
+  metadata.gz: 6035b50982322dc2d90c6a6c286dc4ea626402003389f6bfdb66d26fdccb1aa4418cc088accedba0030bafa31e2eb4bb699203c0c2f608ba6e5849c4946f11b3
+  data.tar.gz: 43615ab44e86f76db4818a89a0d16971a55c3de959331675aa6d47640ea79db7f3d386c3ce4eefdae9a9c3fdce7aa2527f21754a67a4ab0cede9d45cefb09851

data/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.15.0 - 2026-09-15
+
+- Maintain effect-owner heartbeats during long-running handlers, completion, and
+  failure handling, so healthy external I/O cannot trigger abandoned recovery.
+  Report failed heartbeat updates and retry on the next configured interval
+  without consuming effect attempts.
+- Return a stable effect handle from every `emit`. Wrappers must return it;
+  operations relying on an implicit `nil` result should return `nil` explicitly.
+- Add abandoned effect recovery with `on_recovery`, optional `on_status`, staged
+  `request_effect_recovery`, and an extending `recovery_timeout` in seconds.
+  Retirement and durable callbacks share the claim-locking transaction. Add
+  frozen outcome constants and public RBS envelopes. Install the new recovery
+  binding migration before upgrading runtime processes. External actions still
+  require idempotency; retirement does not cancel an old handler or remote call.
+
+## 0.14.7 - 2026-09-14
+
+- Publish RBS contracts for effect callback envelopes and Ruby error summaries.
+  Check the runtime constructors and packaged consumer signatures strictly,
+  preserving ordinary hashes, keyword callbacks, serialization, and retries.
+- Add optional actor-specific RBS generation for staged schedule/transmit calls
+  and effect callback names. Reuse application-declared operation argument types
+  without changing Ruby dispatch, runtime validation, or global effect registries.
+
 ## 0.14.6 - 2026-09-12
 
 - Preserve committed turns when an Active Record after-commit callback raises.

data/README.md

@@ -149,6 +149,7 @@ SQL and should be allowed to enjoy that.
 - One successful turn commits actor state and staged reminders, messages, effects, commit actions, and broadcasts together.
 - Fencing prevents stale Ruby code from committing, but it cannot stop that code from continuing to run.
 - External effects can repeat and must deduplicate with the stable effect ID or another durable idempotency key.
+- [Effect recovery](docs/effect-recovery.md) uses stable `emit` handles and `on_recovery` to retire abandoned work atomically with a durable actor callback.
 - Actor handlers may read application records but cannot write them directly. Use `commit_action` for bounded same-database writes and `emit` for external I/O.
 - `async`, reminders, effects, and broadcasts need `bundle exec solid_objects start`. Pending work remains in SQL while it is down.
 - One hot identity is intentionally sequential. There are no transactions across actor identities.

data/Rakefile

@@ -14,7 +14,7 @@ task :rbs do
   FileUtils.rm_rf(File.expand_path("sig/generated", __dir__))
   sh "bundle exec rbs-inline --base lib --base app --output sig/generated lib app"
   FileUtils.rm_f(File.expand_path("sig/generated/lib/generators/solid_objects/templates/solid_objects.rbs", __dir__))
-  sh "bundle exec rbs -I sig/generated -I sig/support validate"
+  sh "bundle exec rbs -I sig/generated -I sig/support -I sig/public validate"
 end
 
 desc "Run Standard Ruby"

data/app/models/solid_objects/effect_recovery.rb

@@ -0,0 +1,10 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  class EffectRecovery < Record
+    self.table_name = SolidObjects.table_name(:effect_recoveries)
+    self.primary_key = "effect_id"
+
+    belongs_to :instance, class_name: "SolidObjects::Instance"
+  end
+end

data/benchmark/support.rb

@@ -428,9 +428,11 @@ module SolidObjectsBenchmark
       require_relative "../db/migrate/20260805000000_create_solid_objects_tables"
       require_relative "../db/migrate/20260806000000_add_state_revision_to_solid_objects_instances"
       require_relative "../db/migrate/20260813000000_rename_message_dispatch_columns"
+      require_relative "../db/migrate/20260915000000_add_solid_objects_effect_recoveries"
       CreateSolidObjectsTables.new.migrate(:up)
       AddStateRevisionToSolidObjectsInstances.new.migrate(:up)
       RenameMessageDispatchColumns.new.migrate(:up)
+      AddSolidObjectsEffectRecoveries.new.migrate(:up)
     end
 
     # @rbs () -> void
@@ -444,6 +446,7 @@ module SolidObjectsBenchmark
         claimed_message
         reminder
         effect
+        effect_recovery
         broadcast
         dead_letter
       ].each do |model|

data/db/migrate/20260915000000_add_solid_objects_effect_recoveries.rb

@@ -0,0 +1,17 @@
+# rbs_inline: enabled
+
+class AddSolidObjectsEffectRecoveries < ActiveRecord::Migration[7.1]
+  # @rbs () -> void
+  def change
+    create_table SolidObjects.table_name(:effect_recoveries), id: :string, limit: 36, primary_key: :effect_id do |definition|
+      definition.references :instance, null: false,
+        foreign_key: { to_table: SolidObjects.table_name(:instances), on_delete: :cascade, name: "fk_so_effect_recoveries_instance" }
+      definition.string :recovery_operation, limit: 191
+      definition.string :status_operation, limit: 191
+      definition.float :recovery_timeout
+      definition.datetime :retired_at, precision: 6
+      definition.timestamps precision: 6, null: false
+      definition.check_constraint "recovery_timeout IS NULL OR recovery_timeout > 0", name: "chk_so_effect_recoveries_timeout"
+    end
+  end
+end

data/docs/architecture.md

@@ -443,6 +443,10 @@ a dead letter.
 
 `emit` creates a staged effect:
 
+Typed applications can generate [actor-specific RBS signatures](development.md#actor-specific-dispatch-signatures)
+to check callback names and staged `schedule`/`transmit` calls without changing
+their Ruby syntax. Effect and commit-action registry names remain independent.
+
 ```ruby
 emit(
   :charge_payment,
@@ -483,6 +487,50 @@ and `result:`. A failure callback receives `effect_id:`, `arguments:`, and
 `error:`, so an actor can correlate concurrent effects without storing a
 separate callback ledger.
 
+### Typing your on_failure handler
+
+The gem ships `SolidObjects::effect_error`,
+`SolidObjects::effect_failure_payload[Arguments]`, and
+`SolidObjects::effect_success_payload[Arguments, Result]` as public RBS aliases.
+They describe the existing string-keyed hashes; they are not Ruby wrapper classes.
+See [signature loading](development.md#public-effect-payload-signatures) for Steep setup.
+
+For an actor with `generation` and `status` attributes, declare the callback keywords
+in the application's RBS:
+
+```rbs
+class ChatRun < SolidObjects::Actor
+  type run_arguments = { "generation" => Integer }
+  def fail_turn: (effect_id: String, arguments: run_arguments, error: SolidObjects::effect_error) -> void
+end
+```
+
+```ruby
+def fail_turn(effect_id:, arguments:, error:)
+  return unless arguments["generation"] == generation
+
+  self.status = "failed"
+end
+```
+
+Record access with `arguments["generation"]` retains its declared `Integer` type.
+The callback receives top-level keywords, while nested arguments and error keys
+remain strings. The failure envelope requires `"effect_id"`, `"arguments"`, and
+`"error"`; the success envelope replaces `"error"` with `"result"`. Empty original
+arguments remain `{}`, and a success result may be `nil` or any supported JSON value.
+Ruby errors contain `"class"` (`String?`, including anonymous exception classes),
+`"message"` (`String`, limited to 8,192 bytes), and `"backtrace"` (`Array[String]`,
+limited to 50 entries and possibly empty).
+
+Applications supply the generic argument/result types to describe their serialized
+JSON values. These aliases do not infer or validate independently registered effect
+handlers. Their type parameters are deliberately unconstrained: Ruby serialization
+accepts and normalizes values such as symbols, and RBS cannot express that conversion
+as a generic bound. The constructors and consumer fixtures are checked with strict
+Steep diagnostics. JavaScript exposes equivalent contracts with its existing
+camelCase ID and `{ name, message }` error shape in
+[solid-objects-js#47](https://github.com/cardmagic/solid-objects-js/issues/47).
+
 A commit action is registered the same way and runs inside the short fenced
 transaction:
 

data/docs/development.md

@@ -103,6 +103,116 @@ bundle exec rake rbs
 
 This follows the inline convention used by `cardmagic/classifier`.
 
+### Public effect payload signatures
+
+The packaged `sig/public` directory owns the reusable effect payload aliases and
+survives `rake rbs` regeneration. A host application's Steep target can load the
+installed gem's complete signature tree alongside its own signatures:
+
+```ruby
+target :app do
+  library "solid_objects"
+  signature "sig"
+  check "app/actors"
+  configure_code_diagnostics(Diagnostic::Ruby.strict)
+end
+```
+
+This requires no internal runtime imports. See the
+[typed callback example](architecture.md#typing-your-on_failure-handler).
+The gem's strict payload target checks the actual constructors; its packaged
+consumer test also verifies that missing keys and incorrect field types fail.
+
+### Actor-specific dispatch signatures
+
+Typed applications can opt into `SolidObjects::ActorSignatures` to check ordinary
+`schedule`, `transmit`, and effect callback names inside actor methods. Add `rbs`
+and `steep` to the application's development dependencies. This tool is loaded
+explicitly and is not required by workers or ordinary Ruby applications.
+
+Declare application operation types first, including inherited operations and
+block-defined `message` operations. Inline RBS can generate this input, or keep
+handwritten declarations in a separate directory such as `sig/actors`:
+
+```rbs
+class ChatRun < SolidObjects::Actor
+  def recover_if_stuck: (generation: Integer) -> nil
+  def fail_turn: (effect_id: String, arguments: Hash[String, untyped], error: Hash[String, untyped]) -> nil
+  def start: () -> nil
+end
+```
+
+After loading the application's actor classes, generate a separate output file:
+
+```ruby
+require "solid_objects/actor_signatures"
+
+Rails.application.reloader.wrap do
+  signatures = SolidObjects::ActorSignatures.generate(
+    actors: [ChatRun],
+    signatures: [Rails.root.join("sig/actors").to_s]
+  )
+  FileUtils.mkdir_p(Rails.root.join("sig/generated"))
+  File.write(Rails.root.join("sig/generated/solid_objects.rbs"), signatures)
+end
+```
+
+Run that script with `bin/rails runner` during development or CI. Outside Rails,
+require the actor definitions and call `generate` directly. The generator returns
+a string and does not write files, execute actor operations, start workers, or run
+migrations. Rails boot follows the application's normal loading configuration;
+the explicit actor list resolves its autoloaded classes within the reloader boundary.
+Keep generated output out of the input signature paths, and regenerate after a
+message is renamed or removed. Output is deterministic; handwritten signatures
+remain separate.
+
+Load the gem and both application signature directories in `Steepfile`:
+
+```ruby
+target :actors do
+  library "solid_objects"
+  signature "sig/actors"
+  signature "sig/generated"
+  check "app/actors"
+  configure_code_diagnostics(Diagnostic::Ruby.strict)
+end
+```
+
+The usual Ruby code now passes Steep without a dispatcher cast:
+
+```ruby
+schedule(at: Time.now, key: "watchdog").recover_if_stuck(generation: 1)
+transmit.recover_if_stuck(generation: 1)
+emit :run_model, generation: 1, on_failure: :fail_turn
+```
+
+Misspelled operations/callbacks, queries, attributes, private methods, infrastructure
+methods, and incorrect keyword arguments fail the strict check. Both string and
+symbol callback literals work. Staging returns `nil` even when an operation's own
+return type differs. Effect and commit-action names remain global registry names;
+registry contract inference is separate work.
+
+Reflection supplies message names only. Values come from declared RBS signatures;
+missing signatures and positional/block arguments are rejected. Block-defined
+messages require explicit method declarations in RBS; annotate their block-local
+values separately when checking the block body. Generic actor classes currently
+require application-owned dispatcher signatures. The generator preserves method
+overloads and method type parameters.
+
+Deliberately dynamic names can use Ruby's explicit dynamic dispatch:
+
+```ruby
+schedule(at: Time.now).public_send(operation_name, generation: generation)
+public_send(:emit, :run_model, on_failure: callback_name, generation: generation)
+```
+
+Those calls opt out of name/argument checking and retain the existing runtime
+validation. Ordinary calls on the generated dispatcher have no string-name fallback.
+`send_to`, `Reference#async`, direct calls, and queries retain their existing
+signatures and runtime behavior; this generator does not provide complete reference
+typing or Sorbet/Tapioca actor-specific RBI generation. The corresponding TypeScript
+work is tracked in [solid-objects-js#46](https://github.com/cardmagic/solid-objects-js/issues/46).
+
 ## Formatting and security
 
 ```bash

data/docs/effect-recovery.md

@@ -0,0 +1,203 @@
+# Effect recovery coordination
+
+`emit` returns a JSON-serializable handle containing the public `effect_id`.
+Registering `on_recovery` opts the effect into retirement when its owner has
+stopped heartbeating. `on_status` is optional and receives responses only to
+explicit `request_effect_recovery(handle)` intents. Normal success and failure
+retain their existing callbacks.
+
+## Watchdog using supported APIs
+
+```ruby
+class ReportExport < SolidObjects::Actor
+  attribute :revision, default: 0
+  attribute :export_effect, default: nil
+  attribute :artifact_key, default: ""
+  attribute :applied_effect_id, default: nil
+
+  def start
+    self.revision += 1
+    self.export_effect = emit(:build_report,
+      revision: revision,
+      on_success: :export_finished,
+      on_failure: :export_failed,
+      on_recovery: :recover_export,
+      on_status: :inspect_export,
+      recovery_timeout: 120)
+    schedule(at: Time.now + 30, key: "export-watchdog").watchdog
+    nil
+  end
+
+  def watchdog
+    request_effect_recovery(export_effect) if export_effect
+  end
+
+  def recover_export(effect_id:, arguments:, outcome:)
+    return unless effect_id == export_effect&.fetch("effect_id")
+    return unless arguments.fetch("revision") == revision
+
+    start
+  end
+
+  def export_finished(effect_id:, arguments:, result:)
+    apply_export_result(effect_id:, arguments:, result:)
+  end
+
+  def export_failed(effect_id:, arguments:, error:)
+  end
+
+  def inspect_export(effect_id:, outcome:, arguments: nil, result: nil)
+    return unless effect_id == export_effect&.fetch("effect_id")
+
+    case outcome
+    when SolidObjects::EffectRecoveryOutcome::COMPLETED
+      apply_export_result(effect_id:, arguments:, result:)
+    when SolidObjects::EffectRecoveryOutcome::DEFERRED, SolidObjects::EffectRecoveryOutcome::PENDING
+      schedule(at: Time.now + 30, key: "export-watchdog").watchdog
+    end
+  end
+
+  private
+
+  def apply_export_result(effect_id:, arguments:, result:)
+    return unless effect_id == export_effect&.fetch("effect_id")
+    return unless arguments.fetch("revision") == revision
+    return if applied_effect_id == effect_id
+
+    self.artifact_key = result.fetch("artifact_key")
+    self.applied_effect_id = effect_id
+  end
+end
+```
+
+Register `build_report` through the ordinary effect registry. Its successful
+result in this example is `{ "artifact_key" => "reports/example.pdf" }`.
+The library builds the retirement payload, including `"outcome" => "retired"`;
+the effect handler does not return that outcome itself. Ruby actor operations
+receive keywords. `recover_export` needs handle/revision guards but no outcome
+guard because only a new retirement invokes it. The same guarded result helper
+handles success and completed-status repair, preventing duplicate application.
+Only recovery emits a replacement; status observations never do.
+
+The watchdog is optional: `on_recovery` alone enables automatic retirement.
+`on_status` alone does not enable retirement, polling, or subscriptions. Explicit
+checks require both bindings persisted by `emit` and cannot replace either.
+
+## Public envelopes and timeout
+
+`SolidObjects::effect_handle` describes `{ "effect_id" => String }`.
+`SolidObjects::effect_retired_payload[Arguments]` requires the effect ID, original
+arguments, and `"outcome" => "retired"`. Status uses
+`SolidObjects::effect_recovery_payload[Arguments, Result]`, a record union.
+Every variant has an effect ID; retired and completed require original arguments;
+only completed has a recorded result (including `nil`). Other Ruby observations
+contain only the effect ID and outcome.
+
+Strict packaged-consumer tests verify the constant literals and individual
+records. Steep 2.0 does not narrow this string-keyed record union after comparing
+`payload["outcome"]` with `COMPLETED`; accessing `result` through the union still
+fails its return-type check. Use the concrete completed/retired record in typed
+helpers after validating the discriminator, with an explicit type assertion if
+needed. The library retains precise records rather than weakening them to an
+untyped hash. Ordinary Ruby keyword dispatch needs no payload hydration.
+
+| Frozen `SolidObjects::EffectRecoveryOutcome` constant | Wire value | Meaning |
+| --- | --- | --- |
+| `RETIRED` | `"retired"` | This check retired the effect; separate recovery owns replacement. |
+| `DEFERRED` | `"deferred"` | Fresh owner; preserve its claim and attempts. |
+| `PENDING` | `"pending"` | Initial execution or retry remains with the scheduler. |
+| `COMPLETED` | `"completed"` | Original arguments and recorded result are available. |
+| `DEAD` | `"dead"` | Preserve terminal failure and its existing callback. |
+| `ALREADY_RETIRED` | `"already_retired"` | Earlier retirement; no additional recovery notification. |
+| `MISSING` | `"missing"` | Owned binding exists but effect data was pruned. |
+
+`recovery_timeout` must be positive finite seconds and requires `on_recovery`.
+Fractional durations are allowed. Omission uses the current runtime
+`process_alive_threshold`, normally 60 seconds. Smaller positive values are
+floored at that runtime threshold; changing configuration changes the effective
+floor even for existing effects. Database lookup errors surface as errors,
+never as missing/stale observations.
+
+Effect workers maintain their process heartbeat while the handler waits on
+external I/O and while committing success or failure. A long-running healthy
+handler therefore remains protected beyond the recovery timeout. This requires
+an available database connection for the heartbeat, as well as runtime threads
+that can continue running.
+
+Failed updates emit `solid_objects.process.heartbeat_failed` and retry at the
+configured heartbeat interval without consuming effect attempts. If an outage
+lasts beyond the freshness window, recovery can still be permitted; retries do
+not cancel external work or extend the configured window.
+
+## Compatibility and installation
+
+Upgrade all effect workers and process cleanup roles before emitting effects
+with recovery enabled. Older runtimes do not honor the persisted bindings or
+the new lock protocol.
+
+Run `solid_objects:install:migrations` and your application's normal migration
+process before starting upgraded workers. The additive migration creates the
+durable binding table; it does not change existing effect status constraints.
+
+`emit` now returns its handle, including without recovery options. Callers may
+ignore it. Wrappers must return `super`; operations whose last expression used
+to be `emit` may now return the handle to callers. End those operations with
+`nil` if their previous result must remain unchanged. The return-value change is
+intentional and is not strictly backward compatible.
+
+## Transaction and lock protocol
+
+Emission, actor state, the effect, and its recovery binding share the actor's
+fenced commit. An explicit check executes on that same connection. Automatic
+recovery performs one independent library transaction per candidate, with no
+application transaction waiting on a second connection.
+
+The lock order is originating instance, effect rows ordered by public effect
+ID, recovery binding rows in the same order, then owner processes ordered by ID.
+Completion and failure must acquire the instance before the effect. Pending
+claims lock only their effect and do not subsequently acquire an instance lock.
+Mailbox insertion reuses the instance lock already held by the decision.
+Multiple checks in one actor commit lock all their effects and bindings before
+locking any processes. Unlocked candidate reads are hints, never decisions.
+
+Automatic passes prefilter owner freshness and the effective per-effect timeout
+using database time, and visit at most `claim_scan_limit` stale candidates. Fresh
+actors and owners are not locked, including owners protected by extended grace.
+Remaining stale effects are revisited on later polls. Every candidate still
+undergoes the authoritative locked recheck, and successful retirement announces
+the committed mailbox work through the existing wake-up mechanism.
+
+The decision samples database wall time after obtaining the owner lock. The
+effective timeout is the larger of the runtime's `process_alive_threshold` and
+the effect's persisted `recovery_timeout`, in seconds. A heartbeat newer than
+the cutoff is fresh; equality is stale. A stopped or draining process with
+fresh heartbeat evidence still protects an opted-in effect until that timeout.
+Cleanup preserves opted-in claims, and process pruning excludes processes that
+still own effects. Later effect polling and process cleanup revisit deferred
+effects without resetting their last heartbeat.
+
+Retirement stores a durable `retired_at` in `effect_recoveries` and moves the
+effect into the existing terminal `completed` storage state, clearing its
+claim. The recovery record distinguishes retirement from successful completion;
+no success callback is generated. All recovery observations consult that record
+before interpreting the effect row. A late completion or failure is rejected by
+the existing processing/claim fence. This representation avoids rewriting the
+existing effect-status constraint across adapters.
+
+The retirement record and the recovery mailbox message commit atomically. A
+winning explicit check additionally enqueues its status response after the
+retirement notification. Failure to insert either message rolls back the whole
+decision. Retirement is deduplicated per effect; check responses use separate
+per-request idempotency keys. Wake-up signals are delivery hints after commit.
+
+Recovery bindings survive effect/message pruning and remain until the originating
+instance is destroyed or pruned. They do not prevent normal message or instance
+retention. Within that lifetime, a removed non-retired effect reports `missing`
+and a retirement record reports `already_retired`. A handle without an owned
+binding raises an error, without disclosing another actor's state or recreating
+a destroyed actor. Status-response message idempotency follows normal mailbox
+retention; callers cannot supply or reuse internal check request IDs.
+
+An owner heartbeat measures process liveness, not effect progress. Retirement
+does not cancel the old handler or prove a remote request stopped. External
+actions still require idempotency across retries and replacement generations.

data/docs/operations.md

@@ -69,6 +69,12 @@ Rails schema migrations and actor state migrations are separate concerns.
 
 ### Host application tooling
 
+RBS/Steep applications can generate
+[actor-specific dispatch signatures](development.md#actor-specific-dispatch-signatures)
+for reminders, transmit calls, and effect callback names. This is optional development
+tooling; generated signatures do not change runtime dispatch. The generator does
+not supply equivalent Sorbet/Tapioca actor-specific types.
+
 Installed engine migrations are copied as
 `db/migrate/*_create_solid_objects_tables.solid_objects.rb`. If the host enables
 `Rails/CreateTableWithTimestamps`, exclude engine-owned migrations rather than

data/docs/reminders.md

@@ -39,6 +39,14 @@ raises, and nothing is logged except a `solid_objects.reminder.replaced` event.
 
 ## An alarm per item, with `key:`
 
+For watchdogs paired with an effect's give-up callback, see
+[typing your `on_failure` handler](architecture.md#typing-your-on_failure-handler)
+to retain the original argument types without repeating the error hash contract.
+
+For static checking of watchdog operation names and keyword arguments, opt into
+[actor-specific RBS signatures](development.md#actor-specific-dispatch-signatures).
+The Ruby `schedule(...).recover_if_stuck(generation: ...)` syntax stays the same.
+
 Pass `key:` when an actor is waiting on several things at once. The key is your
 own identifier for the item, and it names that item's alarm, so each item gets
 one:

data/docs/roadmap.md

@@ -14,6 +14,13 @@
   dead letters, and tail retry
 - Transactional effects with success/failure actor messages carrying the
   originally staged arguments for callback correlation
+- Stable `emit` handles and opted-in abandoned effect retirement coordinated
+  with effect claims, with atomic recovery/status mailbox notifications and
+  per-effect extending heartbeat timeouts and heartbeats throughout long-running
+  effect handlers. See [effect recovery](effect-recovery.md)
+  for the SQL lock protocol, retention boundary, and external idempotency limit.
+- Public RBS effect success/failure envelopes and error records, checked against
+  the runtime constructors and a packaged consumer with strict Steep diagnostics
 - Actor-to-actor asynchronous outbox delivery. Effects and broadcasts use
   portable status rows with polling indexes and database check constraints on
   status, which works on all three adapters; a future version may add narrow
@@ -65,6 +72,10 @@
   gem's dependencies
 - Inline RBS generation/validation, Steep, Standard Ruby, Solid Queue's exact
   RuboCop policy, and a warning-free Brakeman scan
+- Opt-in actor-specific RBS generation for schedule/transmit keyword arguments
+  and effect callback names, using application declarations and checked consumer
+  fixtures. Dynamic names remain an explicit escape hatch; complete reference
+  typing and actor-specific RBI generation are separate work
 - Compatibility CI across the supported span: Ruby 3.3, 3.4, and 4.0 against
   Rails 7.1, 7.2, 8.0, and 8.1, pinned through `RAILS_VERSION` so the advertised
   range is verified rather than assumed. The compatibility job runs SQLite only;

data/examples/at_least_once/boot.rb

@@ -23,7 +23,7 @@ module AtLeastOnceBoot
     require "solid_objects/database_adapter"
     %w[
       record process instance message ready_message claimed_message
-      reminder effect broadcast dead_letter
+      reminder effect effect_recovery broadcast dead_letter
     ].each { |model| require File.join(ROOT, "app/models/solid_objects", model) }
 
     SolidObjects.configuration.authorize_message = ->(**) { true }
@@ -40,8 +40,10 @@ module AtLeastOnceBoot
     require File.join(ROOT, "db/migrate/20260805000000_create_solid_objects_tables")
     require File.join(ROOT, "db/migrate/20260806000000_add_state_revision_to_solid_objects_instances")
     require File.join(ROOT, "db/migrate/20260813000000_rename_message_dispatch_columns")
+    require File.join(ROOT, "db/migrate/20260915000000_add_solid_objects_effect_recoveries")
     CreateSolidObjectsTables.new.migrate(:up)
     AddStateRevisionToSolidObjectsInstances.new.migrate(:up)
     RenameMessageDispatchColumns.new.migrate(:up)
+    AddSolidObjectsEffectRecoveries.new.migrate(:up)
   end
 end