woods 2.0.0.beta2 → 2.0.0.beta4

data/lib/woods/session_tracer/middleware.rb

@@ -1,13 +1,14 @@
 # frozen_string_literal: true
 
 require 'time'
+require 'active_support/inflector'
 
 module Woods
   module SessionTracer
     # Rack middleware that captures request metadata for session tracing.
     #
     # Wraps `@app.call(env)`, records after response. Extracts controller/action
-    # from `env['action_dispatch.request.path_parameters']`. Session ID from
+    # from the dispatched controller instance and Rails path parameters. Session ID from
     # `X-Trace-Session` header first, falls back to `request.session.id`.
     #
     # Fire-and-forget writes — `rescue StandardError` on recording, never breaks the request.
@@ -98,8 +99,7 @@ module Woods
         action = path_params[:action]
         return unless controller
 
-        # Classify controller name (e.g., "orders" -> "OrdersController")
-        controller_class = classify_controller(controller)
+        controller_class = controller_identity(env['action_controller.instance'], controller)
 
         request_data = {
           'session_id' => session_id,
@@ -144,15 +144,13 @@ module Woods
         @exclude_paths.any? { |prefix| path.start_with?(prefix) }
       end
 
-      # Classify a Rails controller path segment into a controller class name.
-      #
-      # @param controller [String] e.g., "orders" or "admin/orders"
-      # @return [String] e.g., "OrdersController" or "Admin::OrdersController"
-      def classify_controller(controller)
-        parts = controller.to_s
-                          .split('/')
-                          .map { |segment| segment.split('_').map(&:capitalize).join }
-        "#{parts.join('::')}Controller"
+      # Runtime identity is authoritative. Rack adapters without a dispatched
+      # instance still use Rails' configured acronyms when classifying the route.
+      def controller_identity(instance, controller)
+        name = instance.class.name if instance
+        return name if name && !name.empty?
+
+        "#{ActiveSupport::Inflector.camelize(controller.to_s)}Controller"
       end
 
       # Extract response format from the Rack env.

data/lib/woods/session_tracer/redis_store.rb

@@ -56,6 +56,19 @@ module Woods
         return 1
       LUA
 
+      # Read and remove against either index format without converting a
+      # legacy SET. Each type check and operation is atomic with respect to
+      # a concurrent record's migration. Reader-only upgrades therefore do
+      # not prevent older SET writers from continuing to record.
+      INDEX_ACCESS_SCRIPT = <<~LUA
+        local legacy = redis.call('TYPE', KEYS[1]).ok == 'set'
+        if ARGV[1] == 'members' then
+          if legacy then return redis.call('SMEMBERS', KEYS[1]) end
+          return redis.call('ZRANGE', KEYS[1], 0, -1)
+        end
+        return redis.call(legacy and 'SREM' or 'ZREM', KEYS[1], ARGV[2])
+      LUA
+
       # @param redis [Redis] A Redis client instance
       # @param ttl [Integer, nil] Time-to-live in seconds for session keys (nil = no expiry)
       def initialize(redis:, ttl: nil, max_sessions: DEFAULT_MAX_SESSIONS,
@@ -103,14 +116,13 @@ module Woods
       # @param limit [Integer] Maximum number of sessions to return
       # @return [Array<Hash>] Session summaries
       def sessions(limit: 20)
-        all_ids = @redis.zrange(SESSIONS_KEY, 0, -1)
+        all_ids = index_access('members')
 
         # Filter to sessions that still have data (TTL may have expired)
         active = all_ids.select { |id| @redis.exists?(session_key(id)) }
 
         # Remove expired session IDs from the index
-        expired = all_ids - active
-        expired.each { |id| @redis.zrem(SESSIONS_KEY, id) } if expired.any?
+        (all_ids - active).each { |id| index_access('remove', id) }
 
         # Redis sorted sets order by score, but a summary's last_request is
         # the payload timestamp of the session's last record — the same
@@ -133,20 +145,24 @@ module Woods
       # @return [void]
       def clear(session_id)
         @redis.del(session_key(session_id))
-        @redis.zrem(SESSIONS_KEY, session_id)
+        index_access('remove', session_id)
       end
 
       # Remove all session data.
       #
       # @return [void]
       def clear_all
-        all_ids = @redis.zrange(SESSIONS_KEY, 0, -1)
+        all_ids = index_access('members')
         all_ids.each { |id| @redis.del(session_key(id)) }
         @redis.del(SESSIONS_KEY)
       end
 
       private
 
+      def index_access(action, session_id = nil)
+        @redis.eval(INDEX_ACCESS_SCRIPT, keys: [SESSIONS_KEY], argv: [action, *session_id])
+      end
+
       # @param session_id [String]
       # @return [String] Redis key for this session
       def session_key(session_id)
@@ -196,7 +212,7 @@ module Woods
 
         victims.each do |id|
           @redis.del(session_key(id))
-          @redis.zrem(SESSIONS_KEY, id)
+          index_access('remove', id)
         end
       end
 

data/lib/woods/session_tracer/session_flow_assembler.rb

@@ -4,6 +4,7 @@ require 'json'
 require 'set'
 require_relative '../token_utils'
 require_relative 'session_flow_document'
+require_relative 'unit_resolver'
 
 module Woods
   module SessionTracer
@@ -42,8 +43,14 @@ module Woods
       # @param budget [Integer] Maximum token budget (default: 8000)
       # @param depth [Integer] Expansion depth (0=metadata only, 1=direct deps, 2+=full flow)
       # @return [SessionFlowDocument] The assembled document
-      # rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
       def assemble(session_id, budget: 8000, depth: 1)
+        @reader.with_pinned_generation { assemble_pinned(session_id, budget: budget, depth: depth) }
+      end
+
+      private
+
+      # rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
+      def assemble_pinned(session_id, budget:, depth:)
         requests = @store.read(session_id)
         return empty_document(session_id) if requests.empty?
 
@@ -52,6 +59,7 @@ module Woods
         side_effects = []
         dependency_map = {}
         seen_units = Set.new
+        resolver = UnitResolver.new(@reader)
 
         requests.each_with_index do |req, idx|
           step = build_step(req, idx)
@@ -63,18 +71,17 @@ module Woods
           next unless controller_id
 
           # Resolve controller unit
-          unit = @reader.find_unit(controller_id)
+          unit = @reader.find_unit(controller_id, type: 'controller')
           if unit && !seen_units.include?(controller_id)
             seen_units.add(controller_id)
             context_pool[controller_id] = unit_summary(unit)
           end
-          step[:unit_refs] = [controller_id].compact
-
-          # Expand dependencies
+          # Expand dependencies only for a resolved controller.
           next unless unit
 
+          step[:unit_refs] = [controller_id]
           deps = resolve_dependencies(controller_id, seen_units, context_pool,
-                                      side_effects, step, dependency_map, depth)
+                                      side_effects, step, dependency_map, depth, resolver)
           step[:unit_refs].concat(deps)
         end
 
@@ -85,8 +92,6 @@ module Woods
         budgeted_document(parts, budget)
       end
 
-      private
-
       # Build a timeline step from a request record.
       #
       # @param req [Hash] Request data from store
@@ -111,13 +116,13 @@ module Woods
       # @return [Array<String>] Non-async dependency identifiers added
       # rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/ParameterLists, Metrics/PerceivedComplexity
       def resolve_dependencies(unit_id, seen_units, context_pool,
-                               side_effects, step, dependency_map, depth)
+                               side_effects, step, dependency_map, depth, resolver)
         graph = @reader.dependency_graph
