legion-transport 1.4.30 → 1.4.32

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f6143d2993acf25fc55bce28552b4c92e005b4835bd0431dc1f34483022fd29f
-  data.tar.gz: 83cc2c75cf8d799e8e79b721e2b252520f74b5daea593161db921cba5d14386c
+  metadata.gz: 03b783d62b4f350acbc74c3cd55501ad8a86af2123006085e0d78ef0d22101e0
+  data.tar.gz: b5d109c65eb57c52050c61cfe3e5de6330c0a9ad5eaebd814e90355f0ec08264
 SHA512:
-  metadata.gz: 4705576bed71ba1cdf4fd2d69eedf36fce852cf654f6dc5bcf1b4c16cedb75b4e8163328f097de57400684a4afce808785aa46bfb7a46aae4999e9bc5fc69322
-  data.tar.gz: 125eaffbcfed0dd34957e753836db2a3050772f54b7dfc76b5c9cf8cd82a45708e37c40444004ae5c3c49ea91a1631b23062b6277ebaedab722fc8bc06032994
+  metadata.gz: 95416ee45e311a0ba0c3883556ce6e91e384cc7d7980de85e60cb73a5cbe937381e69e3ceeb080f2cf939f095844826e7858588e6f0fa0616bde6933a7bb532a
+  data.tar.gz: e78f9eedf46b3beb2aa69c586ffe41b9c258f6acb1583117ee689dfb3c762d97a7869ba4bf38f98e4373469cf1760caea7c203f0b53ce5dc5e4674e9ac02472a

data/.github/workflows/ci.yml

@@ -8,15 +8,18 @@ on:
 
 jobs:
   ci:
-    uses: LegionIO/.github/.github/workflows/ci.yml@main
+    uses: LegionIO/.github/.github/workflows/ci.yml@e0fc7364b73f446d4cb9bdc162a66ed34bf0daa7
     with:
       needs-rabbitmq: true
+      companion-gems: ${{ github.event_name == 'pull_request' && '{"legion-settings":{"repository":"LegionIO/legion-settings","ref":"8e73a9ef3c13958e3e1e7fc98532e41283159706"}}' || '{}' }}
 
   lint:
     uses: LegionIO/.github/.github/workflows/lint-patterns.yml@main
 
   security:
-    uses: LegionIO/.github/.github/workflows/security-scan.yml@main
+    uses: LegionIO/.github/.github/workflows/security-scan.yml@e0fc7364b73f446d4cb9bdc162a66ed34bf0daa7
+    with:
+      companion-gems: ${{ github.event_name == 'pull_request' && '{"legion-settings":{"repository":"LegionIO/legion-settings","ref":"8e73a9ef3c13958e3e1e7fc98532e41283159706"}}' || '{}' }}
 
   version-changelog:
     uses: LegionIO/.github/.github/workflows/version-changelog.yml@main

data/.gitignore

@@ -16,3 +16,4 @@
 legionio.key
 # git worktrees
 .worktrees/
+/.ci-dependencies/

data/.rubocop.yml

@@ -16,6 +16,9 @@ Layout/HashAlignment:
 Metrics/MethodLength:
   Max: 50
 
+Metrics/ParameterLists:
+  CountKeywordArgs: false
+
 Metrics/ClassLength:
   Max: 1500
 

data/CHANGELOG.md

@@ -2,6 +2,54 @@
 
 ## [Unreleased]
 
