woods 2.0.0.beta2 → 2.0.0.beta4

data/lib/woods/agent_configuration/plan_diff.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'tempfile'
+require 'open3'
+require_relative 'plan'
+
+module Woods
+  module AgentConfiguration
+    module PlanDiff
+      def self.show(plan, output)
+        plan.data.fetch('changes').each do |change|
+          document = Document.new(change.fetch('path'))
+          unless document.fingerprint == change.fetch('before')
+            raise Conflict, "Changed since preview: #{document.path}; create a new plan before viewing its diff"
+          end
+
+          output.write(render(document, Plan.after_content(change)))
+        end
+      end
+
+      def self.render(document, content)
+        Tempfile.create('woods-config-before') do |before|
+          Tempfile.create('woods-config-after') do |after|
+            before.write(document.content.to_s)
+            after.write(content.to_s)
+            before.flush
+            after.flush
+            diff, status = Open3.capture2('diff', '-u', '--label', document.path, '--label', document.path,
+                                          before.path, after.path)
+            raise Conflict, 'Cannot render plan diff' unless [0, 1].include?(status.exitstatus)
+
+            diff
+          end
+        end
+      end
+    end
+  end
+end

data/lib/woods/agent_configuration/planned_files.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Woods
+  module AgentConfiguration
+    # Compute exact document replacements while tracking receipt-owned files.
+    module PlannedFiles
+      private
+
+      def prepare_config
+        document = Document.new(@layout.config_path)
+        value = document.json
+        servers = value.fetch('mcpServers', {})
+        raise Conflict, "mcpServers must be an object: #{document.path}" unless servers.is_a?(Hash)
+
+        validate_server_ownership!(servers)
+        @created_files = @previous ? @previous.fetch('created_files').dup : []
+        track_created_file(document)
+        if @operation == 'remove'
+          servers.delete(@name)
+        else
+          servers[@name] = @entry
+        end
+        value['mcpServers'] = servers
+        @plan.add(document, config_content(document, value),
+                  description: "#{@operation} owned Index MCP entry #{@name}")
+      end
+
+      def config_content(document, value)
+        return if @operation == 'remove' && @created_files.include?(document.path) && value == { 'mcpServers' => {} }
+
+        document.encode_json(value)
+      end
+
+      def prepare_sections
+        previous_sections = @previous ? @previous.fetch('sections') : {}
+        requested = @instructions || previous_sections.keys
+        requested = [] if @operation == 'remove'
+        validate_instruction_selection!(requested, previous_sections)
+        @sections = {}
+        (previous_sections.keys | requested).each do |name|
+          prepare_section(name, previous_sections[name], removing: !requested.include?(name))
+        end
+      end
+
+      def prepare_section(name, previous, removing:)
+        document = Document.new(@layout.instruction_path(name))
+        content, ownership = ManagedSection.change(document.content, previous: previous, remove: removing)
+        track_created_file(document)
+        content = nil if removing && content == '' && @created_files.include?(document.path)
+        @sections[name] = ownership if ownership
+        @plan.add(document, content, description: "#{removing ? 'remove' : 'write'} owned Woods instruction section")
+      end
+
+      def track_created_file(document)
+        return unless document.content.nil? && !@created_files.include?(document.path)
+
+        @created_files << document.path
+      end
+    end
+  end
+end

