mammoth 1.2.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9169e3ff1f9fad3a07df87cee57891aea0ca6815f356f7ef998e94572a432ea4
-  data.tar.gz: 6ee2140075cb22b1fc0aea3977a33adfd1aa49918d184a823ee3cbcab9b87bac
+  metadata.gz: 55bd93a58c383e07fe1930ed71f20ea52c05dbfa77a2354e258caddd726865ce
+  data.tar.gz: 2b01106f391f82ed0079d7efdf934447cdeb168d2ee5d6029fb8ac7cd8a617b8
 SHA512:
-  metadata.gz: 37191be4257dbab756e5e2ba81bae60905df5a921792001daf12b5ece1bcacbf60c353967b6da5c0de4e71311a8b95311ed37e7f8f2587bcb49e7dfbae6a57bd
-  data.tar.gz: 603479a5b0e7e067743eb6dcb8802ea2077954df50e23a3b29b97bdefb161cb1c47f493dfac919aa27d6a0552f018fcc1a7116e876acca50f71bc716f0d8c539
+  metadata.gz: 4359b50a25fada22578bca1ab80c3afcc187ce6d181110d83157d7231bdc9fb5f32ab407b24d39619cd7e63fa8d4a4fc01c14fd27474f640d53c874c5411eff8
+  data.tar.gz: 62eb55bba9825caaf491f8ed38ceb9f3da95580a57736c6998bb2349fa1980eb472e2ce7c775972ce7d7d9f8d6fa1ad43daffb22da7847b03c6b898c02e25762

data/CHANGELOG.md

@@ -1,6 +1,41 @@
+<!--
+# @title Changelog
+-->
+
 # Changelog
 
-## Unreleased
+## 1.4.0 - 2026-07-19
+
+### Added
+
+- Declared PostgreSQL 14 through PostgreSQL 18, inclusive, as Mammoth's
+  supported server range.
+- Replaced the PostgreSQL 17-only CI gate with real logical-replication E2E
+  coverage across PostgreSQL 14, 15, 16, 17, and 18.
+- Documented the maintained-version support policy, version-dependent
+  `pg_replication_slots` fields, and PostgreSQL 18-only
+  `idle_replication_slot_timeout`.
+
+### Fixed
+
+- Query `pg_replication_slots.invalidation_reason` in the E2E helper only on
+  PostgreSQL 17 and newer; PostgreSQL 16 does not expose that field.
+
+## 1.3.0 - 2026-07-19
+
+### Added
+
+- Added opt-in, destination-scoped payload policies that remove or mask
+  selected columns across event data, identity, and changes before webhook
+  delivery.
+- Added deterministic policy fingerprints and exact prepared-payload handling
+  across signing, retries, dead-letter persistence, and replay.
+- Added a payload-policy projection benchmark and updated the dead-letter replay
+  benchmark to measure exact prepared-payload replay without CDC reconstruction
+  or policy reapplication.
+- Updated `webhooks-quickstart` to mask `orders.customer_email` by default and
+  highlight the applied policy and fingerprint in the Event Console and smoke
+  test.
 
 ## 1.2.0 - 2026-07-19
 

data/README.md

@@ -1,13 +1,25 @@
+<!--
+# @markup markdown
+# @title Github Repo README
+# @author Ken C. Demanawa
+-->
+
 <p align="center">
-  <img src="https://raw.githubusercontent.com/kanutocd/mammoth/main/docs/assets/logo/mammoth-horizontal.svg" alt="Mammoth" width="520">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/kanutocd/mammoth/main/docs/branding/logo/exports/png/mammoth-primary-horizontal-reversed-transparent.png">
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/kanutocd/mammoth/main/docs/branding/logo/exports/png/mammoth-primary-horizontal-light.png">
+    <img src="https://raw.githubusercontent.com/kanutocd/mammoth/main/docs/branding/logo/exports/png/mammoth-primary-horizontal-light.png" alt="Mammoth" width="620">
+  </picture>
 </p>
 
 # Mammoth
 
