solid_objects 0.14.0 → 0.14.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a64ced341585dcb4b7e9240b2076e1f47a352b4786806c1bec08c10d91c7d187
-  data.tar.gz: 6d53730c69b2f86cde60d3fdb1ffcefe10dd362dc98652b4afe2b367e1134f32
+  metadata.gz: d3b9abc40f188e1ea4964cfffca89e030990948c937a8aca0ec32c19830da272
+  data.tar.gz: 57707f08fc468d705202bbc3f20ddd60bfed4cd3d9153c58b7a06c981051ef93
 SHA512:
-  metadata.gz: acc3e7a6bb436e0dbadf5a38478fc21d3b072f11fcee0cfed26960cba9c1d8eb790a99cf3b065457de8c2ced86d01718c854635d210ba23ffe571e009eab95f7
-  data.tar.gz: 91faab1647c20ba461dcf065612b549b2f6dbd955f2a2222f89a2556d377b99b4a648dbb71ba441ca01ba1281607292f3f21300256ad65f55c821374dac85d7e
+  metadata.gz: 203477264f47ba941dd4a29b08e00ce5e8ccce298fce361beeaed73f54d3fb1edbbd46f05733e44eaacb366301fc1a6128f084024976268e42ce302d6a7aab76
+  data.tar.gz: 1f82eeb81cd282bbf0cdabc3e4346376b21f5688997440a3f6790f3332f2762764d3a3e3a48778629702c0604480e4e0a6380a677d76a106d9f439c466302cf4

data/CHANGELOG.md

@@ -1,5 +1,50 @@
 # Changelog
 
+## 0.14.1 - 2026-08-24
+
+- Register application actors in every process that boots the application.
+  The engine now loads the host application's `app/actors` directories from a
+  `to_prepare` hook, which previously only the `solid_objects start` process
+  did. An actor registers itself as a side effect of its class loading, so a
+  lazily loading web process began with an empty registry. `ActorChannel`
+  looks the actor up by name, and the resulting `UnknownActorType` reached the
+  rescue that rejects the subscription: a Cable subscription for a real actor
+  was rejected in any web process that had not yet rendered that actor, and
+  the page kept a card that never updated. `ComponentsController` resolves the
+  same way through `ActorSnapshot`. `Transmission.receive` already carried a
+  registry-miss retry for this reason, and it stays as a guard for a host that
+  reaches the gem without the engine.
+- Report why a Cable subscription was rejected. Every reject path in
+  `ActorChannel#subscribed` now emits `solid_objects.subscription.rejected`
+  with a `reason`, the actor identity, and the `error_class` where an
+  exception caused it. Five conditions previously collapsed into one silent
+  `reject`, which is invisible from the browser and left nothing in the log to
+  distinguish an unregistered actor type from a tampered token. Exception
+  messages stay out of the payload, because a component or payload failure can
+  carry actor state.
+
+- State where `async` waits when no worker runs. The `async` section of the
+  README and the runtime section of `docs/operations.md` now say that the
+  generator and the migrations start no role, so an application that serves
+  web requests alone leaves the message ready until
+  `bundle exec solid_objects start` runs the roles. The message is durable
+  and waits; it is not lost. `test/integration/background_pickup_test.rb`
+  pins it: the message reads `ready` and the actor state stays empty until a
+  worker runs. This matches solid-objects-js#22, which reported the same gap
+  for `runtime.run(signal)` in the Node package.
+
+- Add `examples/at_least_once` and `bundle exec rake at_least_once`, an
+  executable proof that the at-least-once clause fires and that the
+  documented remedy absorbs it. One actor turn stages an effect that writes
+  to an external sink file. The first effect worker crashes between the sink
+  write and the acknowledgement, and a second worker reclaims the stale
+  effect after the liveness threshold and delivers again. With deduplication
+  off the sink reads 2, both deliveries carrying the same `context.id` at
+  attempts 1 and 2; with a guard on that id the sink reads 1. The actor state
+  commits exactly once in both runs. CI runs the demo in the SQLite job, and
+  `docs/correctness.md` links it from the handler idempotency section. This
+  mirrors `pnpm run test:at-least-once` in solid-objects-js.
+
 ## 0.14.0 - 2026-08-22
 
 - Add `SolidObjects::Transmission.receive(envelope)`, the server ingest for

data/README.md

