woods 2.0.0.beta2 → 2.0.0.beta3

data/lib/woods/hooks/context_impact.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Woods
+  module Hooks
+    # Resolve one unambiguous edited identity, then reuse the bounded graph walk.
+    class ContextImpact
+      MAX_NODES = 50_000
+
+      def initialize(reader, renderer)
+        @reader = reader
+        @renderer = renderer
+      end
+
+      def call(path, generation, freshness)
+        graph = @reader.raw_graph_data
+        roots = roots_for(graph, path)
+        header = "Woods candidates from generation #{generation} (pre-refresh snapshot; " \
+                 "source freshness: #{freshness}). Changed path: #{JSON.generate(path)}."
+        return unresolved(header, roots) unless roots.size == 1
+
+        root = roots.first
+        traversal = @reader.traverse_dependents(root.fetch('identifier'), depth: 2, explain: true, max_nodes: 10,
+                                                                          max_edges: 100)
+        @renderer.context(header, rows_for(traversal), partial: !!traversal[:partial])
+      end
+
+      private
+
+      def rows_for(traversal)
+        rows = traversal.fetch(:explanation).fetch(:witnesses).filter_map do |_identifier, witness|
+          next if witness[:impact] == 'root'
+
+          edge = traversal[:explanation][:edges].fetch(witness.fetch(:edge_id))
+          evidence_row(edge, witness)
+        end
+        rows << 'No candidate found within this bounded snapshot; verify manually with dependents.' if rows.empty?
+        rows
+      end
+
+      def roots_for(graph, path)
+        records = records_for(graph)
+        matching = records.select { |node| node['file_path'] == path }
+        identities = matching.map { |node| node.slice('identifier', 'type') }.uniq
+        return identities if identities.size != 1
+
+        # A recorded edge target does not identify which same-named type it means.
+        records.select { |node| node['identifier'] == identities.first['identifier'] }
+               .map { |node| node.slice('identifier', 'type') }.uniq
+      end
+
+      def unresolved(header, roots)
+        reason = roots.empty? ? 'unresolved changed path' : 'ambiguous changed identity'
+        rows = roots.first(10).map { |root| "#{root['identifier']} (#{root['type']})" }
+        @renderer.context("#{header} #{reason}; verify with search and typed lookup.", rows, partial: true)
+      end
+
+      def evidence_row(edge, witness)
+        source = edge.fetch(:source)
+        target = edge.fetch(:target)
+        target_type = target[:type] || "ambiguous/unknown #{Array(target[:candidate_types]).join(',')}"
+        test_hint = source[:type] == 'test_mapping' ? '; test suggestion' : ''
+        uncertain = witness[:typed_path_complete] ? '' : '; typed path incomplete'
+        "#{witness[:impact]} candidate: #{source[:identifier]} (#{source[:type]}) " \
+          "--via=#{edge[:via] || 'unknown'}--> #{target[:identifier]} (#{target_type})#{test_hint}#{uncertain}"
+      end
+
+      def records_for(graph)
+        nodes = graph.fetch('nodes')
+        variants = graph.fetch('variants', [])
+        raise ArgumentError unless nodes.is_a?(Hash) && variants.is_a?(Array)
+        raise ArgumentError if nodes.size + variants.size > MAX_NODES
+
+        nodes.map { |identifier, node| node.merge('identifier' => identifier) } + variants
+      end
+    end
+  end
+end

data/lib/woods/hooks/context_output.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Woods
+  module Hooks
+    # Bounds the complete client JSON envelope, preserving whole evidence rows.
+    class ContextOutput
+      MAX_BYTES = 2048
+      UNAVAILABLE = 'Woods context unavailable or incomplete; inspect woods_status ' \
+                    'and verify with search/lookup/dependents.'
+
+      def initialize(kind)
+        @kind = kind
+      end
+
+      def context(header, rows = [], partial: false)
+        selected = []
+        rows.each do |row|
+          if envelope(([header] + selected + [row, footer(true)]).join("\n")).bytesize > MAX_BYTES
+            partial = true
+            break
+          end
+          selected << row
+        end
+        text = ([header] + selected + [footer(partial)]).join("\n")
+        envelope(text).bytesize <= MAX_BYTES ? text : UNAVAILABLE
+      end
+
+      def encode(context)
+        result = envelope(context)
+        result.bytesize <= MAX_BYTES ? result : envelope(UNAVAILABLE)
+      end
+
+      private
+
+      def footer(partial)
+        "truncated: #{partial ? 'yes' : 'no'}; depth<=2, nodes<=10, edges<=100. " \
+          'Verify with dependents explain:true; candidates and test suggestions are not proof.'
+      end
+
+      def envelope(context)
+        JSON.generate(hookSpecificOutput: { hookEventName: @kind, additionalContext: context })
+      end
+    end
+  end
+end

