html2rss 0.27.2 → 0.29.1

data/lib/html2rss/request_service/response.rb

@@ -14,11 +14,15 @@ module Html2rss
 
       # Bodies that look like HTML even when Content-Type is missing, empty, or wrong.
       HTML_BODY_SNIFF = /\A\s*(?:<!DOCTYPE\s+html|<html)/i
+      # Content-Type markers for RSS/Atom syndication responses.
+      FEED_CT_MARKERS = %w[rss+xml atom+xml rss atom].freeze
+      # Body sniff for unlabeled syndication (first 800 bytes, downcased).
+      FEED_BODY_MARKERS = ['<rss', '<feed xmlns', '<feed '].freeze
       # Charset from Content-Type or a leading <meta charset>.
       CHARSET_PARAMETER = /charset\s*=\s*["']?([\w.:-]+)/i
       # Bytes scanned for a meta charset hint (HTML spec looks at the first 1024).
       META_CHARSET_BYTES = 2048
-      private_constant :CHARSET_PARAMETER, :META_CHARSET_BYTES
+      private_constant :CHARSET_PARAMETER, :META_CHARSET_BYTES, :FEED_CT_MARKERS, :FEED_BODY_MARKERS
 
       ##
       # @param body [String] the body of the response
@@ -27,7 +31,7 @@ module Html2rss
       # @param status [Integer, nil] the HTTP status code when available
       # @param transport_meta [Hash] allowlisted upstream telemetry (frozen when present)
       # @param captured_responses [Array<Hash>] JSON XHR/fetch bodies captured during browser scrapes
-      # rubocop:disable Metrics/MethodLength, Metrics/ParameterLists -- transport + capture fields stay co-located
+      # rubocop:disable-next Metrics/MethodLength, Metrics/ParameterLists -- transport + capture fields stay co-located
       def initialize(body:, url:, headers: {}, status: nil, transport_meta: EMPTY_TRANSPORT_META,
                      captured_responses: EMPTY_CAPTURED_RESPONSES)
         @body = body
@@ -46,7 +50,6 @@ module Html2rss
                                 captured_responses.freeze
                               end
       end
-      # rubocop:enable Metrics/MethodLength, Metrics/ParameterLists
 
       # @return [String] the raw body of the response
       attr_reader :body
@@ -74,7 +77,14 @@ module Html2rss
 
       # @return [Boolean] whether response content is HTML (header or sniffed body, never JSON)
       def html_response?
-        content_type.include?('text/html') || (!json_response? && html_looking_body?)
+        content_type.include?('text/html') || (!json_response? && !feed_response? && html_looking_body?)
+      end
+
+      # @return [Boolean] whether response content is RSS/Atom (header or sniffed body)
+      def feed_response?
+        return @feed_response if defined?(@feed_response)
+
+        @feed_response = feed_content_type? || (!json_response? && !html_looking_body? && feed_looking_body?)
       end
 
       ##
@@ -143,6 +153,19 @@ module Html2rss
       def html_looking_body?
         body.to_s.b.match?(HTML_BODY_SNIFF)
       end
+
+      def feed_content_type?
+        ct = content_type.downcase
+        return false if ct.empty? || ct.include?('html') || ct.include?('json')
+
+        # Substring match against Content-Type (not Array#intersect? on a String).
+        FEED_CT_MARKERS.any? { |marker| ct.include?(marker) }
+      end
+
+      def feed_looking_body?
+        snippet = body.to_s[0, 800].downcase
+        FEED_BODY_MARKERS.any? { |marker| snippet.include?(marker) }
+      end
     end
   end
 end

data/lib/html2rss/request_service/strategy.rb

@@ -111,7 +111,7 @@ module Html2rss
 
       # @param reason [String] timeout classification (budget_exhausted / transport)
       # @return [void]
-      # rubocop:disable Metrics/AbcSize -- structured timeout fields stay in one log line
+      # rubocop:disable-next Metrics/AbcSize -- structured timeout fields stay in one log line
       def log_timeout!(reason:)
         remaining = ctx.budget.remaining_timeout_seconds
         remaining_label = remaining.nil? ? 'untracked' : format('%.3f', remaining)
@@ -124,7 +124,6 @@ module Html2rss
         ]
         Log.info("#{self.class}: request timeout #{detail.join(' ')}")
       end