@@ -662,6 +662,12 @@ message = order.async(
 ).submit
 ```
 
+`async` needs a running actor worker. Installing the engine and migrating the
+schema starts no role, so a process that only serves web requests leaves the
+message ready. Nothing is lost. The message waits until
+`bundle exec solid_objects start` runs the roles. See
+[Worker requirements](#worker-requirements) for the feature-by-role table.
+
 Use `available_at:` to spread bulk work or delay one message:
 
 ```ruby
@@ -1117,10 +1123,12 @@ and marks process rows stopped on graceful shutdown. A hard-killed worker's
 claimed turn is recovered after its process heartbeat or activation lease
 becomes stale.
 
-Before any role starts, the CLI loads actors from the host application's
-`app/actors` directories through Rails' main autoloader. This works when
-development eager loading is disabled and does not require actor references in
-an initializer.
+The engine loads actors from the host application's `app/actors` directories
+through Rails' main autoloader, in every process that boots the application.
+This works when eager loading is disabled and does not require actor
+references in an initializer. A web process therefore resolves an actor by
+name for a Cable subscription or a component render without having loaded that
+class through an earlier request.
 
 See the [operations guide](docs/operations.md) for monitoring, reconciliation,
 shutdown, retention, and backup guidance.

data/Rakefile

@@ -32,6 +32,11 @@ task :steep do
   sh "bundle exec steep check"
 end
 
+desc "Prove the at-least-once clause by crashing an effect worker at a sink"
+task :at_least_once do
+  sh "bundle exec ruby examples/at_least_once/demo.rb"
+end
+
 desc "Scan the Rails engine for security warnings"
 task :security do
   sh "bundle exec brakeman --force --no-pager -q ."

data/docs/correctness.md

@@ -93,6 +93,15 @@ end
 The guard prevents a repeated state transition. The effect consumer still
 deduplicates with `context.id`.
 
+This clause is observable, not decorative. `bundle exec rake at_least_once`
+crashes an effect worker between the external sink write and the
+acknowledgement, restarts one after the liveness threshold, and shows the sink
+reading 2 with deduplication off. Both deliveries carry the same `context.id`
+at attempts 1 and 2. A guard on that id absorbs the same duplicate and the
+sink reads 1. The actor state commits exactly once in both runs. The source is
+`examples/at_least_once/`; solid-objects-js runs the same proof with
+`pnpm run test:at-least-once`.
+
 ## Atomic boundaries
 
 The following are atomic:

data/docs/operations.md

@@ -31,12 +31,25 @@ Start all configured roles:
 bundle exec solid_objects start
 ```
 
-The command loads the host application's `app/actors` directories before
+The generator and the migrations prepare the database and start nothing. A
+process claims ready messages only after this command starts its roles, so an
+application that serves web requests alone leaves every `async` message ready.
+The message is durable and waits for the first process that runs the roles. A
+direct call or an explicit `sync` needs no running role, because the caller's
+own path executes it.
+
+The engine loads the host application's `app/actors` directories in every
+process that boots the application, and the command repeats that load before
 starting any runtime role, even when Rails eager loading is disabled. Actors in
 the conventional directory do not need initializer references. The targeted
 loader participates in Rails preparation callbacks so a development reload can
 replace a registered actor class without loading unrelated application code.
 
+An actor registers itself as its class loads, and a web process resolves
+actors by name for Cable subscriptions and component renders. Loading them in
+every process is what lets a freshly booted web process serve a live card for
+an actor no request in that process has rendered yet.
+
 Inspect process records and clean stale ownership:
 
 ```bash
@@ -187,6 +200,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.subscription.rejected` reports a rejected Cable subscription.
+A rejection closes the socket and leaves the page holding a stale card, and
+the browser cannot say which of the conditions applied. The event carries the
+`reason`, the actor identity, and the `error_class` where an exception caused
+it. The reason is one of `unregistered_actor_type`, `invalid_stream_token`,
+`invalid_component_token`, `malformed_component_registration`,
+`missing_subscription_parameter`, or `unauthorized`. Exception messages are
+excluded, because a component or payload failure can carry actor state.
+
 `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

data/docs/roadmap.md

@@ -126,7 +126,13 @@
   untested end to end, which is how a raising payload block came to reject the
   subscription; it is now covered and confined, and the payload authorization
   context is resolved through `payload_authorization_context` rather than