-        dep_ids = graph.dependencies_of(unit_id)
+        dep_ids = graph.dependencies_of(unit_id, type: :controller)
         added = []
 
         dep_ids.each do |dep_id|
-          dep_unit = @reader.find_unit(dep_id)
+          dep_unit = resolver.find(dep_id)
           next unless dep_unit
 
           dep_type = dep_unit['type']&.to_s
@@ -137,13 +142,13 @@ module Woods
               added << dep_id
 
               # Depth 2+: expand transitive dependencies
-              expand_transitive(dep_id, seen_units, context_pool, dependency_map, depth - 1) if depth >= 2
+              expand_transitive(dep_id, seen_units, context_pool, dependency_map, depth - 1, resolver) if depth >= 2
             end
           end
         end
 
         # Record dependency map for this unit
-        all_deps = dep_ids.select { |id| @reader.find_unit(id) }
+        all_deps = dep_ids.select { |id| resolver.find(id) }
         dependency_map[unit_id] = all_deps if all_deps.any?
 
         added
@@ -156,15 +161,16 @@ module Woods
       # @param context_pool [Hash] Accumulator for unit data
       # @param dependency_map [Hash] Accumulator for dependency edges
       # @param remaining_depth [Integer] Remaining expansion depth
-      def expand_transitive(unit_id, seen_units, context_pool, dependency_map, remaining_depth)
+      # rubocop:disable-next Metrics/ParameterLists
+      def expand_transitive(unit_id, seen_units, context_pool, dependency_map, remaining_depth, resolver)
         return if remaining_depth <= 0
 
         graph = @reader.dependency_graph
