mammoth 0.8.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6bca055c346ee0a0b651861f60fca15910708ea772b1cfb661cbc8a46040a1e0
-  data.tar.gz: 03d9953cec8a9d82859cbfe446736b4cdc216d46e36244bb5fca4abe455fb0ef
+  metadata.gz: fc13868a4aa6d845e63c655af36b9bbb69604be8bfb5b7ab6beda7d1a765c145
+  data.tar.gz: 9a3c9514953f68db2d5287903e29980ffb147460691817f5de1a19a8123f1727
 SHA512:
-  metadata.gz: 3394c678ad2135d34d9d5429599d33d02b8390d7d366821f71356fb0ed50bee71892594901372b0083646f4b8f2332e80977933651102c2e72c3a9309770bee2
-  data.tar.gz: 3b67803444f90aa6951f6c554d70b0d7b6e88d7b020a905edbda6357a3f54a7eacbd5b3087a66fd1c002f740596cdcf9515f5ae565e6eb7f00cf66ecba648791
+  metadata.gz: 552aa45078fa0ed209890bbfe8eb2dc0672234d4e008c8cc0edd954a284e0b40bffafe16a2a8c2df8dd0219aee3eed742ba2a38531cd3d2acd7b13b35bb48b11
+  data.tar.gz: 69f509480ecdd46aa50a7879c3dbc1589becce9a651b1697e1f164ea0d6be781edb9f54238940a32553b59956c8cba05cd2b0caaffca57812823cb32e6fa481b

data/CHANGELOG.md

@@ -2,6 +2,110 @@
 
 ## Unreleased
 