-  handing the block a raw Cable connection.
+  handing the block a raw Cable connection. Actor registration in a web process
+  was assumed rather than arranged: an actor registered only as a side effect
+  of its class loading, and only the worker CLI loaded the host's `app/actors`,
+  so a lazily loading web process rejected subscriptions for actors it could
+  serve until some earlier request happened to load the class. The engine now
+  loads them in every process, and a rejected subscription reports which
+  condition caused it instead of closing the socket silently.
 - Backpressure: mailbox/payload/state/result caps and fair yields exist;
   distributed per-actor rate limits and global admission control do not.
 - Administration: `SolidObjects::Web` is a mountable Rack dashboard covering

data/examples/at_least_once/actor.rb

@@ -0,0 +1,14 @@
+# rbs_inline: enabled
+
+class DeliveryCounter < SolidObjects::Actor
+  actor_type "delivery-counter"
+
+  attribute :count, default: 0
+
+  # @rbs () -> Integer
+  def deliver
+    self.count += 1
+    emit :record
+    count
+  end
+end

data/examples/at_least_once/boot.rb

@@ -0,0 +1,47 @@
+# rbs_inline: enabled
+
+require "bundler/setup"
+require "active_record"
+require "solid_objects"
+
+# Boots a standalone runtime against a shared SQLite file, the way the
+# demo's parent and its crashing children all attach to one database.
+module AtLeastOnceBoot
+  ROOT = File.expand_path("../..", __dir__)
+
+  # @rbs (String database_path) -> void
+  def self.call(database_path)
+    ActiveRecord::Base.establish_connection(
+      adapter: "sqlite3",
+      database: database_path,
+      pool: 5,
+      timeout: 5_000
+    )
+    ActiveRecord::Migration.verbose = false
+    migrate unless ActiveRecord::Base.connection.table_exists?("solid_objects_instances")
+
+    require "solid_objects/database_adapter"
+    %w[
+      record process instance message ready_message claimed_message
+      reminder effect broadcast dead_letter
+    ].each { |model| require File.join(ROOT, "app/models/solid_objects", model) }
+
+    SolidObjects.configuration.authorize_message = ->(**) { true }
+    SolidObjects.configuration.authorize_query = ->(**) { true }
+    SolidObjects.configuration.polling_interval = 0.01
+    SolidObjects.configuration.process_heartbeat_interval = 0.075
+    SolidObjects.configuration.process_alive_threshold = 0.3
+    SolidObjects.configuration.lease_duration = 0.25
+    SolidObjects.configuration.lease_renewal_interval = 0.05
+  end
+
+  # @rbs () -> void
+  def self.migrate
+    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")
+    CreateSolidObjectsTables.new.migrate(:up)
+    AddStateRevisionToSolidObjectsInstances.new.migrate(:up)
+    RenameMessageDispatchColumns.new.migrate(:up)
+  end
+end

data/examples/at_least_once/demo.rb