data/lib/woods/agent_configuration/planner.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require_relative 'plan'
+require_relative 'managed_section'
+require_relative 'planner_validation'
+require_relative 'planned_files'
+
+module Woods
+  module AgentConfiguration
+    class Planner
+      include PlannerValidation
+      include PlannedFiles
+
+      TEMPLATE_VERSION = 1
+
+      def initialize(layout:, operation:, entry: nil, **options)
+        unknown = options.keys - %i[name instructions evidence intent]
+        raise ArgumentError, "unknown keywords: #{unknown.join(', ')}" unless unknown.empty?
+
+        name = options.fetch(:name, 'woods')
+        raise Conflict, 'Supported operations: setup, update, remove' unless %w[setup update remove].include?(operation)
+        raise Conflict, 'Server name must be a simple nonempty name' unless name.match?(/\A[a-zA-Z0-9_-]+\z/)
+
+        @layout = layout
+        @operation = operation
+        @entry = entry
+        @name = name
+        @instructions = options[:instructions]
+        @evidence = options.fetch(:evidence, {})
+        @intent = options.fetch(:intent, {})
+      end
+
+      def call
+        @receipt_document = Document.new(@layout.receipt_path)
+        @previous = @receipt_document.content && @receipt_document.json
+        validate_receipt!
+        @plan = Plan.new(layout: @layout, operation: @operation, evidence: @evidence)
+        return @plan if @operation == 'remove' && @previous.nil?
+
+        prepare_config
+        prepare_sections
+        prepare_receipt
+        @plan
+      end
+
+      private
+
+      def prepare_receipt
+        if @operation == 'remove'
+          @plan.add(@receipt_document, nil, description: 'remove installation receipt')
+          return
+        end
+        receipt = { 'schema_version' => 1, 'template_version' => TEMPLATE_VERSION, 'layout' => @layout.identity,
+                    'server_name' => @name, 'entry' => @entry, 'sections' => @sections,
+                    'created_files' => @created_files, 'intent' => @intent, 'evidence' => @evidence }
+        # A repeated setup never silently upgrades the installation's template
+        # or evidence version. The explicit update operation owns that change.
+        receipt = @previous if @operation == 'setup' && @previous && @plan.data.fetch('changes').empty?
+        @plan.add(@receipt_document, @receipt_document.encode_json(receipt), description: 'record owned installation')
+      end
+    end
+  end
+end

data/lib/woods/agent_configuration/planner_validation.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Woods
+  module AgentConfiguration
+    # Receipt and command validation shared by the planner's file preparations.
+    module PlannerValidation
+      private
+
+      def validate_receipt!
+        if @previous
+          validate_receipt_identity!
+        elsif @operation == 'update'
+          raise Conflict, 'No owned installation to update; run setup first'
+        end
+        return if @operation == 'remove'
+
+        validate_entry!
+        validate_setup_compatibility! if @operation == 'setup' && @previous
+      end
+
+      def validate_receipt_identity!
+        valid = @previous['schema_version'] == 1 && @previous['layout'] == @layout.identity &&
+                @previous['server_name'] == @name && @previous['sections'].is_a?(Hash) &&
+                @previous['created_files'].is_a?(Array)
+        raise Conflict, 'Installation receipt does not match this application/client/scope/server' unless valid
+
+        validate_receipt_content!
+      end
+
+      def validate_receipt_content!
+        sections = @previous.fetch('sections')
+        valid_sections = sections.values.all? do |section|
+          section.is_a?(Hash) && section['owned_text'].is_a?(String) && section['prefix'].is_a?(String)
+        end
+        valid_files = (@previous.fetch('created_files') - @layout.allowed_paths).empty?
+        return if valid_sections && valid_files && @previous['entry'].is_a?(Hash)
+
+        raise Conflict, 'Malformed ownership receipt; restore it before updating or removing configuration'
+      end
+
+      def validate_entry!
+        return if @entry.is_a?(Hash) && @entry['command'].is_a?(String) && @entry['args'].is_a?(Array)
+
+        raise Conflict, 'A preflight-validated Index MCP command is required'
+      end
+
+      def validate_setup_compatibility!
+        if @previous['entry'] != @entry
+          raise Conflict, 'Setup differs from the owned installation; preview an explicit update'
+        end
+        return if @previous['template_version'] == self.class::TEMPLATE_VERSION
+
+        raise Conflict, 'The instruction template changed; preview an explicit update'
+      end
+
+      def validate_server_ownership!(servers)
+        if @previous
+          return if servers[@name] == @previous.fetch('entry')
+
+          raise Conflict, 'The owned MCP entry was edited or removed; restore it or resolve ownership manually'
+        end
+        return unless servers.key?(@name)
+
+        raise Conflict, "MCP entry #{@name.inspect} already exists without a Woods receipt; choose another name"
+      end
+
+      def validate_instruction_selection!(requested, previous_sections)
+        unless requested.is_a?(Array) && requested.uniq == requested
+          raise Conflict, 'Instruction files must be a unique list'
+        end
+        return unless @operation == 'setup' && @previous && requested.sort != previous_sections.keys.sort
+
+        raise Conflict, 'Instruction selection differs; preview an explicit update'
+      end
+    end
+  end
+end

