fiber_audit 0.2.0 → 0.3.0

data/lib/fiber_audit/runtime/probes/subprocess.rb

@@ -6,15 +6,25 @@ module FiberAudit
       module Subprocess
         module KernelInstanceHook
           def system(...)
-            Registry.observe(operation: 'Kernel.system') { super }
+            Registry.observe(
+              operation: 'Kernel.system',
+              measurements: { waits_for_child: true }
+            ) { super }
           end
 
           def exec(...)
-            Registry.observe(operation: 'Kernel.exec', emit_start: true) { super }
+            Registry.observe(
+              operation: 'Kernel.exec',
+              measurements: { replaces_process: true },
+              emit_start: true
+            ) { super }
           end
 
           def spawn(...)
-            Registry.observe(operation: 'Kernel.spawn') { super }
+            Registry.observe(
+              operation: 'Kernel.spawn',
+              measurements: { returns_pid: true, does_not_wait: true }
+            ) { super }
           end
 
           private :system, :exec, :spawn
@@ -22,15 +32,25 @@ module FiberAudit
 
         module KernelSingletonHook
           def system(...)
-            Registry.observe(operation: 'Kernel.system') { super }
+            Registry.observe(
+              operation: 'Kernel.system',
+              measurements: { waits_for_child: true }
+            ) { super }
           end
 
           def exec(...)
-            Registry.observe(operation: 'Kernel.exec', emit_start: true) { super }
+            Registry.observe(
+              operation: 'Kernel.exec',
+              measurements: { replaces_process: true },
+              emit_start: true
+            ) { super }
           end
 
           def spawn(...)
-            Registry.observe(operation: 'Kernel.spawn') { super }
+            Registry.observe(
+              operation: 'Kernel.spawn',
+              measurements: { returns_pid: true, does_not_wait: true }
+            ) { super }
           end
         end
 
@@ -41,12 +61,70 @@ module FiberAudit
         end
 
         module ProcessHook
+          def spawn(...)
+            Registry.observe(
+              operation: 'Process.spawn',
+              measurements: { returns_pid: true, does_not_wait: true }
+            ) { super }
+          end
+
+          def exec(...)
+            Registry.observe(
+              operation: 'Process.exec',
+              measurements: { replaces_process: true },
+              emit_start: true
+            ) { super }
+          end
+
+          def wait(...)
+            Registry.observe(
+              operation: 'Process.wait',
+              measurements: { waits_for_child: true }
+            ) { super }
+          end
+
+          def wait2(...)
+            Registry.observe(
+              operation: 'Process.wait2',
+              measurements: { waits_for_child: true }
+            ) { super }
+          end
+
+          def waitpid(...)
+            Registry.observe(
+              operation: 'Process.waitpid',
+              measurements: { waits_for_child: true }
+            ) { super }
+          end
+
+          def waitpid2(...)
+            Registry.observe(
+              operation: 'Process.waitpid2',
+              measurements: { waits_for_child: true }
+            ) { super }
+          end
+
           def waitall(...)
-            Registry.observe(operation: 'Process.waitall') { super }
+            Registry.observe(
+              operation: 'Process.waitall',
+              measurements: { waits_for_child: true }
+            ) { super }
           end
 
           def detach(...)
-            Registry.observe(operation: 'Process.detach') { super }
+            Registry.observe(
+              operation: 'Process.detach',
+              measurements: { returns_thread: true, does_not_wait: true }
+            ) { super }
+          end
+        end
+
+        module ProcessStatusHook
+          def wait(...)
+            Registry.observe(
+              operation: 'Process::Status.wait',
+              measurements: { waits_for_child: true }
+            ) { super }
           end
         end
 
@@ -75,6 +153,9 @@ module FiberAudit
           registry.prepend_once(Kernel.singleton_class, KernelSingletonHook)
           registry.prepend_once(IO.singleton_class, IOHook)
           registry.prepend_once(Process.singleton_class, ProcessHook)
+          if defined?(Process::Status) && Process::Status.respond_to?(:wait)
+            registry.prepend_once(Process::Status.singleton_class, ProcessStatusHook)
+          end
           registry.prepend_once(Open3.singleton_class, Open3Hook) if defined?(Open3)
         end
       end

data/lib/fiber_audit/runtime/probes/thread_state.rb

