mammoth 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6bca055c346ee0a0b651861f60fca15910708ea772b1cfb661cbc8a46040a1e0
-  data.tar.gz: 03d9953cec8a9d82859cbfe446736b4cdc216d46e36244bb5fca4abe455fb0ef
+  metadata.gz: 6333539be1c721f39698edbb27f8285e5b26755b3838dc3f342a198f93b4ff56
+  data.tar.gz: 1c825fea3c20668a1095e69a1931abd01f95bd8eb247365ce1b702e99bb40360
 SHA512:
-  metadata.gz: 3394c678ad2135d34d9d5429599d33d02b8390d7d366821f71356fb0ed50bee71892594901372b0083646f4b8f2332e80977933651102c2e72c3a9309770bee2
-  data.tar.gz: 3b67803444f90aa6951f6c554d70b0d7b6e88d7b020a905edbda6357a3f54a7eacbd5b3087a66fd1c002f740596cdcf9515f5ae565e6eb7f00cf66ecba648791
+  metadata.gz: d2470011cc7d16c9d76afde146d529dc7c56963ade4819e77fa75a81c43b7fc535ba57d7e6291eeea94547365a096e38db9182f0c7af01cc011f05cff81ef5a6
+  data.tar.gz: b06a8a8d35914d9d123fc7843e3c1318624ec5250c3b89656537680ae0bba9b22dfdf8b4bcb278769e3d49d4fabea4571d107119b19fe824b274e8345e45e0e4

data/CHANGELOG.md

@@ -2,6 +2,44 @@
 
 ## Unreleased
 
+## 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

@@ -49,11 +49,12 @@ Mammoth OSS includes:
 - 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, checkpoint, and DLQ handling
 - dead-letter inspection and filtered replay commands
 - CDC-core event serialization boundary
 - CDC Ecosystem source-adapter integration boundary
@@ -61,6 +62,7 @@ Mammoth OSS includes:
 - public Helm chart support
 - unit and e2e test tasks
 - health and 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
@@ -70,8 +72,11 @@ Mammoth OSS includes:
 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
@@ -79,6 +84,17 @@ For the live PostgreSQL stream, `pgoutput-source-adapter` incrementally owns
 transport, parser, decoder, and source adapter and forwards the resulting core
 work to delivery.
 
+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
 
 Mammoth OSS exposes small adapter registries for future extensions:
@@ -135,7 +151,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 +169,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

data/config/mammoth.schema.json

@@ -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,24 +4,28 @@ 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.
   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
 
     # @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)
       @delivery_worker = sink ? build_delivery_worker(sink: sink, sleeper: sleeper) : build_configured_delivery_worker(sleeper:)
     end
@@ -67,41 +71,18 @@ 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
+        process_work(runtime, work)
+        processed += 1
       end
 
-      processed + flush_batch(runtime, batch)
-    end
-
-    def flush_batch(runtime, batch)
-      return 0 unless runtime_batching?(runtime) && batch.any?
-
-      process_batch(runtime, batch)
+      runtime.flush
+      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
@@ -110,7 +91,9 @@ module Mammoth
         processor: DeliveryProcessor.new(delivery_worker:, delivery_unit: delivery_unit),
         concurrency: runtime_concurrency,
         timeout: runtime_timeout,
-        preserve_order: runtime_preserve_order?
+        preserve_order: runtime_preserve_order?,
+        batch_size: runtime_batch_size,
+        observer: observer
       )
     end
 
@@ -124,6 +107,7 @@ module Mammoth
         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 +148,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

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

data/lib/mammoth/commands/status_command.rb

@@ -5,14 +5,14 @@ module Mammoth
   module Commands
     # Reusable local command object for status inspection.
     class StatusCommand
-      attr_reader :config, :sqlite_store, :output
+      attr_reader :config, :state_adapter, :output
 
       # @param config [Mammoth::Configuration] loaded configuration
-      # @param sqlite_store [Mammoth::SQLiteStore, nil] optional operational store
+      # @param state_adapter [Mammoth::OperationalState::Adapter, nil] operational state dependency
       # @param output [#puts] output stream
-      def initialize(config, sqlite_store: nil, output: $stdout)
+      def initialize(config, state_adapter: nil, output: $stdout)
         @config = config