+## [1.4.32] - 2026-10-30
+
+### Added
+- Add strict `Message#publish!` and raw `Publisher.publish!` APIs backed by Transport-owned local `transport.task_publication` policy; return explicit accepted results or raise `PublishRejected` exposing the original result. Keep legacy non-task publication behavior unchanged and disable duplicate spooling for task outbox handoffs by default.
+- Preserve canonical task lineage, policy identity, typed engine/schema context, attempts, deadlines and schedule metadata across task subclasses and raw-byte retries.
+- Own the immutable task wire contract in `Legion::Transport::Task::Protocol`, with status/route lookup and terminal recognition helpers independent of runtime settings, Data and Core. Nest task protocol and envelope implementations under `lib/legion/transport/task/`.
+
+### Fixed
+- Preserve fixed task stage routes and canonical statuses despite local configuration drift, reject missing task routes, and route meaningful short templates/structured conditions without string-length bypasses.
+- Implement lite manual acknowledgement, rejection/requeue, redelivery metadata and ownership-safe cancellation/channel recovery. Resume existing surviving consumers after cancellation/channel closure, including self-cancellation, without delivering onto a closing session. Preserve callback failures as recoverable pending work without claiming delivery or looping synchronously on rejects.
+- Declare Base64 as a direct runtime dependency so standalone consumers can load spool support on Ruby 3.4 and newer without incidental dependencies.
+- Read message limits and metadata, connection/TLS policy, Vault configuration and routing directly from live `Legion::Settings[:transport]`; remove cached settings snapshots and optional-dependency fallbacks.
+- Reject missing or invalid payload safety limits with a configuration error before broker publication.
+- Restore persisted date/time and numeric-string AMQP timestamps to Unix seconds before spool replay; preserve ciphertext and IVs, and retain unparseable timestamp records in recovery without blocking healthy messages.
+- Restore the public `Connection.settings` API used by subscription actors to create dedicated channels. Read the canonical transport settings on every call so live configuration replacement remains effective.
+- Preserve encryption IVs through task-envelope metadata handling for both existing `publish` and opt-in `publish!` callers.
+- Honor Dynamic constructor and per-publication routing overrides, and retain the supported `task.scheduled` and `transformer.exception` statuses.
+
+### Changed
+- Require generic `legion-settings >= 1.4.5`; register Transport defaults at startup, never during policy reads, and document local publication policy versus stable wire identities and lite-mode durability limits.
+
+## [1.4.31] - 2026-10-29
+
+### Fixed
+- Bound pool checkout with a monotonic deadline that includes connection creation; reserve capacity without holding the pool mutex during network operations, wake waiters on shutdown, and reject late connections.
+- Bound connection shutdown across pooled, publisher, log, and build sessions with one five-second deadline; disable recovery, close sockets, and stop old consumer workers before replacing sessions.
+- Keep forced reconnect exclusive to its owning caller and restore existing queue, channel, and consumer references, bindings, and QoS before notifying reconnect callbacks.
+- Reuse and track thread-local publisher channels in pool mode; preserve publisher caches across repeated forced reconnects without accumulating log channels.
+- Start each Bunny session inside its host failover attempt and clean up failed handshakes before advancing to the next host. Fixes #41.
+- Bound recovery snapshot lock acquisition and invalidate the complete reconnect generation on shutdown; cancelled owners cannot reopen transport or disturb a newer session. Stop legacy Bunny readers before intentional socket closure to avoid asynchronous owner-thread errors.
+- Use the supported zero-argument Bunny confirm API with bounded waits, retain Vault PEM owners for the session/recovery lifetime, and keep DLX cleanup failures from masking declaration failures. Fixes #42.
+- Support the common lite-mode channel factory contract, ordered pending-only delivery outside global locks, exchange-scoped direct/topic/fanout routing, and atomic consumer cancellation with session-owned cleanup. Fixes #43.
+- Apply tenant naming at real declaration/binding/DLX boundaries, scope exchange caches by tenant and declaration context, align provisioning with actual resources, and enforce encoded-byte quotas in message/helper publishing and replay. Fixes #44.
+- Correlate mandatory returns on exchanges, retire ambiguous confirm-timeout channels, persist only successful spool writes, and replay claimed wire records asynchronously after connection recovery with at-least-once confirmation semantics.
+- Preserve existing queues, bindings, and DLQ contents on declaration mismatches; surface required DLX failures, report actual HTTP publish outcomes, and default to persistent messages with prefetch 2 while retaining explicit false/zero overrides. Fixes #45.
+- Fail closed when requested encryption is not ready, bound encryption attempts, retain cipher/IV metadata in spool replay, and preserve explicit plaintext and bootstrap exceptions. Fixes #46.
+- Automatically upgrade historical raw JSONL spool records to durable wire envelopes before replay; preserve routing, tenant, encryption intent and false/zero metadata, replace stale IVs, and reuse stored ciphertext across interrupted replay. Retry key readiness and late-loaded exchange classes without a manual trigger. Retain original data on failed or interrupted conversion and hold file ownership across atomic replacement.
+- Keep spool claim cleanup safe when shutdown interrupts draining or conversion before the progress offset or original handle is initialized.
+- Complete tenant queue and DLQ data migration with explicit/registered manifests, nonmutating plans, exclusive source locks, tenant-conflict checks, byte-preserving routed confirmation before source acknowledgement, bounded resumable progress, and an authenticated-host HTTP endpoint.
+- Quarantine malformed and missing/unroutable-destination spool records without blocking healthy work. Add durable inspect/repair/retry APIs, stable recovery IDs, per-record cross-process ownership, atomic ready-state persistence, and delivered tombstones that prevent stale journal markers from resurrecting completed repairs.
+- Recover historical Dynamic destinations from saved function metadata, scope literal legacy exchanges by the saved tenant, and retry unavailable encryption/extension metadata independently of healthy records. Preserve ciphertext and IV during destination repair.
+- Use Bunny's version-aware acknowledgement/rejection APIs during tenant migration, wait for asynchronous requeue visibility, and preserve structured failures when tenant normalization raises without repeating coercion during logging.
+
+### Changed
+- Direct `Local.subscribe` uses `exchange_name:` for named exchanges; its default is the default exchange, not an unscoped routing-key subscription.
+- New spool records preserve encoded payload bytes and the full envelope. Historical unversioned records upgrade automatically during replay; capacity exhaustion rejects new writes instead of evicting pending data.
+- Standardize changed keyword-based transport methods with anonymous `**` when extra context is unused, preserve intentional keyword forwarding, and use kwargs for internal helpers without migrating existing application-facing positional APIs.
+
 ## [1.4.30] - 2026-07-31
 
 ### Fixed

data/Gemfile

@@ -3,6 +3,16 @@
 source 'https://rubygems.org'
 
 gemspec
+
+dependency_root = if File.directory?(File.expand_path('.ci-dependencies',
+                                                      __dir__))
+                    File.expand_path('.ci-dependencies', __dir__)
+                  else
+                    File.expand_path('..', __dir__)
+                  end
+settings_path = File.join(dependency_root, 'legion-settings')
+gem 'legion-settings', path: settings_path if File.directory?(settings_path)
+
 group :test do
   gem 'rake'
   gem 'rspec'
