woods 1.6.1 → 2.0.0.beta1

data/lib/woods/builder.rb

@@ -8,6 +8,8 @@ require_relative 'storage/metadata_store'
 require_relative 'storage/graph_store'
 require_relative 'embedding/provider'
 require_relative 'embedding/openai'
+require_relative 'embedding/fake'
+require_relative 'resilience/retryable_provider'
 require_relative 'embedding/text_preparer'
 require_relative 'embedding/token_counter'
 require_relative 'token_utils'
@@ -69,7 +71,8 @@ module Woods
 
     # Build a {Configuration} populated with the named preset's adapter types.
     #
-    # @param name [Symbol] Preset name — one of :local, :postgresql, or :production
+    # @param name [Symbol] Preset name — one of :local, :shared_filesystem,
+    #   :postgresql, or :production
     # @return [Configuration] A new Configuration with preset values applied
     # @raise [ArgumentError] if the preset name is not recognized
     def self.preset_config(name)
@@ -107,13 +110,13 @@ module Woods
     #   on disk and passes the populated store here.
     # @return [Retriever, Cache::CachedRetriever] A fully wired retriever
     def build_retriever(vector_store: nil, metadata_store: nil, graph_store: nil)
-      provider = build_embedding_provider
+      provider = build_resilient_embedding_provider
       cache = build_cache_store
 
       provider = wrap_with_embedding_cache(provider, cache) if cache
 
       retriever = Retriever.new(
-        vector_store: vector_store || build_vector_store,
+        vector_store: vector_store || build_vector_store(dimensions: vector_dimensions(provider)),
         metadata_store: metadata_store || build_metadata_store,
         graph_store: graph_store || build_graph_store,
         embedding_provider: provider
@@ -124,19 +127,56 @@ module Woods
 
     # Instantiate the vector store adapter specified by the configuration.
     #
+    # The :pgvector branch also ensures the adapter's own schema exists —
+    # see {#build_pgvector_store}.
+    #
     # @return [Storage::VectorStore::Interface] Vector store adapter instance
     # @raise [ArgumentError] if the configured type is not recognized
-    def build_vector_store
+    # @raise [Woods::Error] if the pgvector schema cannot be created
+    def build_vector_store(dimensions: nil)
       case @config.vector_store
       when :in_memory then Storage::VectorStore::InMemory.new
-      when :pgvector then Storage::VectorStore::Pgvector.new(**(@config.vector_store_options || {}))
-      when :qdrant then Storage::VectorStore::Qdrant.new(**(@config.vector_store_options || {}))
+      when :pgvector then build_pgvector_store(dimensions)
+      when :qdrant then build_qdrant_store(dimensions)
       else raise ArgumentError, "Unknown vector_store: #{@config.vector_store}"
       end
     end
 
+    # The provider's advertised dimension count, when a durable store needs
+    # one to size its column or collection.
+    #
+    # Probed exactly like {#safe_max_input_tokens}: {#provider_object?}'s
+    # contract is that only +#embed+/+#embed_batch+ are required of an
+    # injected provider and the rest of the interface is checked at each call
+    # site, and a provider that merely includes {Embedding::Provider::Interface}
+    # answers +respond_to?+ with a +NotImplementedError+ stub (B-108). Either
+    # way the answer is "no dimensions", which lets
+    # {#resolve_pgvector_dimensions}/{#resolve_qdrant_dimensions} fall back to
+    # the explicit +vector_store_options[:dimensions]+ they document (STO-6).
+    #
+    # @param provider [Embedding::Provider::Interface]
+    # @return [Integer, nil]
+    def vector_dimensions(provider)
+      return nil unless %i[pgvector qdrant].include?(@config.vector_store)
+      return nil unless provider.respond_to?(:dimensions)
+
+      provider.dimensions
+    rescue NotImplementedError
+      nil
+    end
+    private :vector_dimensions
+
     # Instantiate the embedding provider specified by the configuration.
     #
+    # `embedding_provider` accepts three shapes (#178):
+    # - +:openai+ / +:ollama+ — the network-backed adapters.
+    # - +:fake+ — {Embedding::Provider::Fake}: deterministic, offline, for
+    #   CI/smoke runs. See {#build_fake_provider} for dimension resolution.
+    # - an already-constructed provider *object* — anything responding to
+    #   +#embed+ and +#embed_batch+ is returned as-is, so hosts can plug in
+    #   their own implementation without patching the Builder. It flows
+    #   through {#build_resilient_embedding_provider} like the built-ins.
+    #
     # Strips `embedding_options` keys that belong to the ResolvedConfig layer
     # (like `:dimension`) before splatting into the provider's constructor —
     # those keys are useful for the Snapshotter's schema header but
@@ -145,27 +185,148 @@ module Woods
     # @return [Embedding::Provider::Interface] Embedding provider instance
     # @raise [ArgumentError] if the configured type is not recognized
     def build_embedding_provider
-      opts = provider_kwargs
-      case @config.embedding_provider
+      configured = @config.embedding_provider
+      return configured if provider_object?(configured)
+
+      opts = provider_kwargs(configured)
+      case configured
       when :openai then Embedding::Provider::OpenAI.new(**opts)
       when :ollama then Embedding::Provider::Ollama.new(**opts)
-      else raise ArgumentError, "Unknown embedding_provider: #{@config.embedding_provider}"
+      when :fake then build_fake_provider(opts)
+      else
+        raise ArgumentError,
+              "Unknown embedding_provider: #{configured}. Valid: :openai, :ollama, :fake, " \
+              'or a provider object responding to #embed and #embed_batch'
       end
     end
 
-    # Kwargs accepted by embedding provider constructors — everything in
-    # `embedding_options` except metadata fields that live there for
-    # ResolvedConfig bookkeeping.
-    SNAPSHOT_ONLY_KEYS = %i[dimension].freeze
-    private_constant :SNAPSHOT_ONLY_KEYS
+    # Wrap an embedding provider in the resilience stack: retry with
+    # full-jitter exponential backoff (Retry-After aware) plus a dedicated
+    # {Resilience::CircuitBreaker}.
+    #
+    # This is the provider every pipeline entry point must hand to the
+    # Indexer or Retriever — with it, a transient 429/5xx burst degrades a
+    # run instead of aborting it (#188 / B-076). {#build_embedding_provider}
+    # deliberately keeps returning the *raw* provider: the MCP boot path
+    # ({MCP::ProviderProbe}) dispatches on the provider's concrete class and
+    # reads its internals, so the wrap happens here, one layer up.
+    #
+    # Each call constructs a fresh breaker — breaker state is per-instance
+    # and must never be shared across unrelated components.
+    #
+    # The wrap is harmless for providers that never raise transient
+    # failures ({Embedding::Provider::Fake}, most injected provider
+    # objects): nothing retryable ever fires, so the wrapper is a
+    # transparent pass-through.
+    #
+    # @param provider [Embedding::Provider::Interface] raw provider to wrap;
+    #   defaults to a freshly built one from the configuration
+    # @return [Resilience::RetryableProvider] the wrapped provider
+    def build_resilient_embedding_provider(provider = build_embedding_provider)
+      Resilience::RetryableProvider.new(
+        provider: provider,
+        circuit_breaker: Resilience::CircuitBreaker.new
+      )
+    end
+
+    PROVIDER_OPTION_KEYS = {
+      openai: %i[api_key model dimension dimensions],
+      ollama: %i[model host num_ctx read_timeout dimension dimensions],
+      fake: %i[model dims dimension dimensions]
+    }.freeze
+    private_constant :PROVIDER_OPTION_KEYS
 
-    def provider_kwargs
+    def provider_kwargs(configured)
       opts = (@config.embedding_options || {}).transform_keys(&:to_sym)
-      SNAPSHOT_ONLY_KEYS.each { |k| opts.delete(k) }
+      validate_provider_options!(configured, opts)
+      apply_embedding_model!(opts)
+      normalize_dimension_option!(configured, opts)
+      validate_required_provider_options!(configured, opts)
       opts
     end
     private :provider_kwargs
 
+    def validate_provider_options!(configured, opts)
+      allowed = PROVIDER_OPTION_KEYS[configured]
+      return unless allowed
+
+      unknown = opts.keys - allowed
+      return if unknown.empty?
+
+      provider_name = configured.to_s.capitalize
+      noun = unknown.one? ? 'option' : 'options'
+      raise ConfigurationError,
+            "Unknown #{provider_name} embedding #{noun}: #{unknown.join(', ')}. " \
+            "Valid options: #{allowed.join(', ')}"
+    end
+    private :validate_provider_options!
+
+    def validate_required_provider_options!(configured, opts)
+      return unless configured == :openai
+      return unless opts[:api_key].nil? || opts[:api_key].to_s.empty?
+
+      raise ConfigurationError,
+            'OpenAI requires embedding_options[:api_key]. Set it explicitly, typically from OPENAI_API_KEY.'
+    end
+    private :validate_required_provider_options!
+
+    def apply_embedding_model!(opts)
+      return if opts.key?(:model)
+      return unless @config.respond_to?(:embedding_model_explicit?) && @config.embedding_model_explicit?
+
+      opts[:model] = @config.embedding_model
+    end
+    private :apply_embedding_model!
+
+    def normalize_dimension_option!(configured, opts)
+      legacy_dimension = opts.delete(:dimension)
+      dimensions = opts.delete(:dimensions)
+      if conflicting_dimensions?(legacy_dimension, dimensions)
+        raise ConfigurationError, 'embedding_options dimension and dimensions must match when both are provided'
+      end
+
+      dimension = dimensions || legacy_dimension
+      return unless dimension
+
+      opts[configured == :fake ? :dims : :dimensions] ||= dimension
+    end
+    private :normalize_dimension_option!
+
+    def conflicting_dimensions?(legacy_dimension, dimensions)
+      !legacy_dimension.nil? && !dimensions.nil? && legacy_dimension != dimensions
+    end
+    private :conflicting_dimensions?
+
+    # True when the configured `embedding_provider` is not a Symbol naming a
+    # built-in adapter but an already-constructed provider object (#178).
+    # Duck-typed on the two methods every pipeline consumer calls; the rest
+    # of {Embedding::Provider::Interface} (+#dimensions+, +#model_name+,
+    # +#max_input_tokens+) is probed with +respond_to?+ at each call site,
+    # so an object that omits them still works where they are optional.
+    #
+    # @param candidate [Object]
+    # @return [Boolean]
+    def provider_object?(candidate)
+      !candidate.is_a?(Symbol) && candidate.respond_to?(:embed) && candidate.respond_to?(:embed_batch)
+    end
+    private :provider_object?
+
+    # Build the deterministic fake provider (#178).
+    #
+    # Dimension resolution: `embedding_options[:dims]` maps directly onto
+    # the {Embedding::Provider::Fake} constructor; failing that, the
+    # ResolvedConfig-level `embedding_options[:dimension]` key — normally
+    # snapshot-only bookkeeping stripped by {#provider_kwargs} — is
+    # honoured, so hosts that declare their dimension there (and the MCP
+    # boot path, which restores exactly that key from woods.json) get
+    # vectors of the recorded dimension.
+    #
+    # @return [Embedding::Provider::Fake]
+    def build_fake_provider(opts)
+      Embedding::Provider::Fake.new(**opts)
+    end
+    private :build_fake_provider
+
     # Build a {Embedding::TextPreparer} calibrated to a given provider.
     #
     # OpenAI embedders use tiktoken (cl100k_base) — 4.0 chars/token is a
@@ -184,7 +345,7 @@ module Woods
     # @return [Embedding::TextPreparer]
     def build_text_preparer(provider)
       chars_per_token = chars_per_token_for(provider)
-      budget = provider.respond_to?(:max_input_tokens) ? provider.max_input_tokens : nil
+      budget = safe_max_input_tokens(provider)
       max_tokens = budget || Embedding::TextPreparer::DEFAULT_MAX_TOKENS
 
       Embedding::TextPreparer.new(max_tokens: max_tokens, chars_per_token: chars_per_token)
@@ -215,7 +376,7 @@ module Woods
     # @param provider [Embedding::Provider::Interface]
     # @return [Chunking::SemanticChunker]
     def build_chunker(provider)
-      budget = provider.respond_to?(:max_input_tokens) ? provider.max_input_tokens : nil
+      budget = safe_max_input_tokens(provider)
       max_chars = ((budget * chars_per_token_for(provider)).floor - CHUNKER_PREFIX_ALLOWANCE if budget)
 
       # Guard against a budget so small that the prefix allowance leaves
@@ -256,7 +417,7 @@ module Woods
     # @param provider [Embedding::Provider::Interface]
     # @return [Embedding::TokenCounter, nil]
     def token_counter_for(provider)
-      return unless provider.is_a?(Embedding::Provider::Ollama)
+      return unless unwrap_provider(provider).is_a?(Embedding::Provider::Ollama)
 
       Embedding::TokenCounter.new
     end
@@ -268,16 +429,50 @@ module Woods
     # @param provider [Embedding::Provider::Interface]
     # @return [Float]
     def chars_per_token_for(provider)
-      symbol = case provider
+      symbol = case unwrap_provider(provider)
                when Embedding::Provider::Ollama then :ollama
                else :openai
                end
       TokenUtils.chars_per_token_for(symbol)
     end
 
+    # Provider input-token budget, or nil when the provider has none.
+    # `respond_to?` alone is the wrong guard here: {Embedding::Provider::Interface}
+    # *defines* +max_input_tokens+ as a +NotImplementedError+ stub, so a
+    # provider that merely includes the interface without overriding it
+    # still answers +respond_to?+ with +true+ (B-108) and raises when
+    # called. A provider with no such method at all still needs the
+    # +respond_to?+ guard to avoid a bare +NoMethodError+.
+    #
+    # @param provider [Embedding::Provider::Interface]
+    # @return [Integer, nil]
+    def safe_max_input_tokens(provider)
+      return nil unless provider.respond_to?(:max_input_tokens)
+
+      provider.max_input_tokens
+    rescue NotImplementedError
+      nil
+    end
+
+    # Reach the concrete provider through the resilience wrapper.
+    # Tokenizer calibration dispatches on the provider's real class, so a
+    # {Resilience::RetryableProvider} handed to {#build_text_preparer} or
+    # {#build_chunker} must calibrate exactly like its inner provider —
+    # without this, a wrapped Ollama silently got OpenAI ratios.
+    #
+    # @param provider [Embedding::Provider::Interface]
+    # @return [Embedding::Provider::Interface] the innermost provider
+    def unwrap_provider(provider)
+      provider.is_a?(Resilience::RetryableProvider) ? provider.provider : provider
+    end
+
     # Diagnostic for the build_chunker budget guard.
+    #
+    # @param provider [Embedding::Provider::Interface]
+    # @param budget [Integer]
+    # @return [String]
     def chunker_budget_message(provider, budget)
-      "embedding model '#{provider.respond_to?(:model) ? provider.model : provider.class}' " \
+      "embedding model '#{provider.respond_to?(:model_name) ? provider.model_name : provider.class}' " \
         "reports a max_input_tokens of #{budget}, which leaves no room for " \
         "the chunk prefix (#{CHUNKER_PREFIX_ALLOWANCE} chars). Configure a " \
         'model with a larger native context, or set num_ctx explicitly.'
@@ -292,11 +487,18 @@ module Woods
     def build_metadata_store
       case @config.metadata_store
       when :in_memory then Storage::MetadataStore::InMemory.new
-      when :sqlite then Storage::MetadataStore::SQLite.new(**(@config.metadata_store_options || {}))
+      when :sqlite then Storage::MetadataStore::SQLite.new(**sqlite_metadata_options)
       else raise ArgumentError, "Unknown metadata_store: #{@config.metadata_store}"
       end
     end
 
+    def sqlite_metadata_options
+      opts = (@config.metadata_store_options || {}).transform_keys(&:to_sym)
+      opts[:database] ||= File.join(@config.output_dir.to_s, 'metadata.sqlite3')
+      opts
+    end
+    private :sqlite_metadata_options
+
     # Instantiate the graph store adapter specified by the configuration.
     #
     # @return [Storage::GraphStore::Interface] Graph store adapter instance
@@ -310,6 +512,92 @@ module Woods
 
     private
 
+    # Construct the pgvector adapter and ensure its schema exists.
+    #
+    # The adapter reads and writes its own `woods_vectors` table. The
+    # `woods:pgvector` generator can create it via a migration, but nothing
+    # guarantees that migration ran — so the builder calls the adapter's
+    # idempotent {Storage::VectorStore::Pgvector#ensure_schema!}
+    # (CREATE ... IF NOT EXISTS DDL) after construction. Without this, the
+    # first embed against a bare database fails with PG::UndefinedTable
+    # (#187 / B-075). Schema/connection failures are re-raised as
+    # {Woods::Error} with the original error preserved as the cause.
+    #
+    # @return [Storage::VectorStore::Pgvector]
+    # @raise [Woods::Error] when the schema cannot be created
+    def build_pgvector_store(provider_dimensions)
+      opts = (@config.vector_store_options || {}).transform_keys(&:to_sym)
+      validate_required_store_options!(:pgvector, opts, :connection)
+      opts[:dimensions] = resolve_pgvector_dimensions(provider_dimensions, opts[:dimensions])
+      store = Storage::VectorStore::Pgvector.new(**opts)
+      begin
+        store.ensure_schema!
+        verify_pgvector_dimensions!(store, opts[:dimensions])
+      rescue ConfigurationError
+        raise
+      rescue StandardError => e
+        raise Woods::Error,
+              "pgvector schema setup failed (#{e.class}: #{e.message}). " \
+              'Verify vector_store_options[:connection] is a live PostgreSQL ' \
+              'connection and that the pgvector extension is available ' \
+              '(`rails generate woods:pgvector && rails db:migrate` sets it up via migration).'
+      end
+      store
+    end
+
+    def verify_pgvector_dimensions!(store, expected)
+      actual = store.stored_dimensions
+      return if actual.nil? || actual == expected
+
+      raise ConfigurationError,
+            "Stored pgvector dimensions #{actual} do not match embedding provider dimensions #{expected}. " \
+            'Use a compatible table or rebuild the index.'
+    end
+
+    def resolve_pgvector_dimensions(provider_dimensions, configured_dimensions)
+      if provider_dimensions && configured_dimensions && provider_dimensions != configured_dimensions
+        raise ConfigurationError,
+              "pgvector dimensions #{configured_dimensions} do not match embedding provider dimensions " \
+              "#{provider_dimensions}"
+      end
+
+      provider_dimensions || configured_dimensions || raise(
+        ConfigurationError,
+        'pgvector requires vector_store_options[:dimensions] when built without an embedding provider'
+      )
+    end
+
+    def build_qdrant_store(provider_dimensions)
+      opts = (@config.vector_store_options || {}).transform_keys(&:to_sym)
+      validate_required_store_options!(:qdrant, opts, :url, :collection)
+      dimensions = resolve_qdrant_dimensions(provider_dimensions, opts[:dimensions])
+      opts[:dimensions] = dimensions
+      store = Storage::VectorStore::Qdrant.new(**opts)
+      store.ensure_collection!(dimensions: dimensions)
+      store
+    end
+
+    def validate_required_store_options!(adapter, opts, *keys)
+      missing = keys.select { |key| opts[key].nil? || opts[key].to_s.empty? }
+      return if missing.empty?
+
+      requirements = missing.map { |key| "vector_store_options[:#{key}]" }.join(' and ')
+      raise ConfigurationError, "#{adapter} requires #{requirements}"
+    end
+
+    def resolve_qdrant_dimensions(provider_dimensions, configured_dimensions)
+      if provider_dimensions && configured_dimensions && provider_dimensions != configured_dimensions
+        raise ConfigurationError,
+              "Qdrant dimensions #{configured_dimensions} do not match embedding provider dimensions " \
+              "#{provider_dimensions}"
+      end
+
+      provider_dimensions || configured_dimensions || raise(
+        ConfigurationError,
+        'Qdrant requires vector_store_options[:dimensions] when built without an embedding provider'
+      )
+    end
+
     # Build a cache store from configuration, or nil if caching is disabled.
     #
     # @return [Cache::CacheStore, nil]

data/lib/woods/cache/cache_middleware.rb

@@ -2,6 +2,11 @@
 
 require 'digest'
 require_relative 'cache_store'
+# CachedEmbeddingProvider includes Embedding::Provider::Interface at load
+# time, so the interface must be defined before this file's class bodies run
+# — otherwise a narrow `require 'woods/cache/cache_middleware'` raises
+# NameError (STO-5).
+require_relative '../embedding/provider'
 
 module Woods
   module Cache
@@ -364,8 +369,8 @@ module Woods
       # persistent shared backend (Redis/SolidCache) returns the previous
       # model's vector after a model switch or upgrade — different dimensions
       # error mid-batch, same dimensions silently corrupt similarity scores
-      # (which IndexValidator can't detect, since it checks provider-vs-store
-      # dims, not cache contents).
+      # (which the provider-vs-store dimension check can't detect, since it
+      # compares declared widths, not cache contents).
       #
       # model_name (a plain attribute) is used rather than dimensions on
       # purpose: for every supported provider the model uniquely determines

data/lib/woods/cache/cache_store.rb

@@ -25,7 +25,11 @@ module Woods
     # @param parts [Array<String>] Key components (will be SHA256-hashed if long)
     # @return [String] Namespaced key
     def self.cache_key(domain, *parts)
-      raw = parts.join(':')
+      raw = if parts.one?
+              parts.first.to_s
+            else
+              parts.map { |part| "#{part.to_s.bytesize}:#{part}" }.join
+            end
       suffix = raw.length > 64 ? Digest::SHA256.hexdigest(raw) : raw
       "woods:cache:#{domain}:#{suffix}"
     end
@@ -148,6 +152,10 @@ module Woods
       # @param max_entries [Integer] Maximum cached entries before LRU eviction
       def initialize(max_entries: 500)
         super()
+        unless max_entries.is_a?(Integer) && max_entries.positive?
+          raise ArgumentError, 'max_entries must be a positive Integer'
+        end
+
         @max_entries = max_entries
         @entries = {}
         @access_order = []

data/lib/woods/cache/solid_cache_store.rb

@@ -56,10 +56,12 @@ module Woods
         effective_ttl = ttl || @default_ttl
 
         opts = effective_ttl ? { expires_in: effective_ttl } : {}
-        @cache.write(key, serialized, **opts)
-      rescue StandardError => e
-        logger.warn("[Woods] SolidCacheStore#write failed for #{key}: #{e.message}")
-        nil
+        begin
+          @cache.write(key, serialized, **opts)
+        rescue StandardError => e
+          logger.warn("[Woods] SolidCacheStore#write failed for #{key}: #{e.message}")
+          nil
+        end
       end
 
       # Delete a key from the cache.

data/lib/woods/change_set.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require 'pathname'
+
+module Woods
+  # A normalized set of changed paths, shared by every entry point that has
+  # to answer "what changed?".
+  #
+  # Two callers feed it: the git-diff-driven `woods:incremental` rake task, and
+  # {Woods::Watch::Daemon}, which builds one per batch of FS events. Two code
+  # paths computing "what changed" independently is exactly how a watcher and a
+  # CI chain drift apart, so the normalization — absolutizing, de-duplicating,
+  # and splitting present-from-vanished — lives here rather than in either
+  # caller.
+  #
+  # Paths are held absolute (matching how {DependencyGraph} registers file
+  # paths) and exposed relative on demand (matching how {PathDispatcher}
+  # rules are written).
+  #
+  # @example
+  #   cs = Woods::ChangeSet.new(paths: %w[app/models/user.rb app/models/gone.rb], root: Rails.root)
+  #   cs.existing_paths # => ["/app/app/models/user.rb"]
+  #   cs.missing_paths  # => ["/app/app/models/gone.rb"]
+  #
+  class ChangeSet
+    # @return [Pathname] the application root paths are resolved against
+    attr_reader :root
+
+    # @param paths [Array<String>] changed paths, absolute or root-relative
+    # @param root [String, Pathname] application root (usually Rails.root)
+    def initialize(paths:, root:)
+      @root = Pathname.new(root.to_s)
+      @absolute_paths = Array(paths).filter_map { |p| absolutize(p) }.uniq.freeze
+    end
+
+    # @return [Array<String>] every changed path, absolute
+    attr_reader :absolute_paths
+
+    # @return [Array<String>] every changed path, relative to {#root}
+    def relative_paths
+      @relative_paths ||= @absolute_paths.map { |p| relativize(p) }.freeze
+    end
+
+    # Changed paths that still exist on disk (created or modified).
+    #
+    # @return [Array<String>] absolute paths
+    def existing_paths
+      @existing_paths ||= @absolute_paths.select { |p| File.exist?(p) }.freeze
+    end
+
+    # Changed paths that no longer exist (deleted, or the old side of a
+    # rename — git's `--no-renames` semantics, which is what the deletion
+    # sweep expects).
+    #
+    # @return [Array<String>] absolute paths
+    def missing_paths
+      @missing_paths ||= (@absolute_paths - existing_paths).freeze
+    end
+
+    # @return [Boolean] true when nothing changed
+    def empty?
+      @absolute_paths.empty?
+    end
+
+    # @return [Integer] number of changed paths
+    def size
+      @absolute_paths.size
+    end
+
+    # Convert an absolute path back to a root-relative one.
+    #
+    # @param path [String] absolute path
+    # @return [String] root-relative path, or the input if outside {#root}
+    def relativize(path)
+      prefix = "#{@root}/"
+      path.start_with?(prefix) ? path.delete_prefix(prefix) : path
+    end
+
+    private
+
+    def absolutize(path)
+      str = path.to_s.strip
+      return nil if str.empty?
+
+      Pathname.new(str).absolute? ? str : @root.join(str).to_s
+    end
+  end
+end

data/lib/woods/checks/generation_resolution.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Woods
+  module Checks
+    # Turns "which two generations should `woods:check:moved_messages`
+    # compare" into a pair of numbers, given the generations a
+    # {Woods::PublishedIndex} currently has published (#280 / M14).
+    #
+    # A pure function over its arguments: it never touches the filesystem or
+    # opens an index. `to` defaults to the newest published generation,
+    # `from` defaults to the newest one strictly older than `to`. Either side
+    # given explicitly is used as-is (converted with `Integer()`, so rake's
+    # string arguments work); explicit values are not checked against
+    # +available+ here, {Woods::PublishedIndex.new} already raises a clear
+    # `ArgumentError` for a generation that is not published.
+    module GenerationResolution
+      # @param available [Array<Integer>] published generation numbers, ascending
+      # @param from [String, Integer, nil] explicit older generation
+      # @param to [String, Integer, nil] explicit newer generation
+      # @return [Array(Integer, Integer), nil] `[from, to]`, or nil when there
+      #   are not two generations to compare (fewer than two retained, and
+      #   neither side was given explicitly)
+      def self.call(available, from: nil, to: nil)
+        to_number = to ? Integer(to) : available.last
+        return nil if to_number.nil?
+
+        from_number = from ? Integer(from) : available.select { |number| number < to_number }.max
+        return nil if from_number.nil?
+
+        [from_number, to_number]
+      end
+    end
+  end
+end