feat: the transmit family, ingest and staging

[cardmagic]

Closes #47. Closes #48.

What this adds

Both sides of the transmit family, over one wire contract:

• SolidObjects::Transmission.receive(envelope) (RFP: SolidObjects::Transmission.receive, the server ingest for browser transmit envelopes #47): the server ingest for transmit envelopes. It validates a camelCase envelope, resolves the actor type, and enqueues one internal message with the idempotency key transmit:<effectId>.
• Actor#transmit and SolidObjects.register_transmit (RFP: Actor#transmit and register_transmit, the staging side of the transmit family #48): the staging side. transmit.increment(amount:) stages a solid-objects.transmit effect in the same commit as the state change; register_transmit drains staged effects into envelopes and hands each to the delivery block. The ordered drain is ported from solid-objects-js: a claimed transmit effect delivers every undelivered sibling for its actor up to its own mailbox sequence, oldest first.

With both sides in place, Rails-to-Rails, Rails-to-Node, Node-to-Rails, and browser-to-Rails replication ride the same contract. docs/transmission.md documents both sides and the controller boundary.

API

• SolidObjects::Transmission.receive(envelope, resolve_actor_type:, mailbox:) returns a MessageReference. resolve_actor_type: is a per-call proc for diverged actor type names; the default is identity.
• Actor#transmit returns the same fluent dispatcher schedule returns. A raw emit "solid-objects.transmit" with explicit actorType / actorId targets a different actor, matching the JS staging surface.
• SolidObjects.register_transmit(&deliver) wraps register_effect("solid-objects.transmit") with envelope construction and the ordered drain. The block raises to retry.
• SolidObjects::InvalidTransmission < SolidObjects::Error is new and covers malformed envelopes on both sides. UnknownActorType, UnknownMessage, and PayloadTooLarge propagate from the existing primitives.
• The engine mounts POST /solid_objects/transmit (the follow-up RFP: SolidObjects::Transmission.receive, the server ingest for browser transmit envelopes #47 deferred), an ActionController::API endpoint behind the new deny-by-default authorize_transmission policy. The policy receives the parsed envelope and the controller as authorization_context:; the new transmission_actor_type_resolver configuration maps diverged actor type names. 403 for an unauthorized envelope, 422 for a permanently unappliable one.

Correctness

• The idempotency key is transmit:<effectId>, byte-identical in both runtimes. Mailbox#enqueue dedup makes a replayed or redelivered envelope apply once.
• The drain keeps per-actor order across a failed delivery. Redelivery of an already-delivered sibling is safe because the ingest dedups.
• Order also holds under concurrent effect workers on one actor, the hazard a Greptile review of this branch flagged as P1. Two workers can deliver overlapping envelope sets, which is the documented at-least-once overlap and dedups on transmit:<effectId>; a reorder cannot happen, because a drain sends older siblings first and only sends a later envelope after the earlier delivery returned successfully. A race test forces the exact interleaving (worker A claims the early effect and stalls mid-delivery, worker B claims the later effect and drains both) and fails with the predicted reorder against a neutered drain.
• A raised delivery retries with backoff and dead-letters on exhaustion, like any other effect. A malformed staged effect raises InvalidTransmission, dead-letters, and is skipped by sibling drains rather than blocking them.
• Ingest validation and registry lookup happen before persistence. A rejected envelope writes nothing.
• Golden fixtures in compatibility/transmit-envelopes.json pin the wire contract, consumed by both the ingest suite and a staging test that asserts a Ruby-staged envelope matches the fixture. The JS side of solid-objects-js#18 now carries the same file with a consuming suite (four tests: valid fixtures apply once, the duplicate pair applies once, malformed fixtures reject, and a staged envelope matches the fixture), so the contract is enforced from both sides of the repo boundary. The parity ledger rows move when both PRs merge.

Security

• The ingest enqueue uses delivery_mode: "internal", so it skips authorize_message by construction, the same semantics as the JS enqueueInternalMessage. The host application must authenticate the request before it calls receive. docs/transmission.md states this and shows the controller example with a 422 path, so the browser outbox dead-letters an unappliable effect instead of retrying it forever.
• The payload byte cap applies through Serialization.dump before persistence.
• Brakeman reports no warnings.

Migration and compatibility

• No schema change and no migration. Both features compose existing primitives (effects, the mailbox, the effect executor).
• No behavior change for existing callers. transmit and register_transmit are new surface; the effect name solid-objects.transmit is namespaced.
• The engine route adds one route and two configuration defaults; existing applications keep their behavior because authorize_transmission denies by default. Bidirectional replication as a declared surface (the "replica" feature) stays out; the RFP issue records its design questions.

Test-first evidence

Both test files ran before their implementations existed and failed for the expected reasons:

NameError: uninitialized constant SolidObjects::Transmission
15 runs, 3 assertions, 3 failures, 12 errors, 0 skips

NoMethodError: undefined method 'register_transmit' for module SolidObjects
9 runs, 0 assertions, 0 failures, 9 errors, 0 skips

The drain-ordering test was additionally verified against a neutered drain that delivers only the claimed effect; it fails with Expected: [1, 2] Actual: [2], so the test observes the ordering guarantee it claims.

Validation

bundle exec ruby -Itest test/integration/transmission_test.rb
# 15 runs, 45 assertions, 0 failures, 0 errors, 0 skips

bundle exec ruby -Itest test/integration/transmit_staging_test.rb
# 11 runs, 28 assertions, 0 failures, 0 errors, 0 skips

bundle exec ruby -Itest test/integration/transmissions_controller_test.rb
# 10 runs, 28 assertions, 0 failures, 0 errors, 0 skips

bundle exec rake
# 572 runs, 1873 assertions, 0 failures, 0 errors, 15 skips (pre-existing adapter/browser skips)
# Standard, RuboCop, RBS generation and validation, Steep, Brakeman: all clean

[cardmagic]

The contract bug is fixed on the JS side in cardmagic/solid-objects-js@acdcba5 (PR cardmagic/solid-objects-js#18): receiveTransmitEnvelope now defaults a missing arguments to an empty object, matching the Ruby ingest and the JS staging side, so the "increment without arguments" fixture case passes both ingests identically. The same commit pins two contracts from this QA with tests — the optional-arguments default, and IdempotencyConflict on a replay whose arguments changed (with the first application left intact) — and the JS api reference handler now maps InvalidPayload and IdempotencyConflict to 422 explicitly, mirroring the Ruby docs controller.