@@ -10,4 +20,5 @@ group :test do
   gem 'rubocop'
   gem 'rubocop-legion'
   gem 'simplecov'
+  gem 'sinatra', '>= 4.0'
 end

data/README.md

@@ -2,7 +2,7 @@
 
 Legion::Transport is the Ruby gem responsible for connecting LegionIO to its FIFO queue system (RabbitMQ over AMQP 0.9.1). It provides thread-safe connection management, exchange/queue abstractions, message publishing with optional encryption, and consumer wrappers.
 
-**Version**: 1.4.23
+**Version**: 1.4.32
 
 ## Features
 
@@ -36,6 +36,8 @@ gem 'legion-transport'
 
 ## Usage
 
+Keyword-based recovery, spooling, and tenant-migration APIs accept unrelated keyword context without rejecting the call; named option splats still consume or forward their options. Existing positional constructor and message-publish interfaces remain supported.
+
 ### Basic Connection
 
 ```ruby
@@ -91,6 +93,102 @@ result[:accepted] # => true/false
 
 Options merge with the message's defaults — you can override `routing_key:` or `persistent:` per-publish without constructing a new message.
 
+Mandatory publishing waits for publisher confirmation before reporting routed acceptance. Confirm waits use Bunny's zero-argument API and retire a timed-out channel so late acknowledgments cannot contaminate the next send. A timeout is an unknown delivery outcome, not proof that the broker rejected the message.
+
+#### Task pipeline publication
+
+Task producers and durable outbox relays can opt into `publish!` when they need explicit acceptance. The existing `publish(options = nil)` API remains available; existing callers do not automatically acquire strict publication policy:
+
+```ruby
+message = Legion::Transport::Messages::Task.new(
+  function: 'process_order', routing_key: 'orders.process',
+  task_id: 42, parent_id: 7, master_id: 1,
+  principal_id: 'order-service', principal_type: 'service',
+  args: { order_id: 123 }
+)
+
+begin
+  result = message.publish!(spool: false)
+  # result[:accepted] == true and result[:status] == :accepted
+rescue Legion::Transport::PublishRejected => error
+  # error.result has the original :status, :accepted, destination and error details.
+  # Keep/release the outbox intent for retry; do not acknowledge it as delivered.
+end
+```
+
+`Message#publish!(**options)` and `Publisher.publish!(exchange:, payload:, envelope:, **options)` use live, process-local `Legion::Settings[:transport][:task_publication]` through `Legion::Transport::Settings::Helper#transport_task_publication_settings`. Transport registers its defaults at startup with generic `legion-settings >= 1.4.5`; reads never register defaults or cache a loader. Message limits and metadata, connection/TLS configuration, and routing read the live canonical Transport subtree. Defaults enable publisher confirmation, mandatory routing and structured results, use a 5000ms confirmation timeout, and disable the secondary disk spool. Constructor options and call options can explicitly override policy; disabling confirmation or mandatory routing weakens the corresponding guarantee. The bang APIs always return a structured accepted result or raise: spooled, unroutable, nacked, failed and ambiguous timeout outcomes are **not** accepted.
+
+The raw `Publisher.publish!` API is for subscription retries: pass the original bytes and full AMQP envelope, including content encoding, IV, message/correlation IDs, and retry headers. It never re-encodes, re-encrypts or spools the payload. The message API continues using the existing Publisher/Spool implementation. Both message publication APIs preserve task encryption IVs; legacy `publish` retains its existing return convention.
+
+Task, SubTask, Dynamic, CheckSubtask and TaskUpdate preserve canonical task metadata in both the JSON body and AMQP headers: lineage, identity/tenant/worker policy, engine/schema/options, execution attempts/tokens, depth/deadline, schedule/occurrence and definition version. Explicit business arguments stay under `args`, separate from orchestration values such as `results`, `function_args`, `conditions` and `transformation`. Dynamic retains its legacy flat-argument fallback; supply `args:` to prevent that fallback from passing orchestration values to the runner. Headers include the fixed `task_protocol_version` (`1`). An empty or missing task routing key is rejected rather than silently sent to the empty route.
+
+`require 'legion/transport/task/protocol'` exposes the immutable wire contract `Legion::Transport::Task::Protocol`: `STATUSES`, `TERMINAL_STATUSES`, `LEGACY_TERMINAL_STATUSES`, `ROUTES`, `MESSAGE_TYPES`, `VERSION` and `METADATA_FIELDS`. Include or extend its `Helper` for `task_status(name:)`, `task_route(name:)` and `task_terminal_status?(status:)`. Status/route lookup rejects unknown names; terminal recognition includes legacy terminal spellings. Shared task-envelope behavior lives in `legion/transport/task/envelope` under `Legion::Transport::Task::Envelope`.
+
+Stage routes remain `task.subtask.check`, `task.subtask.conditioner`, `task.subtask.transform` and `task.update`. CheckSubtask and TaskUpdate always use these fixed routes; Task, SubTask and Dynamic retain explicit target routing keys, including per-publication overrides. Local settings, including obsolete root `task_execution` overrides, cannot rename wire identities or redefine metadata/version/terminal semantics. Settings is not distributed-consistent storage: publication policy is local, while wire identity is fixed and durable execution authority belongs to the hosting application's database.
+
+Nonblank short templates such as `{}` and structured conditions are routed to their stages rather than bypassed by string-length heuristics. TaskUpdate accepts canonical statuses, including the previously supported `task.scheduled` and `transformer.exception`. `Messages::Task` needs no database and supports an explicit exchange/routing key; `Messages::Dynamic` resolves its existing `function_id` through the host's optional Data model.
+
+#### Lite-mode delivery limits
+
+With `LEGION_MODE=lite`, strict publication accepts only a matching declared queue when mandatory routing is enabled. Acceptance means **queued in process memory**, not durable broker storage or successful execution. Restart/session shutdown loses pending work; there are no RabbitMQ durability, priority, TTL or dead-letter guarantees.
+
+Manual consumers must acknowledge successful work. `queue.acknowledge(tag)` removes an outstanding delivery; `queue.reject(tag, requeue: true)` retains the original bytes/properties and marks redelivery. Cancellation and channel closure return unacknowledged work to surviving session-owned queues and resume already-subscribed consumers without waiting for another publication. Session shutdown closes its consumers before handing shared work to surviving sessions. `requeue: false` discards it. A synchronous rejection is left pending until subsequent queue activity or a replacement subscription, avoiding a tight retry loop. Callback failures propagate and retain pending work; a failing initial backlog subscription is cancelled so replacement consumers can recover it. Direct `Local.subscribe` retains its automatic-acknowledgement API.
+
+Use the Data task/outbox APIs in the hosting application when crash-durable intent is required. Transport does not depend on Data and does not claim lite publication provides that durability.
+
+### Spooling and automatic replay
+
+Connection failures can persist the already encoded wire payload, complete AMQP envelope, effective broker destination, and tenant identity. `:spooled` means the disk write succeeded; a full spool or failed write returns `:failed`.
+
+- Startup, native recovery, and forced recovery schedule one asynchronous replay worker. Network operations run outside spool-write and connection locks.
+- Replay uses the original ciphertext and IV, checks the stored tenant's encoded-byte quota, and removes records only after routed broker confirmation.
+- Replay restores numeric strings and saved date/time strings to Unix timestamp seconds, preserving timezone offsets. Unparseable timestamp strings are quarantined with their original records instead of blocking later messages.
+- Delivery is **at least once**: interruption after broker acceptance but before confirmation is recorded can cause redelivery. Consumers must tolerate duplicates.
+- Concurrent appends are not part of a drainer's claimed file. Shutdown retains the unconfirmed tail for the next startup.
+- Configure `Legion::Settings[:transport][:spool][:directory]` or pass `directory:` to `Spool.setup`; the default is `~/.legionio/spool`. Capacity limits reject new writes rather than deleting pending messages.
+- Manual `Spool.drain` callbacks acknowledge a record only by returning literal `true`.
+
+Older unversioned JSONL files upgrade automatically during replay; no migration command or opt-in is required. Their raw payloads are encoded once, with saved routing, tenant and envelope metadata preserved. Saved encryption flags and evidence of an earlier encrypted attempt take precedence over the current encryption default; explicit plaintext and cluster-secret bootstrap requests remain supported. A stale saved IV is replaced with the IV for the newly encoded bytes, not reused.
+
+The claimed file is streamed to a locked replacement, flushed and fsynced, then atomically renamed before any upgraded record is published. Interrupted conversion retains the original data; interruption after conversion replays the stored wire bytes without re-encrypting. Missing key readiness or extension classes still loading at startup are retried automatically. Concurrent appends and existing versioned records remain intact.
+
+Incomplete destinations, malformed records, and broker-rejected destinations are moved into durable per-record recovery storage under `spool/recovery/`; they do not block healthy records. Missing crypto or extension metadata stays `waiting` and retries automatically. Saved Dynamic function metadata is used when available; a destination that was never recorded is supplied through the repair API, never guessed.
+
+#### Inspect, repair, and replay
+
+```ruby
+spool = Legion::Transport::Spool
+spool.status # pending, quarantined, waiting, delivered_recoveries
+entry = spool.recovery_entries(status: 'quarantined', limit: 100, offset: 0).first
+original = spool.recovery_record(id: entry.fetch(:id))
+# original[:record] is the parsed original; original[:raw_line] is exact original bytes in Base64.
+spool.repair_record(id: entry.fetch(:id), changes: { exchange: 'task', routing_key: 'worker.run' })
+```
+
+Repair atomically persists a `ready` wire record and schedules confirmed replay. Destination-only repairs preserve existing ciphertext and IV. Supported changes are `exchange`, `routing_key`, `tenant_id`, `exchange_type`, `payload`, `headers`, and `encrypt`. Changing a wire record's encryption requires an explicit raw `payload`; changing its tenant requires an explicit `exchange`. A completely malformed record can be repaired by supplying its raw payload, exchange, and routing key. Validation/encryption errors leave the stored record unchanged.
+
+After broker acceptance the entry becomes `delivered`, retains an idempotence tombstone, and releases its stored payload. Delivered entries cannot be repaired/re-published. `spool.retry_recovery(id: ...)` retries the retained destination after external topology/metadata repair; retries preserve earlier repairs and are idempotent after delivery. Per-record cross-process locks serialize repair and replay without blocking unrelated inspection or spool writes.
+
+The host Legion API exposes the same operations under its existing authentication:
+
+| Method | Path | Result |
+|--------|------|--------|
+| GET | `/api/transport/spool` | Pending and recovery-state counts |
+| GET | `/api/transport/spool/recovery?status=quarantined&limit=100&offset=0` | Metadata-only page; no message payloads |
+| GET | `/api/transport/spool/recovery/:id` | Explicit original-record/raw-byte inspection |
+| POST | `/api/transport/spool/recovery/:id/repair` | JSON repair fields; `202` means durable and queued, not yet delivered |
+| POST | `/api/transport/spool/recovery/:id/retry` | `202` ready/waiting, `200` already delivered, `422` still quarantined |
+
+Unknown IDs return `404`; invalid repairs return `422`; unavailable encryption/storage returns `503`. `pending` includes waiting/ready recovery work but excludes quarantined records and delivered tombstones. Ordinary wire replay and repaired replay remain at least once across a crash between broker acceptance and durable local completion.
+
+### Encryption policy
+
+`transport.messages.encrypt: true` or `encrypt: true` requires a ready cluster secret. An unready key raises `Legion::Transport::EncryptionNotReady` before publishing or spooling plaintext. Encryption itself is bounded by `crypt.cluster_secret_timeout` (five seconds when unset). Explicit `encrypt: false` and the cluster-secret bootstrap message remain deliberately unencrypted.
+
+### HTTP publish outcomes
+
+`POST /api/transport/publish` requests mandatory routing and publisher confirmation. Responses distinguish accepted (`201`), spooled/deferred (`202`), unroutable (`422`), confirm timeout (`504`), and failed/nacked (`503`) results. `published: true` is returned only for accepted publication; unexpected exceptions return an error response.
+
 ### Creating a Queue
 
 ```ruby
@@ -125,7 +223,67 @@ exchange.publish(payload, routing_key: 'task.my_runner.my_function')
 }
 ```
 
