mammoth 0.9.0 → 1.0.0

data/lib/mammoth/observability_server.rb

@@ -15,18 +15,20 @@ module Mammoth
     # Default TCP port for the observability server.
     DEFAULT_PORT = 9393
 
-    attr_reader :config, :host, :port, :state_adapter, :logger, :server
+    attr_reader :config, :host, :port, :state_adapter, :slot_health_provider, :logger, :server
 
     # @param config [Mammoth::Configuration] loaded configuration
     # @param host [String, nil] bind host override
     # @param port [Integer, nil] bind port override
     # @param state_adapter [Mammoth::OperationalState::Adapter, nil] operational state dependency
+    # @param slot_health_provider [#slot_health, nil] PostgreSQL slot health dependency
     # @param logger [WEBrick::Log, nil] optional WEBrick logger
-    def initialize(config, host: nil, port: nil, state_adapter: nil, logger: nil)
+    def initialize(config, host: nil, port: nil, state_adapter: nil, slot_health_provider: nil, logger: nil)
       @config = config
       @host = host || config.dig("observability", "host") || DEFAULT_HOST
       @port = port || config.dig("observability", "port") || DEFAULT_PORT
       @state_adapter = state_adapter || OperationalState::Registry.build_configured(config)
+      @slot_health_provider = slot_health_provider || Sources::Postgres.new(config)
       @logger = logger || WEBrick::Log.new($stderr, WEBrick::Log::WARN)
       @server = build_server
       mount_endpoints
@@ -81,7 +83,7 @@ module Mammoth
     end
 
     def snapshot
-      ObservabilitySnapshot.new(config, state_adapter: state_adapter)
+      ObservabilitySnapshot.new(config, state_adapter:, slot_health_provider:)
     end
   end
 end

data/lib/mammoth/observability_snapshot.rb

@@ -3,27 +3,30 @@
 require "time"
 
 module Mammoth
-  # Builds health, readiness, and metrics snapshots from Mammoth's local
-  # operational state.
+  # Builds health, readiness, and metrics snapshots from Mammoth's operational
+  # state and optional PostgreSQL slot-health provider.
   #
   # ObservabilitySnapshot is intentionally read-only. It does not start the
-  # relay, mutate checkpoints, replay dead letters, or inspect PostgreSQL. The
-  # health and metrics endpoints use this object to expose Mammoth process and
-  # operational-state adapter status in a predictable format.
-  class ObservabilitySnapshot
+  # relay, mutate checkpoints, replay dead letters, or change PostgreSQL slot
+  # state. An injected provider may perform read-only slot inspection. The
+  # endpoints expose process, operational-state, and source status predictably.
+  class ObservabilitySnapshot # rubocop:disable Metrics/ClassLength
     include ObservabilityMetrics
 
-    attr_reader :config, :state_adapter, :clock, :dispatch_metrics
+    attr_reader :config, :state_adapter, :clock, :dispatch_metrics, :slot_health_provider
 
     # @param config [Mammoth::Configuration] loaded configuration
     # @param state_adapter [Mammoth::OperationalState::Adapter, nil] operational state dependency
     # @param clock [#call] time source returning a Time-like object
     # @param dispatch_metrics [Mammoth::DispatchMetrics] dispatch counter registry
-    def initialize(config, state_adapter: nil, clock: -> { Time.now.utc }, dispatch_metrics: DispatchMetrics::INSTANCE)
+    # @param slot_health_provider [#slot_health, nil] PostgreSQL slot health dependency
+    def initialize(config, state_adapter: nil, clock: -> { Time.now.utc }, dispatch_metrics: DispatchMetrics::INSTANCE,
+                   slot_health_provider: nil)
       @config = config
       @state_adapter = state_adapter || OperationalState::Registry.build_configured(config)
       @clock = clock
       @dispatch_metrics = dispatch_metrics
+      @slot_health_provider = slot_health_provider
     end
 
     # Build a liveness response.
@@ -45,7 +48,7 @@ module Mammoth
     def readiness
       return unready_payload unless state_adapter.ready?
 