+## 1.0.0 - 2026-07-17
+
+### Added
+
+- Added PostgreSQL slot readiness diagnostics and Prometheus gauges for
+  inspection availability, presence, activity, retained WAL bytes, safe WAL
+  size, WAL status, invalidation, inactivity time, and restart/flush LSNs.
+- `/readyz` now fails closed when the configured slot is missing, inactive,
+  invalidated, conflicting, WAL-lost, or cannot be inspected.
+- Added startup validation for every configured publication table that publishes
+  `UPDATE` or `DELETE`, accepting a usable primary key, selected replica-identity
+  index, or `REPLICA IDENTITY FULL` and reporting all invalid tables together.
+- Added catalog-derived, ordered replica-identity mappings for relation OIDs and
+  schema-qualified tables.
+- Added a self-verifying live PostgreSQL example for composite, non-`id`
+  replica identities across `INSERT`, `UPDATE`, and `DELETE`.
+- Added a live PostgreSQL example that shows fail-closed restart after slot
+  invalidation and the explicit operator reconciliation required to resume.
+- Added a PostgreSQL observability example correlating Mammoth readiness and
+  Prometheus slot gauges with native replication and publication catalogs.
+- Added a live additive schema-evolution example demonstrating consumer-first
+  compatibility, relation-metadata refresh, and the non-delivery of DDL.
+- Added a destination idempotency example proving atomic receiver-side
+  duplicate suppression across isolated Mammoth delivery ledgers.
+
+### Fixed
+
+- Added PostgreSQL slot preflight before streaming and fail-closed handling for
+  missing, active, lost, invalidated, incompatible, and
+  checkpoint-unreachable slots.
+- Disabled automatic slot recreation whenever a configured or persisted resume
+  LSN requires WAL continuity.
+- Rejected temporary-slot recovery from durable checkpoints.
+- Preserved pgoutput-client's acknowledgement-compatible transport LSN
+  separately from normalized CDC-core `commit_lsn` payload context.
+- Checkpoints and PostgreSQL feedback now use the source-owned transport
+  watermark, preventing decimal transaction commit values from reaching
+  `runner.ack`.
+- Event-mode delivery resolves an envelope's transport position for each exact
+  child event without mutating or rebuilding CDC-core work.
+- Wired publication identity mappings into
+  `Pgoutput::SourceAdapter::ReplicaIdentityResolver` so composite and non-`id`
+  keys are normalized without partial identity data.
+
+### Quality
+
+- Upgraded pgoutput-client to 0.4.0 and covered slot identity, health,
+  retained-WAL reporting, continuity boundaries, and safe first-time creation.
+- Upgraded pgoutput-source-adapter to 0.3.0 and covered catalog-to-resolver
+  composition for composite replica identities.
+- Upgraded pgoutput-decoder to 0.2.0 so key-only old tuples preserve their
+  exact decoded columns instead of synthesizing absent non-key values.
+- Added end-to-end source/coordinator coverage proving that a transaction with
+  decimal `commit_lsn` checkpoints and acknowledges its formatted transport LSN.
+- Added opt-in PostgreSQL 17 integration coverage for transactional `INSERT`,
+  `UPDATE`, and `DELETE` with composite identity, replication reconnects,
+  concurrent out-of-order completion, contiguous slot acknowledgement, and
+  fail-closed slot invalidation; CI and release gates run the suite against a
+  logical-replication service.
+- Strengthened boundary coverage for source-owned position resolution and
+  publication-catalog inspection, and synchronized PostgreSQL, runtime,
+  operational-state, configuration, and transaction-example documentation.
+- Documented PostgreSQL WAL guardrails, slot/catalog monitoring, DDL and
+  sequence limitations, destination conflict ownership, upgrade recovery,
+  troubleshooting, example caveats, and Kubernetes deployment policy.
+
+## 0.9.0
+
+### Changed
+
+- Refactored observability, status, bootstrap, and dead-letter command
+  composition to consume `OperationalState::Adapter` instead of opening SQLite
+  or constructing concrete stores.
+- Added adapter-owned `bootstrap!`, `ready?`, and configured registry
+  composition for backend-neutral operational tooling.
+- Inject the configured operational-state delivered-envelope store into every
+  delivery worker instead of deriving a SQLite ledger from the checkpoint store.
+- Made `Mammoth::DeliveryProcessor` implement `CDC::Core::Processor` and return
+  `CDC::Core::ProcessorResult` for successful, skipped, and failed deliveries.
+- Wired `CDC::Core::Observer` notifications through inline and concurrent
+  runtimes and translated canonical dispatch metrics into Mammoth Prometheus
+  counters.
+- Replaced duck-typed CDC lookalikes with exact `CDC::Core::ChangeEvent` and
+  `CDC::Core::TransactionEnvelope` objects.
+- Enforced the PostgreSQL source output contract by rejecting non-core work
+  yielded by injected source adapters.
+- Added an explicit persisted-payload deserialization boundary for sample JSON
+  and dead-letter replay.
+- Moved configured batch accumulation and final partial-batch submission out of
+  `Mammoth::Application` and into the delivery runtime layer.
+
+### Quality
+
+- Added processor contract, observer, runtime notification, dispatch counter,
+  and Prometheus exposition coverage.
+- Added exact core-type and persisted-payload round-trip coverage.
+- Strengthened architecture boundary coverage with executable pgoutput adapter
+  output checks, downstream dependency guards, and an exact core-output RBS
+  contract for the PostgreSQL source.
+- Added runtime batching ownership coverage so application orchestration cannot
+  reintroduce buffering or batch partitioning.
+- Updated RBS signatures, YARD API documentation, examples, and benchmark
+  descriptions for the corrected processor/observer boundary.
+
 ## 0.8.0
 
 ### Changed

data/README.md

@@ -39,45 +39,105 @@ API documentation:
 https://kanutocd.github.io/mammoth/Mammoth.html
 
 
-## OSS MVP
+## v1.0 Release Scope
 
-Mammoth OSS includes:
+Mammoth 1.0 includes:
 
-- CLI foundation
+- operator CLI for validation, bootstrap, status, delivery, observability, and
+  dead-letter workflows
 - YAML configuration loading
 - JSON Schema-backed configuration validation
 - SQLite operational memory bootstrap
 - checkpoint persistence
 - dead letter persistence
+- delivered-envelope ledger persistence
 - webhook delivery sink
 - webhook fanout to multiple destinations
 - fanout route filters by schema, table, and operation
 - per-destination enable/disable and retry policy controls
-- delivery worker with retry, checkpoint, and DLQ handling
+- delivery worker with retry, delivered-ledger, and DLQ handling
+- contiguous delivery watermark for checkpoint and PostgreSQL acknowledgement
+- source-owned transport LSN preservation independent of payload `commit_lsn`
+- fail-closed PostgreSQL slot and checkpoint continuity preflight
+- fail-closed publication replica-identity preflight for `UPDATE` and `DELETE`
 - dead-letter inspection and filtered replay commands
 - CDC-core event serialization boundary
 - CDC Ecosystem source-adapter integration boundary
 - Docker image support
 - public Helm chart support
 - unit and e2e test tasks
