solid_objects 0.13.3 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9045039767fa2e9ff5a4b5cd2bceb97ca5bc8ea0101b41aaac8fcefcf8a694ef
-  data.tar.gz: efed76c2524be2f7a9591a631c56355f95edaf39332cea846fb895363b8d8d68
+  metadata.gz: a64ced341585dcb4b7e9240b2076e1f47a352b4786806c1bec08c10d91c7d187
+  data.tar.gz: 6d53730c69b2f86cde60d3fdb1ffcefe10dd362dc98652b4afe2b367e1134f32
 SHA512:
-  metadata.gz: 691972f84f5304cbe3f3be42b5889697b179f1eca38e55d76f87827e0ffc5c095ec97c0d591fa58680829920c807bde08619dc725add17be7f1215439775f064
-  data.tar.gz: 68bff7f63f6557e50a6262e22b33fd7633372ec77a33e35b37f95d074498b66b98b01527776b18acbe2ae6527133c6bf7588e50f98e501a0c5636101dac6f45d
+  metadata.gz: acc3e7a6bb436e0dbadf5a38478fc21d3b072f11fcee0cfed26960cba9c1d8eb790a99cf3b065457de8c2ced86d01718c854635d210ba23ffe571e009eab95f7
+  data.tar.gz: 91faab1647c20ba461dcf065612b549b2f6dbd955f2a2222f89a2556d377b99b4a648dbb71ba441ca01ba1281607292f3f21300256ad65f55c821374dac85d7e

data/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## 0.14.0 - 2026-08-22
+
+- Add `SolidObjects::Transmission.receive(envelope)`, the server ingest for
+  the browser transmit family in solid-objects-js. It validates a camelCase
+  transmit envelope, resolves the actor type through an optional
+  `resolve_actor_type:` proc, and enqueues one internal message with the
+  idempotency key `transmit:<effectId>`, so a replayed envelope applies
+  once. Malformed envelopes raise the new
+  `SolidObjects::InvalidTransmission`. Internal delivery skips
+  `authorize_message`, so the host application must authenticate the
+  request before it calls `receive`; see `docs/transmission.md` for the
+  controller boundary. On a registry miss under Rails, `receive` loads the
+  application's actor classes once and retries, because a lazy-loading web
+  process has no other reason to have loaded the target class. Golden
+  fixtures in `compatibility/transmit-envelopes.json` pin the wire contract
+  shared with the JS runtime.
+- Add `Actor#transmit` and `SolidObjects.register_transmit`, the staging
+  side of the transmit family. `transmit.increment(amount:)` stages a
+  `solid-objects.transmit` effect in the same commit as the state change;
+  `register_transmit` drains staged effects into camelCase envelopes and
+  hands each to the delivery block, which raises to retry. A claimed
+  transmit effect delivers every undelivered sibling for its actor up to
+  its own mailbox sequence, oldest first, so per-actor order survives a
+  failed delivery, and the receiving side dedups on `transmit:<effectId>`.
+  A raw `emit "solid-objects.transmit"` with explicit `actorType` and
+  `actorId` targets a different actor, matching the JS staging surface.
+- Mount `POST /solid_objects/transmit` in the engine, an ingest route
+  behind the new deny-by-default `authorize_transmission` policy. The
+  policy receives the parsed envelope and the controller, an unauthorized
+  envelope gets 403, and a permanently unappliable one gets 422, so a
+  sending outbox dead-letters it instead of retrying forever. The new
+  `transmission_actor_type_resolver` configuration maps diverged actor
+  type names for the engine route.
+
 ## 0.13.3 - 2026-08-18
 
 - Stop loading `ActiveRecord::Base` when the gem is required. The engine now

data/README.md

@@ -1,13 +1,13 @@
 # Solid Objects
 