-      # rubocop:enable Metrics/AbcSize
 
       # @param error [StandardError]
       # @return [void]

data/lib/html2rss/request_service.rb

@@ -29,10 +29,24 @@ module Html2rss
     class CrossOriginFollowUpDenied < Html2rss::Error; end
     # Raised when a response exceeds configured size limits.
     class ResponseTooLarge < Html2rss::Error; end
+    # Raised when HTTP redirect limits are exceeded.
+    class RedirectLimitReached < Html2rss::Error; end
     # Raised when blocked content surfaces are detected.
     class BlockedSurfaceDetected < Html2rss::Error; end
+
     # Raised when a request times out.
-    class RequestTimedOut < Html2rss::Error; end
+    class RequestTimedOut < Html2rss::Error
+      ##
+      # @param message [String, nil] timeout failure summary
+      # @param timeout_phase [String, nil] scrape-api stage when known (+queue+/+boot+/+work+)
+      def initialize(message = nil, timeout_phase: nil)
+        @timeout_phase = timeout_phase
+        super(message)
+      end
+
+      # @return [String, nil] scrape-api timeout stage, or nil for transport/budget timeouts
+      attr_reader :timeout_phase
+    end
 
     # Raised when Botasaurus configuration is missing or invalid.
     class BotasaurusConfigurationError < Html2rss::Error

data/lib/html2rss/request_session.rb

@@ -15,11 +15,13 @@ module Html2rss
       # @param strategy [Symbol] request strategy for the session
       # @param budget [RequestService::Budget] shared request budget
       # @param policy [RequestService::Policy] request policy (from FeedPipeline::RuntimePolicy.resources_for)
+      # @param scrape_url [String, nil] effective fetch URL when it differs from config channel URL
       # @param logger [Logger] logger used for operational warnings
       # @return [RequestSession] configured request session
-      def build(config:, strategy:, budget:, policy:, logger: Html2rss::Log)
+      # rubocop:disable-next Metrics/ParameterLists -- scrape_url override stays beside config
+      def build(config:, strategy:, budget:, policy:, scrape_url: nil, logger: Html2rss::Log)
         context = RequestService::Context.new(
-          url: config.url, headers: config.headers, request: config.request, policy:, budget:
+          url: scrape_url || config.url, headers: config.headers, request: config.request, policy:, budget:
         )
         new(context:, strategy:, logger:)
       end

data/lib/html2rss/scrape_target.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Html2rss
+  ##
+  # Immutable entry vs effective scrape URLs for one pipeline run.
+  #
+  # Replaces mutating +Config#scrape_url=+ after {FeedResolution} rewrites the fetch URL.
+  ScrapeTarget = Data.define(:entry_url, :effective_url) do
+    ##
+    # @param config [Html2rss::Config]
+    # @return [ScrapeTarget]
+    def self.from_config(config)
+      entry = config.url
+      new(entry_url: entry, effective_url: entry)
+    end
+
+    ##
+    # @param url [String, Html2rss::Url]
+    # @return [ScrapeTarget]
+    def with_effective(url)
+      self.class.new(entry_url:, effective_url: Url.from_absolute(url).to_s)
+    end
+  end
+end

data/lib/html2rss/selectors/post_processors/sanitize_html.rb

@@ -105,7 +105,7 @@ module Html2rss
         # @param html [String]
         # @param url [String, Html2rss::Url]
         # @return [String, nil]
-        # rubocop:disable ThreadSafety/ClassInstanceVariable
+        # rubocop:disable-next ThreadSafety/ClassInstanceVariable
         def self.get(html, url)
           return nil if String(html).empty?
 
@@ -117,12 +117,11 @@ module Html2rss
           context = Selectors::Context.new(config: { channel: { url: } }, options: {})
           @fragment_cache[key] = new(html, context).get
         end
-        # rubocop:enable ThreadSafety/ClassInstanceVariable
 
         ##
         # @param channel_url [String, Html2rss::Url]
         # @return [Hash] the memoized sanitize configuration
-        # rubocop:disable Metrics/MethodLength, ThreadSafety/ClassInstanceVariable
+        # rubocop:disable-next Metrics/MethodLength, ThreadSafety/ClassInstanceVariable
         def self.sanitize_config(channel_url)
           @sanitize_configs ||= {}
           @sanitize_configs[channel_url] ||= begin