-        @sqlite_store = sqlite_store
+        @state_adapter = state_adapter || OperationalState::Registry.build_configured(config)
         @output = output
       end
 
@@ -20,7 +20,7 @@ module Mammoth
       #
       # @return [Integer] process-style status code
       def call
-        Status.call(config, sqlite_store: sqlite_store, output: output)
+        Status.call(config, state_adapter: state_adapter, output: output)
         0
       end
     end

data/lib/mammoth/concurrent_delivery_runtime.rb

@@ -7,17 +7,19 @@ module Mammoth
   # I/O fan-out to cdc-concurrent. This class is intentionally small so the
   # runtime boundary remains easy to test and replace.
   class ConcurrentDeliveryRuntime
-    attr_reader :processor, :concurrency, :timeout, :preserve_order, :pool
+    attr_reader :processor, :concurrency, :timeout, :preserve_order, :pool, :observer
 
     # @param processor [#process] delivery processor
     # @param concurrency [Integer] number of concurrent delivery workers
     # @param timeout [Numeric, nil] optional per-item timeout
     # @param preserve_order [Boolean] preserve output order when supported
-    def initialize(processor:, concurrency:, timeout:, preserve_order:)
+    # @param observer [CDC::Core::Observer] dispatch lifecycle observer
+    def initialize(processor:, concurrency:, timeout:, preserve_order:, observer: CDC::Core::Observer.new)
       @processor = processor
       @concurrency = concurrency
       @timeout = timeout
       @preserve_order = preserve_order
+      @observer = observer
       @pool = build_pool
     end
 
@@ -28,7 +30,10 @@ module Mammoth
     def process_many(items)
       return [] if items.empty?
 
-      pool.process_many(items)
+      items.each { |item| observer.dispatch_started(item) }
+      pool.process_many(items).tap do |results|
+        results.each { |result| observe_result(result) }
+      end
     end
 
     # Shutdown the underlying runtime when supported.
@@ -41,6 +46,13 @@ module Mammoth
 
     private
 
+    def observe_result(result)
+      return observer.dispatch_succeeded(result) if result.success?
+      return observer.dispatch_failed(result) if result.failure?
+
+      observer.dispatch_skipped(result)
+    end
+
     def build_pool
       require "cdc/concurrent"
       CDC::Concurrent::ProcessorPool.new(processor:, concurrency:, timeout:, preserve_order:)

data/lib/mammoth/dead_letter_commands.rb

@@ -7,27 +7,19 @@ module Mammoth
   # Operator commands for inspecting and replaying dead letters.
   # rubocop:disable Metrics/ClassLength
   class DeadLetterCommands
-    # 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
-    )
-
     attr_reader :argv, :lifecycle_hooks
 
     # @param argv [Array<String>] command line arguments
-    def self.call(argv, lifecycle_hooks: LifecycleHooks.new)
-      new(argv, lifecycle_hooks: lifecycle_hooks).call
+    def self.call(argv, state_adapter: nil, lifecycle_hooks: LifecycleHooks.new)
+      new(argv, state_adapter: state_adapter, lifecycle_hooks: lifecycle_hooks).call
     end
 
     # @param argv [Array<String>] command line 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.is_a?(LifecycleHooks) ? lifecycle_hooks : LifecycleHooks.new(lifecycle_hooks)
     end
 
@@ -98,11 +90,15 @@ module Mammoth
     end
 
     def dead_letter_store
-      @dead_letter_store ||= DeadLetterStore.new(SQLiteStore.connect(load_config.dig("sqlite", "path")).bootstrap!)
+      @dead_letter_store ||= state_adapter.dead_letter_store
+    end
+
+    def state_adapter
+      @state_adapter ||= OperationalState::Registry.build_configured(load_config)
     end
 
     def worker
-      @worker ||= Application.new(load_config).delivery_worker
+      @worker ||= Application.new(load_config, state_adapter: state_adapter).delivery_worker
     end
 
     def dead_letter_id
@@ -250,9 +246,10 @@ module Mammoth
     end
 
     def replay_event(destination_name, payload)
-      return worker.deliver_to(destination_name, payload) if worker.respond_to?(:deliver_to)
+      event = PersistedPayloadDeserializer.event(payload)
+      return worker.deliver_to(destination_name, event) if worker.respond_to?(:deliver_to)
 
-      worker.deliver(payload)
+      worker.deliver(event)
     end
 
     def replay_transaction(destination_name, envelope)