-        dep_ids = graph.dependencies_of(unit_id)
+        dep_ids = graph.dependencies_of(unit_id, type: resolver.find(unit_id).fetch('type').to_sym)
         resolved_deps = []
 
         dep_ids.each do |dep_id|
-          dep_unit = @reader.find_unit(dep_id)
+          dep_unit = resolver.find(dep_id)
           next unless dep_unit
 
           resolved_deps << dep_id
@@ -173,7 +179,7 @@ module Woods
           seen_units.add(dep_id)
           context_pool[dep_id] = unit_summary(dep_unit)
 
-          expand_transitive(dep_id, seen_units, context_pool, dependency_map, remaining_depth - 1)
+          expand_transitive(dep_id, seen_units, context_pool, dependency_map, remaining_depth - 1, resolver)
         end
 
         dependency_map[unit_id] = resolved_deps if resolved_deps.any?

data/lib/woods/session_tracer/solid_cache_coordination.rb

@@ -157,11 +157,13 @@ module Woods
       end
 
       def inserted?(entry_class, result, key, payload)
-        affected_rows = result.affected_rows if result.respond_to?(:affected_rows)
-        return affected_rows.positive? unless affected_rows.nil?
-        return result.rows.any? if entry_class.connection.supports_insert_returning?
+        # MySQL's FOUND_ROWS can count a duplicate no-op as an affected row.
+        # The per-attempt CAS version makes equal values distinct payloads, so
+        # only our exact stored bytes establish ownership without RETURNING.
+        return entry_class.read(key) == payload unless entry_class.connection.supports_insert_returning?
 
-        entry_class.read(key) == payload
+        affected_rows = result.affected_rows if result.respond_to?(:affected_rows)
+        affected_rows.nil? ? result.rows.any? : affected_rows.positive?
       end
 
       def routed_read(key, failsafe)

