woods 2.0.0 → 2.1.0

data/lib/woods/mcp/server.rb

@@ -601,6 +601,8 @@ module Woods
             respond.call(renderer.render(:search, payload))
           rescue Retrieval::Scope::InvalidScopeError => e
             respond_err.call(e.message, code: :unsupported_argument, tool: 'search', argument: 'scope')
+          rescue ArgumentError => e
+            respond_err.call(e.message, code: :invalid_params, tool: 'search', argument: 'types')
           rescue IOError, SystemCallError, JSON::ParserError, EncodingError
             respond_err.call(
               'Search completeness: unknown (unreadable_or_corrupt_source). ' \
@@ -1169,6 +1171,10 @@ module Woods
             }
           ) do |entry_point:, server_context:, depth: nil|
             max_depth = coerce_int.call(depth) || 3
+            unless reader.find_unit(entry_point.split('#', 2).first)
+              next respond_err.call('Flow entry unit not found; use search and lookup to select an indexed unit.',
+                                    code: :not_found, tool: 'trace_flow', entry_point: entry_point)
+            end
 
             # Prefer the precomputed flow JSON written by FlowPrecomputer during
             # extraction (gated on `config.precompute_flows`) — it avoids
@@ -1316,6 +1322,7 @@ module Woods
                 require_relative '../extractor' unless defined?(Woods::Extractor)
                 extractor = Woods::Extractor.new(output_dir: output_dir)
                 incremental ? extractor.extract_changed(files) : extractor.extract_all
+                extractor.raise_on_publication_failure!
               end
             end
 
@@ -1893,7 +1900,7 @@ module Woods
 
         def define_snapshot_tools(server, snapshot_store, respond, respond_err, snap_missing)
           define_list_snapshots_tool(server, snapshot_store, respond, snap_missing)
-          define_snapshot_diff_tool(server, snapshot_store, respond, snap_missing)
+          define_snapshot_diff_tool(server, snapshot_store, respond, respond_err, snap_missing)
           define_unit_history_tool(server, snapshot_store, respond, snap_missing)
           define_snapshot_detail_tool(server, snapshot_store, respond, respond_err, snap_missing)
         end
@@ -1918,7 +1925,7 @@ module Woods
           end
         end
 
-        def define_snapshot_diff_tool(server, snapshot_store, respond, snap_missing)
+        def define_snapshot_diff_tool(server, snapshot_store, respond, respond_err, snap_missing)
           server.define_tool(
             name: 'snapshot_diff',
             description: 'Compare two extraction snapshots by git SHA. Returns lists of added, modified, and deleted units.',
@@ -1932,6 +1939,17 @@ module Woods
           ) do |sha_a:, sha_b:, server_context:|
             next snap_missing.call('snapshot_diff') unless snapshot_store
 
