woods 2.0.1 → 2.1.0

data/lib/woods/rake_helpers.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'woods/atomic_file'
+require 'woods/change_set'
 require 'woods/generation'
 require 'woods/git_command'
 
@@ -9,6 +10,16 @@ module Woods
   module RakeHelpers # rubocop:disable Metrics/ModuleLength -- existing task helpers grouped without changing behavior
     module_function
 
+    # @return [Float, nil] blank values leave the raw task resident
+    def woods_watch_idle_timeout
+      value = ENV['WOODS_WATCH_IDLE_TIMEOUT'].to_s.strip
+      return if value.empty?
+
+      Float(value)
+    rescue ArgumentError, TypeError
+      raise ArgumentError, 'WOODS_WATCH_IDLE_TIMEOUT must be a number of seconds or blank'
+    end
+
     # ── Multi-instance helpers (#164 phase 4) ────────────────────────────────
     #
     # Worktrees are disjoint by construction (each has its own Rails.root and
@@ -59,6 +70,11 @@ module Woods
     end
 
     def woods_with_extraction_lock(output_dir, wait: nil, raise_on_timeout: false, &block)
+      require 'woods/source_inputs/handoff'
+      if ENV[Woods::SourceInputs::Handoff::ENV_KEY]
+        Woods::SourceInputs::Handoff.validate_output!(root: woods_task_root, output_dir: output_dir)
+      end
+
       # Requires first. The default wait reads a constant from the daemon, so
       # resolving it above these lines NameError'd every write task — the same
       # load-order bug as the missing require in `woods:watch`, reintroduced one
@@ -195,7 +211,8 @@ module Woods
     def woods_sweep_index_dir(output_dir, lock_name)
       preserved = [
         output_dir.join("#{lock_name}.lock"),
-        output_dir.join(Woods::Coordination::PipelineLock.guard_filename(lock_name))
+        output_dir.join(Woods::Coordination::PipelineLock.guard_filename(lock_name)),
+        *['', '.lock', '.lease'].map { |suffix| output_dir.join("#{Woods::Watch::ClaimLease::CLAIM}#{suffix}") }
       ]
       output_dir.children.each do |entry|
         FileUtils.rm_rf(entry) unless preserved.include?(entry)
@@ -235,8 +252,9 @@ module Woods
     # naming both.
     #
     # The diff is rooted at the extracted application (`git -C Rails.root`),
-    # consistent with {Woods::GitProvenance} (#262): extraction launched from
-    # another checkout must not diff that checkout's history.
+    # consistent with {Woods::GitProvenance} (#262). Explicit `--relative` and
+    # the current-directory pathspec keep a nested application's paths relative
+    # to Rails.root and exclude sibling applications in the same repository.
     #
     # The child status is carried out, not discarded (M1): `Open3.capture2`
     # turned an unresolvable range — a GitLab zero-SHA, an unfetched GitHub base
@@ -245,7 +263,7 @@ module Woods
     # never ran.
     #
     # @param range [String] a git diff range/revision expression
-    # @param root [Pathname, String] repository root the diff runs against
+    # @param root [Pathname, String] application root the diff runs against
     # @return [Array(Array<String>, String, nil)] the changed paths (both halves
     #   of any rename included), or nil paths plus a human-readable failure when
     #   the range could not be resolved
@@ -254,7 +272,7 @@ module Woods
       output, error, status = Open3.capture3(
         *Woods::GitCommand.argv(
           root, '-c', 'core.quotePath=false',
-          'diff', '--name-status', '-z', '--no-renames', range
+          'diff', '--relative', '--name-status', '-z', '--no-renames', range, '--', '.'
         )
       )
       return [woods_parse_git_diff_name_status(output), nil] if status.success?
@@ -289,11 +307,11 @@ module Woods
     # @return [Array<String>] changed paths
     def woods_incremental_changed_paths(output_dir)
       explicit = ENV.fetch('CHANGED_FILES', nil)
-      return explicit.split(',').map(&:strip) if explicit
+      return woods_normalize_incremental_paths(explicit.split(',')) if explicit
 
       range = woods_incremental_range
       changed_files, failure = woods_changed_paths_for_range(range)