-- health and metrics endpoints
+- health, PostgreSQL slot readiness, and retained-WAL metrics endpoints
+- canonical CDC dispatch counters through a `CDC::Core::Observer`
 - explicit extension registries for state, destination, and runtime adapters
 - node identity and local capability reporting
 - lifecycle hooks, configuration providers, and reusable local command objects
 
+## Feature Examples
+
+The runnable examples are organized around production behaviors and failure
+modes, not isolated API snippets.
+
+| Example | v1 capability demonstrated |
+| --- | --- |
+| [`live_postgres_webhook`](examples/live_postgres_webhook) | End-to-end PostgreSQL logical replication into webhook delivery. |
+| [`transaction_webhook`](examples/transaction_webhook) | TransactionEnvelope preservation through the concurrent runtime. |
+| [`webhook_fanout`](examples/webhook_fanout) | Routed multi-destination fanout, environment-backed headers, signing, and independent retry policies. |
+| [`ordering`](examples/ordering) | Ordered and throughput-oriented transaction scheduling. |
+| [`checkpoint_recovery`](examples/checkpoint_recovery) | Durable restart recovery, replay suppression, checkpointing, and acknowledgement. |
+| [`slot_invalidation_recovery`](examples/slot_invalidation_recovery) | Fail-closed slot invalidation and explicit operator reconciliation. |
+| [`composite_replica_identity`](examples/composite_replica_identity) | Composite, non-`id` replica identity across `INSERT`, `UPDATE`, and `DELETE`. |
+| [`postgres_observability`](examples/postgres_observability) | Slot readiness and Prometheus metrics correlated with PostgreSQL catalogs. |
+| [`schema_evolution`](examples/schema_evolution) | Consumer-first additive schema evolution without implying DDL delivery. |
+| [`destination_idempotency`](examples/destination_idempotency) | Atomic destination-side duplicate suppression across isolated relay ledgers. |
+| [`failing_webhook_retry`](examples/failing_webhook_retry) | Retry exhaustion and durable dead-letter persistence. |
+| [`operational_state`](examples/operational_state) | Inspectable checkpoints, delivered ledgers, and dead letters. |
+| [`kubernetes_helm`](examples/kubernetes_helm) | Single-consumer Kubernetes deployment using the public Helm chart. |
+
+See [`examples/README.md`](examples/README.md) for the complete index, boundary
+notes, and commands.
+
+## v1 Compatibility
+
+Mammoth 1.x treats its validated configuration, serialized webhook envelopes,
+documented CLI command behavior, and forward operational-state migrations as
+supported contracts. Compatible minor releases may add optional configuration
+or payload fields, but do not remove or reinterpret existing fields.
+
+Human-readable CLI formatting and PostgreSQL-derived row columns are not frozen:
+scripts should rely on documented exit behavior, while receivers must tolerate
+additive fields and coordinate source schema changes. See
+[`docs/COMPATIBILITY.md`](docs/COMPATIBILITY.md) for the complete promise and
+major-version boundaries.
+
 ## Boundary
 
 Mammoth begins at CDC-core work items and ends at webhook fanout delivery.
 
 Mammoth does not own pgoutput protocol parsing, value decoding, source
-normalization, ordering policy, or runtime execution. Those belong to the
-upstream CDC Ecosystem components.
+normalization, or core dispatch vocabulary. Those belong to upstream CDC
+Ecosystem components. Mammoth selects and composes a delivery runtime while
+delegating its scheduling mechanics to the runtime layer. The runtime registry
+wraps the selected adapter with configured batch accumulation; `Application`
+only streams core work and coordinates lifecycle flush and shutdown calls.
 
 For the live PostgreSQL stream, `pgoutput-source-adapter` incrementally owns
 `Begin`/`Commit` buffering and emits exact `CDC::Core::ChangeEvent` or
 `CDC::Core::TransactionEnvelope` work items. Mammoth only composes the
 transport, parser, decoder, and source adapter and forwards the resulting core