-[![Gem Version](https://badge.fury.io/rb/mammoth.svg)](https://badge.fury.io/rb/mammoth)
-[![CI](https://github.com/kanutocd/mammoth/workflows/CI/badge.svg)](https://github.com/kanutocd/mammoth/actions)
-[![Ruby Version](https://img.shields.io/badge/ruby-%3E%3D%204.0-ruby.svg)](https://www.ruby-lang.org/en/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Gem Version](https://img.shields.io/gem/v/mammoth?logo=rubygems&logoColor=white)](https://rubygems.org/gems/mammoth)
+[![Requires Ruby 4.0+](https://img.shields.io/badge/Requires-Ruby%204.0%2B-CC342D?logo=ruby&logoColor=white)](https://www.ruby-lang.org/)
+[![CI](https://github.com/kanutocd/mammoth/actions/workflows/ci.yml/badge.svg)](https://github.com/kanutocd/mammoth/actions/workflows/ci.yml)
+[![Tested Against PostgreSQL 14–18](https://img.shields.io/badge/Tested%20Against-PostgreSQL%2014--18-336791?logo=postgresql&logoColor=white)](https://github.com/kanutocd/mammoth/blob/main/.github/workflows/ci.yml#L50)
+[![License](https://img.shields.io/badge/License-MIT-22C55E)](LICENSE.txt)
+
 
 Mammoth is a self-hosted PostgreSQL event relay focused on reliable delivery
 of database change events.
@@ -28,6 +40,20 @@ Mammoth is intentionally boring infrastructure. It uses YAML configuration,
 JSON Schema validation, local SQLite operational state, and the CDC Ecosystem's
 shared vocabulary so operators can inspect, recover, and reason about delivery.
 
+## Supported PostgreSQL versions
+
+Mammoth supports PostgreSQL 14 through PostgreSQL 18, inclusive. These are the
+PostgreSQL major versions currently maintained by the PostgreSQL community and
+covered by Mammoth's real logical-replication E2E compatibility matrix.
+
+Mammoth supports PostgreSQL major versions that are both maintained by the
+PostgreSQL community and included in Mammoth's compatibility test matrix. New
+PostgreSQL majors are unsupported until explicitly tested and documented. EOL
+versions may be removed from the supported range in a subsequent Mammoth minor
+release with release-note notice.
+
+PostgreSQL 19 is a development release and is not supported.
+
 ## Documentation
 
 Documentation site:
@@ -43,13 +69,18 @@ https://kanutocd.github.io/mammoth/Mammoth.html
 The recommended first-run experience is the
 [`webhooks-quickstart`](webhooks-quickstart) stack. One Compose command starts a
 demo application, logical-replication-enabled PostgreSQL, Mammoth, a signed
-webhook receiver with visible retries, and Mammoth health endpoints:
+webhook receiver with visible retries and payload-policy masking, and Mammoth
+health endpoints:
 
 ```bash
 cd webhooks-quickstart
 docker compose up --build --wait
 ```
 
+Released tags default to their matching Mammoth image. When running `main`
+with Unreleased configuration features, follow the quickstart's local-image
+instructions.
+
 Once the flow is visible, follow its
 [`ADAPTING.md`](webhooks-quickstart/ADAPTING.md) guide to connect Mammoth to an
 existing PostgreSQL application. Its optional `monitoring` profile adds seeded
@@ -72,6 +103,7 @@ Mammoth 1.x includes:
 - webhook delivery sink
 - webhook fanout to multiple destinations
 - fanout route filters by schema, table, and operation
+- per-destination payload removal and masking policies
 - per-destination enable/disable and retry policy controls
 - delivery worker with retry, delivered-ledger, and DLQ handling
 - contiguous delivery watermark for checkpoint and PostgreSQL acknowledgement
@@ -99,7 +131,7 @@ modes, not isolated API snippets.
 | --- | --- |
 | [`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. |
+| [`webhook_fanout`](examples/webhook_fanout) | Routed multi-destination fanout, destination payload masking, 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. |
@@ -155,9 +187,12 @@ 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.
+envelopes. `deliver-sample` input crosses
+`PersistedPayloadDeserializer` before entering the live delivery path, so its
+stored hash does not masquerade as CDC-core work. Dead-letter replay is a
+separate destination boundary: Mammoth sends the exact prepared JSON persisted
+for that destination and does not reconstruct CDC work or reapply the current
+payload policy.
 
 ## Extensions
 
@@ -199,11 +234,18 @@ destinations:
       schemas: [public]
       tables: [orders]
       operations: [insert, update]
+    payload_policy:
+      rules:
+        - columns: [customer_email]
+          action: mask
     retry:
       max_attempts: 3
       schedule_seconds: [1, 10]
 ```
 
+See [`docs/PAYLOAD-POLICIES.md`](docs/PAYLOAD-POLICIES.md) for deterministic
+data minimization, retry and dead-letter behavior, and policy boundaries.
+
 ## CLI
 
 ```bash

data/config/mammoth.example.yml

@@ -288,6 +288,23 @@ webhook:
   #   signature_header: X-Mammoth-Signature
   #   timestamp_header: X-Mammoth-Timestamp
 
+  # Optional deterministic payload projection and PII redaction.
+  #
+  # Rules apply after canonical serialization and route evaluation. Matching
+  # columns are scrubbed consistently from data, identity, and changes before
+  # signing, HTTP delivery, retry, and dead-letter persistence.
+  #
+  # payload_policy:
+  #   rules:
+  #     - schemas: [public]
+  #       tables: [customers, orders]
+  #       columns: [customer_email, phone]
+  #       action: remove
+  #     - tables: [customers]
+  #       columns: [external_customer_id]
+  #       action: mask
+  #       replacement: "[PRIVATE]"
+
 # Optional fanout configuration.
 #
 # Use destinations instead of webhook when one PostgreSQL replication stream
@@ -324,6 +341,14 @@ webhook:
 #         - insert
 #         - update
 #
+#     # Optional destination-specific payload policy. Other destinations still
+#     # receive their own independently prepared payloads.
+#     payload_policy:
+#       rules:
+#         - tables: [orders]
+#           columns: [customer_email]
+#           action: remove
+#
 #     # Optional per-destination retry override. Omit to use top-level retry.
 #     retry:
 #       max_attempts: 3

data/config/mammoth.schema.json

@@ -4,6 +4,85 @@
   "title": "Mammoth Configuration",
   "type": "object",
   "additionalProperties": false,
+  "definitions": {
+    "payloadPolicy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "rules"
+      ],
+      "properties": {
+        "rules": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "columns",
+              "action"
+            ],
+            "properties": {
+              "schemas": {
+                "type": "array",
+                "minItems": 1,
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "description": "PostgreSQL schemas matched by this rule. Omit to match every schema."
+              },
+              "tables": {
+                "type": "array",
+                "minItems": 1,
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "description": "PostgreSQL tables matched by this rule. Omit to match every table."
+              },
+              "operations": {
+                "type": "array",
+                "minItems": 1,
+                "items": {
+                  "type": "string",
+                  "enum": [
+                    "insert",
+                    "update",
+                    "delete"
+                  ]
+                },
+                "description": "CDC operations matched by this rule. Omit to match every operation."
+              },
+              "columns": {
+                "type": "array",
+                "minItems": 1,
+                "uniqueItems": true,
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "description": "Column names scrubbed from data, identity, and changes."
+              },
+              "action": {
+                "type": "string",
+                "enum": [
+                  "remove",
+                  "mask"
+                ],
+                "description": "Remove matching columns or replace their non-null values."
+              },
+              "replacement": {
+                "type": "string",
+                "description": "Replacement used by mask. Defaults to [REDACTED]."
+              }
+            }
+          }
+        }
+      },
+      "description": "Deterministic destination payload projection and PII-redaction rules."
+    }
+  },
   "required": [
     "mammoth",
     "postgres",
@@ -237,6 +316,9 @@
             }
           },
           "description": "Optional HMAC-SHA256 request signing for webhook receivers."
+        },
+        "payload_policy": {
+          "$ref": "#/definitions/payloadPolicy"
         }
       },
       "description": "HTTP webhook destination settings. This is shorthand for a single webhook destination; use destinations for fanout."
@@ -361,6 +443,9 @@
             },
             "description": "Optional destination route filter. Event delivery matches one event; transaction delivery matches when any event in the transaction matches and delivers the full envelope."
           },
+          "payload_policy": {
+            "$ref": "#/definitions/payloadPolicy"
+          },
           "retry": {
             "type": "object",
             "additionalProperties": false,

data/lib/mammoth/application.rb

@@ -30,7 +30,15 @@ module Mammoth
       @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:)
+      @delivery_worker = if sink
+                           build_delivery_worker(
+                             sink: sink,
+                             sleeper: sleeper,
+                             delivery_policy: destination_delivery_policy(config.data["webhook"] || {})
+                           )
+                         else
+                           build_configured_delivery_worker(sleeper: sleeper)
+                         end
     end
 
     # @return [Mammoth::SQLiteStore] underlying SQLite store for compatibility
@@ -155,8 +163,8 @@ module Mammoth
     def destination_specs
       destinations = config.data["destinations"]
       unless destinations
-        delivery_policy = {} # : Hash[String, untyped]
-        return [{ sink: WebhookSink.from_config(config), delivery_policy: delivery_policy }]
+        webhook = config.data.fetch("webhook")
+        return [{ sink: WebhookSink.from_config(config), delivery_policy: destination_delivery_policy(webhook) }]
       end
 
       destinations.map.with_index(1) do |destination, index|
@@ -173,7 +181,8 @@ module Mammoth
         "enabled" => destination.fetch("enabled", true),
         "max_attempts" => retry_config.fetch("max_attempts", config.dig("retry", "max_attempts")),
         "schedule_seconds" => retry_config.fetch("schedule_seconds", config.dig("retry", "schedule_seconds")),
-        "route_filter" => RouteFilter.new(destination["route"])
+        "route_filter" => RouteFilter.new(destination["route"]),
+        "payload_policy" => PayloadPolicy.new(destination["payload_policy"])
       }
     end
 

data/lib/mammoth/capabilities.rb

@@ -13,6 +13,7 @@ module Mammoth
       metrics
       routing
       fanout
+      payload_policies
     ].freeze
 
     attr_reader :config

data/lib/mammoth/dead_letter_commands.rb

@@ -238,38 +238,23 @@ module Mammoth
 
     def replay_row(row)
       payload = JSON.parse(row.fetch("payload_json"))
-      if transaction_payload?(payload)
-        replay_transaction(row.fetch("destination_name"), transaction_envelope(payload))
-      else
-        replay_event(row.fetch("destination_name"), payload)
-      end
-    end
+      return replay_payload(row.fetch("destination_name"), payload) if worker.respond_to?(:deliver_payload)
 
-    def replay_event(destination_name, payload)
-      event = PersistedPayloadDeserializer.event(payload)
-      return worker.deliver_to(destination_name, event) if worker.respond_to?(:deliver_to)
-
-      worker.deliver(event)
+      replay_fanout_payload(row.fetch("destination_name"), payload)
     end
 
-    def replay_transaction(destination_name, envelope)
-      return worker.deliver_transaction_to(destination_name, envelope) if worker.respond_to?(:deliver_transaction_to)
+    def replay_payload(_destination_name, payload)
+      worker.deliver_payload(payload)
+    end
 
-      worker.deliver_transaction(envelope)
+    def replay_fanout_payload(destination_name, payload)
+      worker.deliver_payload_to(destination_name, payload)
     end
 
     def replay_resolved?(result)
       result.fetch(:status) == "delivered" || result.fetch(:duplicate, false)
     end
 
-    def transaction_payload?(payload)
-      payload.fetch("type", nil) == TransactionEnvelopeSerializer::PAYLOAD_TYPE
-    end
-
-    def transaction_envelope(payload)
-      PersistedPayloadDeserializer.transaction(payload)
-    end
-
     def show_payload(row)
       row.merge("payload" => JSON.parse(row.fetch("payload_json")))
     end

data/lib/mammoth/dead_letter_store.rb

@@ -20,9 +20,27 @@ module Mammoth
     # @param error [Exception, nil] delivery failure
     # @param retry_count [Integer] number of delivery attempts
     # @return [Integer] inserted dead letter id
-    def write(event:, destination_name:, error: nil, retry_count: 0, serializer: EventSerializer) # rubocop:disable Metrics/MethodLength
+    def write(event:, destination_name:, error: nil, retry_count: 0, serializer: EventSerializer)
+      write_payload(
+        payload: serializer.call(event),
+        destination_name: destination_name,
+        error: error,
+        retry_count: retry_count
+      )
+    end
+
+    # Store the exact payload prepared for one destination.
+    #
+    # Persisting the prepared payload prevents retries and replay from restoring
+    # fields removed by a destination payload policy.
+    #
+    # @param payload [Hash] prepared destination payload
+    # @param destination_name [String] destination name
+    # @param error [Exception, nil] delivery failure
+    # @param retry_count [Integer] number of delivery attempts
+    # @return [Integer] inserted dead letter id
+    def write_payload(payload:, destination_name:, error: nil, retry_count: 0) # rubocop:disable Metrics/MethodLength
       now = Time.now.utc.iso8601
-      payload = serializer.call(event)
       database.execute(
         <<~SQL,
           INSERT INTO dead_letters(

data/lib/mammoth/delivery_worker.rb

@@ -12,7 +12,7 @@ module Mammoth
     DEFAULT_SOURCE = "postgresql"
 
     attr_reader :sink, :checkpoint_store, :dead_letter_store, :delivered_envelope_store, :retry_schedule, :max_attempts,
-                :sleeper, :source_name, :slot_name, :publication_name, :route_filter, :enabled
+                :sleeper, :source_name, :slot_name, :publication_name, :route_filter, :payload_policy, :enabled
 
     # @param sink [#deliver] destination sink
     # @param checkpoint_store [Mammoth::CheckpointStore] retained dependency; shared progress owns writes
@@ -25,10 +25,11 @@ module Mammoth
     # @param retry_schedule [Array<Integer>] retry wait schedule in seconds
     # @param sleeper [#call] sleep strategy, injectable for tests
     # @param route_filter [Mammoth::RouteFilter, nil] optional destination route matcher
+    # @param payload_policy [Mammoth::PayloadPolicy, nil] destination payload transformation policy
     # @param enabled [Boolean] whether this destination accepts new deliveries
     def initialize(sink:, checkpoint_store:, dead_letter_store:, delivered_envelope_store:, source_name:, slot_name:,
                    publication_name:, max_attempts:, retry_schedule:, sleeper: Kernel.method(:sleep),
-                   route_filter: nil, enabled: true)
+                   route_filter: nil, payload_policy: nil, enabled: true)
       @sink = sink
       @checkpoint_store = checkpoint_store
       @dead_letter_store = dead_letter_store
@@ -40,7 +41,11 @@ module Mammoth
       @retry_schedule = retry_schedule
       @sleeper = sleeper
       @route_filter = route_filter || RouteFilter.new
+      @payload_policy = payload_policy || PayloadPolicy.new
       @enabled = enabled
+      return unless @payload_policy.active? && !sink.respond_to?(:deliver_payload)
+
+      raise ConfigurationError, "destination #{destination_name} does not accept prepared payloads"
     end
 
     # Build a delivery worker from Mammoth configuration and stores.
@@ -66,6 +71,7 @@ module Mammoth
         retry_schedule: delivery_policy.fetch("schedule_seconds", config.dig("retry", "schedule_seconds")),
         sleeper: sleeper,
         route_filter: delivery_policy.fetch("route_filter", RouteFilter.new),
+        payload_policy: delivery_policy.fetch("payload_policy", PayloadPolicy.new),
         enabled: delivery_policy.fetch("enabled", true)
       )
     end
@@ -86,16 +92,32 @@ module Mammoth
       deliver_work(event, serializer: EventSerializer, delivery_method: :deliver)
     end
 
+    # Replay one exact destination payload without reapplying the current policy.
+    #
+    # @param payload [Hash] prepared payload persisted in the dead-letter store
+    # @return [Hash] delivery summary
+    def deliver_payload(payload)
+      prepared = PreparedDelivery.from_payload(payload)
+      delivery_method = transaction_payload?(payload) ? :deliver_transaction : :deliver
+      deliver_prepared(prepared, work: nil, delivery_method: delivery_method)
+    end
+
     private
 
-    # rubocop:disable Metrics/MethodLength
     def deliver_work(work, serializer:, delivery_method:)
+      prepared = PreparedDelivery.build(work, serializer: serializer, payload_policy: payload_policy)
+      deliver_prepared(prepared, work: work, delivery_method: delivery_method)
+    end
+
+    # rubocop:disable Metrics/MethodLength
+    def deliver_prepared(prepared, work:, delivery_method:)
       attempts = 0
-      payload = serializer.call(work)
+      canonical_payload = prepared.canonical_payload
+      payload = prepared.payload
       delivery_unit = delivery_unit_for(delivery_method)
-      idempotency_key = idempotency_key_for(payload:, delivery_unit:)
+      idempotency_key = idempotency_key_for(payload: canonical_payload, delivery_unit: delivery_unit)
 
-      skip_result = skip_result_for(payload, idempotency_key:)
+      skip_result = skip_result_for(canonical_payload, idempotency_key: idempotency_key)
       return skip_result if skip_result
 
       if delivered_envelope_store.delivered?(idempotency_key)
@@ -110,7 +132,7 @@ module Mammoth
 
       begin
         attempts += 1
-        result = sink.public_send(delivery_method, work)
+        result = deliver_to_sink(prepared, work: work, delivery_method: delivery_method)
         delivered_envelope_store.record!(
           idempotency_key: idempotency_key,
           source_name: source_name,
@@ -122,7 +144,7 @@ module Mammoth
         )
         result.merge(attempts: attempts, idempotency_key: idempotency_key)
       rescue DeliveryError => e
-        return dead_letter(work, e, attempts, serializer:) if attempts >= max_attempts
+        return dead_letter(payload, e, attempts) if attempts >= max_attempts
 
         wait_before_retry(attempts)
         retry
@@ -166,20 +188,30 @@ module Mammoth
       }
     end
 
-    def dead_letter(event, error, attempts, serializer:)
-      id = dead_letter_store.write(
-        event: event,
+    def wait_before_retry(attempts)
+      wait_seconds = retry_schedule.fetch(attempts - 1, retry_schedule.last)
+      sleeper.call(wait_seconds)
+    end
+
+    def deliver_to_sink(prepared, work:, delivery_method:)
+      return sink.deliver_payload(prepared.payload) if sink.respond_to?(:deliver_payload)
+      return sink.public_send(delivery_method, work) if work && !payload_policy.active?
+
+      raise ConfigurationError, "destination #{destination_name} does not accept prepared payloads"
+    end
+
+    def dead_letter(payload, error, attempts)
+      id = dead_letter_store.write_payload(
+        payload: payload,
         destination_name: sink.name,
         error: error,
-        retry_count: attempts,
-        serializer: serializer
+        retry_count: attempts
       )
       { status: "dead_lettered", dead_letter_id: id, attempts: attempts }
     end
 
-    def wait_before_retry(attempts)
-      wait_seconds = retry_schedule.fetch(attempts - 1, retry_schedule.last)
-      sleeper.call(wait_seconds)
+    def transaction_payload?(payload)
+      payload["type"] == TransactionEnvelopeSerializer::PAYLOAD_TYPE
     end
   end
 end

data/lib/mammoth/destinations/webhook_adapter.rb

@@ -21,7 +21,13 @@ module Mammoth
 
         # @return [Hash] JSON-friendly capabilities
         def capabilities
-          { type: adapter_type, delivery_units: %w[event transaction], signing: true, header_env: true }
+          {
+            type: adapter_type,
+            delivery_units: %w[event transaction],
+            prepared_payloads: true,
+            signing: true,
+            header_env: true
+          }
         end
       end
     end

data/lib/mammoth/fanout_delivery_worker.rb

@@ -46,6 +46,15 @@ module Mammoth
       worker_for(destination_name).deliver_transaction(envelope)
     end
 
+    # Replay one exact prepared payload to one configured destination.
+    #
+    # @param destination_name [String] destination name
+    # @param payload [Hash] prepared destination payload
+    # @return [Hash] destination delivery summary
+    def deliver_payload_to(destination_name, payload)
+      worker_for(destination_name).deliver_payload(payload)
+    end
+
     private
 
     def fanout(delivery_method, work)

data/lib/mammoth/payload_policy.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+
+module Mammoth
+  # Applies deterministic destination-scoped projection and redaction rules.
+  #
+  # Policies operate on serialized Mammoth payloads, never on CDC-core work
+  # items. Column rules scrub every canonical row-value representation: data,
+  # identity, and old/new values in changes.
+  class PayloadPolicy
+    DEFAULT_MASK = "[REDACTED]"
+    POLICY_METADATA_KEY = "mammoth_payload_policy"
+    SUPPORTED_ACTIONS = %w[remove mask].freeze
+
+    attr_reader :config, :fingerprint
+
+    # @param config [Hash, nil] validated payload-policy configuration
+    def initialize(config = nil)
+      @config = deep_freeze(stringify_keys(config || {}))
+      validate!
+      @fingerprint = build_fingerprint if active?
+    end
+
+    # @return [Boolean] whether the policy contains transformation rules
+    def active?
+      rules.any?
+    end
+
+    # Transform one canonical event or transaction payload.
+    #
+    # @param payload [Hash] canonical serialized Mammoth payload
+    # @return [Hash] independent JSON-compatible destination payload
+    def apply(payload)
+      return payload unless active?
+
+      transformed = JSON.parse(JSON.generate(payload))
+      events_for(transformed).each { |event| apply_rules(event) }
+      metadata = transformed["metadata"]
+      metadata = {} unless metadata.is_a?(Hash) # steep:ignore
+      transformed["metadata"] = metadata
+      metadata[POLICY_METADATA_KEY] = { "fingerprint" => fingerprint }
+      transformed
+    end
+
+    private
+
+    def rules
+      config.fetch("rules", [])
+    end
+
+    def validate!
+      rules.each_with_index do |rule, index|
+        action = rule["action"].to_s
+        unless SUPPORTED_ACTIONS.include?(action)
+          raise ConfigurationError, "payload policy rule #{index} has unsupported action #{action}"
+        end
+        raise ConfigurationError, "payload policy rule #{index} requires columns" if Array(rule["columns"]).empty?
+      end
+    end
+
+    def events_for(payload)
+      return payload.fetch("events") if payload["type"] == TransactionEnvelopeSerializer::PAYLOAD_TYPE
+
+      [payload]
+    end
+
+    def apply_rules(event)
+      rules.each do |rule|
+        apply_rule(event, rule) if match?(event, rule)
+      end
+    end
+
+    def apply_rule(event, rule)
+      columns = rule.fetch("columns")
+      if rule.fetch("action") == "remove"
+        remove_columns(event, columns)
+      else
+        mask_columns(event, columns, rule.fetch("replacement", DEFAULT_MASK))
+      end
+    end
+
+    def remove_columns(event, columns)
+      %w[data identity].each do |field|
+        columns.each { |column| event[field]&.delete(column) }
+      end
+      changes = Array(event["changes"]) # : Array[untyped]
+      event["changes"] = changes.reject { |change| columns.include?(change["name"]) }
+    end
+
+    def mask_columns(event, columns, replacement)
+      %w[data identity].each do |field|
+        columns.each { |column| mask_map_value(event[field], column, replacement) }
+      end
+      changes = Array(event["changes"]) # : Array[untyped]
+      changes.each do |change|
+        next unless columns.include?(change["name"])
+
+        %w[old_value new_value].each do |value_key|
+          change[value_key] = replacement if change.key?(value_key) && !change[value_key].nil?
+        end
+      end
+    end
+
+    def mask_map_value(map, column, replacement)
+      return unless map.is_a?(Hash) && map.key?(column)
+      return if map[column].nil?
+
+      map[column] = replacement
+    end
+
+    def match?(event, rule)
+      matches?(rule["schemas"], event["namespace"]) &&
+        matches?(rule["tables"], event["entity"]) &&
+        matches?(rule["operations"], event["operation"])
+    end
+
+    def matches?(configured, actual)
+      values = Array(configured) # : Array[untyped]
+      values.empty? || values.any? { |value| value.to_s.casecmp?(actual.to_s) }
+    end
+
+    def build_fingerprint
+      canonical = canonicalize(config)
+      "sha256:#{Digest::SHA256.hexdigest(JSON.generate(canonical))}"
+    end
+
+    def canonicalize(value)
+      return value.map { |item| canonicalize(item) } if value.is_a?(Array)
+      return value unless value.is_a?(Hash)
+
+      value.keys.sort.to_h { |key| [key, canonicalize(value.fetch(key))] }
+    end
+
+    def stringify_keys(value)
+      return value.map { |item| stringify_keys(item) } if value.is_a?(Array)
+      return value unless value.is_a?(Hash)
+
+      value.to_h { |key, item| [key.to_s, stringify_keys(item)] }
+    end
+
+    def deep_freeze(value)
+      value.each_value { |item| deep_freeze(item) } if value.is_a?(Hash)
+      value.each { |item| deep_freeze(item) } if value.is_a?(Array)
+      value.freeze
+    end
+  end
+end

data/lib/mammoth/prepared_delivery.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Mammoth
+  # Immutable delivery boundary containing canonical identity and outbound data.
+  PreparedDelivery = Data.define(:canonical_payload, :payload, :policy_fingerprint) do
+    # Serialize and apply one destination payload policy.
+    #
+    # @param work [CDC::Core::ChangeEvent, CDC::Core::TransactionEnvelope]
+    # @param serializer [#call] canonical Mammoth serializer
+    # @param payload_policy [Mammoth::PayloadPolicy]
+    # @return [Mammoth::PreparedDelivery]
+    def self.build(work, serializer:, payload_policy:)
+      canonical_payload = serializer.call(work)
+      new(
+        canonical_payload: canonical_payload,
+        payload: payload_policy.apply(canonical_payload),
+        policy_fingerprint: payload_policy.fingerprint
+      )
+    end
+
+    # Reconstruct a prepared delivery from a persisted destination payload.
+    #
+    # @param payload [Hash] previously prepared destination payload
+    # @return [Mammoth::PreparedDelivery]
+    def self.from_payload(payload)
+      fingerprint = payload.dig("metadata", PayloadPolicy::POLICY_METADATA_KEY, "fingerprint")
+      new(canonical_payload: payload, payload: payload, policy_fingerprint: fingerprint)
+    end
+  end
+end

data/lib/mammoth/version.rb

@@ -2,5 +2,5 @@
 
 module Mammoth
   # Current Mammoth gem version.
-  VERSION = "1.2.0"
+  VERSION = "1.4.0"
 end

data/lib/mammoth/webhook_sink.rb

@@ -110,8 +110,14 @@ module Mammoth
       deliver_payload(TransactionEnvelopeSerializer.call(envelope))
     end
 
-    private
-
+    # Deliver an already prepared destination payload.
+    #
+    # The caller owns canonical serialization and payload-policy application.
+    # WebhookSink signs and sends exactly this payload.
+    #
+    # @param payload [Hash] prepared JSON-compatible destination payload
+    # @return [Hash] delivery result
+    # @raise [Mammoth::DeliveryError] when delivery fails
     def deliver_payload(payload)
       response = perform_request(payload)
       return delivery_result(payload, response) if SUCCESS_RANGE.cover?(response.code.to_i)
@@ -121,6 +127,8 @@ module Mammoth
       raise DeliveryError, "webhook #{name} delivery failed: #{e.message}"
     end
 
+    private
+
     def perform_request(payload)
       Net::HTTP.start(url.host, url.port, use_ssl: url.scheme == "https", open_timeout: timeout_seconds,
                                           read_timeout: timeout_seconds) do |http|

data/lib/mammoth.rb

@@ -33,6 +33,8 @@ require_relative "mammoth/event_serializer"
 require_relative "mammoth/transaction_envelope_serializer"
 require_relative "mammoth/persisted_payload_deserializer"
 require_relative "mammoth/route_filter"
+require_relative "mammoth/payload_policy"
+require_relative "mammoth/prepared_delivery"
 require_relative "mammoth/webhook_sink"
 require_relative "mammoth/operational_state/adapter"
 require_relative "mammoth/operational_state/sqlite_adapter"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mammoth
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Ken C. Demanawa
@@ -219,8 +219,10 @@ files:
 - lib/mammoth/operational_state/adapter.rb
 - lib/mammoth/operational_state/registry.rb
 - lib/mammoth/operational_state/sqlite_adapter.rb
+- lib/mammoth/payload_policy.rb
 - lib/mammoth/persisted_payload_deserializer.rb
 - lib/mammoth/postgres_observability_metrics.rb
+- lib/mammoth/prepared_delivery.rb
 - lib/mammoth/registry.rb
 - lib/mammoth/replication_consumer.rb
 - lib/mammoth/route_filter.rb