data/lib/woods/agent_configuration/preflight.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'open3'
+require 'timeout'
+require 'bundler'
+require_relative 'error'
+
+module Woods
+  module AgentConfiguration
+    class Preflight
+      REQUIRED_TOOLS = %w[woods_status search lookup dependencies dependents].freeze
+      SCRIPT = <<~'RUBY'
+        require 'timeout'
+        Timeout.timeout(25) do
+          require 'json'
+          require 'woods'
+          require 'woods/mcp/server'
+          require 'woods/resilience/index_validator'
+          root = File.realpath(ARGV.fetch(1))
+          index = File.realpath(ARGV.fetch(0))
+          spec = Gem.loaded_specs.fetch('woods')
+          abort 'Installed Woods is missing woods-mcp-start' unless spec.executables.include?('woods-mcp-start')
+          reader = Woods::MCP::IndexReader.new(index)
+          manifest = reader.manifest
+          abort 'Published extraction manifest missing or malformed' unless manifest.is_a?(Hash) && manifest['counts'].is_a?(Hash)
+          report = Woods::Resilience::IndexValidator.new(index_dir: index, app_root: root).validate
+          abort report.errors.join("\n") unless report.valid?
+          tools = Woods::MCP::Server.build(index_dir: index, warmup: false).tools.keys
+          puts JSON.generate(version: Woods::VERSION, tools: tools.sort, root: root, index: index,
+                             generation: reader.loaded_generation, warnings: report.warnings)
+        end
+      RUBY
+
+      def initialize(timeout: 30)
+        @timeout = timeout
+      end
+
+      def call(launcher)
+        output = run(launcher)
+        evidence = JSON.parse(output)
+        raise Conflict, 'Installed Woods preflight expected a JSON object' unless evidence.is_a?(Hash)
+
+        missing = REQUIRED_TOOLS - Array(evidence['tools'])
+        raise Conflict, "Installed Woods lacks required Index capabilities: #{missing.join(', ')}" unless missing.empty?
+        raise Conflict, 'Installed Woods did not report its version' unless evidence['version'].is_a?(String)
+
+        evidence
+      rescue JSON::ParserError
+        raise Conflict, 'Installed Woods preflight did not return valid JSON; inspect application bundle and index'
+      end
+
+      private
+
+      def run(launcher)
+        command = launcher.probe_command(SCRIPT)
+        environment = Bundler.unbundled_env.merge(launcher.probe_environment)
+        Open3.popen3(environment, *command, chdir: launcher.root, unsetenv_others: true,
+                                            pgroup: true) do |stdin, out, err, wait|
+          stdin.close
+          collect(out, err, wait)
+        end
+      rescue Errno::ENOENT => e
+        raise Conflict, "Launch command unavailable: #{e.message}"
+      end
+
+      def collect(stdout, stderr, wait)
+        readers = [stdout, stderr].map { |stream| Thread.new { bounded_read(stream) } }
+        Timeout.timeout(@timeout) do
+          output, errors = readers.map(&:value)
+          raise Conflict, "Installed Woods preflight failed: #{errors.strip}" unless wait.value.success?
+
+          output
+        end
+      rescue Timeout::Error
+        raise Conflict, "Installed Woods preflight exceeded #{@timeout}s; verify the selected command and container"
+      ensure
+        terminate(wait.pid)
+        readers&.each(&:kill)
+      end
+
+      def bounded_read(stream)
+        output = String.new
+        loop do
+          chunk = stream.readpartial(16_384)
+          output << chunk
+          raise Conflict, 'Installed Woods preflight output exceeded 1 MiB' if output.bytesize > 1_048_576
+        end
+      rescue EOFError
+        output
+      end
+
+      def terminate(pid)
+        Process.kill('KILL', -pid)
+      rescue Errno::ESRCH
+        nil
+      end
+    end
+  end
+end