@@ -143,7 +142,6 @@ module Html2rss
             config.freeze
           end
         end
-        # rubocop:enable Metrics/MethodLength, ThreadSafety/ClassInstanceVariable
 
         ##
         # @return [String, nil]

data/lib/html2rss/selectors/post_processors.rb

@@ -23,7 +23,6 @@ module Html2rss
       # The key is the name to use in the feed config.
       NAME_TO_CLASS = {
         gsub: Gsub,
-        html_to_markdown: HtmlToMarkdown,
         markdown_to_html: MarkdownToHtml,
         parse_time: ParseTime,
         parse_uri: ParseUri,

data/lib/html2rss/selectors.rb

@@ -95,13 +95,16 @@ module Html2rss
     # @return [Hash] Hash of attributes for the article.
     def extract_article(item, page_response = response)
       scope = item_scope_for(item, page_response.url)
-      @rss_item_attributes.each_with_object({}) do |selector_key, hash|
+      hash = @rss_item_attributes.each_with_object({}) do |selector_key, h|
         value = scope.select(selector_key)
         next if value.nil?
 
         article_key = SELECTOR_TO_ARTICLE_KEY.fetch(selector_key, selector_key)
-        hash[article_key] = article_key == :enclosures ? wrap_enclosure_value(value) : value
+        h[article_key] = article_key == :enclosures ? wrap_enclosure_value(value) : value
       end
+
+      hash[:url] ||= default_item_url(item, page_response.url) if anchor_element?(item)
+      hash
     end
 
     ##
@@ -112,7 +115,7 @@ module Html2rss
     # @param article_tag [Nokogiri::XML::Element] HTML element to extract additional info from.
     # @param base_url [String, Html2rss::Url] base URL for normalization during enhancement
     # @return [Hash] The enhanced article hash.
-    # rubocop:disable Metrics/MethodLength
+    # rubocop:disable-next Metrics/MethodLength
     def enhance_article_hash(article_hash, article_tag, base_url = @url)
       selected_anchor = Html2rss::Html::Navigator.main_anchor_for(article_tag)
       extracted = Html2rss::Html::ArticleExtractor.call(
@@ -130,7 +133,6 @@ module Html2rss
         hash[key] = value
       end
     end
-    # rubocop:enable Metrics/MethodLength
 
     ##
     # Selects the value for a given attribute from an HTML element.
@@ -157,13 +159,11 @@ module Html2rss
 
       raise InvalidSelectorName, "Attribute selector '#{name}' is reserved for items." if name == ITEMS_SELECTOR_KEY
 
-      selector_key, config = selector_config_for(name)
+      selector_key, config = selector_config_for(name, allow_nil: name == :url)
+      return default_item_url(scope.item, scope.base_url) if fallback_url_selector?(selector_key, config, scope.item)
+      raise InvalidSelectorName, "Selector for '#{selector_key}' is not defined." if config.nil?
 
-      if SPECIAL_ATTRIBUTES.member?(selector_key)
-        select_special(selector_key, scope:, config:)
-      else
-        select_regular(selector_key, scope:, config:)
-      end
+      dispatch_select(selector_key, scope:, config:)
     end
 
     private
@@ -317,5 +317,28 @@ module Html2rss
 
       { url:, type: config[:content_type] }
     end
+
+    def anchor_element?(item)
+      item.respond_to?(:name) && item.name.to_s.casecmp('a').zero?
+    end
+
+    def fallback_url_selector?(selector_key, config, item)
+      selector_key == :url && config.nil? && anchor_element?(item)
+    end
+
+    def dispatch_select(selector_key, scope:, config:)
+      if SPECIAL_ATTRIBUTES.member?(selector_key)
+        select_special(selector_key, scope:, config:)
+      else
+        select_regular(selector_key, scope:, config:)
+      end
+    end
+
+    def default_item_url(item, base_url)
+      href = item['href'].to_s.strip
+      return if href.empty?
+
+      Url.from_relative(href, base_url)
+    end
   end
 end

data/lib/html2rss/sst/attrs.rb

@@ -29,7 +29,7 @@ module Html2rss
         # @param type [String, nil]
         # @param raw [Hash{String => String}, nil]
         # @return [Attrs]
-        # rubocop:disable Metrics/MethodLength, Metrics/ParameterLists
+        # rubocop:disable-next Metrics/MethodLength, Metrics/ParameterLists
         def build(href: nil, src: nil, id: nil, class_names: nil, datetime: nil, itemprop: nil,
                   style: nil, srcset: nil, type: nil, raw: nil)
           new(
@@ -45,7 +45,6 @@ module Html2rss
             raw: normalize_raw(raw)
           )
         end
-        # rubocop:enable Metrics/MethodLength, Metrics/ParameterLists
 
         ##
         # @return [Attrs]

data/lib/html2rss/sst/normalizer.rb

@@ -8,6 +8,9 @@ module Html2rss
     # Sole Nokogiri consumer on the heuristic auto-source path. Builds an
     # immutable SST::Document with parent/depth/chrome indices.
     class Normalizer # rubocop:disable Metrics/ClassLength
+      # Raised when no SST nodes survive normalization for the chosen root.
+      class EmptyTree < ArgumentError; end
+
       # Hard ceiling for SST node allocations; beyond this we degrade.
       MAX_NODES = 5_000
 
@@ -50,6 +53,12 @@ module Html2rss
         )
       /xi
 
+      # Typed Attrs fields excluded from the leftover raw hash.
+      TYPED_ATTR_NAMES = %w[href src id class datetime itemprop style srcset type].to_set.freeze
+
+      # String form of Tags::IGNORED_CONTAINER_NAMES for chrome checks without to_sym.
+      IGNORED_CONTAINER_TAGS = Tags::IGNORED_CONTAINER_NAMES.to_set(&:to_s).freeze
+
       class << self
         ##
         # @param input [String, Nokogiri::HTML::Document, Nokogiri::XML::Node]
@@ -89,9 +98,9 @@ module Html2rss
       ##
       # @return [Document]
       def call
-        root_nk = @parsed_body.respond_to?(:root) ? (@parsed_body.at_css('html') || @parsed_body.root) : @parsed_body
+        root_nk = resolve_root_nk
         root = normalize_element(root_nk, parent: nil, depth: 0, path: '', chrome: false)
-        raise ArgumentError, 'SST Normalizer produced an empty tree' unless root
+        raise EmptyTree, 'SST Normalizer produced an empty tree' unless root
 
         index = Index.new(root:, parents: @parents, depths: @depths, ignored_chrome: @ignored_chrome)
         Document.build(root:, index:, degraded: @degraded, node_count: @node_count)
@@ -99,14 +108,45 @@ module Html2rss
 
       private
 
-      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+      # @return [Nokogiri::XML::Node]
+      # rubocop:disable-next Metrics/MethodLength -- explicit root discovery fallback chain
+      def resolve_root_nk
+        parsed = @parsed_body
+
+        if parsed.respond_to?(:at_css)
+          html = parsed.at_css('html')
+          return html if html
+
+          body = parsed.at_css('body')
+          if body
+            Html2rss::Log.warn('sst.normalizer root fallback: body')
+            return body
+          end
+        end
+
+        if parsed.respond_to?(:element_children)
+          first = parsed.element_children.find { |child| element_root?(child) }
+          if first
+            Html2rss::Log.warn('sst.normalizer root fallback: first element child')
+            return first
+          end
+        end
+
+        Html2rss::Log.warn('sst.normalizer root fallback: self')
+        parsed
+      end
+
+      def element_root?(node)
+        node.element? && !STRIPPED_TAGS.include?(Html2rss::Html::Probe.tag(node))
+      end
+
+      # rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
       def normalize_element(nk_node, parent:, depth:, path:, chrome:)
         return unless nk_node.respond_to?(:name)
-        return if nk_node.text? || nk_node.comment? || nk_node.cdata?
+        return unless nk_node.element?
 
-        tag = nk_node.name.to_s.downcase
+        tag = Html2rss::Html::Probe.tag(nk_node)
         return if STRIPPED_TAGS.include?(tag)
-        return if @degraded && !SEMANTIC_DEGRADE_TAGS.include?(tag)
 
         if @node_count >= MAX_NODES && !@degraded
           @degraded = true
@@ -119,9 +159,9 @@ module Html2rss
         tag_path = path.empty? ? "/#{tag}" : "#{path}/#{tag}"
         attrs = extract_attrs(nk_node)
         own_text = direct_text(nk_node)
-        chrome_here = chrome || Tags::IGNORED_CONTAINER_NAMES.include?(tag.to_sym)
+        chrome_here = chrome || IGNORED_CONTAINER_TAGS.include?(tag)
 
-        children = nk_node.children.filter_map do |child|
+        children = nk_node.element_children.filter_map do |child|
           normalize_element(child, parent: :pending, depth: depth + 1, path: tag_path, chrome: chrome_here)
         end.freeze
 
@@ -135,7 +175,6 @@ module Html2rss
 
         node
       end
-      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
 
       def extract_attrs(nk_node) # rubocop:disable Metrics/MethodLength
         Attrs.build(
@@ -153,10 +192,9 @@ module Html2rss
       end
 
       def raw_attrs(nk_node)
-        typed = %w[href src id class datetime itemprop style srcset type].to_set
         nk_node.attribute_nodes.each_with_object({}) do |attr, raw|
           name = attr.name.to_s
-          next if typed.include?(name)
+          next if TYPED_ATTR_NAMES.include?(name)
           next unless name.match?(RAW_ATTR_KEEP)
 
           raw[name] = attr.value.to_s

data/lib/html2rss/status.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Html2rss
+module Html2rss # rubocop:disable Metrics/ModuleLength -- Status Data.define + marshal stay co-located
   ##
   # Shared RSS +generator+ / JSON Feed +user_comment+ formatter string.
   #
@@ -9,7 +9,7 @@ module Html2rss
   # Tallies and counters are validated and frozen at construction (including Marshal load).
   Status = Data.define(
     :version, :scraper_tallies, :dedup_dropped, :selected_strategy, :attempt_count,
-    :strategy_attempts, :admission_drops
+    :strategy_attempts, :admission_drops, :entry_url, :scrape_url, :entry_resolution
   ) do
     class << self
       ##
@@ -21,10 +21,15 @@ module Html2rss
       # @param attempt_count [Integer] auto-fallback attempt count (0 when not under +:auto+)
       # @param strategy_attempts [Array<Hash>] auto-fallback attempt hashes (empty outside +:auto+)
       # @param admission_drops [Hash{String => Integer}] Cleanup reason → count (empty when unused)
+      # @param scrape_target [Html2rss::ScrapeTarget, nil] domain URL pair (mapped to wire strings)
+      # @param entry_url [String, nil] original channel URL when entry resolution ran
+      # @param scrape_url [String, nil] effective scrape URL after resolution
+      # @param entry_resolution [Html2rss::FeedResolution::Diag, Hash, nil] resolution diagnostics
       # @return [Html2rss::Status]
-      # rubocop:disable Metrics/ParameterLists -- Status kwargs stay co-located
+      # rubocop:disable-next Metrics/ParameterLists, Metrics/MethodLength -- Status kwargs stay co-located
       def build(articles:, dedup_dropped: 0, selected_strategy: nil, attempt_count: 0,
-                strategy_attempts: [], admission_drops: {})
+                strategy_attempts: [], admission_drops: {}, scrape_target: nil,
+                entry_url: nil, scrape_url: nil, entry_resolution: nil)
         tallies = articles.filter_map(&:scraper).tally.transform_keys { |klass| scraper_name(klass) }
         new(
           version: Html2rss::VERSION,
@@ -33,10 +38,12 @@ module Html2rss
           selected_strategy:,
           attempt_count:,
           strategy_attempts:,
-          admission_drops:
+          admission_drops:,
+          entry_url: entry_url || scrape_target&.entry_url,
+          scrape_url: scrape_url || scrape_target&.effective_url,
+          entry_resolution:
         )
       end
-      # rubocop:enable Metrics/ParameterLists
 
       ##
       # @param klass [Class, #to_s] scraper class
@@ -54,10 +61,13 @@ module Html2rss
     # @param attempt_count [Integer]
     # @param strategy_attempts [Array<Hash>]
     # @param admission_drops [Hash{String => Integer}]
-    # rubocop:disable Metrics/ParameterLists, Metrics/MethodLength -- Status Data.define members
+    # @param entry_url [String, nil]
+    # @param scrape_url [String, nil]
+    # @param entry_resolution [Hash, nil]
+    # rubocop:disable-next Metrics/ParameterLists, Metrics/MethodLength -- Status Data.define members
     def initialize(
       version:, scraper_tallies:, dedup_dropped:, selected_strategy: nil, attempt_count: 0,
-      strategy_attempts: [], admission_drops: {}
+      strategy_attempts: [], admission_drops: {}, entry_url: nil, scrape_url: nil, entry_resolution: nil
     )
       dedup = Integer(dedup_dropped)
       attempts = Integer(attempt_count)
@@ -70,21 +80,18 @@ module Html2rss
         selected_strategy:,
         attempt_count: attempts,
         strategy_attempts: freeze_attempts(strategy_attempts),
-        admission_drops: freeze_tallies(admission_drops)
+        admission_drops: freeze_tallies(admission_drops),
+        entry_url: freeze_optional_string(entry_url),
+        scrape_url: freeze_optional_string(scrape_url),
+        entry_resolution: freeze_entry_resolution(entry_resolution)
       )
     end