@@ -0,0 +1,92 @@
+# rbs_inline: enabled
+
+# An executable proof for the at-least-once clause: a contract clause
+# nobody can observe firing is decoration. Run with:
+#
+#   bundle exec rake at_least_once
+#
+# Phase one crashes an effect worker between the external sink write and
+# the acknowledgement, restarts one, and shows the sink reading 2 with
+# deduplication off. Both deliveries carry the same stable effect id.
+# Phase two repeats the crash with a guard on that id; the sink reads 1.
+# The actor state commits exactly once in both phases.
+
+require_relative "boot"
+require_relative "actor"
+require_relative "sink"
+require "fileutils"
+require "json"
+require "rbconfig"
+require "tmpdir"
+
+directory = Dir.mktmpdir("solid_objects_at_least_once_")
+database_path = File.join(directory, "state.sqlite3")
+AtLeastOnceBoot.call(database_path)
+
+# @rbs (String message) -> void
+def prove(message)
+  raise "proof failed: #{message}" unless yield
+end
+
+# @rbs (String actor_id) -> void
+def stage_one_delivery(actor_id)
+  DeliveryCounter.ref(actor_id).async.deliver
+  worker = SolidObjects::Worker.new
+  begin
+    worker.run_until_idle
+  ensure
+    worker.stop
+  end
+end
+
+# @rbs (database_path: String, sink_path: String, mode: String, deduplication: String) -> Integer?
+def run_effect_worker(database_path:, sink_path:, mode:, deduplication:)
+  script = File.expand_path("effect_worker.rb", __dir__)
+  pid = Process.spawn(
+    RbConfig.ruby, script, database_path, sink_path, mode, deduplication,
+    chdir: AtLeastOnceBoot::ROOT
+  )
+  _pid, status = Process.wait2(pid)
+  status.exitstatus
+end
+
+# @rbs (database_path: String, sink_path: String, deduplication: String) -> void
+def crash_then_recover(database_path:, sink_path:, deduplication:)
+  crash = run_effect_worker(database_path:, sink_path:, mode: "crash", deduplication:)
+  prove("the first delivery crashed before acknowledgement") { crash == 1 }
+  sleep 0.4
+  recovery = run_effect_worker(database_path:, sink_path:, mode: "complete", deduplication:)
+  prove("the second delivery completed and acknowledged") { recovery == 0 }
+end
+
+begin
+  sink_off = File.join(directory, "sink-dedup-off.json")
+  stage_one_delivery("dedup-off")
+  crash_then_recover(database_path:, sink_path: sink_off, deduplication: "off")
+  deliveries = AtLeastOnceSink.read(sink_off)
+  effect_ids = deliveries.map { |delivery| delivery.fetch("effect_id") }
+  state_off = SolidObjects::Instance.find_by!(actor_id: "dedup-off").state.fetch("count")
+  prove("the state commit happened exactly once") { state_off == 1 }
+  prove("the sink observed the duplicate") { deliveries.length == 2 }
+  prove("both deliveries carried the same stable effect id") { effect_ids.uniq.length == 1 }
+
+  sink_on = File.join(directory, "sink-dedup-on.json")
+  stage_one_delivery("dedup-on")
+  crash_then_recover(database_path:, sink_path: sink_on, deduplication: "on")
+  guarded = AtLeastOnceSink.read(sink_on)
+  state_on = SolidObjects::Instance.find_by!(actor_id: "dedup-on").state.fetch("count")
+  prove("the state commit happened exactly once") { state_on == 1 }
+  prove("the stable effect id absorbed the duplicate") { guarded.length == 1 }
+
+  puts JSON.pretty_generate(
+    duplicate: {
+      state_commits: state_off,
+      sink_deliveries: deliveries.length,
+      same_effect_id: effect_ids.uniq.length == 1,
+      attempts: deliveries.map { |delivery| delivery.fetch("attempt") }
+    },
+    remedy: { state_commits: state_on, sink_deliveries: guarded.length }
+  )
+ensure
+  FileUtils.remove_entry(directory) if directory
+end

data/examples/at_least_once/effect_worker.rb

@@ -0,0 +1,40 @@
+# rbs_inline: enabled
+
+require_relative "boot"
+require_relative "actor"
+require_relative "sink"
+
+database_path, sink_path, mode, deduplication = ARGV
+raise ArgumentError, "usage: effect_worker.rb DATABASE SINK crash|complete on|off" unless deduplication
+
+AtLeastOnceBoot.call(database_path.to_s)
+
+SolidObjects.register_effect(:record) do |_arguments, context|
+  AtLeastOnceSink.record(
+    path: sink_path.to_s,
+    effect_id: context.id,
+    attempt: context.attempt,
+    deduplication: deduplication.to_sym
+  )
+  # A crash between the external write and the acknowledgement: the sink
+  # has the delivery, the effect row never completes.
+  Process.exit!(1) if mode == "crash"
+  nil
+end
+
+# Production runs this on the dead-process-cleanup interval; the demo runs
+# it once, after the liveness threshold, to release the crashed claim.
+SolidObjects::ProcessRegistry.cleanup_dead
+
+effect_executor = SolidObjects::EffectExecutor.new
+begin
+  worked = false
+  200.times do
+    worked = effect_executor.run_once
+    break if worked
+    sleep 0.01
+  end
+  raise "no effect became claimable" unless worked
+ensure
+  effect_executor.stop
+end

data/examples/at_least_once/sink.rb

@@ -0,0 +1,27 @@
+# rbs_inline: enabled
+
+require "json"
+
+# The external system in the at-least-once demo: a JSON file that records
+# every delivery it accepts. With deduplication :off it accepts everything,
+# which makes an at-least-once duplicate visible. With deduplication :on it
+# accepts each stable effect id once, which is the documented remedy.
+module AtLeastOnceSink
+  # @rbs (String path) -> Array[Hash[String, untyped]]
+  def self.read(path)
+    JSON.parse(File.read(path))
+  rescue Errno::ENOENT
+    []
+  end
+
+  # @rbs (path: String, effect_id: String, attempt: Integer, deduplication: Symbol) -> bool
+  def self.record(path:, effect_id:, attempt:, deduplication:)
+    deliveries = read(path)
+    seen = deliveries.any? { |delivery| delivery.fetch("effect_id") == effect_id }
+    return false if deduplication == :on && seen
+
+    deliveries << { "effect_id" => effect_id, "attempt" => attempt }
+    File.write(path, JSON.pretty_generate(deliveries))
+    true
+  end
+end