data/lib/woods/agent_configuration/recovery.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Woods
+  module AgentConfiguration
+    # Validate every journal snapshot before restoring any managed file.
+    module Recovery
+      private
+
+      def recover_journal(journal)
+        plan = Plan.allocate
+        plan.instance_variable_set(:@data, journal.fetch('plan'))
+        plan.validate!(@layout)
+        changes = plan.data.fetch('changes')
+        originals = journal.fetch('originals')
+        validate_originals!(originals, changes)
+        changes.each { |change| validate_recovery_snapshot!(change) }
+        originals.zip(changes).reverse_each { |original, change| restore_original(original, change) }
+        File.unlink(journal_path)
+      rescue KeyError, TypeError, ArgumentError => e
+        raise Conflict, "Invalid recovery journal; retained for manual recovery: #{e.message}"
+      end
+
+      def validate_originals!(originals, changes)
+        paths = changes.map { |entry| entry['path'] }
+        return if originals.is_a?(Array) && originals.all?(Hash) && originals.map { |entry| entry['path'] } == paths
+
+        raise Conflict, "Invalid recovery journal; retain it for manual recovery: #{journal_path}"
+      end
+
+      def validate_recovery_snapshot!(change)
+        return if [change.fetch('before'), Plan.after_fingerprint(change)].include?(current(change))
+
+        raise Conflict,
+              "Concurrent edit prevents recovery of #{change.fetch('path')}; journal retained: #{journal_path}"
+      end
+
+      def restore_original(original, change)
+        return if current(change) == change.fetch('before')
+
+        content = original['content'] && Base64.strict_decode64(original['content']).force_encoding(Encoding::UTF_8)
+        expected = { 'sha256' => content && Digest::SHA256.hexdigest(content),
+                     'mode' => original.fetch('mode'), 'exists' => !content.nil? }
+        assert_snapshot!(expected, change.fetch('before'), original.fetch('path'))
+        assert_snapshot!(current(change), Plan.after_fingerprint(change), original.fetch('path'))
+        replace(original.fetch('path'), content, original.fetch('mode'))
+      end
+    end
+  end
+end

data/lib/woods/ast/node.rb

@@ -26,6 +26,8 @@ module Woods
       :arguments,   # Array<String>: argument representations (for :send)
       :source,      # String | nil: raw source text of this node
       :end_line,    # Integer | nil: 1-based end line number (when available)
+      :start_byte,   # Integer | nil: inclusive byte offset into the parsed source
+      :end_byte,     # Integer | nil: exclusive byte offset into the parsed source
       keyword_init: true
     ) do
       # Find all descendant nodes matching a type.

data/lib/woods/ast/parser.rb

@@ -32,6 +32,21 @@ module Woods
         raise Woods::ExtractionError, "Failed to parse source: #{e.message}"
       end
 
+      # Validate a candidate excerpt without logging expected syntax failures
+      # (for example a heredoc body outside a method's syntactic AST range).
+      # The parser instance owns its diagnostics; no global stderr redirection.
+      def valid_fragment?(source)
+        return Prism.parse(source).success? if prism_available?
+
+        require 'parser/current' unless defined?(::Parser::CurrentRuby)
+        parser = ::Parser::CurrentRuby.default_parser
+        parser.diagnostics.consumer = nil
+        buffer = ::Parser::Source::Buffer.new('(fragment)', source: source)
+        !parser.parse(buffer).nil?
+      rescue StandardError
+        false
+      end
+
       # Check if Prism is available.
       #
       # @return [Boolean]