-work to delivery.
+work to delivery. Mammoth's publication preflight supplies ordered,
+catalog-derived replica-identity columns to the adapter, which owns composite
+and non-`id` key extraction.
+
+At the downstream boundary, `Mammoth::DeliveryProcessor` implements
+`CDC::Core::Processor` and returns `CDC::Core::ProcessorResult`. Inline and
+concurrent runtimes notify a `CDC::Core::Observer`; Mammoth's default observer
+maps the canonical started, succeeded, failed, and skipped notifications to
+Prometheus counters.
+
+`Mammoth::ReplicationConsumer` accepts only exact core events and transaction
+envelopes. Operator-facing JSON, such as `deliver-sample` input and persisted
+dead letters, is reconstructed by `PersistedPayloadDeserializer` before it
+re-enters delivery; stored hashes do not masquerade as live CDC work.
 
 ## Extensions
 
@@ -135,7 +195,8 @@ bundle exec ./exe/mammoth start config/mammoth.example.yml
 bundle exec ./exe/mammoth observability config/mammoth.example.yml
 ```
 
-Deliver a single normalized event JSON file through Mammoth's delivery path:
+Reconstruct and deliver a single persisted event JSON file through Mammoth's
+core delivery path:
 
 ```bash
 bundle exec ./exe/mammoth deliver-sample \
@@ -152,6 +213,10 @@ Mammoth stores operational memory in SQLite:
 - `dead_letters`
 - `delivered_envelopes`
 
+SQLite is the built-in default behind `operational_state.adapter`. Bootstrap,
+status, observability, and dead-letter commands consume the adapter contract
+rather than opening SQLite directly.
+
 ## Performance
 
 Mammoth includes local benchmarks for the product surfaces operators tune in