data/lib/woods/session_tracer/unit_resolver.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Woods
+  module SessionTracer
+    # A bare dependency name cannot choose between published extraction types.
+    class AmbiguousUnitError < StandardError
+      attr_reader :identifier, :types
+
+      def initialize(identifier, types)
+        @identifier = identifier
+        @types = types.sort.freeze
+        super("Ambiguous session unit #{identifier.inspect}: published types #{@types.join(', ')}. " \
+              'No session context was returned. Use depth: 0 for the timeline, or inspect each type with lookup.')
+      end
+    end
+
+    # Per-assembly resolver. The caller pins its complete lifetime to one generation.
+    # Summary entries may omit type in legacy indexes; the containing bucket and
+    # validated unit body establish the concrete type without reading unrelated bodies.
+    class UnitResolver
+      def initialize(reader)
+        @reader = reader
+        @resolved = {}
+      end
+
+      def find(identifier)
+        return @resolved[identifier] if @resolved.key?(identifier)
+
+        units = candidate_types.fetch(identifier, []).filter_map do |type|
+          @reader.find_unit(identifier, type: type)
+        end
+        raise AmbiguousUnitError.new(identifier, units.map { |unit| unit.fetch('type') }) if units.size > 1
+
+        @resolved[identifier] = units.first
+      end
+
+      private
+
+      def entries_for(dir)
+        path = @reader.payload_dir.join(dir, '_index.json')
+        raise IOError, "symlink unit index: #{dir}" if path.symlink?
+
+        entries = @reader.list_units(type: MCP::IndexReader::DIR_TO_TYPE.fetch(dir))
+        expected = @reader.manifest.dig('counts', dir)
+        if expected.is_a?(Integer) && expected != entries.size
+          raise IOError, "unit count mismatch in #{dir}: expected #{expected}, found #{entries.size}"
+        end
+
+        entries
+      end
+
+      def candidate_types
+        @candidate_types ||= MCP::IndexReader::UNIT_TYPES_BY_DIR.each_with_object({}) do |(dir, types), candidates|
+          entries_for(dir).each do |entry|
+            identifier = entry.fetch('identifier')
+            candidates[identifier] ||= []
+            candidates[identifier] |= types
+          end
+        end
+      end
+    end
+  end
+end

data/lib/woods/source_inputs/consumer_errors.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Woods
+  module SourceInputs
+    # Error handlers can return the same nil/empty result as a successful
+    # negative match. Keep explicit evidence on the consumer instance instead
+    # of guessing from results or intercepting the application's logger.
+    module ConsumerErrors
+      FLAG = :@woods_source_consumer_failed
+
+      module_function
+
+      def record(consumer)
+        consumer.instance_variable_set(FLAG, true)
+      end
+
+      def reset(consumer)
+        consumer.instance_variable_set(FLAG, false)
+      end
+
+      def failed?(consumer)
+        consumer && consumer.instance_variable_get(FLAG) == true
+      end
+
+      def log(consumer, ...)
+        record(consumer)
+        Rails.logger.error(...)
+      end
+    end
+  end
+end

data/lib/woods/source_inputs/handoff.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'woods/source_inputs/manifest'
+
+module Woods
+  module SourceInputs
+    # Private one-process launch handoff. Its environment token names neither an
+    # existing index manifest nor a user-supplied proof of runtime freshness.
+    module Handoff
+      ENV_KEY = 'WOODS_SOURCE_CAPTURE'
+
+      module_function
+
+      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      # Every independent handoff binding must match before a token is consumed.
+      def read(root:, output_dir:, operation:, rules:, key_id:)
+        token = ENV.fetch(ENV_KEY, nil)
+        return nil if token.nil? || token.empty?
+
+        descriptor = JSON.parse(token)
+        return nil unless descriptor.is_a?(Hash)
+
+        data = private_data(descriptor.fetch('path'))
+        return nil unless data.is_a?(Hash)
+
+        expected = { 'version' => 1, 'nonce' => descriptor.fetch('nonce'),
+                     'root' => File.expand_path(root.to_s), 'output' => File.expand_path(output_dir.to_s),
+                     'operation' => operation.to_s, 'rules' => rules, 'launcher_pid' => Process.ppid }
+        return nil unless expected.all? { |key, value| data[key] == value }
+        return nil unless valid_nonce?(data['nonce'])
+
+        snapshot = data.fetch('snapshot')
+        return nil unless valid_snapshot?(snapshot, expected, key_id)
+
+        ENV.delete(ENV_KEY)
+        snapshot
+      rescue JSON::ParserError, KeyError, TypeError, SystemCallError, IOError
+        nil
+      end
+
+      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+      def private_data(path)
+        flags = File::RDONLY | File::NONBLOCK
+        flags |= File::NOFOLLOW if defined?(File::NOFOLLOW)
+        File.open(path, flags) do |file|
+          stat = file.stat
+          return nil unless stat.file? && stat.uid == Process.uid && stat.mode.nobits?(0o077)
+          return nil if stat.size > Manifest::MAX_BYTES
+
+          JSON.parse(file.read(Manifest::MAX_BYTES + 1))
+        end
+      end
+
+      def valid_nonce?(value)
+        value.is_a?(String) && value.match?(/\A[0-9a-f]{64}\z/)
+      end
+
+      def valid_snapshot?(snapshot, expected, key_id)
+        return false unless matching_snapshot?(snapshot, expected, key_id)
+
+        files = snapshot['files']
+        paths = snapshot['scope_paths']
+        return false unless valid_tables?(files, paths)
+
+        expanded = paths.transform_values { |list| list.to_h { |path| [path, files.fetch(path)] } }
+        Manifest.build(snapshot: snapshot, scopes: expanded, boot_verified: true, generation: 1)
+        true
+      rescue Manifest::Invalid, KeyError, TypeError
+        false
+      end
+
+      def matching_snapshot?(snapshot, expected, key_id)
+        snapshot.is_a?(Hash) && snapshot['root'] == expected['root'] &&
+          snapshot['rules'] == expected['rules'] && snapshot['key_id'] == key_id
+      end
+
+      # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      def valid_tables?(files, paths)
+        files.is_a?(Hash) && paths.is_a?(Hash) &&
+          files.all? { |path, digest| path.is_a?(String) && valid_nonce?(digest) } &&
+          paths.values.all? { |list| list.is_a?(Array) && list.all? { |path| files.key?(path) } }
+      end
+
+      # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+      def extra_roots
+        token = ENV.fetch(ENV_KEY, nil)
+        return [] if token.nil? || token.empty?
+
+        descriptor = JSON.parse(token)
+        return [] unless descriptor.is_a?(Hash)
+
+        roots = descriptor.fetch('extra_roots', [])
+        roots.is_a?(Array) ? roots : []
+      rescue JSON::ParserError, TypeError
+        []
+      end
+    end
+  end
+end