-      return changed_files unless failure
+      return woods_normalize_incremental_paths(changed_files) unless failure
 
       if woods_daemon_coverage(output_dir) == :running
         puts "Could not resolve the git diff range #{range.inspect} (#{failure})."
@@ -309,17 +327,31 @@ module Woods
       exit 1
     end
 
+    # Normalize before the task filters against application-relative rules.
+    # ChangeSet retains outside-root paths as absolute; exclude those here so
+    # traversal spellings cannot reach extraction as application source. This
+    # is lexical containment, preserving deleted files and symlink spellings.
+    #
+    # @param paths [Array<String>] absolute or application-relative paths
+    # @return [Array<String>] unique, contained application-relative paths
+    def woods_normalize_incremental_paths(paths)
+      ChangeSet.new(paths: paths, root: Rails.root).relative_paths.reject { |path| Pathname.new(path).absolute? }
+    end
+
     # The git range `woods:incremental` diffs, from the CI environment or the
     # last-commit default.
     #
     # @return [String]
     def woods_incremental_range
-      if ENV['CI_COMMIT_BEFORE_SHA']
+      before = ENV['CI_COMMIT_BEFORE_SHA'].to_s.strip
+      current = ENV['CI_COMMIT_SHA'].to_s.strip
+      base = ENV['GITHUB_BASE_REF'].to_s.strip
+      if !before.empty?
         # GitLab CI
-        "#{ENV['CI_COMMIT_BEFORE_SHA']}..#{ENV.fetch('CI_COMMIT_SHA', nil)}"
-      elsif ENV['GITHUB_BASE_REF']
+        "#{before}..#{current.empty? ? 'HEAD' : current}"
+      elsif !base.empty?
         # GitHub Actions PR
-        "origin/#{ENV['GITHUB_BASE_REF']}...HEAD"
+        "origin/#{base}...HEAD"
       else
         # Default: changes since last commit
         'HEAD~1'

data/lib/woods/release.rb

@@ -2,7 +2,7 @@
 
 module Woods
   # Maintainer-only release machinery, deliberately not packaged with the gem.
-  # These files back `release:prepare` and `release:reopen`, which only ever run
+  # These files back `release:prepare`, `release:reopen`, and `release:retarget`, which run
   # from a source checkout of this repository.
   module Release
     # Every refusal the release flow raises. `lib/tasks/release.rake` rescues

data/lib/woods/resilience/index_validator.rb

@@ -132,19 +132,24 @@ module Woods
 
         warn_unresolvable_paths(warnings, unresolvable)
         validate_dependency_graph(payload, errors)
-        validate_source_inputs(payload, errors)
+        validate_source_inputs(payload, errors, warnings)
       end
 
       # Optional for old generations; malformed new provenance is an artifact
       # integrity error. Source drift itself is advisory and belongs to status.
-      def validate_source_inputs(payload, errors)
+      def validate_source_inputs(payload, errors, warnings)
         path = File.join(payload, SourceInputs::Manifest::FILE_NAME)
         return unless File.exist?(path)
 
         File.open(path, File::RDONLY | File::NONBLOCK) do |file|
           raise SourceInputs::Manifest::Invalid unless file.stat.file?
 
-          SourceInputs::Manifest.parse(file.read(SourceInputs::Manifest::MAX_BYTES + 1))
+          manifest = SourceInputs::Manifest.parse(file.read(SourceInputs::Manifest::MAX_BYTES + 1))
+          if manifest.unavailable?
+            evidence = manifest.data.fetch('unavailable')
+            warnings << "Source freshness unavailable: #{evidence['reason']} (#{evidence['size_bytes']} bytes, " \
+                        "limit #{evidence['limit_bytes']}); the code index remains usable"
+          end
         end
       rescue SourceInputs::Manifest::Invalid, SystemCallError, IOError
         errors << 'Invalid source_inputs.json provenance artifact'

data/lib/woods/resilience/retryable_provider.rb

@@ -81,6 +81,23 @@ module Woods
         @provider.model_name
       end
 