@@ -270,14 +267,7 @@ module Mammoth
     end
 
     def transaction_envelope(payload)
-      DEAD_LETTER_TRANSACTION_ENVELOPE.new(
-        payload.fetch("events"),
-        payload.fetch("transaction_id"),
-        payload["source_position"],
-        payload["commit_lsn"],
-        payload["committed_at"],
-        payload["metadata"] || {}
-      )
+      PersistedPayloadDeserializer.transaction(payload)
     end
 
     def show_payload(row)
@@ -315,6 +305,7 @@ module Mammoth
     def replay_context(extra = {})
       {
         config: load_config,
+        state_adapter: state_adapter,
         dead_letter_store: dead_letter_store,
         delivery_worker: worker
       }.merge(extra)

data/lib/mammoth/dead_letter_store.rb

@@ -15,7 +15,7 @@ module Mammoth
 
     # Store a failed delivery.
     #
-    # @param event [Hash] normalized event payload
+    # @param event [CDC::Core::ChangeEvent, CDC::Core::TransactionEnvelope] normalized core work item
     # @param destination_name [String] destination name
     # @param error [Exception, nil] delivery failure
     # @param retry_count [Integer] number of delivery attempts

data/lib/mammoth/delivery_processor.rb

@@ -6,7 +6,7 @@ module Mammoth
   # The processor keeps cdc-concurrent integration narrow: cdc-concurrent owns
   # I/O-heavy fan-out mechanics, while DeliveryWorker owns Mammoth relay
   # semantics such as retries, dead letters, and checkpoint writes.
-  class DeliveryProcessor
+  class DeliveryProcessor < CDC::Core::Processor
     @concurrent_safe = false
 
     class << self
@@ -37,6 +37,7 @@ module Mammoth
     # @param delivery_worker [Mammoth::DeliveryWorker] relay-aware delivery worker
     # @param delivery_unit [String, Symbol] event or transaction
     def initialize(delivery_worker:, delivery_unit: :event)
+      super()
       @delivery_worker = delivery_worker
       @delivery_unit = delivery_unit.to_sym
     end
@@ -51,7 +52,7 @@ module Mammoth
     # Process one work item from CDC::Concurrent::ProcessorPool.
     #
     # @param work [Object] event or transaction envelope
-    # @return [Hash] delivery summary
+    # @return [CDC::Core::ProcessorResult] normalized processor result
     def call(work)
       process(work)
     end
@@ -59,14 +60,52 @@ module Mammoth
     # Process one work item using the configured delivery unit.
     #
     # @param work [Object] event or transaction envelope
-    # @return [Hash] delivery summary
+    # @return [CDC::Core::ProcessorResult] normalized processor result
     def process(work)
-      case delivery_unit
-      when :transaction
-        delivery_worker.deliver_transaction(work)
+      summary = deliver(work)
+      build_result(work, summary)
+    rescue StandardError => e
+      failure_result(work, e, retryable: e.is_a?(DeliveryError))
+    end
+
+    private
+
+    def deliver(work)
+      return delivery_worker.deliver_transaction(work) if delivery_unit == :transaction
+
+      delivery_worker.deliver(work)
+    end
+
+    def build_result(work, summary)
+      case summary[:status].to_s
+      when "skipped"
+        CDC::Core::ProcessorResult.skipped(work, metadata: result_metadata(summary))
+      when "dead_lettered", "fanout_partial"
+        failure_result(work, DeliveryError.new(failure_reason(summary)), retryable: false, summary: summary)
       else
-        delivery_worker.deliver(work)
+        CDC::Core::ProcessorResult.success(work, value: summary, metadata: result_metadata(summary))
       end
     end
+
+    def failure_result(work, error, retryable:, summary: nil)
+      CDC::Core::ProcessorResult.failure(
+        error,
+        event: work,
+        reason: error.message,
+        retryable: retryable,
+        processor: self.class.name,
+        metadata: result_metadata(summary)
+      )
+    end
+
+    def failure_reason(summary)
+      "delivery completed with #{summary.fetch(:status)} status"
+    end
+
+    def result_metadata(summary)
+      metadata = { processor: self.class.name, delivery_unit: delivery_unit.to_s }
+      metadata[:delivery] = summary if summary
+      metadata
+    end
   end
 end