-Supported server keys: `host:` (string), `hosts:` (array), `server:` (string), `servers:` (array). All are merged and deduped. Port 5672 is injected where omitted. Multiple hosts enable Bunny's cluster failover.
+Supported server keys: `host:` (string), `hosts:` (array), `server:` (string), `servers:` (array). All are merged and deduped. Port 5672 is injected where omitted. Connection setup attempts each configured host, including the AMQP handshake, and closes failed attempts before moving to the next host.
+
+### Pooling and recovery
+
+- Set `transport.connection_pool_size` above `1` to enable lazy session pooling. Publisher channels are reused per thread and tracked for cleanup.
+- Pool checkout uses one monotonic deadline for waiting and connection creation. Shutdown wakes blocked callers with `Legion::Transport::PoolClosed`; a late factory result is closed instead of returning to the pool.
+- `Connection.shutdown` shares a five-second teardown deadline across owned sessions, closes their sockets, and stops consumer workers. Channel or session creation racing with shutdown cannot install stale resources.
+- `Connection.force_reconnect` permits one active reconnect. It restores existing consumer/channel/queue objects, declarations, bindings, and QoS before running `on_force_reconnect` callbacks. Cancelled consumers remain cancelled, and repeated reconnects reuse publisher channels.
+- Restoration failures return `false`, close the failed replacement, and retain the subscription snapshot for a later reconnect attempt. Restoration refuses to rebind channels while old consumer workers remain alive.
+- Recovery snapshots have their own five-second deadline. If an old Bunny channel/consumer lock is stuck, reconnect returns `false` without detaching the old session; release the lock and retry.
+- Shutdown invalidates the entire in-flight reconnect generation. A cancelled snapshot, replacement attempt, or cleanup cannot reopen transport, tear down a newer session, or clear a newer reconnect owner's guard.
+- Intentional teardown stops socket readers before closing their sockets, avoiding Bunny 2.x asynchronous network errors in the session-owning thread. An open lite-mode connection needs no network recovery and retains its consumers during `force_reconnect`.
+
+### Tenant topology and quotas
+
+Enable `transport.tenant_topology.enabled` to scope ordinary queue/exchange declarations, bindings, and DLXs to the active `Legion::TenantContext.current` identity. The default format is `t.<tenant_id>.<name>`; disabled topology and the `default` tenant retain unprefixed names. Configured shared exchanges remain shared. Exchange caches include tenant, effective name, declaration options, and explicit channel context.
+
+`TenantProvisioner.provision(tenant_id)` creates the same `task`, `results`, and `events` resources and corresponding dead-letter topology used by producers and consumers. Message and helper publishing enforce per-tenant message/encoded-byte limits; replay preserves the stored tenant instead of using its worker's ambient context.
+
+Queue, exchange, and DLX mismatches fail without deleting existing topology or messages. Required DLX provisioning errors prevent source-queue construction.
+
+#### Migrating existing unprefixed queues and data
+
+`TenantMigration.migrate` plans and transfers existing queue **and dead-letter** data into tenant-scoped topology. It preserves payload bytes, cipher/IV, AMQP properties and routing keys, and acknowledges each source message only after mandatory routed confirmation at its target. A dedicated per-source transfer exchange prevents delivery to unrelated queues sharing the destination exchange. The original exchange is retained in `x-legion-original-exchange`.
+
+Pause legacy producers and consumers for the selected queues, enable tenant topology, and specify the owning tenant. Active source consumers and contradictory tenant headers/plaintext metadata are refused; ambient thread context never establishes migration ownership.
+
+```ruby
+manifest = [{
+  name: 'orders.jobs',
+  options: { durable: true, arguments: { 'x-queue-type' => 'quorum',
+                                         'x-dead-letter-exchange' => 'orders.dlx' } },
+  bindings: [{ exchange: 'orders', exchange_type: 'topic', routing_key: 'orders.#' }]
+}]
+
+plan = Legion::Transport::TenantMigration.migrate(
+  tenant_id: 'alpha', queues: manifest, dry_run: true
+)
+result = Legion::Transport::TenantMigration.migrate(
+  tenant_id: 'alpha', queues: manifest, max_messages: 10_000, timeout: 30
+)
+```
+
+Dry runs inspect source counts/consumers and resolve names without consuming or creating topology. Execution declares all targets and bindings before transfer, migrates the associated `orders.dlx.queue`, and reports per-queue source/target names, moved/remaining counts, status, and errors. Repeat a `pending` result to resume until `completed`; verify all source counts are zero before resuming tenant-scoped producers/consumers. Sources and their bindings are never deleted. Producers must remain paused during cutover so they cannot repopulate legacy queues after verification.
+
+Omit `queues:` when the process has already instantiated and bound the tenant's real queue wrappers; declarations and bindings are registered automatically and survive wrapper recreation. After a process restart, or for passive-only declarations, supply the manifest or instantiate/bind those wrappers again. Specify non-default exchange types/options and actual queue arguments; unavailable source metadata is not invented. Shared DLQs and connection-exclusive targets are refused rather than assigned to an arbitrary tenant.
+
+`POST /api/transport/tenants/:tenant_id/migrate` accepts the same JSON fields (`queues`, `dry_run`, `max_messages`, `timeout`). Responses are `200` planned/completed, `202` pending, `409` ownership/consumer/topology conflicts, `422` invalid input, or `503` failure. The API inherits the host's authentication.
+
+Broker locks exclude concurrent migrations of the same source. Interrupted/unconfirmed transfers are requeued; a repeat invocation resumes the remaining source messages. Delivery is at least once if the target accepted before source acknowledgement was interrupted. Count/time bounds, encoded-byte quotas, and bounded owned-session teardown apply. Lite mode has no persisted broker topology and explicitly rejects this operation.
+
+### Lite delivery
+
+Lite mode supports exchange-scoped direct, fanout, and topic bindings (`*` matches one word; `#` matches zero or more). Only undelivered messages remain pending; callbacks run outside the global storage mutex, and cancellation unregisters callbacks before completing. Session shutdown retires its own queues and consumers without resetting unrelated sessions.
+
+Direct `Local.subscribe` callers must specify `exchange_name:` for named exchanges; omitting it subscribes only to the default exchange:
+
+```ruby
+Legion::Transport::Local.subscribe('worker.run', exchange_name: 'events') { |payload| puts payload }
+Legion::Transport::Local.publish('events', 'worker.run', 'work')
+```
 
 ## Configuration
 