+      # Optional pure configuration contracts; neither may probe the provider.
+      def cache_identity
+        @provider.cache_identity if @provider.respond_to?(:cache_identity)
+      end
+
+      def input_budget
+        @provider.input_budget if @provider.respond_to?(:input_budget)
+      end
+
+      def configured_dimensions
+        @provider.configured_dimensions if @provider.respond_to?(:configured_dimensions)
+      end
+
+      def requested_dimensions
+        @provider.requested_dimensions if @provider.respond_to?(:requested_dimensions)
+      end
+
       # Delegate the per-provider input cap. The retry wrapper does not
       # change the provider's budget, so just hand through whatever the
       # inner provider reports. `respond_to?` alone is the wrong guard
@@ -135,7 +152,7 @@ module Woods
         begin
           attempt += 1
           yield
-        rescue CircuitOpenError, ArgumentError
+        rescue CircuitOpenError, ArgumentError, Embedding::InputLimitError
           raise
         rescue StandardError => e
           raise e if attempt > @max_retries || !retryable_error?(e)

data/lib/woods/resolved_config.rb

@@ -2,6 +2,7 @@
 
 require 'json'
 require 'time'
+require 'uri'
 require_relative 'mcp/errors'
 
 module Woods
@@ -29,6 +30,12 @@ module Woods
     # The only schema version this gem release can read or write.
     SCHEMA_VERSION_SUPPORTED = 1
 
+    BUILTIN_PROVIDERS = {
+      'Woods::Embedding::Provider::OpenAI' => :openai,
+      'Woods::Embedding::Provider::Ollama' => :ollama,
+      'Woods::Embedding::Provider::Fake' => :fake
+    }.freeze
+
     # @return [Integer]
     attr_reader :schema_version
 
@@ -38,7 +45,7 @@ module Woods
     # @return [Time]
     attr_reader :created_at
 
-    # @return [Hash] Provider details — :class, :model, :host, :num_ctx, :read_timeout, :dimension
+    # @return [Hash] Provider details, including observed :dimension and :requested_dimensions
     attr_reader :embedding_provider
 
     # @return [Hash] Store types — :vector_store, :metadata_store, :graph_store (Symbols)
@@ -74,9 +81,9 @@ module Woods
     # the model, not the config — and doesn't hurt OpenAI, whose provider
     # exposes the same +#dimensions+ interface.
     #
-    # When +provider:+ is omitted, dimension falls back to
-    # +config.embedding_options[:dimension]+ (useful for specs and for
-    # offline ResolvedConfig construction where no provider exists).
+    # Known injected providers expose pure constructor settings, including a
+    # configured or already observed width, without probing. Otherwise an
+    # omitted +provider:+ uses the declared embedding options for offline capture.
     #
     # @param config [Woods::Configuration]
     # @param gem_version [String] Defaults to {Woods::VERSION}
@@ -87,7 +94,11 @@ module Woods
       require_relative 'version'
 
       opts = (config.embedding_options || {}).transform_keys(&:to_sym)
-      declared_dim = opts[:dimensions] || opts[:dimension] || opts[:dims]
+      concrete = unwrap_provider(provider || config.embedding_provider)
+      if BUILTIN_PROVIDERS.key?(concrete.class.name) && concrete.respond_to?(:configuration_options)
+        opts = concrete.configuration_options
+      end
+      declared_dim = opts[:expected_dimensions] || opts[:dimensions] || opts[:dimension] || opts[:dims]
       dim = provider.respond_to?(:dimensions) ? provider.dimensions : declared_dim
       model = provider.respond_to?(:model_name) ? provider.model_name : (opts[:model] || config.embedding_model)
 
@@ -99,6 +110,11 @@ module Woods
         num_ctx: opts[:num_ctx],
         read_timeout: opts[:read_timeout]
       }.compact