-    # rubocop:enable Metrics/ParameterLists, Metrics/MethodLength
 
     ##
-    # Observability hash for web (+scraper_status+). Omits empty/absent optional keys:
-    # +:scraper_tallies+ when empty, +:selected_strategy+ when +nil+, +:attempt_count+ when zero,
-    # +:strategy_attempts+ / +:admission_drops+ when empty.
-    # Data members remain available via readers even when omitted here.
+    # Observability hash for web (+scraper_status+). Omits empty/absent optional keys.
     #
-    # @return [Hash{Symbol => Object}] always +:version+ (String), +:dedup_dropped+ (Integer);
-    #   optionally +:scraper_tallies+, +:selected_strategy+, +:attempt_count+,
-    #   +:strategy_attempts+, +:admission_drops+
-    # rubocop:disable Metrics/AbcSize -- omit-empty optional keys stay explicit
+    # @return [Hash{Symbol => Object}]
+    # rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity -- omit-empty optional keys stay explicit
     def to_h
       {
         version:,
@@ -93,10 +100,12 @@ module Html2rss
         **(selected_strategy.nil? ? {} : { selected_strategy: }),
         **(attempt_count.positive? ? { attempt_count: } : {}),
         **(strategy_attempts.any? ? { strategy_attempts: } : {}),
-        **(admission_drops.any? ? { admission_drops: } : {})
+        **(admission_drops.any? ? { admission_drops: } : {}),
+        **(entry_url ? { entry_url: } : {}),
+        **(scrape_url ? { scrape_url: } : {}),
+        **(entry_resolution ? { entry_resolution: } : {})
       }
     end
-    # rubocop:enable Metrics/AbcSize
 
     ##
     # Formats the RSS +generator+ string and JSON Feed +user_comment+.
@@ -115,13 +124,15 @@ module Html2rss
 
     def marshal_dump
       [version, scraper_tallies, dedup_dropped, selected_strategy, attempt_count, strategy_attempts,
-       admission_drops]
+       admission_drops, entry_url, scrape_url, entry_resolution]
     end
 
-    def marshal_load((version, scraper_tallies, dedup_dropped, selected_strategy, attempt_count,
-                      strategy_attempts, admission_drops))
+    def marshal_load(payload)
+      version, scraper_tallies, dedup_dropped, selected_strategy, attempt_count,
+        strategy_attempts, admission_drops, entry_url, scrape_url, entry_resolution = payload
       initialize(version:, scraper_tallies:, dedup_dropped:, selected_strategy:, attempt_count:,
-                 strategy_attempts:, admission_drops: admission_drops || {})
+                 strategy_attempts:, admission_drops: admission_drops || {}, entry_url:, scrape_url:,
+                 entry_resolution:)
     end
 
     def freeze_tallies(tallies)
@@ -132,6 +143,19 @@ module Html2rss
       Array(attempts).map { |attempt| attempt.to_h.freeze }.freeze
     end
 
+    def freeze_optional_string(value)
+      return if value.nil?
+
+      value.to_s.dup.freeze
+    end
+
+    def freeze_entry_resolution(value)
+      return if value.nil?
+
+      hash = value.respond_to?(:to_h) ? value.to_h : value
+      hash.to_h.transform_keys(&:to_sym).freeze
+    end
+
     def validate_counters!(dedup:, attempts:, selected_strategy:)
       raise ArgumentError, 'dedup_dropped must be >= 0' if dedup.negative?
       raise ArgumentError, 'attempt_count must be >= 0' if attempts.negative?

data/lib/html2rss/surface_category.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Html2rss
+  ##
+  # Closed surface class for no-scraper / page-assessment gates.
+  #
+  # Construction: {AutoSource::Scraper.classify_no_scraper_surface} and {PageRecon.assess}.
+  # Predicates own weak/blocked/listing-bonus decisions — do not re-list WEAK sets in Policy/Scorer.
+  class SurfaceCategory
+    # Surfaces that warrant listing/feed resolution (hubs / shells — not blocked).
+    WEAK = Set[:high_entropy_surface, :app_shell, :unsupported_surface].freeze
+
+    class << self
+      ##
+      # @param value [SurfaceCategory, Symbol, String, nil]
+      # @return [SurfaceCategory]
+      def coerce(value)
+        return value if value.is_a?(self)
+        return new(name: nil) if value.nil?
+
+        new(name: value.to_sym)
+      end
+    end
+
+    ##
+    # @return [Symbol, nil]
+    attr_reader :name
+
+    ##
+    # @param name [Symbol, nil]
+    def initialize(name:)
+      @name = name
+    end
+
+    ##
+    # @return [Boolean]
+    def weak? = WEAK.include?(name)
+
+    ##
+    # @return [Boolean]
+    def blocked? = name == :blocked_surface
+
+    ##
+    # @return [Boolean] non-weak, non-blocked surface eligible for listing bonus
+    def listing_bonus? = !name.nil? && !weak? && !blocked?
+
+    ##
+    # @return [Symbol, nil]
+    def to_sym = name
+
+    ##
+    # @param other [Object]
+    # @return [Boolean]
+    def ==(other)
+      other.is_a?(self.class) && name == other.name
+    end
+    alias eql? ==
+
+    ##
+    # @return [Integer]
+    def hash = [self.class, name].hash
+  end
+end

data/lib/html2rss/syndication/README.md

@@ -0,0 +1,21 @@
+# Syndication
+
+Native RSS/Atom discovery and parse for auto-source promotion and direct feed URLs.
+
+## Ownership
+
+| Concern                                                          | Owner                                                                                              |
+| ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| Head `rel=alternate` + common path probes + status-gated feedish | `Syndication::Discovery`                                                                           |
+| RSS 2.0 / Atom → article hashes                                  | `Syndication::Parser`                                                                              |
+| Strict head-only link parse (no path guessing)                   | `Html::FeedLink`                                                                                   |
+| Response Content-Type / body feed sniff                          | `RequestService::Response#feed_response?` (sole sniff owner; Discovery only adds HTTP status gate) |
+
+## Non-goals
+
+- Entry-URL tournament / listing resolution (`FeedResolution`)
+- Page recon / surface classification (`PageRecon`)
+- Feed channel metadata for output (`Channel` / `FeedBuilder`)
+- Ranking or quality scoring of competing feeds beyond first feedish hit
+
+Discovery stops at the first same-origin feedish URL (lazy probe). Path guessing mirrors the legacy configs `probe_rss` script; that script should eventually thin-wrap this module.

data/lib/html2rss/syndication/candidate_catalog.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Html2rss
+  module Syndication
+    ##
+    # Shared path lexicon for syndication discovery and entry-resolution candidates.
+    module CandidateCatalog
+      # Common feed path suffixes probed after head +rel=alternate+ hints.
+      FEED_PATHS = %w[
+        /feed
+        /feed.xml
+        /rss
+        /rss.xml
+        /atom.xml
+        /index.xml
+        /news/rss
+        /news/feed
+        /blog/feed
+        /blog/rss.xml
+      ].freeze
+
+      # HTML listing paths probed only by {FeedResolution::CandidateGenerator}.
+      LISTING_PATHS = %w[/news /blog /releases /changelog /updates].freeze
+    end
+  end
+end