@@ -143,13 +301,15 @@ Configuration is managed through `legion-settings` with environment variable ove
 | TTL | `transport.messages.ttl` | `nil` |
 | Persistent | `transport.messages.persistent` | `true` |
 
+`Legion::Transport::Connection.settings` exposes the current `Legion::Settings[:transport]` subtree for subscription actors and other connection consumers. It does not cache settings; replacing the live configuration takes effect on the next call.
+
 ### Full Default Settings
 
 ```json
 {
   "type": "rabbitmq",
   "connected": false,
-  "logger_level": "info",
+  "logger_level": "warn",
   "messages": {
     "encrypt": false,
     "ttl": null,
@@ -171,8 +331,7 @@ Configuration is managed through `legion-settings` with environment variable ove
     "block": false,
     "auto_delete": false,
     "arguments": {
-      "x-max-priority": 255,
-      "x-overflow": "reject-publish"
+      "x-queue-type": "quorum"
     }
   },
   "connection": {
@@ -189,7 +348,7 @@ Configuration is managed through `legion-settings` with environment variable ove
     "port": 5672,
     "vhost": "/",
     "recovery_attempts": 10,
-    "logger_level": "info",
+    "logger_level": "warn",
     "connected": false
   },
   "channel": {
@@ -228,10 +387,12 @@ TLS can be configured through transport settings:
   tls_key: '/path/to/key.pem',
   ca_certs: '/path/to/ca.pem',
   verify_peer: true,
-  use_vault_pki: false
+  vault_pki: false
 }
 ```
 