+      provider_hash[:requested_dimensions] = if provider.respond_to?(:requested_dimensions)
+                                               provider.requested_dimensions
+                                             else
+                                               opts[:dimensions] || opts[:dimension]
+                                             end
 
       new(
         schema_version: SCHEMA_VERSION_SUPPORTED,
@@ -123,7 +139,7 @@ module Woods
       @schema_version = schema_version
       @gem_version = gem_version.to_s.freeze
       @created_at = created_at
-      @embedding_provider = deep_freeze(embedding_provider)
+      @embedding_provider = deep_freeze(self.class.sanitize_provider(embedding_provider))
       @stores = deep_freeze(stores)
       @store_options = deep_freeze(store_options)
       freeze
@@ -206,6 +222,22 @@ module Woods
       to_snapshot_json.freeze
     end
 
+    # Only known built-ins with safely recorded settings can be reconstructed.
+    # An explicitly configured host provider may still use this snapshot.
+    def requires_host_provider?
+      embedding_provider[:requires_host_provider] == true
+    end
+
+    def self.sanitize_provider(provider)
+      result = provider.dup
+      result[:requires_host_provider] = true unless BUILTIN_PROVIDERS.key?(result[:class])
+      if result[:host] && !safe_provider_host?(result[:host])
+        result.delete(:host)
+        result[:requires_host_provider] = true
+      end
+      result
+    end
+
     private
 
     def stringify_nested_keys(value)
@@ -289,7 +321,7 @@ module Woods
 
       def parse_provider(raw)
         data = normalize_keys(raw)
-        {
+        parsed = {
           class: data[:class].to_s,
           model: data[:model].to_s,
           dimension: data[:dimension].to_i,
@@ -297,6 +329,19 @@ module Woods
           num_ctx: data[:num_ctx],
           read_timeout: data[:read_timeout]
         }.compact
+        parsed[:requested_dimensions] = data[:requested_dimensions] if data.key?(:requested_dimensions)
+        parsed[:requires_host_provider] = true if data[:requires_host_provider] == true
+        parsed
+      end
+
+      # Paths and URL metadata can contain credentials. Keep only plain origins;
+      # do not strip a prefix/query and silently reconstruct a different service.
+      def safe_provider_host?(host)
+        uri = URI.parse(host)
+        uri.is_a?(URI::HTTP) && uri.host && !uri.userinfo && !uri.query && !uri.fragment &&
+          ['', '/'].include?(uri.path)
+      rescue URI::InvalidURIError, ArgumentError, TypeError
+        false
       end
 
       def parse_stores(raw)
@@ -338,8 +383,23 @@ module Woods
         when String  then provider
         when Class   then provider.name
         when nil     then ''
-        else provider.to_s
+        else resolve_provider_object_class(provider)
+        end
+      end
+
+      def resolve_provider_object_class(provider)
+        unwrap_provider(provider).class.name || '(anonymous provider)'
+      end
+
+      def unwrap_provider(provider)
+        seen = {}.compare_by_identity
+        while %w[Woods::Resilience::RetryableProvider Woods::Cache::CachedEmbeddingProvider].include?(provider.class.name)
+          raise Woods::MCP::ConfigMismatch, 'Embedding provider wrappers contain a cycle' if seen[provider]
+
+          seen[provider] = true
+          provider = provider.provider
         end
+        provider
       end
     end
   end

data/lib/woods/retrieval/context_assembler.rb

@@ -342,7 +342,7 @@ module Woods
 
       def append_compact_candidate(parts, sources, candidate, unit, budget, tokens_used)
         header = "## #{unit_field(unit, :identifier)} (#{unit_field(unit, :type)})\n" \
-                 "File: #{unit_field(unit, :file_path)}\n\n"
+                 "#{SourceContributors.label(unit)}\n\n"
         remaining = budget - tokens_used
         return tokens_used unless remaining.positive?
 
@@ -365,12 +365,11 @@ module Woods
       def format_unit(unit, _candidate)
         identifier = unit_field(unit, :identifier)
         type = unit_field(unit, :type)
-        file_path = unit_field(unit, :file_path)
         source = unit_field(unit, :source_code) || ''
 
         <<~UNIT.strip
           ## #{identifier} (#{type})
-          File: #{file_path}
+          #{SourceContributors.label(unit)}
 
           #{source}
         UNIT
@@ -386,6 +385,7 @@ module Woods
           score: candidate.score,
           file_path: unit_field(unit, :file_path)
         }
+        attribution.merge!(SourceContributors.attribution(unit))
         attribution[:truncated] = true if truncated
         attribution
       end

data/lib/woods/retrieval/lexical_assembler.rb

@@ -23,7 +23,7 @@ module Woods
         sources = []
         candidates.each do |candidate|
           unit = candidate.metadata
-          header = "\n\n## #{unit['identifier']} (#{unit['type']})\nFile: #{unit['file_path']}\n" \
+          header = "\n\n## #{unit['identifier']} (#{unit['type']})\n#{SourceContributors.label(unit)}\n" \
                    "Matched: #{candidate.matched_fields.join(', ')}\n\n"
           remaining = (budget * 4) - context.length - header.length
           next unless remaining.positive?
@@ -37,7 +37,7 @@ module Woods
             context += header + selected.text
             sources << { identifier: unit['identifier'], type: unit['type'], file_path: unit['file_path'],
                          score: candidate.score, matched_fields: candidate.matched_fields,
-                         evidence: selected.provenance }
+                         evidence: selected.provenance }.merge(SourceContributors.attribution(unit))
             next
           end
 