-      {
+      payload = {
         status: "ready",
         service: "mammoth",
         name: mammoth_name,
@@ -54,6 +57,14 @@ module Mammoth
         summary: state_summary,
         checked_at: checked_at
       }
+      return payload unless slot_health_provider
+
+      health = postgres_slot_health
+      return postgres_unready_payload(health) unless health.ready?
+
+      payload.merge(postgres_slot: health.summary)
+    rescue ReplicationError => e
+      postgres_error_payload(e)
     rescue Mammoth::Error => e
       adapter_error_payload(e)
     end
@@ -71,7 +82,7 @@ module Mammoth
       ) + destination_metric_lines(
         dead_letter_store: state_adapter.dead_letter_store,
         delivered_store: state_adapter.delivered_envelope_store
-      ) + dispatch_metric_lines
+      ) + dispatch_metric_lines + postgres_slot_metric_lines
       "#{lines.join("\n")}\n"
     rescue Mammoth::Error
       down_metrics
@@ -92,6 +103,36 @@ module Mammoth
       }
     end
 
+    def postgres_unready_payload(health)
+      {
+        status: "unready",
+        service: "mammoth",
+        name: mammoth_name,
+        operational_state: "ok",
+        adapter: state_summary.fetch(:adapter),
+        summary: state_summary,
+        postgres_slot: health.summary,
+        checked_at: checked_at
+      }
+    end
+
+    def postgres_error_payload(error)
+      {
+        status: "unready",
+        service: "mammoth",
+        name: mammoth_name,
+        operational_state: "ok",
+        adapter: configured_adapter_name,
+        postgres_slot: {
+          ready: false,
+          reason: "inspection failed",
+          error_class: error.class.name,
+          error_message: error.message
+        },
+        checked_at: checked_at
+      }
+    end
+
     def aggregate_metric_lines(checkpoint_store:, dead_letter_store:, delivered_store:)
       [
         metric_line("mammoth_up", 1),
@@ -136,6 +177,18 @@ module Mammoth
       "#{(metric_headers + [metric_line("mammoth_up", 0)] + dispatch_metric_lines).join("\n")}\n"
     end
 
+    def postgres_slot_metric_lines
+      return [] unless slot_health_provider
+
+      postgres_metric_lines(postgres_slot_health)
+    rescue ReplicationError
+      postgres_inspection_error_metric_lines
+    end
+
+    def postgres_slot_health
+      slot_health_provider.slot_health
+    end
+
     def state_summary
       @state_summary ||= state_adapter.summary
     end

data/lib/mammoth/postgres_observability_metrics.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Mammoth
+  # PostgreSQL slot-specific Prometheus formatting helpers.
+  module PostgresObservabilityMetrics
+    # Metric names and help text for PostgreSQL replication-slot gauges.
+    POSTGRES_METRICS = {
+      "mammoth_postgres_slot_inspection_up" => "1 when PostgreSQL slot inspection succeeds.",
+      "mammoth_postgres_slot_present" => "1 when the configured replication slot exists.",
+      "mammoth_postgres_slot_ready" => "1 when the configured slot is healthy and active.",
+      "mammoth_postgres_slot_active" => "1 when PostgreSQL reports the slot as active.",
+      "mammoth_postgres_slot_retained_wal_bytes" => "WAL retained from the slot restart LSN.",
+      "mammoth_postgres_slot_safe_wal_size_bytes" => "WAL bytes that may be written before the slot risks loss.",
+      "mammoth_postgres_slot_wal_status" => "Current PostgreSQL WAL retention status for the slot.",
+      "mammoth_postgres_slot_invalidated" => "1 when PostgreSQL reports invalidation or conflict.",
+      "mammoth_postgres_slot_inactive_since_timestamp_seconds" => "Unix timestamp when the slot became inactive.",
+      "mammoth_postgres_slot_restart_lsn_bytes" => "Numeric PostgreSQL restart LSN.",
+      "mammoth_postgres_slot_confirmed_flush_lsn_bytes" => "Numeric PostgreSQL confirmed flush LSN."
+    }.freeze
+
+    private
+
+    def postgres_metric_headers
+      POSTGRES_METRICS.flat_map { |name, help| ["# HELP #{name} #{help}", "# TYPE #{name} gauge"] }
+    end
+
+    def postgres_metric_lines(health)
+      labels = { slot_name: health.slot_name }
+      lines = postgres_presence_metric_lines(health, labels:)
+      return lines unless health.present
+
+      lines + postgres_status_metric_lines(health, labels:) + postgres_optional_metric_lines(health, labels:)
+    end
+
+    def postgres_presence_metric_lines(health, labels:)
+      [
+        metric_line("mammoth_postgres_slot_inspection_up", 1, labels:),
+        metric_line("mammoth_postgres_slot_present", health.present ? 1 : 0, labels:)
+      ]
+    end
+
+    def postgres_status_metric_lines(health, labels:)
+      [
+        metric_line("mammoth_postgres_slot_ready", health.ready? ? 1 : 0, labels:),
+        metric_line("mammoth_postgres_slot_active", health.active ? 1 : 0, labels:),
+        metric_line("mammoth_postgres_slot_wal_status", 1,
+                    labels: labels.merge(wal_status: health.wal_status || "unknown")),
+        metric_line("mammoth_postgres_slot_invalidated", invalidated?(health) ? 1 : 0, labels:)
+      ]
+    end
+
+    def postgres_optional_metric_lines(health, labels:)
+      {
+        "mammoth_postgres_slot_retained_wal_bytes" => health.retained_wal_bytes,
+        "mammoth_postgres_slot_safe_wal_size_bytes" => health.safe_wal_size,
+        "mammoth_postgres_slot_inactive_since_timestamp_seconds" => timestamp_seconds(health.inactive_since),
+        "mammoth_postgres_slot_restart_lsn_bytes" => health.restart_lsn_bytes,
+        "mammoth_postgres_slot_confirmed_flush_lsn_bytes" => health.confirmed_flush_lsn_bytes
+      }.filter_map { |name, value| metric_line(name, value, labels:) unless value.nil? }
+    end
+
+    def postgres_inspection_error_metric_lines
+      labels = { slot_name: config.dig("replication", "slot") }
+      [metric_line("mammoth_postgres_slot_inspection_up", 0, labels:)]
+    end
+
+    def timestamp_seconds(value)
+      return nil if value.nil?
+      return value.to_i if value.respond_to?(:to_i) && !value.is_a?(String)
+
+      Time.parse(value.to_s).to_i
+    rescue ArgumentError
+      nil
+    end
+
+    def invalidated?(health)
+      health.conflicting || (!health.invalidation_reason.nil? && health.invalidation_reason != "")
+    end
+  end
+end

data/lib/mammoth/replication_consumer.rb

@@ -27,7 +27,7 @@ module Mammoth
 
       count = 0
 
-      each_event do |event|
+      each_grouped_event do |event, _group_end|
         yield event
         count += 1
       end
@@ -35,11 +35,27 @@ module Mammoth
       count
     end
 
+    # Consume work with an explicit source-group boundary for safe progress.
+    #
+    # @yieldparam event [CDC::Core::ChangeEvent, CDC::Core::TransactionEnvelope] core work item
+    # @yieldparam group_end [Boolean] true for the final delivery in a source transaction
+    # @return [Integer] number of consumed work items
+    def start_with_boundaries
+      return enum_for(:start_with_boundaries) unless block_given?
+
+      count = 0
+      each_grouped_event do |event, group_end|
+        yield event, group_end
+        count += 1
+      end
+      count
+    end
+
     private
 
-    def each_event(&block)
+    def each_grouped_event(&block)
       effective_source.each do |work|
-        flatten_cdc_work(work).each(&block)
+        grouped_cdc_work(work).each { |event, group_end| block.call(event, group_end) }
       end
     end
 
@@ -47,15 +63,20 @@ module Mammoth
       source || raise(ReplicationError, "replication source is not configured")
     end
 
-    def flatten_cdc_work(work)
+    def grouped_cdc_work(work)
       return [] if work.nil?
-      return work.flat_map { |item| flatten_cdc_work(item) } if work.is_a?(Array)
-      return transaction_work(work) if work.is_a?(CDC::Core::TransactionEnvelope)
-      return event_work(work) if work.is_a?(CDC::Core::ChangeEvent)
+      return work.flat_map { |item| grouped_cdc_work(item) } if work.is_a?(Array)
+      return grouped_transaction_work(work) if work.is_a?(CDC::Core::TransactionEnvelope)
+      return event_work(work).map { |item| [item, true] } if work.is_a?(CDC::Core::ChangeEvent)
 
       raise ReplicationError, "CDC source yielded non-core work: #{work.class}"
     end
 
+    def grouped_transaction_work(envelope)
+      items = transaction_work(envelope)
+      items.each_with_index.map { |item, index| [item, index == items.length - 1] }
+    end
+
     def transaction_delivery?
       delivery_unit == :transaction
     end

data/lib/mammoth/sources/postgres.rb

@@ -27,6 +27,8 @@ module Mammoth
       attr_reader :adapter
       # @return [Mammoth::CheckpointStore, nil] checkpoint store used for restart resume
       attr_reader :checkpoint_store
+      # @return [#inspect, nil] injected PostgreSQL publication inspector
+      attr_reader :publication_inspector
 
       # Build a PostgreSQL CDC source.
       #
@@ -36,13 +38,16 @@ module Mammoth
       # @param decoder [Object, nil] injected pgoutput decoder
       # @param adapter [Object, nil] injected source adapter
       # @param checkpoint_store [Mammoth::CheckpointStore, nil] persisted checkpoints for restart resume
-      def initialize(config, runner: nil, parser: nil, decoder: nil, adapter: nil, checkpoint_store: nil)
+      # @param publication_inspector [#inspect, nil] injected publication metadata inspector
+      def initialize(config, runner: nil, parser: nil, decoder: nil, adapter: nil, checkpoint_store: nil,
+                     publication_inspector: nil)
         @config = config
         @runner = runner
         @parser = parser
         @decoder = decoder
         @adapter = adapter
         @checkpoint_store = checkpoint_store
+        @publication_inspector = publication_inspector
       end
 
       # Stream CDC::Core work from PostgreSQL logical replication.
@@ -59,13 +64,15 @@ module Mammoth
       def each(&block)
         return enum_for(:each) unless block_given?
 
+        preflight_slot!
+        preflight_replica_identity!
         normalizer = effective_adapter
         unless normalizer.respond_to?(:each_normalized)
           raise ReplicationError, "pgoutput source adapter must respond to #each_normalized"
         end
 
         normalizer.each_normalized(decoded_stream) do |work|
-          block.call(validate_core_work!(work))
+          yield_with_progress_position(validate_core_work!(work), &block)
         end
         nil
       rescue StandardError => e
@@ -74,11 +81,65 @@ module Mammoth
         raise ReplicationError, "PostgreSQL CDC source failed: #{e.message}"
       end
 
+      # Acknowledge a durably handled PostgreSQL WAL position.
+      #
+      # @param lsn [String, Integer] pgoutput-client compatible WAL position
+      # @return [Integer] normalized acknowledged WAL position
+      def acknowledge(lsn)
+        effective_runner.ack(lsn)
+      rescue StandardError => e
+        raise ReplicationError, "PostgreSQL WAL acknowledgement failed: #{e.message}"
+      end
+
+      # Resolve the acknowledgement-compatible transport position for work
+      # currently being yielded by this source.
+      #
+      # @param work [CDC::Core::ChangeEvent, CDC::Core::TransactionEnvelope] yielded work
+      # @return [String, Integer, nil] pgoutput-client compatible WAL position
+      def progress_position_for(work)
+        return nil unless yielded_work_includes?(work)
+
+        @yielded_progress_position
+      end
+
+      # Inspect the configured slot for readiness and operator metrics.
+      #
+      # pgoutput-client owns catalog access. This method converts its snapshot
+      # into Mammoth's PostgreSQL-specific health policy without leaking
+      # transport-library types into the observability layer.
+      #
+      # @return [PostgresSlotHealth]
+      def slot_health
+        status = inspected_slot_status
+        return PostgresSlotHealth.missing(required_config("replication", "slot")) unless status
+
+        PostgresSlotHealth.new(
+          slot_name: value_from(status, :slot_name),
+          present: true,
+          active: value_from(status, :active) == true,
+          retained_wal_bytes: value_from(status, :retained_wal_bytes),
+          wal_status: value_from(status, :wal_status),
+          safe_wal_size: value_from(status, :safe_wal_size),
+          inactive_since: value_from(status, :inactive_since),
+          invalidation_reason: value_from(status, :invalidation_reason),
+          restart_lsn: value_from(status, :restart_lsn),
+          restart_lsn_bytes: metric_lsn(value_from(status, :restart_lsn)),
+          confirmed_flush_lsn: value_from(status, :confirmed_flush_lsn),
+          confirmed_flush_lsn_bytes: metric_lsn(value_from(status, :confirmed_flush_lsn)),
+          conflicting: value_from(status, :conflicting) == true
+        )
+      rescue StandardError => e
+        raise e if e.is_a?(ReplicationError)
+
+        raise ReplicationError, "PostgreSQL slot health inspection failed: #{e.message}"
+      end
+
       private
 
       def decoded_stream
         Enumerator.new do |stream|
           effective_runner.start do |payload, metadata = nil|
+            @latest_progress_position = acknowledgement_position(metadata)
             process_payload(payload, metadata) { |decoded| stream << stream_event(decoded, metadata) }
           end
         end
@@ -108,6 +169,15 @@ module Mammoth
         normalizer.stream_event(decoded, source_position: source_position(metadata))
       end
 
+      def yield_with_progress_position(work)
+        @yielded_work = work
+        @yielded_progress_position = @latest_progress_position
+        yield work
+      ensure
+        @yielded_work = nil
+        @yielded_progress_position = nil
+      end
+
       def validate_core_work!(work)
         return work if work.is_a?(CDC::Core::ChangeEvent)
         return work if work.is_a?(CDC::Core::TransactionEnvelope)
@@ -156,6 +226,22 @@ module Mammoth
         value_from(metadata, :source_position, :commit_lsn, :lsn, :wal_end_lsn, :end_lsn, :final_lsn)
       end
 
+      def acknowledgement_position(metadata)
+        value = value_from(metadata, :wal_end_lsn, :wal_end, :lsn)
+        return nil if value.nil?
+        return value if value.is_a?(Integer) && value >= 0
+        return value if value.is_a?(String) && value.match?(%r{\A[0-9A-F]+/[0-9A-F]+\z}i)
+
+        raise ReplicationError, "invalid PostgreSQL transport LSN for acknowledgement: #{value.inspect}"
+      end
+
+      def yielded_work_includes?(work)
+        return true if @yielded_work.equal?(work)
+        return false unless @yielded_work.is_a?(CDC::Core::TransactionEnvelope)
+
+        @yielded_work.events.any? { |event| event.equal?(work) }
+      end
+
       def effective_runner
         runner || @effective_runner || begin
           @effective_runner = build_runner
@@ -180,6 +266,12 @@ module Mammoth
         end
       end
 
+      def effective_publication_inspector
+        publication_inspector || @effective_publication_inspector || begin
+          @effective_publication_inspector = build_publication_inspector
+        end
+      end
+
       def build_runner
         require_optional!("pgoutput/client", "pgoutput-client")
 
@@ -201,7 +293,12 @@ module Mammoth
       def build_adapter
         require_optional!("pgoutput/source_adapter", "pgoutput-source-adapter")
 
-        Pgoutput::SourceAdapter::Cdc.new
+        resolver = Pgoutput::SourceAdapter::ReplicaIdentityResolver.new(replica_identity_relations)
+        Pgoutput::SourceAdapter::Cdc.new(primary_key_resolver: resolver)
+      end
+
+      def build_publication_inspector
+        PostgresPublicationInspector.new(database_url:)
       end
 
       def runner_options
@@ -210,7 +307,7 @@ module Mammoth
           slot_name: required_config("replication", "slot"),
           publication_names: required_publications,
           start_lsn: replication_start_lsn,
-          auto_create_slot: config.dig("replication", "auto_create_slot") == true,
+          auto_create_slot: safe_auto_create_slot?,
           temporary_slot: config.dig("replication", "temporary_slot") == true
         }.tap do |options|
           feedback_interval = config.dig("replication", "feedback_interval")