data/lib/woods/hooks/context_state.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'json'
+require 'securerandom'
+
+module Woods
+  module Hooks
+    # Separate, bounded emitted-hint history; never touches refresh queue/leases.
+    class ContextState
+      MAX_BYTES = 131_072
+      MAX_SESSIONS = 32
+      MAX_HINTS = 32
+
+      def initialize(output_dir)
+        @file = File.join(output_dir, 'hook-context-state.json')
+      end
+
+      def emit(result)
+        return yield unless suppressible?(result)
+
+        key = Digest::SHA256.hexdigest(JSON.generate([result[:root], result[:session]]))
+        open_regular("#{@file}.lock", File::RDWR | File::CREAT) do |lock|
+          return unless lock.flock(File::LOCK_EX | File::LOCK_NB)
+
+          state = read_state
+          history = state.delete(key) || []
+          return if history.include?(result[:identity])
+
+          yield
+          state[key] = (history + [result[:identity]]).last(MAX_HINTS)
+          state.shift while state.size > MAX_SESSIONS
+          write_state(state)
+        end
+      rescue SystemCallError, IOError
+        # State contention/unavailability may skip an optional hint, never refresh.
+        nil
+      end
+
+      private
+
+      def suppressible?(result)
+        result[:identity] && result[:session]
+      end
+
+      def open_regular(path, flags)
+        flags |= File::NOFOLLOW if defined?(File::NOFOLLOW)
+        File.open(path, flags | File::NONBLOCK, 0o600) do |file|
+          raise IOError unless file.stat.file?
+
+          yield file
+        end
+      end
+
+      def read_state
+        open_regular(@file, File::RDONLY) do |file|
+          return {} if file.stat.size > MAX_BYTES
+
+          state = JSON.parse(file.read(MAX_BYTES + 1))
+          return {} unless valid_state?(state)
+
+          state
+        end
+      rescue Errno::ENOENT, JSON::ParserError
+        {}
+      end
+
+      def valid_state?(state)
+        state.is_a?(Hash) && state.size <= MAX_SESSIONS && state.all? do |key, history|
+          digest?(key) && valid_history?(history)
+        end
+      end
+
+      def valid_history?(history)
+        history.is_a?(Array) && history.size <= MAX_HINTS && history.all? { |id| digest?(id) }
+      end
+
+      def digest?(value)
+        value.is_a?(String) && value.match?(/\A[0-9a-f]{64}\z/)
+      end
+
+      def write_state(state)
+        temporary = "#{@file}.tmp-#{SecureRandom.hex(12)}"
+        owned = nil
+        open_regular(temporary, File::WRONLY | File::CREAT | File::EXCL) do |file|
+          owned = file.stat
+          file.write(JSON.generate(state))
+        end
+        File.rename(temporary, @file)
+      ensure
+        remove_owned_temporary(temporary, owned) if owned
+      end
+
+      def remove_owned_temporary(path, owned)
+        current = File.lstat(path)
+        File.unlink(path) if current.dev == owned.dev && current.ino == owned.ino
+      rescue Errno::ENOENT
+        nil
+      end
+    end
+  end
+end