+Vault-issued PEM files remain owned by their Bunny session through native recovery and are explicitly removed when that session is retired or connection creation fails.
+
 ## Dependencies
 
 | Gem | Version | Purpose |

data/legion-transport.gemspec

@@ -26,10 +26,11 @@ Gem::Specification.new do |spec|
     'rubygems_mfa_required' => 'true'
   }
 
+  spec.add_dependency 'base64'
   spec.add_dependency 'bunny', '>= 2.23'
   spec.add_dependency 'concurrent-ruby', '>= 1.2'
   spec.add_dependency 'legion-json', '>= 1.2.0'
   spec.add_dependency 'legion-logging', '>= 1.5.0'
-  spec.add_dependency 'legion-settings', '>= 1.3.12'
+  spec.add_dependency 'legion-settings', '>= 1.4.5'
   spec.add_dependency 'logger'
 end

data/lib/legion/transport/connection/recovery.rb

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+
+require 'timeout'
+
+module Legion
+  module Transport
+    module Connection
+      # A forced reconnect replaces the session, unlike Bunny's automatic recovery.
+      # Keep the original channels: actors retain queues, consumers and channel references.
+      # Capture before teardown; restore only after the old transport and workers stop.
+      class Recovery
+        def self.capture(sessions:, excluded_channels: [], timeout: Legion::Transport::Connection::SHUTDOWN_TIMEOUT, **)
+          Timeout.timeout(timeout) do
+            new(sessions: sessions.compact.uniq, excluded_channels: excluded_channels)
+          end
+        end
+
+        def initialize(sessions:, excluded_channels: [], **)
+          @excluded_channels = excluded_channels
+          @registered_sessions = {}
+          @states = sessions.filter_map { |session| capture_session(session: session) }
+          @mutex = Mutex.new
+          @restored = false
+        end
+
+        def restore(session:, **)
+          @mutex.synchronize do
+            return true if @restored || @states.empty?
+            raise IOError, 'replacement session is not open' unless session&.open?
+            raise IOError, 'partially restored session must be torn down before retrying' if @attempted_session.equal?(session)
+
+            ensure_quiescent_sources!
+            @attempted_session = session
+            active = @states.to_h { |state| [state, active_consumers(state: state)] }
+            @states.each do |state|
+              state[:channels].each { |channel| restore_channel(channel: channel, session: session) }
+            end
+            restore_topology(active: active)
+            active.each do |state, consumers|
+              consumers.each do |consumer|
+                consumer.consumer_tag = state[:consumer_tags].fetch(consumer)
+                consumer.channel.basic_consume_with(consumer)
+                @registered_sessions[consumer] = session
+              end
+            end
+            @restored = true
+          end
+        end
+
+        private
+
+        def capture_session(session:, **)
+          # Network recovery closes channels without unregistering them. Explicit
+          # Channel#close unregisters them, so retained closed channels still need recovery.
+          channels = session.instance_variable_get(:@channel_mutex).synchronize do
+            session.instance_variable_get(:@channels).values.reject do |channel|
+              channel.number.zero? || @excluded_channels.include?(channel)
+            end
+          end
+          return if channels.empty?
+
+          registrations = channels.flat_map do |channel|
+            channel.instance_variable_get(:@consumer_mutex).synchronize { channel.consumers.to_a }
+          end
+          consumers = registrations.map(&:last)
+          queues = (channels.flat_map { |channel| channel.queues.values } + consumers.map(&:queue).grep(::Bunny::Queue)).uniq
+          exchanges = channels.flat_map { |channel| channel.exchanges.values }.uniq
+          state = { session: session, channels: channels, consumers: consumers,
+                    consumer_names: consumers.to_h { |consumer| [consumer, consumer.queue_name] },
+                    consumer_tags: registrations.to_h { |tag, consumer| [consumer, tag] },
+                    queues: [], exchanges: [], queue_bindings: [], exchange_bindings: [] }
+          if session.respond_to?(:topology_registry)
+            capture_registry(state: state, registry: session.topology_registry, queues: queues, exchanges: exchanges)
+          else
+            capture_objects(state: state, queues: queues, exchanges: exchanges)
+          end
+          state
+        end
+
+        def capture_registry(state:, registry:, queues:, exchanges:, **)
+          queues_by_name = queues.group_by(&:name)
+          exchanges_by_name = exchanges.to_h { |exchange| [exchange.name, exchange] }
+          registry.filtered_queues.each do |record|
+            objects = queues_by_name[record.name] || []
+            options = if objects.empty?
+                        { durable: record.durable, exclusive: record.exclusive, auto_delete: record.auto_delete, arguments: record.arguments }
+                      else
+                        objects.first.options.dup
+                      end
+            state[:queues] << { name: record.name, server_named: record.server_named?, options: options, objects: objects,
+                                channel: recovery_channel(state: state, channel: objects.first&.channel || record.channel) }
+          end
+          registry.filtered_exchanges.reject(&:predeclared?).each do |record|
+            object = exchanges_by_name[record.name]
+            options = if object
+                        object.instance_variable_get(:@options).dup
+                      else
+                        { durable: record.durable, auto_delete: record.auto_delete, arguments: record.arguments }
+                      end
+            state[:exchanges] << { name: record.name, type: record.type, options: options,
+                                   channel: recovery_channel(state: state, channel: object&.channel || record.channel) }
+          end
+          capture_registry_bindings(state: state, registry: registry)
+        end
+
+        def capture_registry_bindings(state:, registry:, **)
+          registry.filtered_queue_bindings.each do |binding|
+            state[:queue_bindings] << { queue: binding.destination, exchange: binding.source,
+                                       options: { routing_key: binding.routing_key, arguments: binding.arguments },
+                                       channel: recovery_channel(state: state, channel: binding.channel) }
+          end
+          registry.filtered_exchange_bindings.each do |binding|
+            state[:exchange_bindings] << { source: binding.source, destination: binding.destination,
+                                          options: { routing_key: binding.routing_key, arguments: binding.arguments },
+                                          channel: recovery_channel(state: state, channel: binding.channel) }
+          end
+        end
+
+        def capture_objects(state:, queues:, exchanges:, **)
+          queues.group_by(&:name).each do |name, objects|
+            queue = objects.first
+            state[:queues] << { name: name, server_named: queue.server_named?, options: queue.options.dup,
+                                objects: objects, channel: queue.channel }
+            objects.each do |object|
+              object.instance_variable_get(:@bindings).each do |binding|
+                state[:queue_bindings] << { queue: name, exchange: binding[:exchange], channel: object.channel,
+                                           options: { routing_key: binding[:routing_key], arguments: binding[:arguments] } }
+              end
+            end
+          end
+          exchanges.each do |exchange|
+            unless exchange.predefined?
+              state[:exchanges] << { name: exchange.name, type: exchange.type, channel: exchange.channel,
+                                     options: exchange.instance_variable_get(:@options).dup }
+            end
+            exchange.instance_variable_get(:@bindings).each do |binding|
+              source = binding[:source]
+              state[:exchange_bindings] << { source: source.respond_to?(:name) ? source.name : source,
+                                            destination: exchange.name, channel: exchange.channel, options: binding[:opts].dup }
+            end
+          end
+          state[:queue_bindings].uniq!
+          state[:exchange_bindings].uniq!
+        end
+
+        def recovery_channel(state:, channel:, **)
+          state[:channels].include?(channel) ? channel : state[:channels].first
+        end
+
+        def active_consumers(state:, **)
+          # Channel#close retains the consumer map, whereas Basic.CancelOk removes it.
+          # Recheck after teardown so a cancellation after capture is not resurrected.
+          state[:consumers].select do |consumer|
+            tag = state[:consumer_tags].fetch(consumer)
+            source = @registered_sessions.fetch(consumer, state[:session])
+            registered = !source.respond_to?(:topology_registry) || source.topology_registry.consumers.key?(tag)
+            registered && consumer.channel.consumers[tag].equal?(consumer)
+          end
+        end
+
+        def ensure_quiescent_sources!
+          channels = @states.flat_map { |state| state[:channels] }
+          channels.map(&:connection).uniq.each do |source|
+            reader = source.instance_variable_get(:@reader_loop)&.instance_variable_get(:@thread)
+            raise IOError, 'old session transport or reader is still running' if source.transport.open? || reader&.alive?
+          end
+          # Bunny 3.x delivers plain integer tags. A callback from an old work pool
+          # could acknowledge an unrelated new delivery if allowed to survive rebinding.
+          return unless channels.any? { |channel| Array(channel.work_pool.threads).any?(&:alive?) }
+
+          raise IOError, 'old consumer workers are still running'
+        end
+
+        def restore_channel(channel:, session:, **)
+          number = session.next_channel_id
+          raise IOError, 'replacement session channel limit exhausted' if number.negative?
+
+          pool = channel.work_pool
+          channel.instance_variable_set(:@connection, session)
+          channel.instance_variable_set(:@logger, session.logger)
+          channel.instance_variable_set(:@frame_max, session.frame_max)
+          channel.id = number
+          channel.instance_variable_set(:@work_pool, ::Bunny::ConsumerWorkPool.new(pool.size, pool.abort_on_exception,
+                                                                                   pool.instance_variable_get(:@shutdown_timeout)))
+          channel.send(:reset_continuations)
+          # Bunny 2.x uses versioned delivery tags; advance before accepting deliveries.
+          channel.increment_recoveries_counter if channel.respond_to?(:increment_recoveries_counter)
+          channel.open
+          channel.recover_prefetch_setting
+          channel.recover_confirm_mode
+          channel.recover_tx_mode
+        end
+
+        def restore_topology(active:, **)
+          # Bunny's aggregate recovery either swallows declaration errors (2.x) or
+          # replaces consumers and loses the original queue references (3.x). Use its
+          # recorded topology and protocol APIs, but let every failure reach the caller.
+          active.each_key do |state|
+            state[:exchanges].each do |exchange|
+              next if exchange[:options][:no_declare]
+
+              exchange[:channel].exchange_declare(exchange[:name], exchange[:type], exchange[:options])
+            end
+          end
+          names = active.to_h do |state, _consumers|
+            [state, state[:queues].to_h { |queue| [queue[:name], restore_queue(queue: queue)] }]
+          end
+          active.each do |state, consumers|
+            state[:exchange_bindings].each do |binding|
+              binding[:channel].exchange_bind(binding[:source], binding[:destination], binding[:options])
+            end
+            state[:queue_bindings].each do |binding|
+              binding[:channel].queue_bind(names[state].fetch(binding[:queue], binding[:queue]), binding[:exchange], binding[:options])
+            end
+            consumers.each do |consumer|
+              next if consumer.queue.respond_to?(:name)
+
+              original_name = state[:consumer_names].fetch(consumer)
+              consumer.instance_variable_set(:@queue, names[state].fetch(original_name, original_name))
+            end
+          end
+        end
+
+        def restore_queue(queue:, **)
+          name = queue[:name]
+          unless queue[:options][:no_declare]
+            requested_name = queue[:server_named] ? '' : name
+            name = queue[:channel].queue_declare(requested_name, queue[:options]).queue
+          end
+          queue[:objects].each do |object|
+            object.channel.deregister_queue(object)
+            object.instance_variable_set(:@name, name)
+            object.channel.register_queue(object)
+            object.channel.record_queue(object) if object.channel.respond_to?(:record_queue)
+          end
+          name
+        end
+      end
+    end
+  end
+end