data/lib/woods/source_inputs/launcher.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require 'optparse'
+require 'tempfile'
+require 'base64'
+require 'securerandom'
+require 'woods/source_inputs/scanner'
+require 'woods/source_inputs/handoff'
+require 'woods/hooks/refresh'
+
+module Woods
+  module SourceInputs
+    # Captures before a fresh child evaluates Bundler, the Rakefile and Rails.
+    # The parent waits so all exit paths can remove the private handoff.
+    class Launcher # rubocop:disable Metrics/ClassLength -- parser and child lifetime form one CLI contract
+      OPERATIONS = %w[full incremental refresh].freeze
+
+      def self.run(argv, **options)
+        new(argv, **options).run
+      rescue OptionParser::ParseError, ArgumentError, PrivateKey::Unavailable, SystemCallError => e
+        warn "woods-extract: #{e.message}"
+        1
+      end
+
+      def initialize(argv, command: %w[bundle exec rake])
+        @arguments = argv.dup
+        @command = command
+        @original_directory = Dir.pwd
+        @root = @original_directory
+        @output = ENV.fetch('WOODS_OUTPUT', 'tmp/woods')
+        @extra_roots = []
+        parse!
+      end
+
+      def run # rubocop:disable Metrics/MethodLength -- handoff lifetime encloses the fresh child
+        return 0 if @help
+
+        operation, task = task_for_arguments
+        key = PrivateKey.new(output_dir: @output, create: true)
+        rules = Scopes.new(extra_roots: @extra_roots)
+        snapshot = Scanner.new(root: @root, output_dir: @output, key: key, scopes: rules).call
+        nonce = SecureRandom.hex(32)
+        Tempfile.create(['woods-source-capture-', '.json']) do |file|
+          file.binmode
+          file.chmod(0o600)
+          file.write(JSON.generate(version: 1, nonce: nonce, root: @root, output: @output,
+                                   operation: operation, rules: rules.fingerprint,
+                                   launcher_pid: Process.pid, snapshot: snapshot))
+          file.flush
+          file.fsync
+          descriptor = JSON.generate(path: file.path, nonce: nonce, extra_roots: @extra_roots)
+          environment = { Handoff::ENV_KEY => descriptor, 'WOODS_OUTPUT' => @output }
+          if ENV['BUNDLE_GEMFILE']
+            environment['BUNDLE_GEMFILE'] = File.expand_path(ENV.fetch('BUNDLE_GEMFILE'), @original_directory)
+          end
+          run_child(environment, task)
+        end
+      end
+
+      private
+
+      def parse!
+        parser.permute!(@arguments)
+        validate_arguments! unless @help
+      end
+
+      def parser
+        OptionParser.new do |options|
+          options.banner = 'Usage: woods-extract [options] full | incremental PATH... | refresh TYPE...'
+          options.on('--root PATH', 'Application root (default: current directory)') { |path| @root = path }
+          options.on('--output PATH', 'Index output (default: WOODS_OUTPUT or tmp/woods)') { |path| @output = path }
+          options.on('--source-root PATH', 'Additional application-relative runtime source root') do |path|
+            @extra_roots << path
+          end
+          options.on('-h', '--help', 'Show usage') do
+            puts options
+            @help = true
+          end
+        end
+      end
+
+      def validate_arguments!
+        @root = File.expand_path(@root)
+        raise ArgumentError, 'application root does not exist' unless File.directory?(@root)
+
+        @output = File.expand_path(@output, @root)
+        @operation = @arguments.shift
+        raise ArgumentError, 'choose full, incremental, or refresh' unless OPERATIONS.include?(@operation)
+        if @operation == 'full' && !@arguments.empty?
+          raise ArgumentError,
+                'full does not accept paths or extractor names'
+        end
+        if @operation != 'full' && @arguments.empty?
+          raise ArgumentError,
+                "#{@operation} requires paths or extractor names"
+        end
+
+        @extra_roots = Scopes.new(extra_roots: @extra_roots).extra_roots
+      end
+
+      def task_for_arguments
+        return ['full', 'woods:extract'] if @operation == 'full'
+        return refresh_task if @operation == 'refresh'
+
+        incremental_task
+      end
+
+      def incremental_task
+        paths = @arguments.map { |path| relative_path(path) }.uniq
+        action = InputRules.new
+        operation = paths.any? { |path| action.action(path) == :full } ? 'full' : 'incremental'
+        if paths.size > Hooks::Refresh::MAX_EVENTS
+          raise ArgumentError, 'too many incremental paths; split the input or run full'
+        end
+
+        batch = Base64.strict_encode64(JSON.generate(version: 1, output: @output,
+                                                     events: paths.map { |path| { path: path, operation: 'update' } }))
+        raise ArgumentError, 'incremental batch too large; split the input or run full' if batch.bytesize > 120_000
+
+        [operation, "woods:hook_refresh[#{batch}]"]
+      end
+
+      def refresh_task
+        names = @arguments.uniq
+        unless names.all? { |name| name.match?(/\A[a-z_]+\z/) && Extractor::EXTRACTORS.key?(name.to_sym) }
+          raise ArgumentError, 'refresh requires known extractor names'
+        end
+
+        ['refresh', "woods:refresh[#{names.join(',')}]"]
+      end
+
+      def relative_path(path)
+        absolute = File.expand_path(path, @root)
+        unless absolute.start_with?("#{@root}/") && !path.include?("\0")
+          raise ArgumentError, 'incremental paths must be inside the application root'
+        end
+
+        absolute.delete_prefix("#{@root}/")
+      end
+
+      def run_child(environment, task)
+        pid = Process.spawn(environment, *@command, task, chdir: @root, pgroup: true)
+        previous = %w[INT TERM].to_h do |signal|
+          [signal, Signal.trap(signal) do
+            Process.kill(signal, -pid)
+          rescue StandardError
+            nil
+          end]
+        end
+        _finished, status = Process.wait2(pid)
+        status.exitstatus || (128 + status.termsig)
+      ensure
+        previous&.each { |signal, handler| Signal.trap(signal, handler) }
+      end
+    end
+  end
+end