data/lib/woods/hooks/refresh.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'json'
+require 'woods/input_rules'
+require 'woods/rake_helpers'
+
+module Woods
+  module Hooks
+    # The JSON argument is portable across host/container command boundaries.
+    # Exit 75 explicitly defers work; only successful consumption acknowledges it.
+    class Refresh
+      MAX_BYTES = 128 * 1024
+      MAX_EVENTS = 1000
+      OPERATIONS = %w[add update delete move].freeze
+
+      def initialize(encoded)
+        raise ArgumentError, 'hook batch too large' if encoded.to_s.bytesize > MAX_BYTES * 2
+
+        @batch = JSON.parse(Base64.strict_decode64(encoded.to_s))
+        validate!
+      end
+
+      def call
+        output = File.expand_path(@batch.fetch('output'), RakeHelpers.woods_task_root)
+        if RakeHelpers.woods_daemon_coverage(output) == :running
+          warn 'Woods hook deferred: watch daemon is active; this batch has not been acknowledged.'
+          exit 75
+        end
+
+        Rake::Task[:environment].invoke
+        require 'woods/extractor'
+        actions, paths = extraction_work
+        return if paths.empty?
+
+        extractor = Extractor.new(output_dir: output)
+        RakeHelpers.woods_with_extraction_lock(output) do
+          actions.include?(:full) ? extractor.extract_all : extractor.extract_changed(paths)
+          extractor.raise_on_publication_failure!
+        end
+      end
+
+      private
+
+      def extraction_work
+        rules = InputRules.new
+        events = @batch.fetch('events')
+        actions = events.map { |event| rules.action(event.fetch('path'), operation: event.fetch('operation')) }
+        paths = events.zip(actions).filter_map { |event, action| event.fetch('path') unless action == :ignore }.uniq
+        [actions, paths]
+      end
+
+      def validate!
+        raise ArgumentError, 'unsupported hook batch' unless @batch.is_a?(Hash) && @batch['version'] == 1
+        raise ArgumentError, 'invalid hook output' unless valid_string?(@batch['output'])
+
+        events = @batch['events']
+        raise ArgumentError, 'invalid hook events' unless valid_events?(events)
+      end
+
+      def valid_events?(events)
+        events.is_a?(Array) && events.size.between?(1, MAX_EVENTS) && events.all? { |event| valid_event?(event) }
+      end
+
+      def valid_event?(event)
+        return false unless event.is_a?(Hash) && OPERATIONS.include?(event['operation'])
+
+        path = event['path']
+        valid_string?(path) && !path.start_with?('/') && path.split('/', -1).none? do |part|
+          ['', '.', '..'].include?(part)
+        end
+      end
+
+      def valid_string?(value)
+        value.is_a?(String) && !value.empty? && !value.include?("\0") && value.bytesize <= MAX_BYTES
+      end
+    end
+  end
+end