@@ -12,20 +12,6 @@ module FiberAudit
           def thread_variable_set(...)
             Registry.observe(operation: 'Thread.thread_variable_set') { super }
           end
-
-          def [](...)
-            return super unless equal?(Thread.current)
-
-            Registry.observe(operation: 'Thread.current.[]') { super }
-          end
-
-          def []=(...)
-            if equal?(Thread.current)
-              Registry.observe(operation: 'Thread.current.[]=') { super }
-            else
-              super
-            end
-          end
         end
 
         module_function

data/lib/fiber_audit/runtime/rails_integration.rb

@@ -125,6 +125,15 @@ module FiberAudit
       def install_require_hook
         return if @require_hook_installed
 
+        # Zeitwerk replaces Kernel#require. Load its optional integration before
+        # prepending FiberAudit so later Rails autoloads retain Zeitwerk's require
+        # semantics. This remains a no-op when Zeitwerk is not installed.
+        begin
+          require 'zeitwerk'
+        rescue LoadError
+          nil
+        end
+
         # Install narrow guarded require hook for late Rails loading
         # Independent of probe registry
         ::Kernel.prepend(RequireHook) unless ::Kernel.ancestors.include?(RequireHook)
@@ -132,33 +141,57 @@ module FiberAudit
       end
 
       def install_controller_hook
-        return unless defined?(::ActionController::Metal)
+        namespace = loaded_constant(Object, :ActionController)
+        target = loaded_constant(namespace, :Metal)
+        return unless target
 
-        ::ActionController::Metal.prepend(ControllerHook) unless ::ActionController::Metal.ancestors.include?(ControllerHook)
+        target.prepend(ControllerHook) unless target.ancestors.include?(ControllerHook)
       end
 
       def install_job_hook
-        return unless defined?(::ActiveJob::Base)
+        namespace = loaded_constant(Object, :ActiveJob)
+        target = loaded_constant(namespace, :Base)
+        return unless target
 
-        ::ActiveJob::Base.prepend(JobHook) unless ::ActiveJob::Base.ancestors.include?(JobHook)
+        target.prepend(JobHook) unless target.ancestors.include?(JobHook)
       end
 
       def install_cable_hook
-        return unless defined?(::ActionCable::Channel::Base)
+        namespace = loaded_constant(Object, :ActionCable)
+        channel = loaded_constant(namespace, :Channel)
+        target = loaded_constant(channel, :Base)
+        return unless target
+
+        target.prepend(CableHook) unless target.ancestors.include?(CableHook)
+      end
+
+      def loaded_constant(namespace, name)
+        return unless namespace.is_a?(Module)
+        return if namespace.autoload?(name)
+        return unless namespace.const_defined?(name, false)
 
-        ::ActionCable::Channel::Base.prepend(CableHook) unless ::ActionCable::Channel::Base.ancestors.include?(CableHook)
+        namespace.const_get(name, false)
+      rescue NameError
+        nil
       end
 
       def try_install_middleware_hook
-        return unless defined?(::Rails) && ::Rails.respond_to?(:application) && ::Rails.application
+        rails = loaded_constant(Object, :Rails)
+        return unless rails
 
-        stack = ::Rails.application.config.middleware
-        return if @middleware_stack.equal?(stack)
+        # Rails.application may instantiate the application class. Calling it
+        # from a require hook while Rails itself is loading can re-enter a
+        # partially initialized application, so only inspect an existing instance.
+        application = rails.instance_variable_get(:@application)
+        return unless application
+
+        stack = application.config.middleware
+        return if @middleware_stack.equal?(stack) || middleware_installed_in?(stack)
 
         # Try to insert middleware into Rails stack. A replacement stack (for
         # example after a Rails reload) is eligible for installation again.
         begin
-          stack.use(Middleware)
+          stack.insert_before(0, Middleware)
           @middleware_stack = stack
         rescue StandardError => e
           # Stack may be finalized - that's okay, middleware is optional
@@ -166,6 +199,14 @@ module FiberAudit
         end
       end
 
+      def middleware_installed_in?(stack)
+        return false unless stack.respond_to?(:any?)
+
+        stack.any? do |entry|
+          entry.equal?(Middleware) || (entry.respond_to?(:klass) && entry.klass.equal?(Middleware))
+        end
+      end
+
       # Require hook for late Rails loading - independent of probe registry
       # Narrow, guarded, behavior-preserving
       module RequireHook

data/lib/fiber_audit/runtime/scheduler_observer.rb

@@ -10,14 +10,14 @@ module FiberAudit
         # Ruby's scheduler API fixes this writer-like method name.
         # rubocop:disable Naming/AccessorMethodName
         def set_scheduler(scheduler)
-          FiberAudit::Runtime::SchedulerObserver.scheduler_replacing(thread: Thread.current) if Fiber.scheduler
+          previous = Fiber.scheduler
           result = super
-          if scheduler
-            FiberAudit::Runtime::SchedulerObserver.scheduler_installed(
-              scheduler: scheduler,
-              thread: Thread.current
-            )
-          end
+          current = Fiber.scheduler
+          FiberAudit::Runtime::SchedulerObserver.scheduler_changed(
+            previous: previous,
+            current: current,
+            thread: Thread.current
+          )
           result
         end
         # rubocop:enable Naming/AccessorMethodName
@@ -25,7 +25,10 @@ module FiberAudit
 
       module SchedulerCloseHook
         def close(...)
-          FiberAudit::Runtime::SchedulerObserver.scheduler_closing(thread: Thread.current)
+          FiberAudit::Runtime::SchedulerObserver.scheduler_closing(
+            scheduler: self,
+            thread: Thread.current
+          )
           super
         end
       end
@@ -41,19 +44,15 @@ module FiberAudit
           observer
         end
 
-        def scheduler_replacing(thread:)
-          current_for_process&.scheduler_closing(thread: thread)
-        end
-
-        def scheduler_installed(scheduler:, thread:)
+        def scheduler_changed(previous:, current:, thread:)
           observer = current_for_process
           return unless observer
 
-          observer.scheduler_installed(scheduler: scheduler, thread: thread)
+          observer.scheduler_changed(previous: previous, current: current, thread: thread)
         end
 
-        def scheduler_closing(thread:)
-          current_for_process&.scheduler_closing(thread: thread)
+        def scheduler_closing(thread:, scheduler: nil)
+          current_for_process&.scheduler_closing(scheduler: scheduler, thread: thread)
         end
 
         def deactivate(observer)
@@ -82,6 +81,8 @@ module FiberAudit
         @watchdog = watchdog
         @owner_pid = Process.pid
         @active = true
+        @mutex = Mutex.new
+        @schedulers = {}
       end
 
       def active_for_current_process?
@@ -94,8 +95,17 @@ module FiberAudit
         self
       end
 
+      def scheduler_changed(previous:, current:, thread:)
+        return self unless active_for_current_process?
+
+        scheduler_closing(scheduler: previous, thread: thread) if previous && !previous.equal?(current)
+        scheduler_installed(scheduler: current, thread: thread) if current
+        self
+      end
+
       def scheduler_installed(scheduler:, thread:)
         return self unless active_for_current_process? && watchdog.enabled?
+        return self unless track_scheduler(scheduler, thread)
 
         install_close_hook!(scheduler)
         watchdog.scheduler_installed(thread: thread)
@@ -107,13 +117,17 @@ module FiberAudit
         self
       end
 
-      def scheduler_closing(thread:)
-        watchdog.scheduler_closing(thread: thread) if active_for_current_process?
+      def scheduler_closing(thread:, scheduler: nil)
+        return self unless active_for_current_process?
+        return self unless untrack_scheduler(scheduler, thread)
+
+        watchdog.scheduler_closing(thread: thread)
         self
       end
 
       def deactivate
         @active = false
+        @mutex.synchronize { @schedulers.clear }
         self
       end
 
@@ -123,6 +137,28 @@ module FiberAudit
         singleton = scheduler.singleton_class
         singleton.prepend(SchedulerCloseHook) unless singleton.ancestors.include?(SchedulerCloseHook)
       end
+
+      def track_scheduler(scheduler, thread)
+        @mutex.synchronize do
+          key = thread.object_id
+          return false if @schedulers[key].equal?(scheduler)
+
+          @schedulers[key] = scheduler
+          true
+        end
+      end
+
+      def untrack_scheduler(scheduler, thread)
+        @mutex.synchronize do
+          key = thread.object_id
+          tracked = @schedulers[key]
+          return false unless tracked
+          return false if scheduler && !tracked.equal?(scheduler)
+
+          @schedulers.delete(key)
+          true
+        end
+      end
     end
   end
 end