@@ -225,6 +322,157 @@ module Mammoth
         checkpoint_lsn
       end
 
+      def preflight_slot!
+        resume_lsn = replication_start_lsn
+        validate_temporary_slot_resume!(resume_lsn)
+        status = inspected_slot_status
+
+        if status.nil?
+          return if safe_auto_create_slot?
+
+          raise ReplicationError, missing_slot_message(resume_lsn)
+        end
+
+        validate_slot_identity!(status)
+        validate_slot_health!(status)
+        validate_slot_reachability!(status, resume_lsn) unless blank?(resume_lsn)
+        nil
+      rescue StandardError => e
+        raise e if e.is_a?(ReplicationError)
+
+        raise ReplicationError, "PostgreSQL slot preflight failed: #{e.message}"
+      end
+
+      def preflight_replica_identity!
+        invalid_tables = publication_tables.reject(&:identity_usable?)
+        return if invalid_tables.empty?
+
+        details = invalid_tables.map do |table|
+          "#{table.qualified_name} (actions=#{table.identity_actions.join("/")}, " \
+            "replica_identity=#{replica_identity_name(table.replica_identity)})"
+        end
+        raise ReplicationError,
+              "PostgreSQL replica identity preflight failed for #{details.join(", ")}. " \
+              "Add a primary key, select an eligible unique index with REPLICA IDENTITY USING INDEX, " \
+              "use REPLICA IDENTITY FULL, or remove UPDATE/DELETE from the publication."
+      rescue StandardError => e
+        raise e if e.is_a?(ReplicationError)
+
+        raise ReplicationError, "PostgreSQL replica identity preflight failed: #{e.message}"
+      end
+
+      def publication_tables
+        @publication_tables ||= effective_publication_inspector.inspect(required_publications).freeze
+      end
+
+      def replica_identity_relations
+        relations = {} # : Hash[Integer | [String, String], Array[String]]
+        publication_tables.each do |table|
+          next if table.replica_identity_columns.empty?
+
+          columns = table.replica_identity_columns
+          relations[table.relation_id] = columns
+          relations[[table.schema_name, table.table_name]] = columns
+        end
+        relations
+      end
+
+      def inspected_slot_status
+        client = effective_runner
+        unless client.respond_to?(:slot_status)
+          raise ReplicationError, "pgoutput-client 0.4+ with #slot_status is required for PostgreSQL slot inspection"
+        end
+
+        client.slot_status
+      end
+
+      def validate_temporary_slot_resume!(resume_lsn)
+        return if blank?(resume_lsn)
+        return unless config.dig("replication", "temporary_slot") == true
+
+        raise ReplicationError, "cannot resume durable PostgreSQL checkpoint #{resume_lsn} with a temporary slot"
+      end
+
+      def validate_slot_identity!(status)
+        slot_name = required_config("replication", "slot")
+        unless value_from(status, :slot_name) == slot_name
+          raise ReplicationError, "PostgreSQL slot preflight returned the wrong slot for #{slot_name}"
+        end
+        unless value_from(status, :slot_type) == "logical" && value_from(status, :plugin) == "pgoutput"
+          raise ReplicationError, "PostgreSQL slot #{slot_name} must be a logical pgoutput slot"
+        end
+
+        database = required_config("postgres", "database")
+        return if value_from(status, :database) == database
+
+        raise ReplicationError, "PostgreSQL slot #{slot_name} belongs to a different database"
+      end
+
+      def validate_slot_health!(status)
+        slot_name = required_config("replication", "slot")
+        raise ReplicationError, "PostgreSQL slot #{slot_name} is already active" if value_from(status, :active) == true
+
+        wal_status = value_from(status, :wal_status)
+        if %w[lost unreserved].include?(wal_status)
+          raise ReplicationError, "PostgreSQL slot #{slot_name} cannot retain required WAL (wal_status=#{wal_status})"
+        end
+
+        invalidation_reason = value_from(status, :invalidation_reason)
+        if value_from(status, :conflicting) == true || !blank?(invalidation_reason)
+          raise ReplicationError,
+                "PostgreSQL slot #{slot_name} is invalidated#{": #{invalidation_reason}" unless blank?(invalidation_reason)}"
+        end
+
+        return unless blank?(value_from(status, :restart_lsn))
+
+        raise ReplicationError, "PostgreSQL slot #{slot_name} has no reachable restart LSN"
+      end
+
+      def validate_slot_reachability!(status, resume_lsn)
+        requested = parse_transport_lsn(resume_lsn, "resume checkpoint")
+        %i[restart_lsn confirmed_flush_lsn].each do |field|
+          boundary = value_from(status, field)
+          next if blank?(boundary)
+          next unless requested < parse_transport_lsn(boundary, field.to_s)
+
+          raise ReplicationError,
+                "PostgreSQL slot cannot serve checkpoint #{resume_lsn}; #{field}=#{boundary} has already advanced past it"
+        end
+      end
+
+      def parse_transport_lsn(value, label)
+        require_optional!("pgoutput/client", "pgoutput-client")
+        Pgoutput::Client::LSN.parse(value)
+      rescue StandardError => e
+        raise ReplicationError, "invalid PostgreSQL #{label} LSN #{value.inspect}: #{e.message}"
+      end
+
+      def metric_lsn(value)
+        return nil if blank?(value)
+
+        parse_transport_lsn(value, "slot metric")
+      end
+
+      def replica_identity_name(value)
+        {
+          "d" => "default",
+          "n" => "nothing",
+          "f" => "full",
+          "i" => "index"
+        }.fetch(value, value)
+      end
+
+      def safe_auto_create_slot?
+        config.dig("replication", "auto_create_slot") == true && blank?(replication_start_lsn)
+      end
+
+      def missing_slot_message(resume_lsn)
+        slot_name = required_config("replication", "slot")
+        return "PostgreSQL slot #{slot_name} is missing and auto_create_slot is disabled" if blank?(resume_lsn)
+
+        "PostgreSQL slot #{slot_name} is missing; refusing to recreate it while checkpoint #{resume_lsn} requires continuity"
+      end
+
       def checkpoint_lsn
         return nil unless checkpoint_store