@@ -49,6 +49,7 @@ module Woods
           context += header + (truncated ? source[0, remaining - marker.length] + marker : source)
           sources << { identifier: unit['identifier'], type: unit['type'], file_path: unit['file_path'],
                        score: candidate.score, matched_fields: candidate.matched_fields, truncated: truncated }
+                     .merge(SourceContributors.attribution(unit))
           break if truncated
         end
         body = context[notice.length..].to_s

data/lib/woods/retrieval/scope.rb

@@ -3,6 +3,7 @@
 require 'json'
 require 'set'
 require_relative '../storage_identity'
+require_relative '../source_contributors'
 require_relative '../storage/metadata_store'
 
 module Woods
@@ -83,13 +84,28 @@ module Woods
       def validate_packages!(records)
         names = records.filter_map { |unit| unit['identifier'] if unit['type'] == 'package' }
         names.concat(records.filter_map { |unit| unit.dig('metadata', 'package') })
+        names.concat(records.flat_map do |unit|
+          SourceContributors.records(unit).filter_map do |record|
+            record['package']
+          end
+        end)
         unknown = packages - names
         raise InvalidScopeError, "unknown package scope: #{unknown.join(', ')}" unless unknown.empty?
       end
 
       def eligible?(unit, types, excluded)
-        return false unless packages.empty? || packages.include?(unit.dig('metadata', 'package'))
-        return false unless source_paths.empty? || path_match?(unit['file_path'])
+        contributors = SourceContributors.records(unit)
+        owners = if contributors.empty?
+                   [unit.dig('metadata', 'package')]
+                 else
+                   contributors.map do |record|
+                     record['package']
+                   end
+                 end
+        return false unless packages.empty? || owners.all? { |owner| packages.include?(owner) }
+
+        paths = SourceContributors.paths(unit)
+        return false unless source_paths.empty? || (paths.any? && paths.all? { |path| path_match?(path) })
         return Array(types).map(&:to_s).include?(unit['type']) if types && !types.empty?
 
         !Array(excluded).map(&:to_s).include?(unit['type'])

data/lib/woods/retrieval/source_evidence.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative '../source_contributors'
+
 require 'digest'
 require 'json'
 require_relative '../ast/parser'
@@ -170,7 +172,7 @@ module Woods
 
       def format_evidence(mode, selected, metadata, total)
         parts = ["Evidence: #{mode}; published-unit coordinates (physical location unavailable).",
-                 "Unit: #{field(:type)}:#{field(:identifier)}; path: #{field(:file_path)}",
+                 "Unit: #{field(:type)}:#{field(:identifier)}; #{SourceContributors.label(@unit)}",
                  "Source SHA256: #{Digest::SHA256.hexdigest(@source)}",
                  "Generation: #{@generation || 'unavailable (not recorded by this metadata store)'}"]
         selected.each do |span|
@@ -183,17 +185,27 @@ module Woods
         parts.join("\n\n")
       end
 
