fiber_audit 0.2.1 → 0.3.1

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_evidence_classifier.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative '../operation_semantics'
+require_relative 'scheduler_snapshot'
+
+module FiberAudit
+  module Runtime
+    module SchedulerEvidenceClassifier
+      module_function
+
+      def measurements(operation:, scheduler_snapshot:)
+        unless scheduler_snapshot.nil? || scheduler_snapshot.is_a?(SchedulerSnapshot)
+          raise RuntimeContractError, 'scheduler_snapshot must be a SchedulerSnapshot or nil'
+        end
+
+        profile = OperationSemantics.resolve_runtime_operation(operation)
+        capability_supported = capability_supported(profile.scheduler_capability, scheduler_snapshot)
+        {
+          operation_wait_possible: profile.wait_possible,
+          operation_inventory_only: profile.inventory_only,
+          operation_scheduler_capability_required: profile.known? ? profile.scheduler_capability_required? : nil,
+          operation_scheduler_capability_supported: capability_supported,
+          operation_scheduler_cooperation_available: cooperation_available(
+            profile,
+            scheduler_snapshot,
+            capability_supported
+          )
+        }.freeze
+      end
+
+      def capability_supported(capability, snapshot)
+        return nil if capability.nil? || snapshot.nil?
+
+        case capability
+        when :block, :kernel_sleep
+          snapshot.scheduler_present
+        when :io_select
+          snapshot.scheduler_io_select_supported
+        when :process_wait
+          snapshot.scheduler_process_wait_supported
+        when :address_resolve
+          snapshot.scheduler_address_resolve_supported
+        end
+      end
+      private_class_method :capability_supported
+
+      def cooperation_available(profile, snapshot, capability_supported)
+        return nil unless profile.wait_possible == true
+        return nil if snapshot.nil? || snapshot.scheduler_present.nil?
+        return false unless snapshot.scheduler_present
+        return nil if snapshot.fiber_blocking.nil?
+        return false if snapshot.fiber_blocking
+        return nil unless profile.scheduler_capability_required?
+
+        capability_supported
+      end
+      private_class_method :cooperation_available
+    end
+  end
+end

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,95 @@
+# 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_optional_boolean(scheduler_present, 'scheduler_present'),
+          fiber_blocking: normalize_optional_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_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?
+
+        current_fiber = Fiber.current
+        fiber_blocking = current_fiber.respond_to?(:blocking?) ? current_fiber.blocking? : nil
+
+        # 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 without inventing scheduler or Fiber state.
+        SchedulerSnapshot.new(scheduler_present: nil, fiber_blocking: nil)
+      end
+    end
+  end
+end

data/lib/fiber_audit/runtime/watchdog.rb

@@ -6,6 +6,7 @@ require_relative 'event'
 require_relative 'heartbeat'
 require_relative 'recorder'
 require_relative 'redactor'
+require_relative 'scheduler_evidence_classifier'
 require_relative 'watchdog_policy'
 
 module FiberAudit
@@ -15,6 +16,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)
@@ -259,6 +261,7 @@ module FiberAudit
         start_stall(channel, snapshot, age_ns, now_ns) if policy.stalled?(age_ns: age_ns)
       end
 
+      # rubocop:disable Metrics/AbcSize
       def start_stall(channel, snapshot, age_ns, now_ns)
         @stall_sequence += 1
         channel.stall = Stall.new(
@@ -266,7 +269,8 @@ module FiberAudit
           progress_sequence: snapshot.sequence,
           began_monotonic_ns: snapshot.last_progress_ns
         )
-        operations = active_operations.snapshot(thread_id: snapshot.thread_id)
+        operation_snapshot = active_operations.snapshot_with_metadata(thread_id: snapshot.thread_id)
+        operations = operation_snapshot.entries
         frames = safe_frames(channel.thread)
         measurements = {
           stall_sequence: @stall_sequence,
@@ -275,7 +279,8 @@ module FiberAudit
           stall_threshold_ns: policy.stall_threshold_ns,
           heartbeat_interval_ns: policy.heartbeat_interval_ns,
           frame_count: frames.size,
-          active_operation_count: operations.size,
+          active_operation_count: operation_snapshot.total_count,
+          active_operation_snapshot_truncated: operation_snapshot.truncated?,
           active_operation_first_sequence: operations.first&.sequence,
           active_operation_last_sequence: operations.last&.sequence
         }
@@ -296,6 +301,49 @@ module FiberAudit
             measurements: { stall_sequence: @stall_sequence, frame_index: index }
           )
         end
+        emit_stall_operation_overlap_events(operations, operation_snapshot.total_count, now_ns)
+      end
+      # rubocop:enable Metrics/AbcSize
+
+      def emit_stall_operation_overlap_events(operations, total_count, now_ns)
+        return if operations.empty?
+
+        bounded_operations = operations.first(MAX_OVERLAP_EVENTS)
+        truncated = total_count > bounded_operations.size
+        bounded_operations.each do |entry|
+          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: build_overlap_measurements(entry, truncated, total_count)
+          )
+        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.merge!(
+          SchedulerEvidenceClassifier.measurements(
+            operation: entry.operation,
+            scheduler_snapshot: entry.scheduler_snapshot
+          )
+        )
+        measurements
       end
 
       def complete_stall(channel, now_ns:, resumed:)
@@ -358,7 +406,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 +415,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

@@ -3,10 +3,12 @@
 require_relative 'version'
 require_relative 'errors'
 require_relative 'operation_vocabulary'
+require_relative 'operation_semantics'
 require_relative 'execution_context'
 require_relative 'runtime/validation'
 require_relative 'runtime/policy'
 require_relative 'runtime/watchdog_policy'
+require_relative 'runtime/operation_liveness_policy'
 require_relative 'runtime/location'
 require_relative 'runtime/event'
 require_relative 'runtime/session'
@@ -22,7 +24,10 @@ 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/scheduler_evidence_classifier'
 require_relative 'runtime/watchdog'
+require_relative 'runtime/operation_liveness_monitor'
 require_relative 'runtime/scheduler_observer'
 require_relative 'runtime/probes/base'
 require_relative 'runtime/probes/subprocess'

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