feat: mount an engine transmit ingest route

Add POST /solid_objects/transmit, the engine-mounted ingest that #47
deferred. The route parses the body, authorizes it through the new
authorize_transmission policy, and hands it to Transmission.receive
with the new transmission_actor_type_resolver configuration.

The policy denies by default like the other five, because the ingest
skips authorize_message by design. It receives the parsed envelope
and the controller as authorization_context, so an application can
bind actorType and actorId to the authenticated caller rather than
only compare a shared token. An unauthorized envelope gets 403; a
permanently unappliable one (malformed, unknown type or operation,
oversized, conflicting replay, unparseable body) gets 422, so a
sending outbox dead-letters it instead of retrying forever.

The controller inherits ActionController::API: the endpoint is
token-authenticated machine traffic with no session, which keeps the
Brakeman scan warning-free where a null_session forgery setting does
not. The install generator template gains the policy with a bearer
token example, and the generator test pins six deny-by-default
policies.

Verified live in a scratch Rails app: 403 without or with a wrong
token, 200 with the token, 422 for malformed and unparseable bodies,
and the effect worker delivering through the engine route end to end
with the configured actor type resolver.

Author: cardmagic

CHANGELOG.md

@@ -26,6 +26,13 @@
   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
 

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

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]

docs/roadmap.md

@@ -81,7 +81,10 @@
   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`. An engine-mounted ingest route
+  `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

docs/transmission.md

@@ -114,10 +114,36 @@ executor uses. Internal delivery skips `authorize_message` by construction.
 The host application must authenticate the request before it calls
 `receive`.
 
-## The host application owns HTTP
+## The engine route
 
-The gem draws the same boundary here that it draws for realtime transport:
-the host owns the route, authentication, and rate limits.
+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
@@ -157,6 +183,7 @@ SolidObjects::Transmission.receive(
 
 ## Scope
 
-An engine-mounted route with an authentication hook is a possible
-follow-up; it stays out because it carries authentication, CSRF, and
-rate-limit decisions of its own.
+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.

lib/generators/solid_objects/templates/solid_objects.rb

@@ -49,6 +49,22 @@
   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.
 

lib/solid_objects/configuration.rb

@@ -47,6 +47,8 @@ class Configuration
     # @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 @@ class Configuration
       :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 @@ def initialize
       @authorize_destroy = ->(**) { false }
       @authorize_subscription = ->(**) { false }
       @authorize_administration = ->(**) { false }
+      @authorize_transmission = ->(**) { false }
+      @transmission_actor_type_resolver = ->(actor_type) { actor_type }
       @additional_components = []
     end
 

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

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
 

test/integration/install_generator_test.rb

@@ -23,7 +23,8 @@ class InstallGeneratorTest < ActiveSupport::TestCase
       assert_includes initializer, "authorization_context[:source] == \"cli\""
       assert_includes initializer, "component_authorization_context"
       refute_includes initializer, "component_authorization_context = lambda"
-      assert_equal 5, initializer.scan("= ->(**) { false }").length
+      assert_includes initializer, "configuration.authorize_transmission = ->(**) { false }"
+      assert_equal 6, initializer.scan("= ->(**) { false }").length
     end
   end
 end