data/lib/woods/hooks/rule_projection.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'shellwords'
+require 'woods/input_rules'
+
+module Woods
+  module Hooks
+    # Generated Bash predicate: the plugin also runs on hosts with no Ruby/bundle.
+    # This is a projection of authoritative rules, never a second path inventory.
+    class RuleProjection
+      def render
+        lines = [
+          '# Generated by script/generate-hook-rules; do not edit.',
+          'woods_input_action() {',
+          '  local path="$1" operation="${2:-update}"'
+        ]
+        restart_conditions.each { |condition| lines << "  if #{condition}; then printf full; return; fi" }
+        rules.each do |rule|
+          lines << "  if #{condition_for(rule)}; then"
+          lines << '    case "$operation" in delete|move) printf full ;; *) printf incremental ;; esac'
+          lines << '    return'
+          lines << '  fi'
+        end
+        lines.push('  printf ignore', '}', '').join("\n")
+      end
+
+      private
+
+      def rules
+        PathDispatcher.runtime_rules +
+          PathDispatcher.file_rules + PathDispatcher.whole_app_rules
+      end
+
+      def restart_conditions
+        policy = ReloadPolicy
+        conditions = policy::RESTART_PATHS.map { |path| "[[ \"$path\" == #{quote(path)} ]]" }
+        conditions += policy::RESTART_DIRECTORIES.map { |dir| "[[ \"$path\" == #{quote("#{dir}/")}* ]]" }
+        conditions + policy::RESTART_PATH_PATTERNS.map do |pattern|
+          regex = pattern.source.gsub('\\A', '^').gsub('\\z', '$')
+          "[[ \"$path\" =~ #{regex} ]]"
+        end
+      end
+
+      def condition_for(rule)
+        alternatives = rule.exact_paths.to_a.map { |path| "[[ \"$path\" == #{quote(path)} ]]" }
+        filters = rule.exclude.to_a.map { |part| "[[ \"$path\" != *#{quote(part)}* ]]" }
+        filters += if rule.basenames
+                     [either(rule.basenames.map { |name| "[[ \"${path##*/}\" == #{quote(name)} ]]" })]
+                   else
+                     directory_filters(rule)
+                   end
+        alternatives << "{ #{filters.join(' && ')}; }"
+        either(alternatives)
+      end
+
+      def directory_filters(rule)
+        filters = []
+        filters << either(rule.extensions.map { |ext| "[[ \"$path\" == *#{quote(ext)} ]]" }) if rule.extensions
+        filters << "[[ \"$path\" == *#{quote(rule.require_segment)}* ]]" if rule.require_segment
+        filters << either(rule.dirs.to_a.map { |dir| directory_condition(dir, rule.recursive) })
+      end
+
+      def directory_condition(dir, recursive)
+        variable = recursive == false ? '${path%/*}' : '$path'
+        suffix = recursive == false ? quote(dir) : "#{quote("#{dir}/")}*"
+        "[[ \"#{variable}\" == #{suffix} ]]"
+      end
+
+      def either(conditions)
+        conditions.empty? ? 'false' : "{ #{conditions.join(' || ')}; }"
+      end
+
+      def quote(value)
+        Shellwords.escape(value)
+      end
+    end
+  end
+end

data/lib/woods/input_rules.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'woods/reload_policy'
+require 'woods/path_dispatcher'
+
+module Woods
+  # Shared fresh-process action contract. Loading this class does not boot Rails.
+  # Extractor constants are needed only when deriving the dispatcher projection.
+  class InputRules
+    def action(path, operation: 'update')
+      return :full if ReloadPolicy.new.classify(path) == :restart
+      return :ignore unless PathDispatcher.new.relevant?(path)
+
+      # A removed runtime class may no longer be discoverable in a fresh boot.
+      # Full extraction also handles the old side of a rename conservatively.
+      %w[delete move].include?(operation) ? :full : :incremental
+    end
+  end
+end

data/lib/woods/mcp/bearer_auth.rb

@@ -35,19 +35,12 @@ module Woods
       # @param enabled [#call, nil] Optional request-time predicate. When it
       #   returns falsy the request passes through unguarded. Nil (the
       #   default) means always guard.
-      def initialize(app, token:, path: nil, enabled: nil)
-        @app = app
-        @path = path
-        @enabled = enabled
-        @warned_unusable_token = false
+      # Rails 6.0 forwards middleware options as a positional hash on Ruby 3.
+      # Delegate to explicit keywords to preserve required/unknown option checks.
+      def initialize(app, options = {}, **keywords)
+        raise TypeError, 'middleware options must be a Hash' unless options.is_a?(Hash)
 
-        if token.respond_to?(:call)
-          @token_source = token
-        else
-          validate_static_token!(token)
-          static_token = token.to_s
-          @token_source = -> { static_token }
-        end
+        initialize_options(app, **options, **keywords)
       end
 
       # Rack entry point. Out-of-scope requests (non-matching `path:` prefix
@@ -72,6 +65,21 @@ module Woods
 
       private
 
+      def initialize_options(app, token:, path: nil, enabled: nil)
+        @app = app
+        @path = path
+        @enabled = enabled
+        @warned_unusable_token = false
+
+        if token.respond_to?(:call)
+          @token_source = token
+        else
+          validate_static_token!(token)
+          static_token = token.to_s
+          @token_source = -> { static_token }
+        end
+      end
+
       # @param env [Hash] Rack environment
       # @return [Boolean] whether this request falls under the guard
       def guard?(env)

data/lib/woods/mcp/bootstrapper.rb

@@ -6,6 +6,7 @@ require_relative 'errors'
 require_relative 'bootstrap_state'
 require_relative 'config_resolver'
 require_relative 'provider_probe'
+require_relative 'published_lexical_retriever'
 require_relative '../index_artifact'
 require_relative '../builder'
 require_relative '../resolved_config'
@@ -128,6 +129,12 @@ module Woods
       #   credentials, dimension mismatch, unsupported artifact, or a missing
       #   artifact under WOODS_REQUIRE_INDEX=1).
       def self.build_retriever(index_dir: nil)
+        mode = ENV.fetch('WOODS_RETRIEVAL_MODE', Woods.configuration.retrieval_mode.to_s)
+        unless %w[semantic lexical].include?(mode)
+          raise BootstrapError, "WOODS_RETRIEVAL_MODE must be semantic or lexical, got #{mode.inspect}"
+        end
+        return build_lexical_retriever(index_dir) if mode == 'lexical'
+
         state = BootstrapState.new
         state.mark(:hydrating)
 
@@ -161,6 +168,20 @@ module Woods
         [retriever, state]
       end
 
+      def self.build_lexical_retriever(index_dir)
+        state = BootstrapState.new
+        state.mark(:hydrating)
+        retriever = PublishedLexicalRetriever.new(index_dir: index_dir || Woods.configuration.output_dir,
+                                                  default_budget: Woods.configuration.max_context_tokens)
+        retriever.warmup!
+        state.mark(:hydrated)
+        warn '[woods-mcp] lexical retrieval: hydrated (published extraction units; no embeddings)'
+        [retriever, state]
+      rescue StandardError => e
+        raise BootstrapError, "lexical index could not be loaded: #{e.class}: #{e.message}"
+      end
+      private_class_method :build_lexical_retriever
+
       def self.static_source_map_without_embeddings?(artifact)
         return false unless artifact
 
@@ -248,6 +269,10 @@ module Woods
         zero_counts = { vectors: 0, metadata: 0, graph: 0 }
         return refresh_reader_only(reader, zero_counts) unless retriever
 
+        if retriever.is_a?(PublishedLexicalRetriever)
+          return reload_lexical_stores!(retriever, index_dir, reader || retriever.reader, state, hooks)
+        end
+
         target = swap_target(retriever)
         return refresh_reader_only(reader, zero_counts) unless target
 
@@ -312,6 +337,43 @@ module Woods
       # Refresh the reader's cached index state and answer the zero-count
       # no-op (MCP-2).
       #
+      def self.reload_lexical_stores!(retriever, index_dir, reader, state, hooks)
+        generation = Woods::Generation.new(output_dir: index_dir)
+        captured = generation.current
+        candidate = PublishedLexicalRetriever.new(index_dir: index_dir).warmup!
+        run_hook(hooks, :after_candidates)
+        lock = reload_extraction_lock(index_dir)
+        unless acquire_writer_lock_briefly(lock)
+          raise ReloadDegraded.new('lexical reload could not acquire the extraction writer lock',
+                                   generation: reader.loaded_generation || 0, stores: ['metadata'])
+        end
+
+        begin
+          reader.with_exclusive_generation do
+            identity = candidate.snapshot.first
+            expected = [captured.number, captured.token, generation.payload_dir(captured).to_s]
+            unless same_generation_marker?(captured, generation.current) &&
+                   [identity.first.to_i, *identity.drop(1)] == expected
+              raise ReloadGenerationMoved.new('generation moved during lexical reload; nothing was swapped',
+                                              generation: reader.loaded_generation || 0, stores: ['metadata'])
+            end
+            counts = { vectors: 0, metadata: candidate.metadata_store.count, graph: 0 }
+            reader.reload!
+            retriever.install_snapshot!(candidate.snapshot)
+            state&.clear_reload_failure!
+            counts
+          end
+        ensure
+          lock.release
+        end
+      rescue ReloadDegraded
+        raise
+      rescue StandardError => e
+        raise ReloadDegraded.new("lexical snapshot reload failed: #{e.class}: #{e.message}",
+                                 generation: reader.loaded_generation || 0, stores: ['metadata'])
+      end
+      private_class_method :reload_lexical_stores!
+
       # A store no-op is not an index no-op: the caller invoked `reload`
       # because something on disk moved, and on a flat (pre-2.0) index
       # {IndexReader} never self-refreshes, so skipping this reports