fiber_audit 0.2.1 → 0.3.1

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

@@ -4,22 +4,72 @@ require_relative 'base'
 require_relative '../../findings/evidence'
 require_relative '../../correlation/fingerprint'
 require_relative '../../findings/finding'
+require_relative '../../operation_semantics'
 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.'
+        OPERATION_CATEGORY = OperationSemantics::FA1001_CATEGORIES
+
+        # 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 +110,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 = OperationSemantics.resolve(operation).category
+          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 +125,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

@@ -4,28 +4,51 @@ require_relative 'base'
 require_relative '../../findings/evidence'
 require_relative '../../correlation/fingerprint'
 require_relative '../../findings/finding'
+require_relative '../../operation_semantics'
 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: Inventory and semantic classification for direct socket constructors.
       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 constructors range from inventory-only allocation to endpoint setup.'
 
-        TITLE    = 'Direct socket creation'
+        TITLE = 'Direct socket construction'
         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.'
+        CATEGORY_METADATA = {
+          socket_allocation: {
+            title: 'Direct socket allocation',
+            message: 'This constructor is inventory-level socket setup without a client connection; ' \
+                     'later accept, connect, address resolution, or I/O may require scheduler cooperation.',
+            remediation: 'Treat allocation as inventory and verify scheduler-aware behavior at later ' \
+                         'accept, connect, resolution, and I/O calls.'
+          },
+          socket_resolve_connect: {
+            title: 'Direct socket endpoint setup',
+            message: 'This constructor may resolve an address and establish a network endpoint, requiring ' \
+                     'scheduler cooperation from address-resolution and I/O hooks.',
+            remediation: 'Verify address_resolve and scheduler-aware I/O hooks, and confirm runtime progress ' \
+                         'for endpoint setup.'
+          },
+          socket_local_connect: {
+            title: 'Direct local-socket connection',
+            message: 'This constructor may establish a local socket connection and wait for endpoint progress.',
+            remediation: 'Verify runtime progress for local-socket connection and move blocking setup outside ' \
+                         'the fiber-scheduled path.'
+          },
+          socket_constructor_unknown: {
+            title: 'Direct socket subclass construction',
+            message: 'This IPSocket subclass constructor has unknown allocation/connect semantics and may ' \
+                     'require scheduler cooperation.',
+            remediation: 'Inspect the subclass constructor and verify scheduler-aware resolution, connection, ' \
+                         'and I/O behavior.'
+          }
+        }.freeze
 
         class << self
           def title = TITLE
@@ -82,27 +105,39 @@ module FiberAudit
 
         def build_finding(site, const)
           operation = "#{const}.new"
-          ctx = site.execution_context || :unknown
+          profile = if EXACT.include?(const)
+                      OperationSemantics.resolve(operation)
+                    else
+                      OperationSemantics.resolve_socket_constructor(operation)
+                    end
+          metadata = CATEGORY_METADATA.fetch(profile.category)
 
           Finding.new(
             rule_id: self.class.id,
-            title: self.class.title,
+            title: metadata.fetch(:title),
             category: self.class.category,
-            severity: severity_for(:medium, ctx),
+            severity: advisory_severity(:low),
             confidence: site.confidence,
             location: site.location,
             symbol: site.enclosing_symbol,
             operation: operation,
-            execution_context: ctx,
-            message: MESSAGE,
+            execution_context: site.execution_context || :unknown,
+            message: metadata.fetch(:message),
             evidence: [
               Evidence.new(
                 source: 'static_analysis',
-                message: "Direct socket creation: #{operation}",
-                details: { receiver_constant: const, method: :new }
+                message: "Matched #{operation} (#{profile.category})",
+                details: {
+                  receiver_constant: const,
+                  method: :new,
+                  semantic: profile.category,
+                  wait_possible: profile.wait_possible,
+                  inventory_only: profile.inventory_only,
+                  scheduler_capability: profile.scheduler_capability
+                }
               )
             ],
-            remediation: REMEDIATION
+            remediation: metadata.fetch(:remediation)
           )
         end
       end

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,28 @@ require_relative '../../operation_vocabulary'
 module FiberAudit
   module Static
     module Rules
-      # Detect thread-variable and Thread.current index state.
+      # FA1004: Detect thread-variable state access without inferring stored data.
       class ThreadCurrentState < Base
         id 'FA1004'
-        severity :high
+        severity :medium
         confidence :high
-        description 'Thread-local state in fiber code may be shared across fibers and leak request-local data'
+        description 'Thread-variable access may share mutable state across fibers on one thread'
 
-        TITLE = 'Thread-local state in fiber code'
+        TITLE = 'Thread-variable access shared across fibers'
         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 variables are visible to fibers sharing a thread. This access may expose mutable ' \
+                  'state across concurrent work, but static analysis does not establish request-sensitive leakage.'
+        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
@@ -68,43 +69,32 @@ module FiberAudit
 
           instance_match = site.receiver_constant == 'Thread' && site.receiver_source != 'Thread'
           current_match = site.receiver_source == 'Thread.current'
-
           return unless instance_match || current_match
 
-          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))
+          build_finding(site, 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)
-          context = site.execution_context
-          severity = severity_for(default_sev, context)
-
+        def build_finding(site, operation)
           Finding.new(
             rule_id: self.class.id,
             title: TITLE,
             category: CATEGORY,
-            severity: severity,
-            confidence: conf,
+            severity: advisory_severity(:medium),
+            confidence: :high,
             location: site.location,
             symbol: site.enclosing_symbol,
             operation: operation,
-            execution_context: context,
+            execution_context: site.execution_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: "Matched 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.1'
+  VERSION = '0.3.1'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fiber_audit
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.1
 platform: ruby
 authors:
 - FiberAudit Contributors
@@ -61,6 +61,7 @@ files:
 - lib/fiber_audit/findings/finding.rb
 - lib/fiber_audit/findings/location.rb
 - lib/fiber_audit/findings/severity.rb
+- lib/fiber_audit/operation_semantics.rb
 - lib/fiber_audit/operation_vocabulary.rb
 - lib/fiber_audit/project.rb
 - lib/fiber_audit/reporters/base.rb
@@ -80,6 +81,8 @@ files:
 - lib/fiber_audit/runtime/lifecycle.rb
 - lib/fiber_audit/runtime/limits.rb
 - lib/fiber_audit/runtime/location.rb
+- lib/fiber_audit/runtime/operation_liveness_monitor.rb
+- lib/fiber_audit/runtime/operation_liveness_policy.rb
 - lib/fiber_audit/runtime/policy.rb
 - lib/fiber_audit/runtime/probes/base.rb
 - lib/fiber_audit/runtime/probes/http.rb
@@ -94,7 +97,9 @@ files:
 - lib/fiber_audit/runtime/recorder.rb
 - lib/fiber_audit/runtime/redactor.rb
 - lib/fiber_audit/runtime/sampler.rb
+- lib/fiber_audit/runtime/scheduler_evidence_classifier.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