-[![CI](https://github.com/cardmagic/solid_objects/actions/workflows/ci.yml/badge.svg)](https://github.com/cardmagic/solid_objects/actions/workflows/ci.yml)
+[![CI](https://github.com/cardmagic/solid-objects-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/cardmagic/solid-objects-ruby/actions/workflows/ci.yml)
 
 **Self-hosted, distributed Durable Objects in Rails without a daemon using your existing SQL database.**
 
-Solid Objects brings the Durable Objects programming model—addressable objects,
-durable state, serialized turns, alarms, and live clients—to ordinary Rails
-applications. It runs on the MySQL, PostgreSQL, or SQLite database the
-application already has, following the database-backed operating model of the
+Solid Objects ports the Durable Objects programming model to ordinary Rails
+applications: addressable objects, durable state, serialized turns, alarms,
+and live clients. It runs on the MySQL, PostgreSQL, or SQLite database that
+the application already has, in the database-backed operating model of the
 Solid family. No Redis, Cloudflare account, or separate actor service is
 required.
 
@@ -113,7 +113,7 @@ maps those ideas into Rails:
 | Storage deletion | Authorized `reference.destroy` |
 | Cloudflare Workers platform | Your Rails processes and SQL database |
 
-Rails already has excellent tools for jobs, records, and realtime transport.
+Rails already has tools for jobs, records, and realtime transport.
 None of those primitives alone provides this complete stateful-object shape.
 Solid Objects adds five capabilities:
 
@@ -1273,7 +1273,7 @@ for staged cutovers.
 | --- | --- |
 | Cloudflare Durable Objects | Solid Objects ports the named, stateful, serialized-object model to Ruby and Rails. It uses your SQL database and Rails workers rather than Cloudflare's globally distributed serverless runtime, placement, and storage APIs. |
 | Active Job | Jobs are independent work units. Solid Objects adds addressable identity, durable state, explicit per-identity order, activation leases, and fencing. |
-| Solid Queue | Solid Queue is an excellent database backend for Active Job. Its concurrency controls cap overlap but do not guarantee order. Solid Objects provides actor mailboxes, state, fencing, per-identity reminders, and state-driven views. |
+| Solid Queue | Solid Queue is a database backend for Active Job. Its concurrency controls cap overlap but do not guarantee order. Solid Objects provides actor mailboxes, state, fencing, per-identity reminders, and state-driven views. |
 | Action Cable | Cable transports transient realtime messages. Solid Objects owns durable state and work; Cable is an optional delivery path for committed observable projections. |
 | Orleans | Orleans provides the virtual-actor lineage behind the model, with grains, reminders, and activation lifecycle. Solid Objects is a smaller Rails-native runtime and does not match Orleans clustering or placement breadth. |
 | Active Record service object | A service object runs directly against records. Solid Objects adds durable asynchronous ordering, retries, activation fencing, reminders, and outboxes at greater operational cost. |

data/app/controllers/solid_objects/transmissions_controller.rb

@@ -0,0 +1,32 @@
+# rbs_inline: enabled
+
+require "action_controller/api"
+
+module SolidObjects
+  class TransmissionsController < ActionController::API
+    # @rbs () -> void
+    def create
+      envelope = JSON.parse(request.body.read)
+      return head :forbidden unless authorized_transmission?(envelope)
+
+      Transmission.receive(
+        envelope,
+        resolve_actor_type: SolidObjects.configuration.transmission_actor_type_resolver
+      )
+      head :ok
+    rescue JSON::ParserError, InvalidTransmission, UnknownActorType, UnknownMessage,
+      PayloadTooLarge, IdempotencyConflict
+      head :unprocessable_entity
+    end
+
+    private
+
+    # @rbs (untyped) -> bool
+    def authorized_transmission?(envelope)
+      SolidObjects.configuration.authorize_transmission.call(
+        envelope:,
+        authorization_context: self
+      )
+    end
+  end
+end

data/config/routes.rb

@@ -1,6 +1,7 @@
 # rbs_inline: enabled
 
 SolidObjects::Engine.routes.draw do
+  post :transmit, to: "transmissions#create"
   get :components, to: "components#show"
   get "components/batch", to: "components#batch"
   resources :instances, only: %i[index show]

data/docs/research/solid_queue.md

@@ -526,8 +526,8 @@ Source: [Cloudflare Durable Objects overview](https://developers.cloudflare.com/
 - Solid Queue findings are tied to v1.6.0. Earlier releases did not have all current async/fiber supervision and concurrency finalization behavior.
 - PostgreSQL documentation inspected was current PostgreSQL 18 documentation. `SKIP LOCKED` has existed since PostgreSQL 9.5, but Solid Objects supports PostgreSQL 14 and newer.
 - MySQL documentation inspected was MySQL 8.4. Solid Objects supports MySQL 8.0 and newer with InnoDB.
-- SQLite documentation inspected covers current SQLite behavior. Solid Objects requires SQLite 3.35 or newer for modern DML support.
-- Rails documentation and source inspected cover Rails 8.1. Solid Objects requires Rails 8.0 or newer because Rails 8 changed the SQLite adapter's default write transaction from deferred to immediate, which the SQLite coordination contract relies on.
+- SQLite documentation inspected covers current SQLite behavior. Solid Objects supports SQLite 3.35 or newer, the oldest server version the adapter accepts.
+- Rails documentation and source inspected cover Rails 8.1. Solid Objects requires Rails 7.1 or newer. Rails 8 changed the SQLite adapter's default write transaction from deferred to immediate, and the test suite also passes on Rails 7.1 and 7.2 with the deferred default. Rails 7.0 stays out of range because its SQLite adapter requires sqlite3 1.4, and the busy-handler control this gem depends on arrived in sqlite3 2.x.
 - Orleans documentation describes current Orleans behavior, not a compatibility promise for this Ruby implementation.
 - `LISTEN/NOTIFY` and Action Cable are optimizations and delivery channels, never durable truth.
 - A separate actor database is compatible only when all rows participating in an atomic actor commit, including message, state, effects, and broadcasts, live in that same actor database.

data/docs/roadmap.md

@@ -72,6 +72,20 @@
   Rails 7.1 and 7.2 is unmeasured against those servers. Rails 7.0 is out of
   range because its SQLite adapter requires `sqlite3 ~> 1.4`, and this gem needs
   the busy-handler control that arrived in `sqlite3` 2.x
+- The transmit family, both sides. `SolidObjects::Transmission.receive` is
+  the ingest: envelope validation, actor type resolution with a per-call
+  `resolve_actor_type:` escape hatch, and an internal idempotent enqueue
+  keyed `transmit:<effectId>`. `Actor#transmit` and
+  `SolidObjects.register_transmit` are the staging side: a transactional
+  `solid-objects.transmit` effect and a drain that delivers every
+  undelivered sibling for the actor up to the claimed effect's mailbox
+  sequence, oldest first, so per-actor order survives a failed delivery.
+  The wire contract is pinned by golden fixtures in
+  `compatibility/transmit-envelopes.json`. The engine mounts
+  `POST /solid_objects/transmit` behind a deny-by-default
+  `authorize_transmission` policy with a configurable actor type resolver.
+  Bidirectional replication as a declared surface, with echo suppression,
+  is not implemented
 - A JavaScript suite covering every browser module, run in CI with Node's test
   runner and jsdom, plus a browser suite running the same modules against real
   Chromium and a real Turbo build, with every GitHub Actions reference pinned to
@@ -129,7 +143,10 @@
   of who pressed what, and bulk-safe tools: retry is one dead letter at a time,
   because `DeadLetterManager` exposes no bulk operation. Pause is an operator
   brake and not a stop, since a pass already in flight finishes its turn and a
-  synchronous caller waiting on a paused instance times out. The page cost was
+  synchronous caller waiting on a paused instance times out. Retry also only
+  exists for message dead letters: a dead effect or broadcast has no retry
+  API, which matters for transmit effects because a dead one is a lost
+  replay until an operator returns its row to pending. The page cost was
   reasoned about rather than measured: the summary bar issues a fixed set of
   indexed aggregate queries per page, which is why `HEAD /` exists for uptime
   monitors, but no dashboard latency has been benchmarked against a large

data/docs/state-migrations.md

@@ -47,6 +47,6 @@ A safe destructive rollout normally uses:
 Never update actor JSON in a bulk SQL migration. Use actor messages so fencing,
 ordering, observables, and outboxes remain intact.
 
-This guide covers evolution after state belongs to Solid Objects. For moving
+This guide covers changes to state that Solid Objects already owns. To move
 existing Redis, key-value, or relational state into actors without downtime,
 use the [legacy-state migration cookbook](migrating-existing-state.md).

data/docs/transmission.md

@@ -0,0 +1,198 @@
+# The transmit family
+
+The transmit family replays one runtime's actor operations onto another
+runtime over a shared wire contract. The Ruby gem holds both sides:
+
+- `Actor#transmit` and `SolidObjects.register_transmit` stage and deliver
+  envelopes. This is the sending side.
+- `SolidObjects::Transmission.receive(envelope)` ingests envelopes. This is
+  the receiving side.
+
+[solid-objects-js](https://github.com/cardmagic/solid-objects-js) holds the
+same two sides for the browser and Node. A browser actor stages a transmit
+intent with `this.transmit().increment({ amount })` in the same transaction
+as its state change; its effect worker drains that outbox with
+at-least-once delivery, per-actor order, and retry backoff, and posts one
+JSON envelope per effect to a route the host application owns. A Rails
+actor does the same with `transmit.increment(amount:)`. Either ingest
+accepts either sender, so Rails-to-Rails, Rails-to-Node, Node-to-Rails,
+and browser-to-Rails replication all ride one contract.
+
+## The sending side
+
+```ruby
+class Counter < SolidObjects::Actor
+  actor_type "counters"
+
+  attribute :count, default: 0
+
+  def increment(amount: 1)
+    self.count += amount
+    transmit.increment(amount:)
+  end
+end
+
+SolidObjects.register_transmit do |envelope|
+  DeliverToUpstream.call(envelope)
+end
+```
+
+`transmit` returns the same fluent dispatcher `schedule` returns. It stages
+one `solid-objects.transmit` effect in the same commit as the state change,
+targeting the same operation on the same actor in the receiving runtime. For
+a different target, stage the effect directly:
+
+```ruby
+emit "solid-objects.transmit",
+  operation: "increment",
+  arguments: { amount: 2 },
+  actorType: "other-counters",
+  actorId: "counter-1"
+```
+
+`SolidObjects.register_transmit(&deliver)` registers the drain handler for
+that effect. The block receives one camelCase envelope per staged effect.
+Raise inside the block while the upstream is unreachable; the effect
+retries with backoff and dead-letters on exhaustion, like any other effect.
+
+The drain keeps per-actor order across failures: a claimed transmit effect
+delivers every undelivered sibling for its actor up to its own mailbox
+sequence, oldest first. The receiving side dedups on `transmit:<effectId>`,
+so a redelivered envelope applies once.
+
+Delivery is at-least-once by design, and the drain accepts redundant sends
+as the price of ordering without cross-worker coordination. A drained
+sibling's own effect row stays pending, because completing it would
+require taking over another worker's claim; when its own claim runs, it
+delivers again and the receiving side drops the replay. The same is true
+when two workers claim effects for one actor concurrently. Both runtimes
+share this behavior, and the Ruby suite pins it with a race test: order
+holds, duplicates apply nothing, and every effect completes.
+
+## Retry budget and offline tolerance
+
+A raised delivery follows the effect retry policy: `max_attempts` (default
+5) and `retry_delay` (default `2 ** (attempt - 1)` seconds, capped at 60).
+The defaults give roughly fifteen seconds of offline tolerance before an
+envelope dead-letters. An application that transmits across real outages
+must raise both:
+
+```ruby
+SolidObjects.configure do |configuration|
+  configuration.max_attempts = 30
+  configuration.retry_delay = ->(attempt) { [ 2**(attempt - 1), 300 ].min.to_f }
+end
+```
+
+These settings apply to every effect, not only transmits. A dead transmit
+effect has no retry API; the dashboard lists it, and recovery means
+returning its row to `pending` with a cleared `attempt_count`. Order
+survives that recovery, because the drain orders by mailbox sequence, not
+by retry time.
+
+## Wire contract
+
+The JS side owns the envelope format. The Ruby ingest accepts it verbatim.
+
+- Keys arrive camelCase: `effectId`, `actorType`, `actorId`, `operation`,
+  and an optional `arguments` object. There is no snake_case dialect.
+- The idempotency key is `transmit:<effectId>`, byte-identical to the JS
+  server ingest. A replayed envelope applies once.
+- Delivery is at-least-once and per-actor ordered by the browser's drain.
+  The server preserves mailbox order and adds no ordering of its own.
+
+`compatibility/transmit-envelopes.json` pins the contract. Both runtimes
+run a consuming test against the same fixture file.
+
+## What `receive` does
+
+1. It validates the envelope shape. A malformed envelope raises
+   `SolidObjects::InvalidTransmission`.
+2. It resolves the actor type and looks it up in the registry. On a miss
+   under Rails it loads the application's actor classes once and retries,
+   because a lazy-loading process has no other reason to have loaded the
+   target class. A type that is still unknown raises
+   `SolidObjects::UnknownActorType`. An undeclared operation raises
+   `SolidObjects::UnknownMessage`.
+3. It enqueues one internal message with the idempotency key
+   `transmit:<effectId>`. Oversized arguments raise
+   `SolidObjects::PayloadTooLarge` before persistence.
+
+The enqueue uses `delivery_mode: "internal"`, the same mode the effect
+executor uses. Internal delivery skips `authorize_message` by construction.
+The host application must authenticate the request before it calls
+`receive`.
+
+## The engine route
+
+The engine mounts `POST /solid_objects/transmit` (under wherever the host
+mounts `SolidObjects::Engine`). It parses the body, authorizes it through
+`authorize_transmission`, and passes it to `Transmission.receive` with the
+configured `transmission_actor_type_resolver`. The policy denies by
+default, because the ingest skips `authorize_message` by design; an
+unauthorized envelope gets 403, and an envelope the server can never apply
+gets 422:
+
+```ruby
+SolidObjects.configure do |configuration|
+  configuration.authorize_transmission = lambda do |envelope:, authorization_context:|
+    ActiveSupport::SecurityUtils.secure_compare(
+      authorization_context.request.headers["Authorization"].to_s,
+      "Bearer #{Rails.application.credentials.transmit_token}"
+    )
+  end
+end
+```
+
+The policy receives the parsed envelope and the controller as
+`authorization_context:`, so it can bind `actorType` and `actorId` to the
+authenticated caller, not only check a shared token. Rate limits stay with
+the host (Rack::Attack or the proxy), the same boundary the dashboard
+draws.
+
+## A hand-rolled route
+
+An application that wants its own controller keeps the same shape:
+
+```ruby
+class TransmitController < ApplicationController
+  skip_forgery_protection
+
+  def create
+    head :forbidden and return unless authenticated_device?
+
+    SolidObjects::Transmission.receive(JSON.parse(request.body.read))
+    head :ok
+  rescue SolidObjects::InvalidTransmission, SolidObjects::UnknownActorType,
+    SolidObjects::UnknownMessage, SolidObjects::PayloadTooLarge,
+    SolidObjects::IdempotencyConflict, JSON::ParserError
+    head :unprocessable_entity
+  end
+end
+```
+
+Return 422 for an envelope the server can never apply. The browser outbox
+dead-letters that effect instead of retrying it forever. Return a 5xx for a
+transient server fault, so the browser retries with backoff.
+`SolidObjects::IdempotencyConflict` belongs in the 422 list: it means the
+effect id was replayed with a different invocation, and no retry can ever
+make that envelope apply.
+
+## Actor type mapping
+
+When both runtimes use the same actor type strings, no configuration is
+needed. When the names diverge, pass `resolve_actor_type:` per call:
+
+```ruby
+SolidObjects::Transmission.receive(
+  envelope,
+  resolve_actor_type: ->(actor_type) { actor_type.sub("browser-", "server-") }
+)
+```
+
+## Scope
+
+Bidirectional replication as a first-class surface, where two runtimes
+declare a replica pair and echo suppression keeps a replayed operation
+from transmitting back, is a separate feature. The transmit family gives
+it the mechanism; the declaration API does not exist yet.

data/lib/generators/solid_objects/templates/solid_objects.rb

@@ -37,7 +37,7 @@ SolidObjects.configure do |configuration|
   #
   # Prefer policies that bind actor_type and actor_id to a trusted
   # authorization_context. See:
-  # https://github.com/cardmagic/solid_objects/blob/main/docs/authorization.md
+  # https://github.com/cardmagic/solid-objects-ruby/blob/main/docs/authorization.md
   # and run:
   #
   #   bin/rails solid_objects:doctor
@@ -49,6 +49,22 @@ SolidObjects.configure do |configuration|
   configuration.authorize_subscription = ->(**) { false }
   configuration.authorize_administration = ->(**) { false }
 
+  # The engine route POST /solid_objects/transmit ingests transmit envelopes
+  # from another Solid Objects runtime. It stays denied until its callers are
+  # authenticated, because the ingest skips authorize_message by design:
+  #
+  # configuration.authorize_transmission = lambda do |envelope:, authorization_context:|
+  #   ActiveSupport::SecurityUtils.secure_compare(
+  #     authorization_context.request.headers["Authorization"].to_s,
+  #     "Bearer #{Rails.application.credentials.transmit_token}"
+  #   )
+  # end
+  #
+  # When the sending runtime names actor types differently, map them here:
+  #
+  # configuration.transmission_actor_type_resolver = ->(actor_type) { actor_type.sub("browser-", "server-") }
+  configuration.authorize_transmission = ->(**) { false }
+
   # Configure component_authorization_context to return the authenticated
   # principal used for reactive component refreshes.
 

data/lib/solid_objects/actor.rb

@@ -190,6 +190,17 @@ module SolidObjects
       nil
     end
 
+    # @rbs () -> OperationDispatcher
+    def transmit
+      OperationDispatcher.new(
+        actor_type: self.class.actor_type,
+        handlers: self.class.definition.messages
+      ) do |operation, arguments|
+        emit(Transmission::EFFECT_NAME, operation: operation.to_s, arguments:)
+        nil
+      end
+    end
+
     # @rbs (Symbol | String, **untyped) -> nil
     def commit_action(name, **arguments)
       CommitActionIntent.new(

data/lib/solid_objects/configuration.rb

@@ -47,6 +47,8 @@ module SolidObjects
     # @rbs @authorize_destroy: Proc
     # @rbs @authorize_subscription: Proc
     # @rbs @authorize_administration: Proc
+    # @rbs @authorize_transmission: Proc
+    # @rbs @transmission_actor_type_resolver: Proc
 
     attr_accessor :table_name_prefix,
       :polling_interval,
@@ -92,7 +94,9 @@ module SolidObjects
       :authorize_query,
       :authorize_destroy,
       :authorize_subscription,
-      :authorize_administration
+      :authorize_administration,
+      :authorize_transmission,
+      :transmission_actor_type_resolver
 
     # @rbs @additional_components: Array[untyped]
     attr_reader :additional_components
@@ -148,6 +152,8 @@ module SolidObjects
       @authorize_destroy = ->(**) { false }
       @authorize_subscription = ->(**) { false }
       @authorize_administration = ->(**) { false }
+      @authorize_transmission = ->(**) { false }
+      @transmission_actor_type_resolver = ->(actor_type) { actor_type }
       @additional_components = []
     end
 

data/lib/solid_objects/errors.rb

@@ -19,6 +19,9 @@ module SolidObjects
   class UnknownMessage < Error
   end
 
+  class InvalidTransmission < Error
+  end
+
   class InvalidPayload < Error
   end
 

data/lib/solid_objects/transmission.rb

@@ -0,0 +1,139 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  module Transmission
+    REQUIRED_FIELDS = %w[effectId actorType actorId operation].freeze
+    IDEMPOTENCY_PREFIX = "transmit:"
+    EFFECT_NAME = "solid-objects.transmit"
+    UNDELIVERED_STATUSES = %w[pending processing].freeze
+
+    class << self
+      # @rbs (untyped envelope, ?resolve_actor_type: ^(String) -> (String | Symbol), ?mailbox: Mailbox, ?actor_loader: ^() -> bool) -> MessageReference
+      def receive(envelope, resolve_actor_type: :itself.to_proc, mailbox: Mailbox.new, actor_loader: method(:load_application_actors))
+        validate!(envelope)
+
+        actor_type = resolve_actor_type.call(envelope["actorType"]).to_s
+        actor_class = fetch_actor_class(actor_type, actor_loader)
+        operation = envelope["operation"].to_sym
+        unless actor_class.definition.messages.key?(operation)
+          raise UnknownMessage, "unknown operation #{envelope["operation"].inspect}"
+        end
+
+        mailbox.enqueue(
+          reference: Reference.new(actor_type:, actor_id: envelope["actorId"]),
+          operation:,
+          arguments: envelope.fetch("arguments", {}),
+          delivery_mode: "internal",
+          idempotency_key: "#{IDEMPOTENCY_PREFIX}#{envelope["effectId"]}"
+        )
+      end
+
+      # @rbs (effect_name: String, arguments: Hash[String, untyped], context: EffectContext, deliver: Proc) -> nil
+      def deliver_through(effect_name:, arguments:, context:, deliver:)
+        staged_envelope(
+          arguments,
+          effect_id: context.id,
+          actor_type: context.actor_type,
+          actor_id: context.actor_id
+        )
+        undelivered_envelopes_through(effect_name:, context:).each do |envelope|
+          deliver.call(envelope)
+        end
+        nil
+      end
+
+      private
+
+      # @rbs (String, ^() -> bool) -> Class
+      def fetch_actor_class(actor_type, actor_loader)
+        SolidObjects.registry.fetch(actor_type)
+      rescue UnknownActorType
+        raise unless actor_loader.call
+
+        SolidObjects.registry.fetch(actor_type)
+      end
+
+      # @rbs () -> bool
+      def load_application_actors
+        return false unless defined?(Rails.application) && Rails.application
+
+        ApplicationActorLoader.new.call
+        true
+      end
+
+      # @rbs (Hash[String, untyped], effect_id: String, actor_type: String, actor_id: String) -> Hash[String, untyped]
+      def staged_envelope(arguments, effect_id:, actor_type:, actor_id:)
+        operation = arguments["operation"]
+        unless operation.is_a?(String) && !operation.empty?
+          raise InvalidTransmission, "transmit effect arguments require a non-empty operation"
+        end
+
+        target_arguments = arguments["arguments"]
+        target_arguments = {} if target_arguments.nil?
+        unless target_arguments.is_a?(Hash)
+          raise InvalidTransmission, %(transmit effect arguments must hold a JSON object in "arguments")
+        end
+
+        target_type = arguments["actorType"].nil? ? actor_type : arguments["actorType"]
+        target_id = arguments["actorId"].nil? ? actor_id : arguments["actorId"]
+        { "actorType" => target_type, "actorId" => target_id }.each do |field, value|
+          next if value.is_a?(String) && !value.empty?
+
+          raise InvalidTransmission, "transmit effect #{field} must be a non-empty string"
+        end
+
+        {
+          "effectId" => effect_id,
+          "actorType" => target_type,
+          "actorId" => target_id,
+          "operation" => operation,
+          "arguments" => target_arguments
+        }
+      end
+
+      # @rbs (effect_name: String, context: EffectContext) -> Array[Hash[String, untyped]]
+      def undelivered_envelopes_through(effect_name:, context:)
+        source_sequence = Message.find(context.source_message_id).sequence
+        effects = Effect
+          .joins(:message)
+          .where(name: effect_name, status: UNDELIVERED_STATUSES)
+          .merge(
+            Message.where(
+              actor_type: context.actor_type,
+              actor_id: context.actor_id,
+              sequence: ..source_sequence
+            )
+          )
+          .order(Message.arel_table[:sequence].asc, :id)
+
+        effects.filter_map do |effect|
+          staged_envelope(
+            effect.arguments,
+            effect_id: effect.effect_id,
+            actor_type: context.actor_type,
+            actor_id: context.actor_id
+          )
+        rescue InvalidTransmission
+          nil
+        end
+      end
+
+      # @rbs (untyped) -> void
+      def validate!(envelope)
+        raise InvalidTransmission, "envelope must be a JSON object" unless envelope.is_a?(Hash)
+
+        REQUIRED_FIELDS.each do |field|
+          value = envelope[field]
+          next if value.is_a?(String) && !value.empty?
+
+          raise InvalidTransmission, "envelope field #{field.inspect} must be a non-empty string"
+        end
+
+        arguments = envelope.fetch("arguments", {})
+        return if arguments.is_a?(Hash)
+
+        raise InvalidTransmission, %(envelope field "arguments" must be a JSON object)
+      end
+    end
+  end
+end

data/lib/solid_objects/version.rb

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

data/lib/solid_objects.rb

@@ -63,6 +63,8 @@ require "solid_objects/lease_renewer"
 # was reachable only through the caller path, so requiring the gem was not
 # enough to run a role that uses it.
 require "solid_objects/mailbox"
+require "solid_objects/application_actor_loader"
+require "solid_objects/transmission"
 require "solid_objects/worker"
 require "solid_objects/effect_executor"
 require "solid_objects/reminder_scheduler"
@@ -100,6 +102,20 @@ module SolidObjects
       effect_registry.register(name, handler)
     end
 
+    # @rbs (?effect_name: String | Symbol) { (Hash[String, untyped]) -> untyped } -> Proc
+    def register_transmit(effect_name: Transmission::EFFECT_NAME, &deliver)
+      raise ArgumentError, "register_transmit requires a delivery block" unless deliver
+
+      register_effect(effect_name) do |arguments, context|
+        Transmission.deliver_through(
+          effect_name: effect_name.to_s,
+          arguments:,
+          context:,
+          deliver:
+        )
+      end
+    end
+
     # @rbs () -> CommitActionRegistry
     def commit_action_registry
       @commit_action_registry ||= CommitActionRegistry.new

data/sig/generated/controllers/solid_objects/transmissions_controller.rbs

@@ -0,0 +1,13 @@
+# Generated from app/controllers/solid_objects/transmissions_controller.rb with RBS::Inline
+
+module SolidObjects
+  class TransmissionsController < ActionController::API
+    # @rbs () -> void
+    def create: () -> void
+
+    private
+
+    # @rbs (untyped) -> bool
+    def authorized_transmission?: (untyped) -> bool
+  end
+end

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

@@ -161,6 +161,9 @@ module SolidObjects
     # @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 () -> OperationDispatcher
+    def transmit: () -> OperationDispatcher
+
     # @rbs (Symbol | String, **untyped) -> nil
     def commit_action: (Symbol | String, **untyped) -> nil
 

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

@@ -4,8 +4,6 @@ module SolidObjects
   class Configuration
     @table_name_prefix: String
 
-    @process_alive_threshold: Float
-
     @shutdown_timeout: Float
 
     @supervisor_monitor_interval: Float
@@ -58,6 +56,10 @@ module SolidObjects
 
     @authorize_administration: Proc
 
+    @authorize_transmission: Proc
+
+    @transmission_actor_type_resolver: Proc
+
     @polling_interval: Float
 
     @idle_polling_interval: Float
@@ -92,6 +94,8 @@ module SolidObjects
 
     @process_heartbeat_interval: Float
 
+    @process_alive_threshold: Float
+
     attr_accessor table_name_prefix: untyped
 
     attr_accessor polling_interval: untyped
@@ -182,6 +186,10 @@ module SolidObjects
 
     attr_accessor authorize_administration: untyped
 
+    attr_accessor authorize_transmission: untyped
+
+    attr_accessor transmission_actor_type_resolver: untyped
+
     # @rbs @additional_components: Array[untyped]
     attr_reader additional_components: untyped
 

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

@@ -19,6 +19,9 @@ module SolidObjects
   class UnknownMessage < Error
   end
 
+  class InvalidTransmission < Error
+  end
+
   class InvalidPayload < Error
   end
 

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

@@ -0,0 +1,34 @@
+# Generated from lib/solid_objects/transmission.rb with RBS::Inline
+
+module SolidObjects
+  module Transmission
+    REQUIRED_FIELDS: untyped
+
+    IDEMPOTENCY_PREFIX: ::String
+
+    EFFECT_NAME: ::String
+
+    UNDELIVERED_STATUSES: untyped
+
+    # @rbs (untyped envelope, ?resolve_actor_type: ^(String) -> (String | Symbol), ?mailbox: Mailbox, ?actor_loader: ^() -> bool) -> MessageReference
+    def self.receive: (untyped envelope, ?resolve_actor_type: ^(String) -> (String | Symbol), ?mailbox: Mailbox, ?actor_loader: ^() -> bool) -> MessageReference
+
+    # @rbs (effect_name: String, arguments: Hash[String, untyped], context: EffectContext, deliver: Proc) -> nil
+    def self.deliver_through: (effect_name: String, arguments: Hash[String, untyped], context: EffectContext, deliver: Proc) -> nil
+
+    # @rbs (String, ^() -> bool) -> Class
+    private def self.fetch_actor_class: (String, ^() -> bool) -> Class
+
+    # @rbs () -> bool
+    private def self.load_application_actors: () -> bool
+
+    # @rbs (Hash[String, untyped], effect_id: String, actor_type: String, actor_id: String) -> Hash[String, untyped]
+    private def self.staged_envelope: (Hash[String, untyped], effect_id: String, actor_type: String, actor_id: String) -> Hash[String, untyped]
+
+    # @rbs (effect_name: String, context: EffectContext) -> Array[Hash[String, untyped]]
+    private def self.undelivered_envelopes_through: (effect_name: String, context: EffectContext) -> Array[Hash[String, untyped]]
+
+    # @rbs (untyped) -> void
+    private def self.validate!: (untyped) -> void
+  end
+end

data/sig/generated/lib/solid_objects.rbs

@@ -18,6 +18,9 @@ module SolidObjects
   # @rbs (String | Symbol) { (Hash[String, untyped], EffectContext) -> untyped } -> Proc
   def self.register_effect: (String | Symbol) { (Hash[String, untyped], EffectContext) -> untyped } -> Proc
 
+  # @rbs (?effect_name: String | Symbol) { (Hash[String, untyped]) -> untyped } -> Proc
+  def self.register_transmit: (?effect_name: String | Symbol) { (Hash[String, untyped]) -> untyped } -> Proc
+
   # @rbs () -> CommitActionRegistry
   def self.commit_action_registry: () -> CommitActionRegistry
 

data/sig/support/framework.rbs

@@ -21,6 +21,9 @@ end
 module ActionController
   class Base
   end
+
+  class API
+  end
 end
 
 module Rails

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: solid_objects
 version: !ruby/object:Gem::Version
-  version: 0.13.3
+  version: 0.14.0
 platform: ruby
 authors:
 - Lucas Carlson
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-18 00:00:00.000000000 Z
+date: 2026-08-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actioncable
@@ -297,6 +297,7 @@ files:
 - app/controllers/solid_objects/components_controller.rb
 - app/controllers/solid_objects/dead_letters_controller.rb
 - app/controllers/solid_objects/instances_controller.rb
+- app/controllers/solid_objects/transmissions_controller.rb
 - app/helpers/solid_objects/actor_helper.rb
 - app/models/solid_objects/broadcast.rb
 - app/models/solid_objects/claimed_message.rb
@@ -358,6 +359,7 @@ files:
 - docs/roadmap.md
 - docs/security.md
 - docs/state-migrations.md
+- docs/transmission.md
 - examples/application/README.md
 - examples/application/app/actors/chat_room_actor.rb
 - examples/application/app/actors/shopping_cart_actor.rb
@@ -436,6 +438,7 @@ files:
 - lib/solid_objects/sync_diagnostics.rb
 - lib/solid_objects/synchronous_invocation.rb
 - lib/solid_objects/test_helper.rb
+- lib/solid_objects/transmission.rb
 - lib/solid_objects/turbo_stream_renderer.rb
 - lib/solid_objects/version.rb
 - lib/solid_objects/wake_up.rb
@@ -457,6 +460,7 @@ files:
 - sig/generated/controllers/solid_objects/components_controller.rbs
 - sig/generated/controllers/solid_objects/dead_letters_controller.rbs
 - sig/generated/controllers/solid_objects/instances_controller.rbs
+- sig/generated/controllers/solid_objects/transmissions_controller.rbs
 - sig/generated/helpers/solid_objects/actor_helper.rbs
 - sig/generated/lib/generators/solid_objects/install_generator.rbs
 - sig/generated/lib/solid_objects.rbs
@@ -523,6 +527,7 @@ files:
 - sig/generated/lib/solid_objects/sync_diagnostics.rbs
 - sig/generated/lib/solid_objects/synchronous_invocation.rbs
 - sig/generated/lib/solid_objects/test_helper.rbs
+- sig/generated/lib/solid_objects/transmission.rbs
 - sig/generated/lib/solid_objects/turbo_stream_renderer.rbs
 - sig/generated/lib/solid_objects/version.rbs
 - sig/generated/lib/solid_objects/wake_up.rbs
@@ -575,12 +580,12 @@ licenses:
 - MIT
 metadata:
   allowed_push_host: https://rubygems.org
-  bug_tracker_uri: https://github.com/cardmagic/solid_objects/issues
-  changelog_uri: https://github.com/cardmagic/solid_objects/blob/main/CHANGELOG.md
-  documentation_uri: https://github.com/cardmagic/solid_objects#readme
+  bug_tracker_uri: https://github.com/cardmagic/solid-objects-ruby/issues
+  changelog_uri: https://github.com/cardmagic/solid-objects-ruby/blob/main/CHANGELOG.md
+  documentation_uri: https://github.com/cardmagic/solid-objects-ruby#readme
   homepage_uri: https://solidobjects.dev
   rubygems_mfa_required: 'true'
-  source_code_uri: https://github.com/cardmagic/solid_objects
+  source_code_uri: https://github.com/cardmagic/solid-objects-ruby
 post_install_message:
 rdoc_options: []
 require_paths: