fiber_audit 0.2.0 → 0.3.0

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

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

@@ -9,23 +9,22 @@ require_relative '../../operation_vocabulary'
 module FiberAudit
   module Static
     module Rules
-      # FA1006 – Detects direct socket creation that may bypass
-      # scheduler-aware networking and block the scheduler thread.
+      # FA1006 – Detects direct socket construction whose DNS, connection, and
+      # later I/O require scheduler cooperation. Advisory rule with :low default.
       class DirectSocket < Base
         id 'FA1006'
-        severity :medium
+        severity :low
         default_confidence :high
-        description 'Detects direct socket creation that may bypass scheduler-aware networking.'
+        description 'Direct socket paths require scheduler-aware DNS and I/O cooperation.'
 
         TITLE    = 'Direct socket creation'
         CATEGORY = :network
 
         EXACT = OperationVocabulary::FA1006_EXACT
 
-        MESSAGE = 'Direct socket use may bypass scheduler-aware networking ' \
-                  'and block the scheduler thread.'
-        REMEDIATION = 'Use scheduler-aware networking APIs or verify the ' \
-                      'socket operations cooperate with the active Fiber scheduler.'
+        MESSAGE = 'This socket path may require scheduler cooperation for DNS, connection, or subsequent I/O.'
+        REMEDIATION = 'Distinguish allocation from DNS/connect/I/O, then verify ' \
+                      'the active scheduler hooks and runtime progress.'
 
         class << self
           def title = TITLE
@@ -88,7 +87,7 @@ module FiberAudit
             rule_id: self.class.id,
             title: self.class.title,
             category: self.class.category,
-            severity: severity_for(:medium, ctx),
+            severity: advisory_severity(:low),
             confidence: site.confidence,
             location: site.location,
             symbol: site.enclosing_symbol,

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

@@ -9,19 +9,19 @@ require_relative '../../operation_vocabulary'
 module FiberAudit
   module Static
     module Rules
-      # FA1005: Detects explicit IO.select calls that may bypass
-      # scheduler-aware I/O and block the scheduler thread.
+      # FA1005: Detects explicit IO.select scheduler-capability requirements.
+      # Advisory rule with :medium default.
       class IOSelect < Base
         id 'FA1005'
         severity :medium
         default_confidence :high
-        description 'Explicit IO.select call that may bypass scheduler-aware I/O'
+        description 'Explicit IO.select requires scheduler io_select cooperation'
 
         TITLE    = 'Explicit IO.select call'
         CATEGORY = :blocking_io
 
-        MESSAGE = 'IO.select may bypass scheduler-aware I/O and block the thread running the fiber scheduler.'
-        REMEDIATION = 'Use scheduler-aware I/O APIs or allow the active Fiber scheduler to manage readiness.'
+        MESSAGE = 'IO.select requires scheduler io_select support when used from a non-blocking Fiber.'
+        REMEDIATION = 'Verify the selected scheduler implements io_select and confirm runtime progress under load.'
 
         TARGETS = OperationVocabulary::FA1005_TARGETS
 
@@ -79,7 +79,7 @@ module FiberAudit
             rule_id: self.class.id,
             title: TITLE,
             category: CATEGORY,
-            severity: severity_for(:medium, context),
+            severity: advisory_severity(:medium),
             confidence: confidence,
             location: site.location,
             symbol: site.enclosing_symbol,

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

@@ -9,19 +9,22 @@ require_relative '../../operation_vocabulary'
 module FiberAudit
   module Static
     module Rules
-      # FA1007: Detects blocking HTTP calls in request-like contexts.
+      # FA1007: Detects HTTP scheduler-cooperation requirements in request-like contexts.
       # Targets Net::HTTP.{get,get_response,start,request}, URI.open, OpenURI.open_uri.
       # Excludes Net::HTTP.get_print. Emits only for request/middleware/websocket/callback.
+      #
+      # Advisory rule with :medium default, no context ceiling.
       class NetHTTPInRequest < Base
         id 'FA1007'
-        severity :high
+        severity :medium
         default_confidence :high
-        description 'Blocking HTTP call in request path'
+        description 'HTTP calls require scheduler-aware DNS, socket, and TLS cooperation in request contexts'
 
-        TITLE = 'Blocking HTTP call in request path'
+        TITLE = 'HTTP scheduler-cooperation requirement'
         CATEGORY = :network
