solid_objects 0.14.6 → 0.14.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0616851aa1c44a26313dac95fa3f868324910a64a7023435d2c2b6aed83b7610'
-  data.tar.gz: b54b99a40ee18b68f7d6b7f21eb9879c92a867b0715a52647f4f58b4f35997d9
+  metadata.gz: d36e77947a8de94216c9174cc3a34a878803bdf242efa0b10f6067d48b4e7cda
+  data.tar.gz: 178955e77093552df5569ee5c0badfb6035a51a479c7bcfbd1025465ac5947a4
 SHA512:
-  metadata.gz: 5a1a03e584ad3305114993f1898294ebcc719330d2ea6466aa29b38b218bae50fca92394cc57dac95dd8f584da6c506a57f7c145d4238ed2c06e0411a93fa4a8
-  data.tar.gz: 45b4818bc0beb1de4697155bd438c58bc3432e2d40e93c1deb6ff6db5c295d54fe9994e021ff5f7167564a3444fd2b8918b669f2dc550a88985b53e57f55d96c
+  metadata.gz: 491698862debab8266650dbdc21a86561d3fa7dd51764edd469a7b5173a1b2a24a2542d39a584796d3433a2bc66794d7d5251ebfe73d7c991d539f2a4c92d287
+  data.tar.gz: 705ce841595e49cbc892535afd15fb96b8ac4134bb01a1c92de8d12061a6fe5717b745d989decf82fb1c25a19966b9e50a88afb30a1426c23055e1333c00f2cc

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 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/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/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/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,8 @@
   dead letters, and tail retry
 - Transactional effects with success/failure actor messages carrying the
   originally staged arguments for callback correlation
+- 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 +67,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/lib/solid_objects/actor_signatures.rb