data/lib/fiber_audit/runtime/scheduler_snapshot.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module FiberAudit
+  module Runtime
+    # Immutable scheduler snapshot/context fields captured at operation start.
+    # All fields are Boolean or nil only, as per JSONL 1.0 schema requirements.
+    SchedulerSnapshot = Data.define(
+      :scheduler_present,
+      :fiber_blocking,
+      :scheduler_io_select_supported,
+      :scheduler_process_wait_supported,
+      :scheduler_address_resolve_supported
+    ) do
+      def initialize(
+        scheduler_present:,
+        fiber_blocking:,
+        scheduler_io_select_supported: nil,
+        scheduler_process_wait_supported: nil,
+        scheduler_address_resolve_supported: nil
+      )
+        super(
+          scheduler_present: normalize_boolean(scheduler_present, 'scheduler_present'),
+          fiber_blocking: normalize_boolean(fiber_blocking, 'fiber_blocking'),
+          scheduler_io_select_supported: normalize_optional_boolean(
+            scheduler_io_select_supported,
+            'scheduler_io_select_supported'
+          ),
+          scheduler_process_wait_supported: normalize_optional_boolean(
+            scheduler_process_wait_supported,
+            'scheduler_process_wait_supported'
+          ),
+          scheduler_address_resolve_supported: normalize_optional_boolean(
+            scheduler_address_resolve_supported,
+            'scheduler_address_resolve_supported'
+          )
+        )
+      end
+
+      def to_measurements
+        {
+          scheduler_present: scheduler_present,
+          fiber_blocking: fiber_blocking,
+          scheduler_io_select_supported: scheduler_io_select_supported,
+          scheduler_process_wait_supported: scheduler_process_wait_supported,
+          scheduler_address_resolve_supported: scheduler_address_resolve_supported
+        }.freeze
+      end
+
+      private
+
+      def normalize_boolean(value, field)
+        raise RuntimeContractError, "#{field} must be a Boolean" unless [true, false].include?(value)
+
+        value
+      end
+
+      def normalize_optional_boolean(value, field)
+        return value if value.nil?
+        raise RuntimeContractError, "#{field} must be a Boolean or nil" unless [true, false].include?(value)
+
+        value
+      end
+    end
+
+    # Captures immutable scheduler snapshot at the current point in time.
+    # This is called at operation start to provide immutable context.
+    module SchedulerSnapshotCapture
+      module_function
+
+      def capture
+        scheduler = Fiber.scheduler
+        scheduler_present = !scheduler.nil?
+
+        # Normalize Fiber#blocking? to Boolean
+        fiber_blocking = begin
+          current_fiber = Fiber.current
+          if current_fiber.respond_to?(:blocking?)
+            !current_fiber.blocking?.nil?
+          else
+            false
+          end
+        rescue StandardError
+          false
+        end
+
+        # Query scheduler capabilities if present
+        io_select_supported = nil
+        process_wait_supported = nil
+        address_resolve_supported = nil
+
+        if scheduler_present
+          io_select_supported = scheduler.respond_to?(:io_select)
+          process_wait_supported = scheduler.respond_to?(:process_wait)
+          address_resolve_supported = scheduler.respond_to?(:address_resolve)
+        end
+
+        SchedulerSnapshot.new(
+          scheduler_present: scheduler_present,
+          fiber_blocking: fiber_blocking,
+          scheduler_io_select_supported: io_select_supported,
+          scheduler_process_wait_supported: process_wait_supported,
+          scheduler_address_resolve_supported: address_resolve_supported
+        )
+      rescue StandardError
+        # Fail open: return a safe default snapshot
+        SchedulerSnapshot.new(
+          scheduler_present: false,
+          fiber_blocking: false
+        )
+      end
+    end
+  end
+end

data/lib/fiber_audit/runtime/watchdog.rb

@@ -15,6 +15,7 @@ module FiberAudit
     class Watchdog
       SOURCE = :scheduler_watchdog
       STOP_TIMEOUT_SECONDS = 1
+      MAX_OVERLAP_EVENTS = 10
 
       Stall = Data.define(:sequence, :progress_sequence, :began_monotonic_ns)
       Channel = Struct.new(:thread, :heartbeat, :active, :unsupported, :stall, keyword_init: true)