@@ -262,7 +277,9 @@ module Woods
           end_line: end_line_for_prism(prism_node),
           method_name: prism_node.name.to_s,
           receiver: receiver_text,
-          source: extract_prism_source_span(prism_node, source)
+          source: extract_prism_source_span(prism_node, source),
+          start_byte: prism_node.location.start_offset,
+          end_byte: prism_node.location.end_offset
         )
       end
 
@@ -524,12 +541,16 @@ module Woods
             line: parser_node.loc.line,
             end_line: parser_node.loc.expression.last_line,
             method_name: parser_node.children[0].to_s,
-            source: extract_parser_source_span(parser_node, source)
+            source: extract_parser_source_span(parser_node, source),
+            start_byte: original_byte_offset(source, parser_node.loc.expression.line,
+                                             parser_node.loc.expression.column),
+            end_byte: original_byte_offset(source, parser_node.loc.expression.last_line,
+                                           parser_node.loc.expression.last_column)
           )
         when :defs
           body = parser_node.children[3] ? convert_parser_node(parser_node.children[3], source) : nil
           body_children = parser_body_children(body)
-          receiver = parser_node.children[0].type == :self ? 'self' : parser_node.children[0].to_s
+          receiver = extract_parser_receiver_text(parser_node.children[0], source)
           Node.new(
             type: :defs,
             children: body_children,
@@ -537,7 +558,11 @@ module Woods
             end_line: parser_node.loc.expression.last_line,
             method_name: parser_node.children[1].to_s,
             receiver: receiver,
-            source: extract_parser_source_span(parser_node, source)
+            source: extract_parser_source_span(parser_node, source),
+            start_byte: original_byte_offset(source, parser_node.loc.expression.line,
+                                             parser_node.loc.expression.column),
+            end_byte: original_byte_offset(source, parser_node.loc.expression.last_line,
+                                           parser_node.loc.expression.last_column)
           )
         when :send
           receiver_text = parser_node.children[0] ? extract_parser_receiver_text(parser_node.children[0], source) : nil
@@ -611,8 +636,16 @@ module Woods
         end
       end
 
+      # parser gem normalizes CRLF in its source buffer. Its line/character
+      # columns still identify the original source, but absolute positions do
+      # not. Map through original lines to preserve both CRLF and Unicode bytes.
+      def original_byte_offset(source, line, column)
+        lines = source.lines
+        lines.take(line - 1).sum(&:bytesize) + lines.fetch(line - 1)[0, column].bytesize
+      end
+
       def parser_body_children(body_node)
-        body_node&.type == :begin ? body_node.children : [body_node].compact
+        body_node.is_a?(Node) && body_node.type == :begin ? body_node.children : [body_node].compact
       end
 
       def extract_parser_source_span(node, source)

data/lib/woods/builder.rb

@@ -110,6 +110,11 @@ 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)
+      if @config.retrieval_mode == :lexical
+        return build_lexical_retriever(metadata_store: metadata_store,
+                                       graph_store: graph_store)
+      end
+
       provider = build_resilient_embedding_provider
       cache = build_cache_store
 
@@ -119,12 +124,21 @@ module Woods
         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
+        embedding_provider: provider, default_budget: @config.max_context_tokens
       )
 
       cache ? wrap_with_retriever_cache(retriever, cache) : retriever
     end
 