-        MESSAGE = 'Synchronous HTTP activity in a request-like context may block the thread running the fiber scheduler.'
-        REMEDIATION = 'Use a scheduler-aware HTTP client, or move outbound HTTP work outside the request path.'
+        MESSAGE = 'HTTP activity requires scheduler-aware DNS and I/O cooperation in a non-blocking Fiber.'
+        REMEDIATION = 'Verify the selected HTTP/TLS/DNS stack and active scheduler ' \
+                      'under load; investigate correlated stalls.'
 
         NET_HTTP_METHODS = OperationVocabulary::FA1007_NET_HTTP_METHODS
         URI_METHODS = OperationVocabulary::FA1007_URI_METHODS
@@ -82,7 +85,7 @@ module FiberAudit
         def build_finding(site, match)
           context = site.execution_context
           sev, conf = if match[:type] == :net_http
-                        [severity_for(:high, context), site.confidence]
+                        [advisory_severity(:medium), site.confidence]
                       else
                         %i[medium low]
                       end
@@ -101,7 +104,7 @@ module FiberAudit
             evidence: [
               FiberAudit::Evidence.new(
                 source: 'static_analysis',
-                message: "Blocking HTTP call detected: #{match[:operation]}",
+                message: "HTTP scheduler-cooperation point: #{match[:operation]}",
                 details: { receiver: site.receiver_constant, method: site.method_name, context: context }
               )
             ],

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

@@ -9,20 +9,24 @@ require_relative '../../operation_vocabulary'
 module FiberAudit
   module Static
     module Rules
+      # FA1003: Thread synchronization primitives that may interfere with
+      # fiber scheduler cooperation. Advisory rule with :low default.
+      #
+      # Detects Mutex, ConditionVariable, Monitor, and MonitorMixin
+      # synchronization operations. try_lock is treated as :info since
+      # it's non-blocking but indicates thread-oriented synchronization.
       class Synchronization < Base
         id 'FA1003'
-        severity :medium
+        severity :low
         default_confidence :high
-        description 'Thread synchronization primitives that may block the fiber scheduler thread'
+        description 'Thread synchronization may interfere with fiber scheduler cooperation'
 
         RULE_TITLE = 'Thread synchronization'
         RULE_CATEGORY = :synchronization
         TARGETS = OperationVocabulary::FA1003_TARGETS
-        TRY_LOCK_MSG = 'Mutex.try_lock is non-blocking but may indicate ' \
-                       'thread-oriented synchronization in fiber-scheduled code.'
-        NORMAL_MSG = 'Synchronization operation may block the thread running the fiber scheduler.'
-        REMEDIATION = 'Use scheduler-aware synchronization primitives, or verify ' \
-                      'contention and scheduler behaviour under load.'
+        TRY_LOCK_MSG = 'Mutex#try_lock is non-blocking and identifies a thread-oriented coordination point.'
+        NORMAL_MSG = 'Synchronization contention requires scheduler block/unblock cooperation in a non-blocking Fiber.'
+        REMEDIATION = 'Verify scheduler coordination and contention behavior under load; investigate correlated stalls.'
 
         def analyze(call_sites:)
           explicit_monitor_mixins = explicit_monitor_mixin_classes(call_sites)
@@ -98,7 +102,8 @@ module FiberAudit
         def build_finding(site, target, method)
           try_lock = target == 'Mutex' && method == :try_lock
           operation = "#{target}##{method}"