data/lib/solid_objects/actor_channel.rb

@@ -4,6 +4,14 @@ require "action_cable"
 
 module SolidObjects
   class ActorChannel < ActionCable::Channel::Base
+    REJECT_REASONS = {
+      UnknownActorType => "unregistered_actor_type",
+      InvalidStreamToken => "invalid_stream_token",
+      InvalidComponentToken => "invalid_component_token",
+      JSON::ParserError => "malformed_component_registration",
+      KeyError => "missing_subscription_parameter"
+    }.freeze
+
     # @rbs () -> void
     def subscribed
       identity = StreamToken.verify(params.fetch("token"))
@@ -15,7 +23,9 @@ module SolidObjects
         actor_id:,
         authorization_context: connection
       )
-      return reject unless authorized
+      unless authorized
+        return reject_and_report("unauthorized", actor_type:, actor_id:)
+      end
 
       @reference = Reference.new(actor_type:, actor_id:)
       @scalar_observables = identity["observables"]
@@ -43,8 +53,8 @@ module SolidObjects
       JSON::ParserError,
       InvalidStreamToken,
       InvalidComponentToken,
-      UnknownActorType
-      reject
+      UnknownActorType => error
+      reject_and_report(reject_reason(error), actor_type:, actor_id:, error:)
     end
 
     private
@@ -54,6 +64,26 @@ module SolidObjects
       :scalar_observables,
       :payload_names
 
+    # The exception message stays out of the payload, because a component or
+    # payload error can carry actor state into logs.
+    # @rbs (String, actor_type: String?, actor_id: String?, ?error: Exception?) -> void
+    def reject_and_report(reason, actor_type:, actor_id:, error: nil)
+      SolidObjects.instrument(
+        :"subscription.rejected",
+        reason:,
+        actor_type:,
+        actor_id:,
+        error_class: error&.class&.name
+      )
+      reject
+    end
+
+    # @rbs (Exception) -> String
+    def reject_reason(error)
+      match = REJECT_REASONS.find { |error_class, _| error.is_a?(error_class) }
+      match ? match.last : "invalid_subscription"
+    end
+
     # @rbs (String) -> void
     def receive_broadcast(stream)
       invalidation = TurboStreamRenderer.invalidation(stream)

data/lib/solid_objects/engine.rb

@@ -15,6 +15,10 @@ module SolidObjects
       SolidObjects::LogSubscriber.install
     end
 
+    initializer "solid_objects.actors" do |application|
+      application.config.to_prepare { ApplicationActorLoader.new.call }
+    end
+
     initializer "solid_objects.database", after: :load_config_initializers do
       ActiveSupport.on_load(:active_record) do
         require RECORD_PATH

data/lib/solid_objects/version.rb

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

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

@@ -2,6 +2,8 @@
 
 module SolidObjects
   class ActorChannel < ActionCable::Channel::Base
+    REJECT_REASONS: untyped
+
     # @rbs () -> void
     def subscribed: () -> void
 
@@ -15,6 +17,14 @@ module SolidObjects
 
     attr_reader payload_names: untyped
 
+    # The exception message stays out of the payload, because a component or
+    # payload error can carry actor state into logs.
+    # @rbs (String, actor_type: String?, actor_id: String?, ?error: Exception?) -> void
+    def reject_and_report: (String, actor_type: String?, actor_id: String?, ?error: Exception?) -> void
+
+    # @rbs (Exception) -> String
+    def reject_reason: (Exception) -> String
+
     # @rbs (String) -> void
     def receive_broadcast: (String) -> void
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: solid_objects
 version: !ruby/object:Gem::Version
-  version: 0.14.0
+  version: 0.14.1
 platform: ruby
 authors:
 - Lucas Carlson
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-23 00:00:00.000000000 Z
+date: 2026-08-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actioncable
@@ -371,6 +371,11 @@ files:
 - examples/application/app/views/chat_rooms/show.html.erb
 - examples/application/config/initializers/solid_objects.rb
 - examples/application/config/routes.rb
+- examples/at_least_once/actor.rb
+- examples/at_least_once/boot.rb
+- examples/at_least_once/demo.rb
+- examples/at_least_once/effect_worker.rb
+- examples/at_least_once/sink.rb
 - exe/solid_objects
 - lib/generators/solid_objects/install_generator.rb
 - lib/generators/solid_objects/templates/solid_objects.rb