html2rss 0.28.0 → 0.29.1

data/lib/html2rss/config/schema.rb

@@ -48,7 +48,7 @@ module Html2rss
       ##
       # Orchestrates schema assembly from runtime validator contracts plus
       # client-facing overlays.
-      # rubocop:disable Metrics/ClassLength -- overlay assembly stays in one builder
+      # rubocop:disable-next Metrics/ClassLength -- overlay assembly stays in one builder
       class Builder
         class << self
           # @return [Hash{String => Object}] fully assembled JSON schema hash
@@ -110,9 +110,13 @@ module Html2rss
           registry.keys.sort.to_h { |name| [name.to_s, registry.fetch(name).schema_doc] }
         end
 
-        # rubocop:disable Metrics/MethodLength, Metrics/AbcSize, Layout/LineLength
+        # rubocop:disable-next Metrics/MethodLength, Metrics/AbcSize, Layout/LineLength
         def overlay
           items_schema = Html2rss::Config::SelectorsValidator::Items.new.schema.json_schema(loose: true)
+          items_schema[:properties][:enhance] = items_schema.fetch(:properties).fetch(:enhance).merge(
+            description: 'List-card enrichment: run Html::ArticleExtractor on each matched item node ' \
+                         'to fill missing fields from the card HTML.'
+          )
           items_schema[:properties][:pagination] = {
             description: 'Pagination configuration or maximum page count integer.',
             oneOf: [
@@ -166,7 +170,7 @@ module Html2rss
               description: 'Selectors used to extract article attributes.',
               properties: {
                 items: items_schema.merge(
-                  description: 'Defines the items selector and optional enhancement settings.'
+                  description: 'Defines the items selector and list-card enhance settings.'
                 ),
                 enclosure: enclosure_schema.merge(
                   description: 'Describes enclosure extraction settings.'
@@ -183,7 +187,6 @@ module Html2rss
             }
           }
         end
-        # rubocop:enable Metrics/MethodLength, Metrics/AbcSize, Layout/LineLength
 
         def reference_array(description)
           {
@@ -197,7 +200,6 @@ module Html2rss
           }
         end
       end
-      # rubocop:enable Metrics/ClassLength
 
       ##
       # Wires extractor / post_process to thin oneOf $refs into the registry catalog.

data/lib/html2rss/config/validator.rb

@@ -19,6 +19,7 @@ module Html2rss
       DIRECTORY_TOPICS = %w[
         sports energy tech science news entertainment jobs finance
         security travel environment consumer civic product research
+        health culture education rights transport
       ].freeze
 
       # Contract for the top-level `channel` section.

data/lib/html2rss/config.rb

@@ -16,6 +16,32 @@ module Html2rss
     # Sentinel to differentiate omitted params from explicit `nil`.
     UNSET = Object.new.freeze
 
+    ValidationResult = Data.define(:success, :errors_hash)
+
+    ##
+    # Duck-compatible with +Dry::Validation::Result+ for resolve-time outcomes
+    # (+#success?+, +#errors#to_h+). Used for parse failures so callers never see a Struct snowflake.
+    class ValidationResult
+      ##
+      # @param message [String]
+      # @return [Html2rss::Config::ValidationResult]
+      def self.parse_failure(message)
+        new(success: false, errors_hash: { parse: [message] })
+      end
+
+      ##
+      # @return [Boolean]
+      def success? = success
+
+      ##
+      # @return [self]
+      def errors = self
+
+      ##
+      # @return [Hash]
+      def to_h = errors_hash
+    end
+
     class << self
       ##
       # Returns the exported JSON Schema for html2rss configuration.
@@ -34,6 +60,22 @@ module Html2rss
         pretty ? JSON.pretty_generate(json_schema) : JSON.generate(json_schema)
       end
 
+      ##
+      # Resolves a Hash, YAML file path, or YAML string to a working config Hash and validates it.
+      # The returned Hash is a deep copy — callers may stamp strategy/params without mutating input.
+      #
+      # @param config_input [Hash, String] config hash, YAML string, or file path
+      # @param feed_name [String, nil] optional feed name for multi-feed files
+      # @param params [Hash] dynamic feed params
+      # @return [Array(Hash, Dry::Validation::Result, Html2rss::Config::ValidationResult)]
+      def resolve_and_validate(config_input, feed_name: nil, params: {})
+        param_arg = params.empty? ? UNSET : params
+        working = HashUtil.deep_dup(resolve_raw_hash(config_input, feed_name))
+        [working, validate(working, params: param_arg)]
+      rescue StandardError => error
+        [{}, ValidationResult.parse_failure(error.message)]
+      end
+
       ##
       # Validates a configuration hash with the runtime validator.
       #
@@ -59,22 +101,10 @@ module Html2rss
         Schema.path
       end
 
-      ##
-      # Loads and validates a YAML configuration file.
-      #
-      # @param file [String] the YAML file to load
-      # @param feed_name [String, nil] optional feed name for multi-feed files
-      # @param multiple_feeds_key [Symbol] key under which multiple feeds are defined
-      # @param params [Hash{Symbol => Object, Hash{String => Object, nil}}] dynamic parameters for string formatting
-      # @return [Dry::Validation::Result] validation result after defaults are applied
-      def validate_yaml(file, feed_name = nil, multiple_feeds_key: MultipleFeedsConfig::CONFIG_KEY_FEEDS, params: UNSET)
-        validate(load_yaml(file, feed_name, multiple_feeds_key:), params:)
-      end
-
       ##
       # Serializes a configuration hash to string-key YAML.
       #
-      # This is the single serializer for CLI capture and MCP +capture_config+.
+      # This is the single serializer for CLI capture and MCP +capture+.
       #
       # @param hash [Hash] configuration hash (symbol or string keys)
       # @return [String] YAML document without Ruby symbol-key prefixes
@@ -109,7 +139,7 @@ module Html2rss
       # @param multiple_feeds_key [Symbol] the key under which multiple feeds are defined.
       # @return [Hash{Symbol => Object}] the configuration hash.
       # @raise [ArgumentError] if the file doesn't exist or feed is not found.
-      # rubocop:disable Metrics/MethodLength
+      # rubocop:disable-next Metrics/MethodLength
       def load_yaml(file, feed_name = nil, multiple_feeds_key: MultipleFeedsConfig::CONFIG_KEY_FEEDS)
         raise ArgumentError, "File '#{file}' does not exist" unless File.exist?(file)
         raise ArgumentError, "`#{multiple_feeds_key}` is a reserved feed name" if feed_name == multiple_feeds_key
@@ -129,7 +159,6 @@ module Html2rss
 
         MultipleFeedsConfig.to_single_feed(config, yaml, multiple_feeds_key:)
       end
-      # rubocop:enable Metrics/MethodLength
 
       ##
       # Processes the provided configuration hash, applying dynamic parameters if given,
@@ -216,6 +245,20 @@ module Html2rss
       def prepare_for_validation(config)
         Config::Preparer.new.call(HashUtil.deep_dup(config))
       end
+
+      # @param config_input [Hash, String]
+      # @param feed_name [String, nil]
+      # @return [Hash]
+      def resolve_raw_hash(config_input, feed_name)
+        if config_input.is_a?(Hash)
+          config_input
+        elsif File.file?(config_input.to_s)
+          load_yaml(config_input.to_s, feed_name)
+        else
+          from_yaml(config_input.to_s)
+        end
+      end
+      private :resolve_raw_hash
     end
 
     ##
@@ -270,11 +313,6 @@ module Html2rss
     # @return [String]
     def url = config.dig(:channel, :url)
 
-    ##
-    # @deprecated Use {ScrapeTarget} for entry vs effective URLs after resolution.
-    # @return [String]
-    def scrape_url = url
-
     # @return [String, nil] configured channel time zone
     def time_zone = config.dig(:channel, :time_zone)
 
@@ -331,8 +369,7 @@ module Html2rss
     def normalized_headers(validated_config)
       validated_config[:headers] = RequestHeaders.normalize(
         validated_config[:headers],
-        channel_language: validated_config.dig(:channel, :language),
-        url: validated_config.dig(:channel, :url)
+        channel_language: validated_config.dig(:channel, :language)
       )
       validated_config
     end

data/lib/html2rss/doctor/botasaurus.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'json'
+
+module Html2rss
+  ##
+  # CLI runtime health checks for optional scrape dependencies.
+  module Doctor
+    ##
+    # Preflight checks for Botasaurus scrape-api connectivity.
+    module Botasaurus
+      ##
+      # One named doctor check outcome.
+      Check = Data.define(:name, :ok, :detail) do
+        ##
+        # @return [Hash{Symbol => Object}]
+        def to_h
+          { name: name.to_s, ok:, detail: }
+        end
+      end
+
+      ##
+      # Aggregate doctor command outcome.
+      Result = Data.define(:ok, :checks, :message) do
+        ##
+        # @return [Hash{Symbol => Object}]
+        def to_h
+          { ok:, message:, checks: checks.map(&:to_h) }
+        end
+      end
+
+      module_function
+
+      ENV_VAR = 'BOTASAURUS_SCRAPER_URL'
+      private_constant :ENV_VAR
+
+      ##
+      # @param sample_url [String, nil] optional URL for a sample scrape smoke test
+      # @return [Result]
+      def call(sample_url: nil) # rubocop:disable Metrics/AbcSize
+        env = env_check
+        checks = [env_check_record(env)]
+        return missing_env_failure(checks) unless checks.first.ok
+
+        checks << health_check_record(env[:base_url])
+        return failure(checks, 'Botasaurus health check failed.') unless checks.last.ok
+
+        checks << sample_scrape_record(sample_url) if sample_url
+        return failure(checks, 'Sample scrape failed.') if sample_url && !checks.last.ok
+
+        Log.info('doctor botasaurus: preflight passed')
+        Result.new(ok: true, checks:, message: 'Botasaurus preflight passed.')
+      end
+
+      ##
+      # @return [Hash{Symbol => Object}]
+      def env_check
+        base = ENV.fetch(ENV_VAR, '').strip
+        {
+          configured: MCP::Runtime.botasaurus_configured?,
+          var: ENV_VAR,
+          base_url: base.empty? ? nil : base
+        }
+      end
+
+      ##
+      # @param base_url [String]
+      # @return [Hash{Symbol => Object}]
+      def health_check(base_url)
+        uri = Url.for_channel(base_url)
+        client = Faraday.new(url: uri.to_s.chomp('/'), request: { timeout: 5 })
+        response = client.get('/health')
+        body = JSON.parse(response.body)
+        { ok: response.status == 200, status: response.status, version: body['version'] }
+      rescue StandardError => error
+        { ok: false, error: "#{error.class}: #{error.message}" }
+      end
+
+      ##
+      # @param url [String]
+      # @return [Hash{Symbol => Object}]
+      def sample_scrape(url)
+        wire = PageRecon::Diagnostics.call(url:, strategy: :botasaurus).to_wire_h
+        {
+          ok: wire[:status].to_i.between?(200, 399),
+          status: wire[:status],
+          articles_count: wire[:articles_count]
+        }
+      rescue StandardError => error
+        { ok: false, error: "#{error.class}: #{error.message}" }
+      end
+
+      def env_check_record(env = env_check)
+        Check.new(name: :env, ok: env[:configured], detail: { var: env[:var], base_url_set: !env[:base_url].nil? })
+      end
+      module_function :env_check_record
+      private_class_method :env_check_record
+
+      def health_check_record(base_url)
+        return Check.new(name: :health, ok: false, detail: { error: 'missing base URL' }) unless base_url
+
+        health = health_check(base_url)
+        Check.new(name: :health, ok: health[:ok], detail: health)
+      end
+      module_function :health_check_record
+      private_class_method :health_check_record
+
+      def sample_scrape_record(url)
+        sample = sample_scrape(url)
+        Check.new(name: :sample_scrape, ok: sample[:ok], detail: sample)
+      end
+      module_function :sample_scrape_record
+      private_class_method :sample_scrape_record
+
+      def missing_env_failure(checks)
+        Log.info("doctor botasaurus: #{ENV_VAR} unset")
+        failure(checks, "Set #{ENV_VAR} to the scrape-api base URL.")
+      end
+      module_function :missing_env_failure
+      private_class_method :missing_env_failure
+
+      def failure(checks, message)
+        Result.new(ok: false, checks:, message:)
+      end
+      module_function :failure
+      private_class_method :failure
+    end
+  end
+end

data/lib/html2rss/feed_builder/rss.rb

@@ -96,7 +96,7 @@ module Html2rss
         @stylesheets.map { |style| Stylesheet.new(**style) }
       end
 
-      # rubocop:disable Metrics/AbcSize
+      # rubocop:disable-next Metrics/AbcSize
       def make_channel(maker)
         channel_maker = maker.channel
         %i[language title description ttl].each do |key|
@@ -111,7 +111,6 @@ module Html2rss
 
         make_image(maker.image) if channel.image
       end
-      # rubocop:enable Metrics/AbcSize
 
       def make_image(image_maker)
         image_maker.url = channel.image.to_s

data/lib/html2rss/feed_pipeline/README.md

@@ -1,6 +1,6 @@
 # FeedPipeline — `auto` request strategy
 
-`:auto` is the default request plan for feed builds (`auto_source`, `auto_json_feed`, Capture, and MCP `scrape_url` / `capture_config`). `FeedPipeline::StrategyPlan` resolves it; `FeedPipeline::AutoFallback` executes `AutoFallback::CHAIN`.
+`:auto` is the default request plan for feed builds (`auto_source`, `auto_json_feed`, Capture, and MCP `scrape` / `capture`). `FeedPipeline::StrategyPlan` resolves it; `FeedPipeline::AutoFallback` executes `AutoFallback::CHAIN`.
 
 Use `:auto` when you want Faraday first and a browser-backed hop only if that fetch fails or yields zero items. Pin a concrete strategy (`faraday`, `botasaurus`, `local_file`) when you need a single transport.
 
@@ -17,10 +17,10 @@ There is no Browserless / Puppeteer-in-gem tier. Pin `botasaurus` when you want
 
 ## Surfaces
 
-| Surface | `:auto` behavior |
-|---------|------------------|
-| Gem / CLI feed build, MCP `scrape_url`, Capture | Full AutoFallback chain (`faraday` → `botasaurus`) |
-| MCP `inspect_url` | Cheap diagnostic: `StrategyPlan.concrete_for_diagnostic` maps `auto` to Faraday (pin `botasaurus` when you need browser rendering) |
+| Surface                                  | `:auto` behavior                                                                                                                   |
+| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| Gem / CLI `apply`, MCP `scrape`, Capture | Full AutoFallback chain (`faraday` → `botasaurus`)                                                                                 |
+| MCP `inspect`                            | Cheap diagnostic: `StrategyPlan.concrete_for_diagnostic` maps `auto` to Faraday (pin `botasaurus` when you need browser rendering) |
 
 ## Fallback vs abort
 

data/lib/html2rss/feed_pipeline/auto_fallback.rb

@@ -10,6 +10,9 @@ module Html2rss
       # Ordered list of concrete request strategies attempted by the :auto plan.
       CHAIN = %i[faraday botasaurus].freeze
 
+      # Deterministic HTTP statuses that indicate permanent failure rather than anti-bot challenges.
+      DETERMINISTIC_HTTP_STATUSES = Set[400, 404, 410, 422, 451].freeze
+
       # Error classes that should abort auto fallback immediately.
       NON_FALLBACK_ERRORS = [
         RequestService::UnknownStrategy,
@@ -18,7 +21,8 @@ module Html2rss
         RequestService::RequestBudgetExceeded,
         RequestService::PrivateNetworkDenied,
         RequestService::CrossOriginFollowUpDenied,
-        RequestService::ResponseTooLarge
+        RequestService::ResponseTooLarge,
+        RequestService::RedirectLimitReached
       ].freeze
 
       ##
@@ -32,11 +36,20 @@ module Html2rss
           @last_response = nil
           @entry_resolution = nil
           @resolution_tried = false
+          @aborted = false
         end
 
         # @return [Boolean] true when a strategy already yielded items
         def succeeded? = !result.nil?
 
+        # @return [Boolean] whether attempts were aborted due to deterministic errors
+        def aborted? = @aborted
+
+        # @return [void]
+        def abort!
+          @aborted = true
+        end
+
         # @return [Boolean] whether entry resolution already ran for this chain
         def resolution_tried? = @resolution_tried
 
@@ -82,7 +95,7 @@ module Html2rss
         # @param admission_drops [Hash{String => Integer}] Cleanup drop tallies
         # @param scrape_target [Html2rss::ScrapeTarget]
         # @return [void]
-        # rubocop:disable Metrics/ParameterLists, Metrics/MethodLength -- PipelineOutcome kwargs stay co-located
+        # rubocop:disable-next Metrics/ParameterLists, Metrics/MethodLength -- PipelineOutcome kwargs stay co-located
         def succeed!(response:, articles:, dedup_dropped:, selected_strategy:, attempt_count:,
                      scrape_target:, admission_drops: {})
           @result = PipelineOutcome.new(
@@ -97,7 +110,6 @@ module Html2rss
             entry_resolution:
           )
         end
-        # rubocop:enable Metrics/ParameterLists, Metrics/MethodLength
       end
 
       ##
@@ -133,7 +145,7 @@ module Html2rss
         AttemptState.new.tap do |state|
           strategies.each_with_index do |strategy, index|
             attempt(strategy:, next_strategy: strategies[index + 1], state:)
-            break if state.succeeded?
+            break if state.succeeded? || state.aborted?
           end
         end
       end
@@ -161,7 +173,7 @@ module Html2rss
         nil
       end
 
-      # rubocop:disable Metrics/MethodLength, Metrics/AbcSize -- extract + resolution delegate
+      # rubocop:disable-next Metrics/MethodLength, Metrics/AbcSize -- extract + resolution delegate
       def process_response(response:, strategy:, next_strategy:, request_session:, state:)
         articles, dedup_dropped, admission_drops = articles_for(response:, request_session:)
         state.remember_response(response)
@@ -184,15 +196,24 @@ module Html2rss
                                 state:)
         end
 
+        if deterministic_status?(response)
+          state.abort!
+          Log.debug("#{self.class}: deterministic HTTP #{response.status}; aborting auto fallback")
+          return
+        end
+
         log_info_fallback_zero_items(strategy:, next_strategy:, response:) if next_strategy
       end
-      # rubocop:enable Metrics/MethodLength, Metrics/AbcSize
+
+      def deterministic_status?(response)
+        DETERMINISTIC_HTTP_STATUSES.member?(response&.status)
+      end
 
       def articles_for(response:, request_session:)
         pipeline.deduplicated_articles(config:, response:, request_session:)
       end
 
-      # rubocop:disable Metrics/ParameterLists -- success kwargs match PipelineOutcome
+      # rubocop:disable-next Metrics/ParameterLists -- success kwargs match PipelineOutcome
       def record_success(response:, strategy:, articles:, dedup_dropped:, admission_drops:, state:)
         attempt_count = state.attempts.size
         state.succeed!(
@@ -206,7 +227,6 @@ module Html2rss
                  "host=#{response.url.host} elapsed=#{format('%.3f', budget.elapsed_seconds)}s " \
                  "budget_remaining=#{budget_remaining_label}")
       end
-      # rubocop:enable Metrics/ParameterLists
 
       def finalize_failure(attempts:, response:)
         surface_category = surface_category_for(response)
@@ -219,7 +239,7 @@ module Html2rss
         PageRecon.surface_category_for(response:, url: response.url)
       end
 
-      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      # rubocop:disable-next Metrics/AbcSize, Metrics/MethodLength
       def log_fallback_error(strategy:, next_strategy:, error:, request_session:)
         host = request_session.url.host
         detail = "host=#{host} elapsed=#{format('%.3f', budget.elapsed_seconds)}s " \
@@ -233,7 +253,6 @@ module Html2rss
         end
         Log.debug("#{self.class}: strategy=#{strategy} error=#{error.class}: #{error.message} #{detail}")
       end
-      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
 
       def log_info_fallback_zero_items(strategy:, next_strategy:, response:)
         Log.info("#{self.class}: auto fallback #{strategy} -> #{next_strategy} after zero extracted items " \

data/lib/html2rss/feed_pipeline.rb

@@ -31,28 +31,25 @@ module Html2rss
       pipeline_outcome_for(config)
     end
 
+    ##
+    # Runs the pipeline once and returns scrape outcome plus {FeedResult} without a second fetch.
+    #
+    # @return [Array(PipelineOutcome, FeedResult)]
+    def to_outcome_and_result
+      config = Config.from_hash(raw_config, params: raw_config[:params])
+      outcome = pipeline_outcome_for(config)
+      [outcome, feed_result_for(config, outcome)]
+    end
+
     ##
     # Runs the pipeline once and returns an opaque, Marshal-cacheable result.
     #
     # @return [Html2rss::FeedResult]
-    # rubocop:disable Metrics/AbcSize, Metrics/MethodLength -- Status kwargs stay co-located with Channel
     def to_result
       config = Config.from_hash(raw_config, params: raw_config[:params])
       outcome = pipeline_outcome_for(config)
-      channel = Channel.from_response(outcome.response, overrides: config.channel)
-      status = Status.build(
-        articles: outcome.articles,
-        dedup_dropped: outcome.dedup_dropped,
-        selected_strategy: outcome.selected_strategy,
-        attempt_count: outcome.attempt_count,
-        strategy_attempts: outcome.strategy_attempts,
-        admission_drops: outcome.admission_drops,
-        scrape_target: outcome.scrape_target,
-        entry_resolution: outcome.entry_resolution
-      )
-      FeedResult.new(channel:, articles: outcome.articles, status:, stylesheets: config.stylesheets)
+      feed_result_for(config, outcome)
     end
-    # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
 
     # @api private Host seam for {AutoFallback} (and single-strategy path).
     # @param config [Html2rss::Config]
@@ -135,7 +132,7 @@ module Html2rss
       [selector + auto, admission_drops]
     end
 
-    # rubocop:disable Metrics/MethodLength
+    # rubocop:disable-next Metrics/MethodLength
     def selector_articles(config:, response:, request_session:)
       return [] unless (selectors = config.selectors)
       return [] if response.feed_response?
@@ -154,7 +151,6 @@ module Html2rss
       end
       articles
     end
-    # rubocop:enable Metrics/MethodLength
 
     # @return [Array(Array<Html2rss::Article>, Hash{String => Integer})]
     def auto_source_articles(config:, response:, request_session:)
@@ -171,5 +167,20 @@ module Html2rss
       end
       [articles, {}]
     end
+
+    def feed_result_for(config, outcome) # rubocop:disable Metrics/MethodLength
+      channel = Channel.from_response(outcome.response, overrides: config.channel)
+      status = Status.build(
+        articles: outcome.articles,
+        dedup_dropped: outcome.dedup_dropped,
+        selected_strategy: outcome.selected_strategy,
+        attempt_count: outcome.attempt_count,
+        strategy_attempts: outcome.strategy_attempts,
+        admission_drops: outcome.admission_drops,
+        scrape_target: outcome.scrape_target,
+        entry_resolution: outcome.entry_resolution
+      )
+      FeedResult.new(channel:, articles: outcome.articles, status:, stylesheets: config.stylesheets)
+    end
   end
 end

data/lib/html2rss/feed_resolution/README.md

@@ -10,17 +10,17 @@ tournament on item count (feed-as-means) — intentional.
 
 ## Ownership
 
-| Concern | Owner |
-| --- | --- |
-| When to resolve (`articles:` required; floor / weak / NativeFeed ≥50%) | `FeedResolution::Policy` |
-| Candidate mix (1 feed + up to 4 listing; taxonomy nav; segment first-wins) | `FeedResolution::CandidateGenerator` |
-| Listing path lexicon (`LISTING_PATHS`) | `Syndication::CandidateCatalog` (consumed, not owned here) |
-| Cheap probe + score + winner pick | `FeedResolution::Probe` + `FeedResolution::Scorer` |
-| Typed entry_resolution options | `FeedResolution::Options` |
-| Wire-safe resolution diag (`applied` = tournament win, not sticky URL) | `FeedResolution::Diag` |
-| Public `call` → `Result`; retry orchestration (sticky `ScrapeTarget` only on `:succeeded`) | `FeedResolution` (`try_apply!`) |
-| Page surface for policy/scoring | `PageRecon::Assessment` + `Html2rss::SurfaceCategory` |
-| Native feed discover/parse | `Syndication` (not this module) |
+| Concern                                                                                    | Owner                                                      |
+| ------------------------------------------------------------------------------------------ | ---------------------------------------------------------- |
+| When to resolve (`articles:` required; floor / weak / NativeFeed ≥50%)                     | `FeedResolution::Policy`                                   |
+| Candidate mix (1 feed + up to 4 listing; taxonomy nav; segment first-wins)                 | `FeedResolution::CandidateGenerator`                       |
+| Listing path lexicon (`LISTING_PATHS`)                                                     | `Syndication::CandidateCatalog` (consumed, not owned here) |
+| Cheap probe + score + winner pick                                                          | `FeedResolution::Probe` + `FeedResolution::Scorer`         |
+| Typed entry_resolution options                                                             | `FeedResolution::Options`                                  |
+| Wire-safe resolution diag (`applied` = tournament win, not sticky URL)                     | `FeedResolution::Diag`                                     |
+| Public `call` → `Result`; retry orchestration (sticky `ScrapeTarget` only on `:succeeded`) | `FeedResolution` (`try_apply!`)                            |
+| Page surface for policy/scoring                                                            | `PageRecon::Assessment` + `Html2rss::SurfaceCategory`      |
+| Native feed discover/parse                                                                 | `Syndication` (not this module)                            |
 
 ### CandidateGenerator mix