-          severity = try_lock ? :info : severity_for(:medium, site.execution_context)
+          # try_lock has fixed :info, no config override
+          severity = try_lock ? :info : advisory_severity(:low)
           confidence = try_lock ? :high : site.confidence
           message = try_lock ? TRY_LOCK_MSG : NORMAL_MSG
           evidence = Evidence.new(source: operation, message: message,

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

@@ -9,27 +9,32 @@ require_relative '../../operation_vocabulary'
 module FiberAudit
   module Static
     module Rules
-      # Detect thread-variable and Thread.current index state.
+      # FA1004: Detect thread-variable state access.
+      #
+      # Detects only thread_variable_get/set operations, not Thread.current[]
+      # index operations. Thread variables are shared across all fibers on the
+      # same thread and may leak request-local data.
       class ThreadCurrentState < Base
         id 'FA1004'
         severity :high
         confidence :high
-        description 'Thread-local state in fiber code may be shared across fibers and leak request-local data'
+        description 'Thread thread variables in fiber code may be shared across fibers and leak request-local data'
 
-        TITLE = 'Thread-local state in fiber code'
+        TITLE = 'Thread thread variables in fiber code'
         CATEGORY = :thread_local
-        MESSAGE = 'Thread-local state may be shared across fibers and leak request-local data.'
-        REMEDIATION = 'Use fiber-local or framework-provided request-local state instead of Thread thread variables.'
+        MESSAGE = 'Thread thread variables are shared across all fibers on the same thread ' \
+                  'and may leak request-local data between concurrent requests.'
+        REMEDIATION = 'Prefer fiber-local storage (Fiber[:key]) or framework-provided ' \
+                      'request-local state over thread_variable_get/set.'
 
         THREAD_VARIABLE_METHODS = OperationVocabulary::FA1004_THREAD_VARIABLE_METHODS
-        INDEX_METHODS = OperationVocabulary::FA1004_INDEX_METHODS
 
         def analyze(call_sites:)
           findings = []
           call_sites.each do |site|
             next if skip?(site)
 
-            finding = match_thread_variable(site) || match_index_op(site)
+            finding = match_thread_variable(site)
             findings << finding if finding
           end
           findings
@@ -74,19 +79,8 @@ module FiberAudit
           build_finding(site, :high, :high, operation(site))
         end
 
-        def match_index_op(site)
-          return unless INDEX_METHODS.include?(site.method_name)
-          return unless site.receiver_source == 'Thread.current'
-
-          build_finding(site, :medium, :high, operation(site))
-        end
-
         def operation(site)
-          if INDEX_METHODS.include?(site.method_name)
-            "Thread.current.#{site.method_name}"
-          else
-            "Thread.#{site.method_name}"
-          end
+          "Thread.#{site.method_name}"
         end
 
         def build_finding(site, default_sev, conf, operation)
@@ -104,7 +98,11 @@ module FiberAudit
             operation: operation,
             execution_context: context,
             message: MESSAGE,
-            evidence: [Evidence.new(source: site.receiver_source, message: "Thread-local access via #{site.method_name}")],
+            evidence: [Evidence.new(
+              source: site.receiver_source,
+              message: "Thread thread variable access via #{site.method_name}",
+              details: { operation: operation, receiver: site.receiver_source }
+            )],
             remediation: REMEDIATION
           )
         end

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

@@ -9,7 +9,7 @@ require_relative '../../operation_vocabulary'
 module FiberAudit
   module Static
     module Rules
-      # FA1002: Thread#join / Thread#value may block the fiber-scheduler thread.
+      # FA1002: Thread#join / Thread#value are scheduler coordination points.
       #
       # Matches join/value on Thread instances whose receiver_constant is
       # 'Thread' but whose receiver_source is not the bare literal 'Thread'.
@@ -20,17 +20,19 @@ module FiberAudit
       # and workspace-shadowed Thread (checked via workspace or
       # workspace.semantic_index resolve_constant seam). Adapter errors from
       # those seams are swallowed — they never raise.
+      #
+      # Advisory rule: uses advisory_severity (no context ceiling), default :low.
       class ThreadJoin < Base
         id 'FA1002'
-        severity :high
+        severity :low
         confidence :high
-        description 'Waiting for a thread may block the thread running the fiber scheduler.'
+        description 'Thread waits require scheduler block/unblock cooperation'
 
         TITLE    = 'Thread wait'
         CATEGORY = :synchronization
-        MESSAGE  = 'Waiting for a thread may block the thread running the fiber scheduler.'
-        REMEDIATION = 'Replace thread waits with scheduler-aware coordination, ' \
-                      'or move the work outside the fiber-scheduled path.'
+        MESSAGE  = 'Thread#join/value requires scheduler block/unblock cooperation in a non-blocking Fiber.'
+        REMEDIATION = 'Verify scheduler coordination and runtime progress, ' \
+                      'or move the wait outside the fiber-scheduled path.'
         TARGET_METHODS  = OperationVocabulary::FA1002_METHODS
         CANONICAL_OPS   = OperationVocabulary::FA1002_OPERATIONS
         DIRECT_CLASS_SOURCE = 'Thread'
@@ -73,7 +75,7 @@ module FiberAudit
         def build_finding(site)
           loc  = site.location
           op   = "Thread.#{site.method_name}"
-          sev  = severity_for(self.class.severity, site.execution_context)
+          sev  = advisory_severity(self.class.severity)
           conf = site.receiver_source == 'Thread.current' ? :high : site.confidence
 
           Finding.new(

data/lib/fiber_audit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module FiberAudit
-  VERSION = '0.2.0'
+  VERSION = '0.3.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fiber_audit
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - FiberAudit Contributors
@@ -95,6 +95,7 @@ files:
 - lib/fiber_audit/runtime/redactor.rb
 - lib/fiber_audit/runtime/sampler.rb
 - lib/fiber_audit/runtime/scheduler_observer.rb
+- lib/fiber_audit/runtime/scheduler_snapshot.rb
 - lib/fiber_audit/runtime/session.rb
 - lib/fiber_audit/runtime/supervisor.rb
 - lib/fiber_audit/runtime/validation.rb