@@ -185,7 +250,17 @@ script/test-e2e
 ```
 
 The e2e task uses a real HTTP receiver, real SQLite database, and real
-filesystem paths.
+filesystem paths. Set `MAMMOTH_E2E_POSTGRES_URL` to include the real PostgreSQL
+logical-replication scenarios:
+
+```bash
+MAMMOTH_E2E_POSTGRES_URL=postgres://postgres:postgres@127.0.0.1:5432/mammoth_e2e \
+  bundle exec rake test:e2e
+```
+
+The PostgreSQL fixture must have `wal_level=logical`; its test role must be able
+to create publications and logical replication slots, terminate replication
+backends, and change `max_slot_wal_keep_size`.
 
 ## Kubernetes
 
@@ -204,6 +279,14 @@ helm install mammoth charts/mammoth
 The chart uses one replica and `Recreate` strategy to respect PostgreSQL's
 logical replication slot constraint: one slot, one active subscriber.
 
+Production operators should also monitor retained WAL and slot readiness,
+configure PostgreSQL retention guardrails, and alert on database disk and
+catalog health. DDL and sequence state are not replicated; coordinate schema
+changes with webhook consumers and synchronize sequences externally when
+building a writable database copy. See
+[`docs/POSTGRESQL.md`](docs/POSTGRESQL.md) and
+[`docs/TROUBLESHOOTING.md`](docs/TROUBLESHOOTING.md).
+
 ## License
 
 Mammoth OSS is licensed under the [MIT License](LICENSE.txt).

data/config/mammoth.example.yml

@@ -89,6 +89,8 @@ replication:
   #
   # Publications define which table changes PostgreSQL sends to Mammoth.
   # Create them explicitly in production so the database boundary is clear.
+  # Tables that publish UPDATE or DELETE must have a primary key, an eligible
+  # REPLICA IDENTITY USING INDEX, or REPLICA IDENTITY FULL.
   #
   # Example SQL:
   #   CREATE PUBLICATION mammoth_publication FOR TABLE users, orders;
@@ -98,7 +100,9 @@ replication:
   # Optional start LSN for advanced recovery or controlled replay.
   #
   # Leave unset for normal operation. Mammoth will use its checkpoint store and
-  # the replication slot position.
+  # the replication slot position. Persisted PostgreSQL checkpoints use the
+  # acknowledgement-compatible transport LSN, not a normalized transaction's
+  # decimal commit_lsn.
   #
   # Example:
   #   start_lsn: "0/16B6C50"
@@ -108,10 +112,15 @@ replication:
   # Automatically create the replication slot if it does not exist.
   #
   # true:
-  #   Convenient for development, demos, and first-time bootstrap.
+  #   Convenient for development, demos, and first-time bootstrap. Mammoth
+  #   creates a missing slot only when no configured or persisted resume LSN
+  #   requires continuity.
   #
   # false:
   #   Recommended for production when slots are DBA-managed infrastructure.
+  #
+  # A missing slot is never recreated while a checkpoint exists. Mammoth fails
+  # closed because a replacement slot cannot recover the lost WAL interval.
   auto_create_slot: false
 
   # Use a temporary replication slot.
@@ -127,8 +136,9 @@ replication:
 
   # Standby feedback interval in seconds.
   #
-  # Mammoth sends periodic feedback while streaming so PostgreSQL knows the
-  # consumer is alive and can advance slot state safely.
+  # Mammoth sends periodic feedback while streaming. The feedback position
+  # advances only after every earlier delivery has a durable outcome and the
+  # same contiguous position has been written to Mammoth's checkpoint store.
   #
   # Lower values:
   #   faster liveness/feedback visibility, slightly more network chatter
@@ -145,13 +155,13 @@ delivery:
   # Delivery granularity.
   #
   # event:
-  #   Deliver each change event independently. This has lower latency but weaker
-  #   transaction-level semantics.
+  #   Deliver each change event independently. This has lower latency but does
+  #   not give consumers one atomic transaction payload. Checkpoint and WAL
+  #   acknowledgement still wait for every event in the transaction.
   #
   # transaction:
-  #   Deliver a complete TransactionEnvelope as one payload. This is the safer
-  #   default because checkpointing can advance only after the whole transaction
-  #   has been delivered successfully.
+  #   Deliver a complete TransactionEnvelope as one payload. This is recommended
+  #   when downstream consumers need transaction-level context.
   #
   # Recommended:
   #   transaction

data/config/mammoth.schema.json

@@ -141,7 +141,7 @@
             "type": "string",
             "minLength": 1
           },
-          "description": "PostgreSQL publications to subscribe to. Publications define which table changes PostgreSQL sends to Mammoth."
+          "description": "PostgreSQL publications to subscribe to. Publications define which table changes PostgreSQL sends to Mammoth. Tables publishing UPDATE or DELETE require a usable primary key, selected replica-identity index, or REPLICA IDENTITY FULL."
         },
         "start_lsn": {
           "type": [
@@ -152,7 +152,7 @@
         },
         "auto_create_slot": {
           "type": "boolean",
-          "description": "When true, Mammoth creates the replication slot if it does not exist. Convenient for development; DBA-managed slots are recommended for production."
+          "description": "When true, Mammoth creates a missing replication slot only for a fresh stream with no configured or persisted resume LSN. Mammoth never recreates a missing slot while checkpoint continuity is required."
         },
         "temporary_slot": {
           "type": "boolean",
@@ -513,7 +513,7 @@
         "batch_size": {
           "type": "integer",
           "minimum": 1,
-          "description": "Number of work units submitted to the concurrent runtime together. Values greater than 1 allow ordering-insensitive deliveries to overlap more visibly."
+          "description": "Number of work units accumulated by the runtime layer before submission to the selected adapter. Values greater than 1 allow ordering-insensitive deliveries to overlap more visibly."
         },
         "preserve_order": {
           "type": "boolean",

data/lib/mammoth/application.rb

@@ -4,25 +4,32 @@ module Mammoth
   # Top-level Mammoth application runtime.
   #
   # Application wires Mammoth's delivery-side runtime pieces: configuration,
-  # SQLite operational memory, replication consumer, delivery worker, checkpoint
-  # store, dead letter store, and webhook sink. Upstream PostgreSQL transport
+  # operational-state adapter, replication consumer, delivery worker, checkpoint
+  # store, dead-letter store, and webhook sink. Upstream PostgreSQL transport
   # composition stays outside this class so the application runtime consumes an
   # injected CDC work source rather than owning upstream CDC source-adapter
   # lifecycle decisions.
+  # rubocop:disable Metrics/ClassLength
   class Application
-    attr_reader :config, :state_adapter, :consumer, :delivery_worker, :checkpoint_store, :lifecycle_hooks
+    attr_reader :config, :state_adapter, :consumer, :delivery_worker, :checkpoint_store, :lifecycle_hooks, :observer,
+                :progress_coordinator
 
     # @param config [Mammoth::Configuration] loaded configuration
     # @param source [#each, nil] injectable event source for tests and demos
     # @param sink [#deliver, nil] optional destination sink
+    # @param state_adapter [Mammoth::OperationalState::Adapter, nil] operational state dependency
     # @param sleeper [#call] retry sleep strategy
     # @param lifecycle_hooks [Mammoth::LifecycleHooks, Hash] local lifecycle callbacks
-    def initialize(config, source: nil, sink: nil, sleeper: Kernel.method(:sleep), lifecycle_hooks: LifecycleHooks.new)
+    # @param observer [CDC::Core::Observer, nil] dispatch lifecycle observer
+    def initialize(config, source: nil, sink: nil, state_adapter: nil, sleeper: Kernel.method(:sleep),
+                   lifecycle_hooks: LifecycleHooks.new, observer: nil)
       @config = config
       @lifecycle_hooks = build_lifecycle_hooks(lifecycle_hooks)
-      @state_adapter = build_state_adapter
-      @checkpoint_store = state_adapter.checkpoint_store
+      @observer = observer || MetricsObserver.new
+      @state_adapter = state_adapter || build_state_adapter
+      @checkpoint_store = @state_adapter.checkpoint_store
       @consumer = ReplicationConsumer.new(source: source || build_source, delivery_unit: delivery_unit)
+      @progress_coordinator = build_progress_coordinator
       @delivery_worker = sink ? build_delivery_worker(sink: sink, sleeper: sleeper) : build_configured_delivery_worker(sleeper:)
     end
 
@@ -67,50 +74,35 @@ module Mammoth
 
     def process_consumer(runtime)
       processed = 0
-      batch = [nil].compact
-
-      consumer.start do |work|
-        if runtime_batching?(runtime)
-          batch << work
-          next unless batch.size >= runtime_batch_size
-
-          processed += process_batch(runtime, batch)
-          batch = []
-        else
-          process_work(runtime, work)
-          processed += 1
-        end
-      end
-
-      processed + flush_batch(runtime, batch)
-    end
 
-    def flush_batch(runtime, batch)
-      return 0 unless runtime_batching?(runtime) && batch.any?
+      consumer.start_with_boundaries do |work, group_end|
+        progress_coordinator.register(work, group_end:)
+        process_work(runtime, work)
+        processed += 1
+      end
 
-      process_batch(runtime, batch)
+      runtime.flush
+      progress_coordinator.finalize
+      processed
     end
 
     def process_work(runtime, work)
-      runtime.process_many([work])
-    end
-
-    def process_batch(runtime, batch)
-      runtime.process_many(batch)
-      batch.size
-    end
-
-    def runtime_batching?(runtime)
-      runtime && runtime_batch_size > 1
+      runtime.process(work)
     end
 
     def build_runtime
       Runtimes::Registry.build(
         runtime_adapter,
-        processor: DeliveryProcessor.new(delivery_worker:, delivery_unit: delivery_unit),
+        processor: DeliveryProcessor.new(
+          delivery_worker:,
+          delivery_unit: delivery_unit,
+          progress_coordinator: progress_coordinator
+        ),
         concurrency: runtime_concurrency,
         timeout: runtime_timeout,
-        preserve_order: runtime_preserve_order?
+        preserve_order: runtime_preserve_order?,
+        batch_size: runtime_batch_size,
+        observer: observer
       )
     end
 
@@ -118,12 +110,34 @@ module Mammoth
       Sources::Postgres.new(config, checkpoint_store: checkpoint_store)
     end
 
+    def build_progress_coordinator
+      DeliveryProgressCoordinator.new(
+        checkpoint_store: checkpoint_store,
+        source_name: config.dig("mammoth", "name"),
+        slot_name: config.dig("replication", "slot"),
+        publication_name: Array(config.dig("replication", "publications")).join(","),
+        acknowledger: source_acknowledger,
+        position_resolver: source_position_resolver
+      )
+    end
+
+    def source_acknowledger
+      source = consumer.source
+      source.method(:acknowledge) if source.respond_to?(:acknowledge)
+    end
+
+    def source_position_resolver
+      source = consumer.source
+      source.method(:progress_position_for) if source.respond_to?(:progress_position_for)
+    end
+
     def build_delivery_worker(sink:, sleeper:, delivery_policy: {})
       DeliveryWorker.from_config(
         config,
         sink: sink,
         checkpoint_store: checkpoint_store,
         dead_letter_store: state_adapter.dead_letter_store,
+        delivered_envelope_store: state_adapter.delivered_envelope_store,
         sleeper: sleeper,
         delivery_policy: delivery_policy
       )
@@ -164,11 +178,7 @@ module Mammoth
     end
 
     def build_state_adapter
-      OperationalState::Registry.build(operational_state_adapter, config)
-    end
-
-    def operational_state_adapter
-      config.dig("operational_state", "adapter") || "sqlite"
+      OperationalState::Registry.build_configured(config)
     end
 
     def delivery_unit
@@ -196,4 +206,5 @@ module Mammoth
       value.nil? || value
     end
   end
+  # rubocop:enable Metrics/ClassLength
 end

data/lib/mammoth/cli.rb

@@ -5,16 +5,6 @@ require "json"
 module Mammoth
   # Small command dispatcher for Mammoth's operator-facing CLI.
   class CLI
-    # Internal replay envelope used for transaction dead-letter recovery.
-    DEAD_LETTER_TRANSACTION_ENVELOPE = Data.define(
-      :events,
-      :transaction_id,
-      :source_position,
-      :commit_lsn,
-      :committed_at,
-      :metadata
-    )
-
     # Human-readable command usage printed for invalid or incomplete invocations.
     USAGE = [
       "Usage:",
@@ -94,9 +84,7 @@ module Mammoth
     end
 
     def status
-      config = load_config
-      store = SQLiteStore.connect(config.dig("sqlite", "path"))
-      Commands::StatusCommand.new(config, sqlite_store: store).call
+      Commands::StatusCommand.new(load_config).call
     end
 
     def start

data/lib/mammoth/commands/bootstrap_command.rb

@@ -2,23 +2,27 @@
 
 module Mammoth
   module Commands
-    # Initializes the configured operational SQLite database.
+    # Initializes the configured operational-state backend.
     class BootstrapCommand
-      attr_reader :config, :output
+      attr_reader :config, :state_adapter, :output
 
       # @param config [Mammoth::Configuration] loaded configuration
+      # @param state_adapter [Mammoth::OperationalState::Adapter, nil] operational state dependency
       # @param output [#puts] output stream
-      def initialize(config, output: $stdout)
+      def initialize(config, state_adapter: nil, output: $stdout)
         @config = config
+        @state_adapter = state_adapter || OperationalState::Registry.build_configured(config)
         @output = output
       end
 
       # @return [Integer] process-style status code
       def call
-        store = SQLiteStore.connect(config.dig("sqlite", "path")).bootstrap!
-        output.puts "SQLite database initialized"
-        output.puts "Path: #{store.path}"
-        output.puts "Tables: #{store.tables.join(", ")}"
+        state_adapter.bootstrap!
+        summary = state_adapter.summary
+        output.puts "Operational state initialized"
+        output.puts "Adapter: #{summary.fetch(:adapter)}"
+        output.puts "Path: #{summary.fetch(:path)}" if summary.key?(:path)
+        output.puts "Tables: #{Array(summary.fetch(:tables)).join(", ")}" if summary.key?(:tables)
         0
       end
     end

data/lib/mammoth/commands/dead_letters_command.rb

@@ -4,18 +4,20 @@ module Mammoth
   module Commands
     # Reusable local command object for dead-letter inspection and replay.
     class DeadLettersCommand
-      attr_reader :argv, :lifecycle_hooks
+      attr_reader :argv, :state_adapter, :lifecycle_hooks
 
       # @param argv [Array<String>] dead-letters CLI-style arguments
+      # @param state_adapter [Mammoth::OperationalState::Adapter, nil] operational state dependency
       # @param lifecycle_hooks [Mammoth::LifecycleHooks, Hash] local lifecycle callbacks
-      def initialize(argv, lifecycle_hooks: LifecycleHooks.new)
+      def initialize(argv, state_adapter: nil, lifecycle_hooks: LifecycleHooks.new)
         @argv = argv
+        @state_adapter = state_adapter
         @lifecycle_hooks = lifecycle_hooks
       end
 
       # @return [Integer] process-style status code
       def call
-        DeadLetterCommands.call(argv, lifecycle_hooks: lifecycle_hooks)
+        DeadLetterCommands.call(argv, state_adapter: state_adapter, lifecycle_hooks: lifecycle_hooks)
       end
     end
   end

data/lib/mammoth/commands/deliver_sample_command.rb

@@ -23,7 +23,7 @@ module Mammoth
       def call
         raise ConfigurationError, "event JSON file not found: #{event_path}" unless File.file?(event_path)
 
-        event = JSON.parse(File.read(event_path))
+        event = PersistedPayloadDeserializer.event(JSON.parse(File.read(event_path)))
         processed = Application.new(config, source: [event], lifecycle_hooks: lifecycle_hooks).start
         output.puts "Processed sample events: #{processed}"
         0