+    def build_lexical_retriever(metadata_store:, graph_store:)
+      retriever = Retriever.new(vector_store: nil, metadata_store: metadata_store || build_metadata_store,
+                                graph_store: graph_store, embedding_provider: nil, mode: :lexical,
+                                default_budget: @config.max_context_tokens)
+      cache = build_cache_store
+      cache ? wrap_with_retriever_cache(retriever, cache) : retriever
+    end
+    private :build_lexical_retriever
+
     # Instantiate the vector store adapter specified by the configuration.
     #
     # The :pgvector branch also ensures the adapter's own schema exists —
@@ -482,19 +496,21 @@ module Woods
 
     # Instantiate the metadata store adapter specified by the configuration.
     #
+    # @param output_dir [String, Pathname] Default SQLite database directory; an
+    #   explicit metadata_store_options[:database] still takes precedence.
     # @return [Storage::MetadataStore::Interface] Metadata store adapter instance
     # @raise [ArgumentError] if the configured type is not recognized
-    def build_metadata_store
+    def build_metadata_store(output_dir: @config.output_dir)
       case @config.metadata_store
       when :in_memory then Storage::MetadataStore::InMemory.new
-      when :sqlite then Storage::MetadataStore::SQLite.new(**sqlite_metadata_options)
+      when :sqlite then Storage::MetadataStore::SQLite.new(**sqlite_metadata_options(output_dir))
       else raise ArgumentError, "Unknown metadata_store: #{@config.metadata_store}"
       end
     end
 
-    def sqlite_metadata_options
+    def sqlite_metadata_options(output_dir)
       opts = (@config.metadata_store_options || {}).transform_keys(&:to_sym)
-      opts[:database] ||= File.join(@config.output_dir.to_s, 'metadata.sqlite3')
+      opts[:database] ||= File.join(output_dir.to_s, 'metadata.sqlite3')
       opts
     end
     private :sqlite_metadata_options

data/lib/woods/cache/cache_middleware.rb

@@ -418,6 +418,8 @@ module Woods
       def vector_store   = @retriever.vector_store
       def metadata_store = @retriever.metadata_store
       def graph_store    = @retriever.graph_store
+      def mode = @retriever.respond_to?(:mode) ? @retriever.mode : :semantic
+      def default_budget = @retriever.respond_to?(:default_budget) ? @retriever.default_budget : 8000
 
       # Invalidate every cached context result. Called from the MCP +reload+
       # tool after the retriever's stores have been re-hydrated from a fresh
@@ -449,12 +451,17 @@ module Woods
       # @param types [Array<String, Symbol>, nil] Include-only filter
       # @param exclude_types [Array<String, Symbol>, nil] Additional exclusions
       # @return [Retriever::RetrievalResult]
-      def retrieve(query, budget: 8000, types: nil, exclude_types: nil)
-        key = context_key(query, budget, types: types, exclude_types: exclude_types)
+      def retrieve(query, budget: default_budget, types: nil, exclude_types: nil, packages: nil, source_paths: nil,
+                   evidence: 'full') # rubocop:disable Metrics/ParameterLists
+        Retrieval::SourceEvidence.validate_mode!(evidence)
+        scoped = Retrieval::Scope.requested?(packages: packages, source_paths: source_paths)
+        scope_options = scoped ? { packages: packages, source_paths: source_paths } : {}
+        scope_options[:evidence] = evidence unless evidence == 'full'
+        key = context_key(query, budget, types: types, exclude_types: exclude_types, **scope_options)
         cached = @cache_store.read(key)
         return rehydrate_cached(cached, budget) if cached
 
-        result = @retriever.retrieve(query, budget: budget, types: types, exclude_types: exclude_types)
+        result = @retriever.retrieve(query, budget: budget, types: types, exclude_types: exclude_types, **scope_options)
 
         begin
           @cache_store.write(key, serialize_result(result), ttl: @context_ttl)
@@ -478,8 +485,14 @@ module Woods
       # @param types [Array<String, Symbol>, nil]
       # @param exclude_types [Array<String, Symbol>, nil]
       # @return [String]