+            unless [sha_a, sha_b].all? { |sha| sha.match?(/\A[0-9a-f]+\z/i) }
+              next respond_err.call('Snapshot SHAs must be hexadecimal identifiers from list_snapshots.',
+                                    code: :invalid_params, tool: 'snapshot_diff')
+            end
+            sha_a = sha_a.downcase
+            sha_b = sha_b.downcase
+            unless snapshot_store.find(sha_a) && snapshot_store.find(sha_b)
+              next respond_err.call('One or both snapshots were not found; use list_snapshots for available SHAs.',
+                                    code: :not_found, tool: 'snapshot_diff')
+            end
+
             result = snapshot_store.diff(sha_a, sha_b)
             respond.call(JSON.pretty_generate({
                                                 sha_a: sha_a, sha_b: sha_b,
@@ -1981,6 +1999,7 @@ module Woods
           ) do |git_sha:, server_context:|
             next snap_missing.call('snapshot_detail') unless snapshot_store
 
+            git_sha = git_sha.downcase
             snapshot = snapshot_store.find(git_sha)
             if snapshot
               respond.call(JSON.pretty_generate(snapshot))
@@ -2497,8 +2516,9 @@ module Woods
 
           target = URI::DEFAULT_PARSER.unescape(raw_target).force_encoding(Encoding::UTF_8)
           return unless target.valid_encoding?
-          return if target.match?(%r{[%\\/\x00-\x1f\x7f]})
-          return if %w[. ..].include?(target)
+          return if target.match?(/[%\\\x00-\x1f\x7f]/) || target.start_with?('/')
+          return if target.split('/').any? { |part| %w[. ..].include?(part) }
+          return if parsed.host == 'type' && target.include?('/')
 
           [parsed.host.to_sym, target]
         rescue URI::InvalidURIError

data/lib/woods/module_reconciliation.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module Woods
+  # Keeps callable app/models modules under one extractor owner as model
+  # inclusions change. Partial runtime discovery cannot establish removals.
+  module ModuleReconciliation # rubocop:disable Metrics/ModuleLength -- one ownership/provenance policy across writers
+    private
+
+    # @param affected_types [Set<Symbol>] extractor keys requiring index updates
+    # @return [Set<String>] added, migrated or removed module identifiers
+    def reconcile_model_mixins(affected_types)
+      concerns = extractor_for(:concerns)
+      return Set.new unless concerns.respond_to?(:runtime_model_mixins)
+
+      live = concerns.runtime_model_mixins
+      live_names = live.values.flatten.to_set(&:name)
+      known = @dependency_graph.units_of_type(:concern).to_set
+      added = newly_claimed_concerns(concerns, live, known)
+      touched = register_and_write(:concerns, added, affected_types)
+      touched.merge(remove_claimed_standalone_modules(live_names, affected_types))
+      touched.merge(remove_unclaimed_concerns(concerns, known - live_names, affected_types)) if @eager_load_complete
+      touched.merge(add_standalone_modules(affected_types))
+    end
+
+    def newly_claimed_concerns(concerns, live, known)
+      live.flat_map do |path, modules|
+        next [] if modules.all? { |mod| known.include?(mod.name) }
+
+        checked_extraction(:concerns, concerns) do
+          Array(concerns.extract_model_mixin_file(path)).reject { |unit| known.include?(unit.identifier) }
+        end || []
+      end
+    end
+
+    def remove_claimed_standalone_modules(live_names, affected_types)
+      live_names.each_with_object(Set.new) do |identifier, touched|
+        next unless standalone_module_identity?(identifier)
+
+        touched.add(identifier) if remove_unit(identifier, affected_types, type: :poro)
+      end
+    end
+
+    def remove_unclaimed_concerns(concerns, stale, affected_types)
+      stale.each_with_object(Set.new) do |identifier, touched|
+        path = @dependency_graph.node(identifier, type: :concern)[:file_path]
+        next if concerns.conventional_concern_path?(path)
+
+        touched.add(identifier) if remove_unit(identifier, affected_types, type: :concern)
+      end
+    end
+
+    def runtime_model_mixin_file?(extractor, type, path)
+      type == :concern && extractor.respond_to?(:extract_model_mixin_file) &&
+        extractor.respond_to?(:conventional_concern_path?) && !extractor.conventional_concern_path?(path)
+    end
+
+    def add_standalone_modules(affected_types)
+      poros = extractor_for(:poros)
+      return Set.new unless poros.respond_to?(:standalone_modules)
+
+      discovered = checked_extraction(:poros, poros) { poros.standalone_modules }
+      return Set.new unless discovered
+
+      added = discovered.values.flatten.reject do |unit|
+        @dependency_graph.node(unit.identifier, type: :poro) ||
+          @dependency_graph.node(unit.identifier, type: :concern)
+      end
+      register_and_write(:poros, added, affected_types)
+    end
+
+    def standalone_module_identity?(identifier)
+      return false unless @dependency_graph.node(identifier, type: :poro)
+
+      path = payload_dir.join('poros', collision_safe_filename(identifier))
+      return false unless path.file?
+
+      JSON.parse(AtomicFile.read(path)).fetch('metadata', {})['ruby_kind'] == 'module'
+    end
+
+    # A missing includer during fallback boot does not transfer its previously
+    # published concern to the PORO extractor. Filter fresh candidates too.
+    def authoritative_module_units(units)
+      return units if @eager_load_complete
+
+      units.reject do |unit|
+        unit.type == :poro && unit.metadata[:ruby_kind] == 'module' &&
+          @dependency_graph.node(unit.identifier, type: :concern)
+      end
+    end
+
+    # @param identifier [String] published typed identity
+    # @param type [Symbol] current owner
+    # @return [Boolean] whether incomplete loading requires retaining this unit
+    def retain_partial_module?(identifier, type)
+      return false if @eager_load_complete
+
+      return false unless runtime_module_identity?(identifier, type)
+      return false if type == :poro && live_concern_identity?(identifier)
+
+      verify_retained_module_source!(identifier, type)
+      true
+    end
+
+    def runtime_module_identity?(identifier, type)
+      return standalone_module_identity?(identifier) if type == :poro
+      return false unless type == :concern
+
+      concerns = extractor_for(:concerns)
+      path = @dependency_graph.node(identifier, type: type)[:file_path]
+      concerns.respond_to?(:conventional_concern_path?) && !concerns.conventional_concern_path?(path)
+    end
+
+    def live_concern_identity?(identifier)
+      concerns = extractor_for(:concerns)
+      concerns.respond_to?(:runtime_model_mixins) &&
+        concerns.runtime_model_mixins.values.any? { |modules| modules.any? { |mod| mod.name == identifier } }
+    end
+
+    # Cache identities predate every consumption update in this run. A freshly
+    # written shared-file sibling must not certify retained module metadata as
+    # having consumed changed source during incomplete eager loading.
+    def verify_retained_module_source!(identifier, type)
+      return unless @source_inputs
+
+      path = @dependency_graph.node(identifier, type: type)[:file_path]
+      relative = File.expand_path(path, Rails.root).delete_prefix("#{File.expand_path(Rails.root)}/")
+      before = @source_reference_baseline&.dig('files', relative, 'identity')
+      return if before && before == @source_inputs.source_identity(path)
+
+      raise SourceReferences::RebuildRequired,
+            "Cannot refresh retained #{type}:#{identifier} after incomplete eager loading. " \
+            'Retry in a fresh Rails process with a complete eager load; the previous generation remains active.'
+    end
+
+    def consume_module_aware_refresh(key, units)
+      if !@eager_load_complete && %i[poros concerns].include?(key)
+        @source_inputs&.unverified("extractor:#{key}")
+      else
+        @source_inputs&.consume_extractor(key, units)
+      end
+    end
+
+    # These formerly file-only families now retain runtime-discovered modules
+    # on a partial boot, so their replacement authority follows the same gate.
+    def replacement_discovery_complete?(key)
+      return @eager_load_complete if %i[poros concerns].include?(key)
+
+      super
+    end
+  end
+end

data/lib/woods/path_dispatcher.rb

@@ -165,7 +165,7 @@ module Woods
           file_rule(:migrations, :extract_migration_file, %w[db/migrate], recursive: false),
           # POROs are app/models classes that are *not* ActiveRecord models;
           # the extractor makes that call itself given ar_names.
-          file_rule(:poros, :extract_poro_file, %w[app/models], exclude: %w[/concerns/]),
+          file_rule(:poros, :extract_poro_units, %w[app/models], exclude: %w[/concerns/]),
           file_rule(:libs, :extract_lib_file, %w[lib], exclude: ex::LibExtractor::EXCLUDED_SEGMENTS),
           file_rule(:test_mappings, :extract_test_file, %w[spec], extensions: %w[_spec.rb]),
           file_rule(:test_mappings, :extract_test_file, %w[test], extensions: %w[_test.rb])
@@ -184,11 +184,16 @@ module Woods
         Woods::Extractors::ViewTemplateExtractor::ENGINES.flat_map { |k| k.new.extensions }.uniq
       end
 
+      def aggregate_source_rules
+        [whole_app_rule(:libs, %w[lib], extensions: %w[.rb], exclude: Woods::Extractors::LibExtractor::EXCLUDED_SEGMENTS),
+         whole_app_rule(:rake_tasks, Woods::Extractors::RakeTaskExtractor::RAKE_DIRECTORIES, extensions: %w[.rake])]
+      end
+
       def build_whole_app_rules
         [
           # A task may combine definitions from several files; any change or
           # deletion must reconcile the complete task set, not its primary file.
-          whole_app_rule(:rake_tasks, Woods::Extractors::RakeTaskExtractor::RAKE_DIRECTORIES, extensions: %w[.rake]),
+          *aggregate_source_rules,
           whole_app_rule(:routes, %w[config/routes], exact_paths: %w[config/routes.rb]),
           whole_app_rule(:engines, %w[config/routes], exact_paths: %w[config/routes.rb Gemfile.lock]),
           whole_app_rule(:middleware, %w[config/initializers config/environments],

data/lib/woods/railtie_support.rb

@@ -114,6 +114,7 @@ module Woods
         warn_late_console_path(config)
         return unless config.console_mcp_enabled && config.console_mcp_http_enabled
 
+        verify_console_origins!
         require 'woods/mcp/bearer_auth'
         token = config.console_mcp_token.to_s
         if token.empty?
@@ -147,6 +148,13 @@ module Woods
 
       private
 
+      def verify_console_origins!
+        require 'woods/mcp/origin_policy'
+        Woods::MCP::OriginPolicy.new(allowed_origins: config.console_mcp_allowed_origins)
+      rescue ArgumentError => e
+        raise Woods::ConfigurationError, "[Woods Console] #{e.message}"
+      end
+
       # Warn when the configured console path no longer matches the path the
       # stack was mounted at — the path was set after railtie initializers
       # captured the middleware arguments.

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