@@ -0,0 +1,80 @@
+# rbs_inline: enabled
+
+require "solid_objects"
+require "rbs"
+require "pathname"
+
+module SolidObjects
+  class ActorSignatures
+    # @rbs (actors: Array[Class], signatures: Array[String]) -> String
+    def self.generate(actors:, signatures:)
+      new(signatures:).generate(actors:)
+    end
+
+    # @rbs @builder: untyped
+
+    # @rbs (signatures: Array[String]) -> void
+    def initialize(signatures:)
+      loader = RBS::EnvironmentLoader.new
+      loader.add(path: Pathname.new(File.expand_path("../../sig", __dir__)))
+      signatures.sort.each { |path| loader.add(path: Pathname.new(path)) }
+      environment = RBS::Environment.from_loader(loader).resolve_type_names
+      @builder = RBS::DefinitionBuilder.new(env: environment)
+    end
+
+    # @rbs (actors: Array[Class]) -> String
+    def generate(actors:)
+      actors.uniq.sort_by { |actor| actor.name.to_s }.map { |actor| actor_signature(actor) }.join("\n")
+    end
+
+    private
+
+    # @rbs (untyped) -> String
+    def actor_signature(actor)
+      unless actor < Actor && actor.name
+        raise ArgumentError, "actor signatures require named SolidObjects::Actor subclasses"
+      end
+
+      name = RBS::TypeName.parse("::#{actor.name}")
+      definition = @builder.build_instance(name)
+      if definition.type_params.any?
+        raise ArgumentError, "generic actor classes require application-owned dispatcher signatures"
+      end
+      messages = actor.definition.messages.keys.sort
+      methods = messages.map do |operation|
+        method = definition.methods[operation]
+        unless method && method.accessibility == :public
+          raise ArgumentError, "declare a public RBS signature for #{actor.name}##{operation}"
+        end
+        types = method.method_types.map { |type| staged_type(type, actor.name, operation).to_s }
+        "    def #{operation}: #{types.join("\n      | ")}"
+      end
+      callback_names = messages.flat_map { |operation| [ operation.inspect, operation.to_s.inspect ] }
+      callbacks = (callback_names + [ "nil" ]).join(" | ")
+      <<~RBS
+        class #{name}
+          interface _SolidObjectsOperations
+        #{methods.join("\n")}
+            def public_send: (Symbol | String, **untyped) -> nil
+          end
+
+          def schedule: (at: Time, ?every: Numeric?, ?missed: Symbol | String, ?key: (String | Symbol | Integer)?) -> #{name}::_SolidObjectsOperations
+          def transmit: () -> #{name}::_SolidObjectsOperations
+          def emit: (Symbol | String, ?on_success: (#{callbacks}), ?on_failure: (#{callbacks}), **untyped) -> nil
+        end
+      RBS
+    end
+
+    # @rbs (untyped, String, Symbol) -> untyped
+    def staged_type(method_type, actor_name, operation)
+      function = method_type.type
+      if !function.is_a?(RBS::Types::Function) || method_type.block ||
+          function.required_positionals.any? || function.optional_positionals.any? ||
+          function.rest_positionals || function.trailing_positionals.any?
+        raise ArgumentError, "#{actor_name}##{operation} must declare keyword-only arguments without a block"
+      end
+
+      method_type.update(type: function.update(return_type: RBS::Types::Bases::Nil.new(location: nil)))
+    end
+  end
+end

data/lib/solid_objects/effect_executor.rb

@@ -184,11 +184,11 @@ module SolidObjects
           effect: locked_effect,
           operation: locked_effect.success_operation,
           outcome: "success",
-          arguments: {
-            "effect_id" => locked_effect.effect_id,
-            "arguments" => locked_effect.arguments,
-            "result" => serialized_result
-          }
+          arguments: EffectPayload.success(
+            effect_id: locked_effect.effect_id,
+            arguments: locked_effect.arguments,
+            result: serialized_result
+          )
         )
         locked_effect.update!(
           status: "completed",
@@ -216,21 +216,17 @@ module SolidObjects
         locked_effect = Effect.lock.find(effect.id)
         verify_claim!(locked_effect)
         dead = locked_effect.attempt_count >= locked_effect.max_attempts
-        error_details = {
-          "class" => error.class.name,
-          "message" => error.message.to_s.byteslice(0, 8_192),
-          "backtrace" => Array(error.backtrace).first(50)
-        }
+        error_details = EffectPayload.error(error)
         if dead
           result_message = enqueue_result_message(
             effect: locked_effect,
             operation: locked_effect.failure_operation,
             outcome: "failure",
-            arguments: {
-              "effect_id" => locked_effect.effect_id,
-              "arguments" => locked_effect.arguments,
-              "error" => error_details
-            }
+            arguments: EffectPayload.failure(
+              effect_id: locked_effect.effect_id,
+              arguments: locked_effect.arguments,
+              error: error_details
+            )
           )
         end
         locked_effect.update!(

data/lib/solid_objects/effect_payload.rb

@@ -0,0 +1,27 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  module EffectPayload
+    class << self
+      # @rbs [Arguments, Result] (effect_id: String, arguments: Arguments, result: Result) -> effect_success_payload[Arguments, Result]
+      def success(effect_id:, arguments:, result:)
+        { "effect_id" => effect_id, "arguments" => arguments, "result" => result }
+      end
+
+      # @rbs [Arguments] (effect_id: String, arguments: Arguments, error: effect_error) -> effect_failure_payload[Arguments]
+      def failure(effect_id:, arguments:, error:)
+        { "effect_id" => effect_id, "arguments" => arguments, "error" => error }
+      end
+
+      # @rbs (Exception) -> effect_error
+      def error(exception)
+        message = exception.message.to_s.byteslice(0, 8_192) # : String
+        {
+          "class" => exception.class.name,
+          "message" => message,
+          "backtrace" => Array(exception.backtrace).first(50)
+        }
+      end
+    end
+  end
+end

data/lib/solid_objects/version.rb

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

data/lib/solid_objects.rb

@@ -55,6 +55,7 @@ require "solid_objects/wake_up_adapters/redis"
 require "solid_objects/wake_up_adapters"
 require "solid_objects/polling_backoff"
 require "solid_objects/effect_registry"
+require "solid_objects/effect_payload"
 require "solid_objects/commit_action_registry"
 require "solid_objects/lease"
 require "solid_objects/lease_renewer"

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/effect_payload.rbs

@@ -0,0 +1,14 @@
+# Generated from lib/solid_objects/effect_payload.rb with RBS::Inline
+
+module SolidObjects
+  module EffectPayload
+    # @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/public/effect_payload.rbs

@@ -0,0 +1,19 @@
+module SolidObjects
+  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.14.7
 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
@@ -389,6 +389,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 +417,7 @@ 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_registry.rb
 - lib/solid_objects/engine.rb
 - lib/solid_objects/errors.rb
@@ -478,6 +480,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 +508,7 @@ 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_registry.rbs
 - sig/generated/lib/solid_objects/engine.rbs
 - sig/generated/lib/solid_objects/errors.rbs
@@ -561,6 +565,7 @@ files:
 - 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