-      def context_key(query, budget, types: nil, exclude_types: nil)
-        Cache.cache_key(:context, query, budget.to_s, fingerprint(types), fingerprint(exclude_types))
+      def context_key(query, budget, types: nil, exclude_types: nil, packages: nil, source_paths: nil, evidence: 'full') # rubocop:disable Metrics/ParameterLists
+        parts = [query, budget.to_s, fingerprint(types), fingerprint(exclude_types)]
+        parts << 'lexical' if mode == :lexical
+        parts << JSON.generate(evidence: evidence) unless evidence == 'full'
+        if Retrieval::Scope.requested?(packages: packages, source_paths: source_paths)
+          parts << JSON.generate(packages: packages, source_paths: source_paths)
+        end
+        Cache.cache_key(:context, *parts)
       end
 
       def fingerprint(types)
@@ -504,7 +517,8 @@ module Woods
           tokens_used: cached['tokens_used'],
           budget: budget,
           trace: nil,
-          type_rank_context: rehydrate_type_rank_context(cached['type_rank_context'])
+          type_rank_context: rehydrate_type_rank_context(cached['type_rank_context']),
+          applied_scope: rehydrate_scope(cached['applied_scope'])
         )
       end
 
@@ -514,10 +528,17 @@ module Woods
           'sources' => result.sources,
           'strategy' => result.strategy&.to_s,
           'tokens_used' => result.tokens_used,
-          'type_rank_context' => serialize_type_rank_context(result.type_rank_context)
+          'type_rank_context' => serialize_type_rank_context(result.type_rank_context),
+          'applied_scope' => result.applied_scope
         }
       end
 
+      def rehydrate_scope(scope)
+        return nil unless scope
+
+        scope.transform_keys(&:to_sym).tap { |value| value[:outcome] = value[:outcome]&.to_sym }
+      end
+
       # type_rank_context is a Hash<String => Hash<Symbol, ...>> with
       # :source carrying a Symbol value. JSON-backed caches (Redis,
       # SolidCache) collapse both to strings on the round-trip, so we

data/lib/woods/cache/cache_store.rb

@@ -25,11 +25,10 @@ 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 = if parts.one?
-              parts.first.to_s
-            else
-              parts.map { |part| "#{part.to_s.bytesize}:#{part}" }.join
-            end
+      raw = parts.map do |part|
+        value = part.to_s
+        "#{value.bytesize}:#{value}"
+      end.join
       suffix = raw.length > 64 ? Digest::SHA256.hexdigest(raw) : raw
       "woods:cache:#{domain}:#{suffix}"
     end

data/lib/woods/change_set.rb

@@ -15,7 +15,8 @@ module Woods
   #
   # Paths are held absolute (matching how {DependencyGraph} registers file
   # paths) and exposed relative on demand (matching how {PathDispatcher}
-  # rules are written).
+  # rules are written). Normalization is lexical, so vanished files remain
+  # representable without resolving symlink targets or consulting the filesystem.
   #
   # @example
   #   cs = Woods::ChangeSet.new(paths: %w[app/models/user.rb app/models/gone.rb], root: Rails.root)
@@ -29,7 +30,7 @@ module Woods
     # @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)
+      @root = Pathname.new(root.to_s).expand_path
       @absolute_paths = Array(paths).filter_map { |p| absolutize(p) }.uniq.freeze
     end
 
@@ -72,7 +73,7 @@ module Woods
     # @param path [String] absolute path
     # @return [String] root-relative path, or the input if outside {#root}
     def relativize(path)
-      prefix = "#{@root}/"
+      prefix = File.join(@root.to_s, '')
       path.start_with?(prefix) ? path.delete_prefix(prefix) : path
     end
 
@@ -82,7 +83,7 @@ module Woods
       str = path.to_s.strip
       return nil if str.empty?
 
-      Pathname.new(str).absolute? ? str : @root.join(str).to_s
+      @root.join(str).cleanpath.to_s
     end
   end
 end