@@ -296,6 +297,45 @@ module FiberAudit
             measurements: { stall_sequence: @stall_sequence, frame_index: index }
           )
         end
+        emit_stall_operation_overlap_events(operations, now_ns, snapshot)
+      end
+
+      def emit_stall_operation_overlap_events(operations, now_ns, _snapshot)
+        return if operations.empty?
+
+        truncated = operations.size > MAX_OVERLAP_EVENTS
+        bounded_operations = operations.first(MAX_OVERLAP_EVENTS)
+
+        bounded_operations.each do |entry|
+          overlap_measurements = build_overlap_measurements(entry, truncated, operations.size)
+          emit_event(
+            kind: :scheduler_stall_operation_overlap,
+            monotonic_ns: now_ns,
+            operation: entry.operation,
+            location: entry.location,
+            execution_context: entry.execution_context,
+            thread_id: entry.thread_id,
+            fiber_id: entry.fiber_id,
+            measurements: overlap_measurements
+          )
+        end
+      rescue StandardError => e
+        account_internal_error unless recorder.disabled?
+        raise e unless fail_open?
+      end
+
+      def build_overlap_measurements(entry, truncated, total_count)
+        measurements = {
+          stall_sequence: @stall_sequence,
+          operation_sequence: entry.sequence,
+          operation_started_monotonic_ns: entry.started_monotonic_ns,
+          overlap_truncated: truncated,
+          overlap_total_count: total_count
+        }
+
+        measurements.merge!(entry.scheduler_snapshot.to_measurements) if entry.scheduler_snapshot
+
+        measurements
       end
 
       def complete_stall(channel, now_ns:, resumed:)
@@ -358,7 +398,8 @@ module FiberAudit
         )
       end
 
-      def emit_event(kind:, monotonic_ns:, duration_ns: nil, location: nil, thread_id: nil, fiber_id: nil, measurements: {})
+      def emit_event(kind:, monotonic_ns:, duration_ns: nil, location: nil, thread_id: nil, fiber_id: nil, operation: nil,
+                     execution_context: :unknown, measurements: {})
         recorder.record_control do
           Event.new(
             kind: kind,
@@ -366,8 +407,9 @@ module FiberAudit
             occurred_at: @clock.wall_time,
             monotonic_ns: monotonic_ns,
             duration_ns: duration_ns,
+            operation: operation,
             location: location,
-            execution_context: :unknown,
+            execution_context: execution_context,
             thread_id: thread_id,
             fiber_id: fiber_id,
             measurements: measurements

data/lib/fiber_audit/runtime.rb

@@ -22,6 +22,7 @@ require_relative 'runtime/rails_integration'
 require_relative 'runtime/environment'
 require_relative 'runtime/active_operations'
 require_relative 'runtime/heartbeat'
+require_relative 'runtime/scheduler_snapshot'
 require_relative 'runtime/watchdog'
 require_relative 'runtime/scheduler_observer'
 require_relative 'runtime/probes/base'

data/lib/fiber_audit/static/call_site_extractor.rb

@@ -20,6 +20,7 @@ module FiberAudit
         Open3
         IO
         Process
+        Process::Status
         Thread
         Mutex
         ConditionVariable

data/lib/fiber_audit/static/rules/base.rb

@@ -179,6 +179,25 @@ module FiberAudit
         def severity_index(severity)
           Severity.index(severity)
         end
+
+        # Compute the advisory severity for a finding without applying
+        # the context ceiling. Advisory rules (FA1002, FA1003, FA1005,
+        # FA1006, FA1007) use this to respect configuration overrides
+        # but not escalate based on execution context.
+        #
+        # Resolution order:
+        #   1. configuration.severity_override(rule_id) replaces the default
+        #   2. No context ceiling is applied
+        #
+        # @param default_sev [Symbol, String] rule's default severity
+        # @return [Symbol] the resolved severity
+        def advisory_severity(default_sev)
+          # Normalize String to Symbol defensively
+          default_sev = default_sev.to_sym if default_sev.is_a?(String)
+
+          # Configuration override replaces default entirely, no ceiling
+          configuration.severity_override(self.class.id) || default_sev
+        end
       end
     end
   end