solid_objects 0.13.3 → 0.14.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9045039767fa2e9ff5a4b5cd2bceb97ca5bc8ea0101b41aaac8fcefcf8a694ef
-  data.tar.gz: efed76c2524be2f7a9591a631c56355f95edaf39332cea846fb895363b8d8d68
+  metadata.gz: d3b9abc40f188e1ea4964cfffca89e030990948c937a8aca0ec32c19830da272
+  data.tar.gz: 57707f08fc468d705202bbc3f20ddd60bfed4cd3d9153c58b7a06c981051ef93
 SHA512:
-  metadata.gz: 691972f84f5304cbe3f3be42b5889697b179f1eca38e55d76f87827e0ffc5c095ec97c0d591fa58680829920c807bde08619dc725add17be7f1215439775f064
-  data.tar.gz: 68bff7f63f6557e50a6262e22b33fd7633372ec77a33e35b37f95d074498b66b98b01527776b18acbe2ae6527133c6bf7588e50f98e501a0c5636101dac6f45d
+  metadata.gz: 203477264f47ba941dd4a29b08e00ce5e8ccce298fce361beeaed73f54d3fb1edbbd46f05733e44eaacb366301fc1a6128f084024976268e42ce302d6a7aab76
+  data.tar.gz: 1f82eeb81cd282bbf0cdabc3e4346376b21f5688997440a3f6790f3332f2762764d3a3e3a48778629702c0604480e4e0a6380a677d76a106d9f439c466302cf4

data/CHANGELOG.md

@@ -1,5 +1,84 @@
 # 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
+  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:
 
@@ -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.
@@ -1273,7 +1281,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/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/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/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/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
@@ -112,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
@@ -129,7 +149,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/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