fiber_audit 0.2.1 → 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/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

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

@@ -9,17 +9,90 @@ require_relative '../../operation_vocabulary'
 module FiberAudit
   module Static
     module Rules
+      # FA1001: Subprocess lifecycle operations that may interfere with
+      # the fiber scheduler. Detects subprocess creation, replacement,
+      # waiting, detachment, and stream lifecycle operations.
+      #
+      # Operations are classified into semantic categories:
+      # - creation: spawning a new process (info)
+      # - replacement: replacing the current process via exec (info)
+      # - waiting: blocking waits for subprocess completion (medium)
+      # - detach: detaching a subprocess without waiting (info)
+      # - stream: subprocess pipe/stream lifecycle via IO.popen (medium)
+      #
+      # Severity: info for creation/replacement/detach, medium for waits/stream.
+      # These are scheduler-cooperation requirements, so execution context does
+      # not by itself escalate them to critical.
       class BlockingSubprocess < Base
         id 'FA1001'
-        severity :high
+        severity :medium
         default_confidence :high
-        description 'Blocking subprocess call in the fiber scheduler path'
+        description 'Subprocess lifecycle operations may interfere with the fiber scheduler'
 
         TARGETS = OperationVocabulary::FA1001_TARGETS
         BARE_KERNEL_METHODS = OperationVocabulary::FA1001_KERNEL_METHODS
 
-        MESSAGE = 'Subprocess operation may block the thread running the fiber scheduler.'
-        REMEDIATION = 'Move long-running subprocess work outside the request path, or verify scheduler behaviour under load.'
+        # Per-operation semantic category
+        OPERATION_CATEGORY = {
+          # Creation (info) - spawning a new process
+          'Kernel.spawn' => :creation,
+          'Process.spawn' => :creation,
+          # Replacement (info) - replacing current process via exec
+          'Kernel.exec' => :replacement,
+          'Process.exec' => :replacement,
+          # Waiting (medium) - blocking waits for subprocess completion
+          'Kernel.system' => :waiting,
+          'Process.wait' => :waiting,
+          'Process.wait2' => :waiting,
+          'Process.waitpid' => :waiting,
+          'Process.waitpid2' => :waiting,
+          'Process.waitall' => :waiting,
+          'Process::Status.wait' => :waiting,
+          'Open3.capture2' => :waiting,
+          'Open3.capture2e' => :waiting,
+          'Open3.capture3' => :waiting,
+          'Open3.pipeline' => :waiting,
+          # Detach (info) - detaching subprocess without waiting
+          'Process.detach' => :detach,
+          # Stream (medium) - subprocess pipe/stream lifecycle
+          'IO.popen' => :stream
+        }.freeze
+
+        # Per-category metadata
+        CATEGORY_METADATA = {
+          creation: {
+            severity: :info,
+            title: 'Subprocess creation',
+            message: 'Spawning a subprocess may leave background processes that outlive the fiber scheduler session.',
+            remediation: 'Track spawned processes or move subprocess creation outside the fiber-scheduled path.'
+          },
+          replacement: {
+            severity: :info,
+            title: 'Process replacement',
+            message: 'Process replacement via exec replaces the current process image, terminating the fiber scheduler.',
+            remediation: 'Avoid exec in fiber-scheduled code; prefer subprocess creation with explicit lifecycle management.'
+          },
+          waiting: {
+            severity: :medium,
+            title: 'Subprocess wait',
+            message: 'Subprocess waiting requires scheduler process-wait cooperation in a non-blocking Fiber.',
+            remediation: 'Verify scheduler process_wait support and runtime progress, ' \
+                         'or move waits outside the fiber-scheduled path.'
+          },
+          detach: {
+            severity: :info,
+            title: 'Subprocess detach',
+            message: 'Detaching a subprocess may leave it unmanaged by the fiber scheduler.',
+            remediation: 'Avoid detaching subprocesses in fiber-scheduled code; use explicit lifecycle management.'
+          },
+          stream: {
+            severity: :medium,
+            title: 'Subprocess pipe stream',
+            message: 'Subprocess pipe I/O requires scheduler cooperation while the stream is open.',
+            remediation: 'Verify scheduler-aware I/O and runtime progress on the pipe, ' \
+                         'or move pipe operations outside the fiber-scheduled path.'
+          }
+        }.freeze
 
         def analyze(call_sites:)
           call_sites.filter_map do |site|
@@ -60,11 +133,14 @@ module FiberAudit
         def build_finding(site, match)
           operation = "#{match[:constant]}.#{match[:method]}"
           context = site.execution_context || :unknown
-          sev = severity_for(self.class.severity, context)
+          category = OPERATION_CATEGORY.fetch(operation, :waiting)
+          metadata = CATEGORY_METADATA.fetch(category)
+          base_severity = metadata[:severity]
+          sev = advisory_severity(base_severity)
 
           Finding.new(
             rule_id: self.class.id,
-            title: 'Blocking subprocess call',
+            title: metadata[:title],
             category: :subprocess,
             severity: sev,
             confidence: match[:confidence],
@@ -72,15 +148,19 @@ module FiberAudit
             symbol: site.enclosing_symbol,
             operation: operation,
             execution_context: context,
-            message: MESSAGE,
+            message: metadata[:message],
             evidence: [
               Evidence.new(
                 source: :static,
-                message: "Matched #{operation}",
-                details: { receiver: match[:constant], method: match[:method] }
+                message: "Matched #{operation} (#{category})",
+                details: {
+                  receiver: match[:constant],
+                  method: match[:method],
+                  semantic: category
+                }
               )
             ],
-            remediation: REMEDIATION
+            remediation: metadata[:remediation]
           )
         end
       end