+      def span_provenance(span)
+        result = span.to_h.merge(sha256: Digest::SHA256.hexdigest(span_text(span)))
+        if SourceContributors.multiple?(@unit)
+          result[:physical_location] =
+            SourceContributors.physical_span(@unit, start_byte: span.start_byte, end_byte: span.end_byte)
+        end
+        result
+      end
+
       def provenance(mode, selected, metadata, all)
         { mode: mode, owner: { identifier: field(:identifier), type: field(:type) },
           coordinate_system: 'published_unit', source_sha256: Digest::SHA256.hexdigest(@source),
           source_path: field(:file_path), physical_location: nil,
           physical_location_reason: 'published unit may contain synthesized or inlined source',
           generation: @generation, generation_status: @generation ? 'recorded' : 'unavailable',
-          spans: selected.map { |span| span.to_h.merge(sha256: Digest::SHA256.hexdigest(span_text(span))) },
+          spans: selected.map { |span| span_provenance(span) },
           omitted_spans: all.size - selected.size, runtime_fields: metadata.map(&:first),
           source_complete: false, full_evidence: { tool: 'lookup', evidence: 'full',
                                                    identifier: field(:identifier), type: field(:type),
                                                    source_sha256: Digest::SHA256.hexdigest(@source) } }
+          .merge(SourceContributors.attribution(@unit))
       end
     end
   end

data/lib/woods/source_contributor_validation.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'digest'
+
+module Woods
+  # Checks the versioned contributor boundary before consumers use its paths or coordinates.
+  module SourceContributorValidation
+    class Invalid < ArgumentError; end
+
+    RANGE_KEYS = %w[source_start_line source_end_line published_start_byte published_end_byte
+                    published_start_line published_end_line].freeze
+
+    module_function
+
+    def validate!(records, type:, version:, source:)
+      unless type.to_s == 'lib' && version == 1 && records.is_a?(Array) && records.size.between?(2, 100_000)
+        raise Invalid, 'Invalid library contributor version or records'
+      end
+
+      validate_records!(records)
+      records.each { |record| validate_source!(source, record) } if source.is_a?(String)
+      records
+    end
+
+    def validate_records!(records)
+      previous = 0
+      paths = records.map do |record|
+        unless valid_record?(record) && valid_ranges?(record, previous)
+          raise Invalid, 'Invalid library contributor path or range'
+        end
+
+        previous = record.fetch('published_end_byte')
+        record.fetch('file_path')
+      end
+      raise Invalid, 'Unordered or duplicate library contributor path' unless paths.uniq.sort == paths
+    end
+
+    def valid_record?(record)
+      record.is_a?(Hash) && record.keys.all?(String) && valid_path?(record['file_path']) &&
+        valid_hash?(record['source_sha256']) &&
+        record['facts'].is_a?(Hash) && RANGE_KEYS.all? { |key| record[key].is_a?(Integer) }
+    end
+
+    def valid_hash?(hash)
+      hash.is_a?(String) && hash.match?(/\A[0-9a-f]{64}\z/)
+    end
+
+    def valid_ranges?(record, previous)
+      record['source_start_line'] == 1 && record['source_end_line'].positive? &&
+        record['published_start_byte'] >= previous && record['published_end_byte'] > record['published_start_byte'] &&
+        record['published_start_line'].positive? && record['published_end_line'] >= record['published_start_line']
+    end
+
+    def valid_path?(path)
+      path.is_a?(String) && path.start_with?('lib/') && path.end_with?('.rb') && !path.include?("\0") &&
+        !path.include?('\\') && path.split('/', -1).none? { |part| ['', '.', '..'].include?(part) }
+    end
+
+    def validate_source!(source, record)
+      raise Invalid, 'Contributor range exceeds published source' if record['published_end_byte'] > source.bytesize
+
+      fragment = source.byteslice(record['published_start_byte']...record['published_end_byte'])
+      first = source.byteslice(0...record['published_start_byte']).count("\n") + 1
+      return if valid_fragment?(fragment, first, record)
+
+      raise Invalid, 'Library contributor bytes do not match published provenance'
+    end
+
+    def valid_fragment?(fragment, first, record)
+      Digest::SHA256.hexdigest(fragment) == record['source_sha256'] &&
+        fragment.lines.size == record['source_end_line'] && first == record['published_start_line'] &&
+        first + fragment.lines.size - 1 == record['published_end_line']
+    end
+    private_class_method :validate_records!, :valid_record?, :valid_hash?, :valid_ranges?, :valid_path?,
+                         :validate_source!,
+                         :valid_fragment?
+  end
+end