fiber_audit 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f76c5789a7f5490e2e568cb6ea912520ae1350cc5a0de15053b3b30fd271e10d
-  data.tar.gz: aac0a9b350682e2c1abb167057ab4ea9ba912f277efa8818dd7269cee8d71058
+  metadata.gz: 64afd3fe0ced532129e0d6e55508edca15e7a613ca30c064a61b9a868b155488
+  data.tar.gz: a4db073387d08a250c8c79e95251ebc39ddb414a2a830d5ddb91c85d673d9989
 SHA512:
-  metadata.gz: 9d1cbe6bca9cc0363a483f9c2902a13c0389fc1fc0b833023d923342c23e8ea01b884e71233ddc2ba5b6f802cb83f7af6c5bb17ae67ef1b01d96958517ea5bca
-  data.tar.gz: f14db18581138d051937fbb788b4c3d6a8ec8970647fa82612d5911d2809b55918adfd27e02ec790500e86ae80c8cdeec112a60515d8cc22eb1f52da07ffcf89
+  metadata.gz: a632c52483c6b266bbbe1d99ca7e5dfb3c35d5556d364da7bd3adaab44308c551eda6db22d77c8b15871158386015ac2fe9c0fe69d0336a31d4094df5f4d5c4d
+  data.tar.gz: 638caf18b5c0273abe010457b74e33bc79082a857d3196c6020394b8d771d5a3479d27d83f1cc97abdcc4ace7dbc6eee01285fa7013b8a59019ac4bc53646a2b

data/ARCHITECTURE.md

@@ -20,13 +20,10 @@ produces hypotheses, while observational runtime sessions provide bounded eviden
 without establishing complete coverage. FiberAudit never claims unconditional
 `PASS`.
 
-> **Repository status:** v0.2.1 includes the v0.1.0 static pipeline end to end:
-> project discovery, configuration, semantic and syntax analysis, execution
-> contexts, FA1001–FA1007, suppressions, status derivation, text/JSON reports,
-> and the CLI. The v0.2 runtime contracts, bounded JSONL recorder, explicit
-> child-process boot, lifecycle, supervising command, bounded scheduler
-> watchdog, targeted FA1001–FA1007 operation probes, and Rails runtime execution
-> contexts are implemented; static/runtime correlation remains future work.
+> **Repository status:** v0.3.0 includes the static pipeline end to end,
+> observational runtime probes, propagated Rails execution context,
+> scheduler-capability snapshots, and bounded operation/stall overlap events.
+> Combined static/runtime reporting remains future work.
 
 ## 2. Scope
 
@@ -60,8 +57,8 @@ Current code and specs define implementation truth. This document records the
 supported architecture and dependency boundaries; README and CHANGELOG record
 the user-facing release contract.
 
-The corrected platform target is Ruby `>= 3.3` with CI configured for Ruby 3.3
-and 3.4. Ruby 3.2 is excluded because it is end-of-life.
+The platform target is Ruby `>= 3.3` with CI configured for Ruby 3.3, 3.4,
+and 4.0. Ruby 3.2 is excluded because it is end-of-life.
 
 ## 4. Architectural Principles
 
@@ -363,17 +360,17 @@ explicit and can lower confidence.
 Rules consume FiberAudit `CallSite` values and emit `Finding` values. They do
 not parse files and do not access Rubydex directly.
 
-Shipped v0.1.0 rules:
+Shipped rules:
 
 | ID | Concern | Default severity |
 |---|---|---:|
-| FA1001 | Blocking subprocess operations | high |
-| FA1002 | `Thread#join` / `Thread#value` | high |
-| FA1003 | Blocking synchronization | medium |
-| FA1004 | Thread-local request state | medium/high by operation |
-| FA1005 | Explicit `IO.select` | medium |
-| FA1006 | Direct socket creation | medium |
-| FA1007 | `Net::HTTP` in request-like contexts | high |
+| FA1001 | Subprocess lifecycle and process-wait cooperation | info/medium |
+| FA1002 | Thread-wait scheduler coordination | low |
+| FA1003 | Synchronization scheduler coordination | low/info |
+| FA1004 | True Thread variables shared across sibling Fibers | high |
+| FA1005 | `IO.select` scheduler capability requirement | medium |
+| FA1006 | Socket/DNS/I/O scheduler cooperation | low |
+| FA1007 | HTTP scheduler cooperation in request-like contexts | medium |
 
 A rule registry owns registration, enumeration, configuration enablement, and
 metadata used by `list-rules` and `explain`.
@@ -595,7 +592,8 @@ spec/fixtures/apps/rails_contexts
 spec/fixtures/reports/rails_blockers_v0.1.json
 ```
 
-CI is configured to run linting, specs, and gem packaging on Ruby 3.3 and 3.4.
+CI is configured to run linting, specs, and gem packaging on Ruby 3.3, 3.4,
+and 4.0.
 The workflow configuration does not itself prove that remote CI has passed.
 
 ## 13. Runtime Architecture Beyond v0.1.0
@@ -666,11 +664,11 @@ stall, and only then closes the recorder. Fork rebinding discards inherited prob
 and watchdog references before touching their locks and creates process-local
 replacements.
 
-Stage 6 adds Rails execution context detection. A bounded, PID-aware fiber-local
-context stack tracks the current execution context during probe observations.
-The fiber-local stack uses `Fiber.current` instance variables to avoid thread-local
-key visibility, validates against `Context::ALL`, enforces `MAX_DEPTH = 32`, and
-resets on fork. A process-local `RailsIntegration` class hooks into Rails boundaries
+Rails execution context detection uses a bounded immutable frame chain in Ruby
+Fiber storage. Child Fibers inherit the current logical context snapshot, while
+child overrides and `clear!` remain local to that Fiber. Frames carry PID and
+Thread ownership, validate against `Context::ALL`, enforce `MAX_DEPTH = 32`, and
+reset on fork. A process-local `RailsIntegration` class hooks into Rails boundaries
 via `Module#prepend`: Rack middleware (`:middleware`), `ActionController::Metal#process_action`
 (`:request`), `ActiveJob::Base#perform_now` (`:job`), and `ActionCable::Channel::Base#dispatch_action`
 (`:websocket`). Wrappers consult the active integration before setting context and become
@@ -680,7 +678,11 @@ even after runtime boot. Probe observations snapshot the context once at start a
 propagate it through active operations and events. Lifecycle wires context store and
 Rails integration ownership, shutdown deactivates Rails integration before probes,
 and fork rebinding resets context and rebuilds integration. JSONL schema 1.0 and
-privacy requirements are preserved; no new schema fields are added.
+privacy requirements are preserved; no new schema fields are added. Runtime
+operation events also record scheduler presence, blocking-Fiber state, and
+optional hook support. Watchdog stalls emit bounded
+`scheduler_stall_operation_overlap` events for operations active on the same
+Thread. These events establish temporal overlap, not causality.
 
 Loading the gem normally performs no instrumentation, fibers, threads, or file
 I/O. The observer is activated only by explicit runtime boot. A native operation

data/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 ## Unreleased
 
+## 0.3.0 (2026-08-12)
+
+### Changed
+
+- Reframed static rules as scheduler-cooperation requirements. Advisory rules no
+  longer escalate solely because they appear in request-like execution contexts.
+- Split FA1001 under its existing rule ID into subprocess creation, replacement,
+  waiting, detach, and stream lifecycle semantics; added Process `spawn`, `exec`,
+  `wait`, `wait2`, `waitpid`, `waitpid2`, and `Process::Status.wait` coverage.
+- Corrected FA1004 to report only true Thread variables. `Thread.current[]` and
+  `Thread.current[]=` are Fiber-local and are no longer static or runtime findings.
+- Propagated Rails/runtime execution context into child Fibers through immutable
+  Ruby Fiber storage, with explicit current-Fiber `clear!`/`reset!` behavior.
+- Added scheduler presence, blocking-Fiber state, and optional scheduler-hook
+  capability measurements to targeted operation events.
+- Added bounded `scheduler_stall_operation_overlap` JSONL 1.0 events. They record
+  temporal overlap between a watchdog stall and active operations, not causality.
+- Reconciled scheduler observer state only after `Fiber.set_scheduler` accepts a
+  change, so rejected replacement attempts preserve the previous observation.
+- Added Ruby 4.0 to the required CI matrix and executable local scheduler-semantic
+  reproductions under `script/scheduler-semantics`, including Ruby 4's
+  `fiber_interrupt` scheduler protocol hook.
+
 ## 0.2.1 (2026-08-12)
 
 ### Fixed

data/README.md

@@ -1,8 +1,8 @@
 # FiberAudit
 
-FiberAudit audits Ruby and Rails code for operations that can block the thread
-running a Fiber scheduler. Version 0.2.1 includes static analysis and an explicit,
-observational runtime audit.
+FiberAudit audits Ruby and Rails code for operations that require cooperation
+from a Fiber scheduler. Version 0.3.0 includes static analysis and an explicit,
+observational runtime audit with scheduler-capability and stall-overlap evidence.
 
 > **Safety disclaimer:** FiberAudit does not prove that an application is
 > fiber-safe. Static findings are hypotheses, and absence of runtime events does
@@ -10,7 +10,7 @@ observational runtime audit.
 
 ## Requirements and installation
 
-FiberAudit v0.2.1 supports Ruby 3.3 and 3.4.
+FiberAudit v0.3.0 supports Ruby 3.3, 3.4, and 4.0.
 
 ```sh
 gem install fiber_audit
@@ -52,13 +52,13 @@ Explicit `--format` always wins.
 
 | ID | Detects | Default severity |
 |---|---|---|
-| FA1001 | Blocking subprocess operations | high |
-| FA1002 | `Thread#join` and `Thread#value` | high |
-| FA1003 | Thread-oriented synchronization | medium |
-| FA1004 | Thread-local state access | high/medium |
-| FA1005 | Explicit `IO.select`/`Kernel.select` | medium |
-| FA1006 | Direct socket construction | medium |
-| FA1007 | Synchronous HTTP in request-like contexts | high |
+| FA1001 | Subprocess creation, replacement, waiting, and streams | info/medium |
+| FA1002 | Thread-wait scheduler coordination | low |
+| FA1003 | Synchronization scheduler coordination | low/info |
+| FA1004 | True Thread-variable state shared by sibling Fibers | high |
+| FA1005 | `IO.select` scheduler capability requirement | medium |
+| FA1006 | Socket/DNS/I/O scheduler cooperation | low |
+| FA1007 | HTTP scheduler cooperation in request-like contexts | medium |
 
 Use `fiber-audit explain <RULE_ID>` for exact targets and remediation.
 
@@ -82,13 +82,17 @@ Libraries such as Open3, Monitor, Socket, Net::HTTP, and OpenURI may be loaded
 after runtime boot; FiberAudit rescans only these known targets after `require`.
 
 Rails execution contexts (`:request`, `:middleware`, `:job`, `:websocket`) are
-captured automatically when Rails integration is active. A bounded, PID-aware
-fiber-local context stack tracks the current execution context during probe
-observations. Rails boundaries are wrapped via prepend hooks that become inert
+captured automatically when Rails integration is active. A bounded, PID- and
+Thread-aware immutable context chain uses inheritable Ruby Fiber storage, so
+child Fibers receive a snapshot of their parent's logical context. FiberAudit's
+`ExecutionContext.clear!` explicitly detaches the current Fiber without allowing
+enclosing scopes to restore stale context. Rails boundaries use prepend hooks that become inert
 after deactivation or fork, preserving application semantics without interfering
 with normal Rails operation. The integration supports late loading: hooks are
 installed when Rails components become available, even after runtime boot.
-Static/runtime correlation remains future work.
+Raw runtime JSONL now records bounded `scheduler_stall_operation_overlap`
+events linking active operation sequences to watchdog stalls. This establishes
+temporal overlap, not causality. Combined static/runtime reporting remains future work.
 
 The scheduler watchdog records one bounded start/completion pair when its
 scheduler-owned heartbeat stops progressing past the configured threshold.
@@ -190,7 +194,7 @@ Missing reasons and invalid configuration return exit code 2.
 - `PASS_WITH_WARNINGS` — only low or informational findings.
 - `NO_FINDINGS` — no findings at the configured threshold.
 
-FiberAudit never emits unconditional `PASS` in v0.2.1.
+FiberAudit never emits unconditional `PASS` in v0.3.0.
 
 ## Exit codes
 
@@ -199,10 +203,30 @@ FiberAudit never emits unconditional `PASS` in v0.2.1.
 | 0 | No active finding at or above the configured threshold |
 | 1 | One or more active findings at or above the threshold |
 | 2 | Invalid options, configuration, analysis, or report output |
-| 3 | Reserved; never emitted by v0.2.1 |
+| 3 | Reserved; never emitted by v0.3.0 |
 
 Source parse errors are included in report data while analysis continues on
 other files.
 
+## Development and semantic verification
+
+```sh
+bundle exec rspec
+bundle exec rubocop
+bundle exec ruby script/scheduler-semantics
+gem build fiber_audit.gemspec
+bundle exec rake release:sanity
+```
+
+The semantic probe uses only local Threads, pipes, and child processes. It checks
+scheduler coordination, Fiber-storage inheritance, Thread/Fiber state semantics,
+and rejected scheduler replacement against each supported Ruby in CI.
+
+Relevant Ruby contracts:
+
+- [Fiber and inheritable storage](https://docs.ruby-lang.org/en/3.4/Fiber.html)
+- [Fiber::Scheduler hooks](https://docs.ruby-lang.org/en/3.4/Fiber/Scheduler.html)
+- [Thread Fiber-local and Thread-wide storage](https://docs.ruby-lang.org/en/3.4/Thread.html#method-i-5B-5D)
+
 See [ARCHITECTURE.md](ARCHITECTURE.md) for implementation boundaries, runtime
-architecture, and explicitly deferred correlation work.
+architecture, raw stall-overlap evidence, and deferred combined reporting.

data/lib/fiber_audit/cli.rb

@@ -274,12 +274,25 @@ module FiberAudit
       stdout.puts "Description: #{rule_class.description}"
       stdout.puts 'Targets:'
       rule_targets(rule_class).each { |target| stdout.puts "  - #{target}" }
-      stdout.puts "Remediation: #{rule_class.const_get(:REMEDIATION)}"
+      print_rule_remediations(rule_class, stdout)
       0
     end
 
+    def print_rule_remediations(rule_class, stdout)
+      values = if rule_class.const_defined?(:REMEDIATION, false)
+                 [rule_class.const_get(:REMEDIATION)]
+               elsif rule_class.const_defined?(:CATEGORY_METADATA, false)
+                 rule_class.const_get(:CATEGORY_METADATA).values.map { |metadata| metadata.fetch(:remediation) }.uniq
+               else
+                 []
+               end
+      values.each_with_index do |remediation, index|
+        stdout.puts "#{index.zero? ? 'Remediation:' : '            '} #{remediation}"
+      end
+    end
+
     def rule_title(rule_class)
-      return 'Blocking subprocess call' if rule_class.id == 'FA1001'
+      return 'Subprocess lifecycle operations' if rule_class.id == 'FA1001'
 
       %i[TITLE RULE_TITLE].each do |name|
         return rule_class.const_get(name) if rule_class.const_defined?(name, false)
@@ -296,8 +309,7 @@ module FiberAudit
       when 'FA1003'
         expand_target_map(rule_class::TARGETS, '#')
       when 'FA1004'
-        rule_class::THREAD_VARIABLE_METHODS.map { |method| "Thread##{method}" } +
-          rule_class::INDEX_METHODS.map { |method| "Thread.current.#{method}" }
+        rule_class::THREAD_VARIABLE_METHODS.map { |method| "Thread##{method}" }
       when 'FA1005'
         expand_target_map(rule_class::TARGETS.transform_values { |method| [method] }, '.')
       when 'FA1006'

data/lib/fiber_audit/operation_vocabulary.rb

@@ -7,7 +7,8 @@ module FiberAudit
       'Kernel' => %i[system exec spawn].freeze,
       'Open3' => %i[capture2 capture2e capture3 pipeline].freeze,
       'IO' => %i[popen].freeze,
-      'Process' => %i[waitall detach].freeze
+      'Process' => %i[spawn exec wait wait2 waitpid waitpid2 waitall detach].freeze,
+      'Process::Status' => %i[wait].freeze
     }.freeze
     FA1001_KERNEL_METHODS = %i[system exec spawn].freeze
 

data/lib/fiber_audit/runtime/active_operations.rb

@@ -2,6 +2,7 @@
 
 require_relative 'event'
 require_relative 'location'
+require_relative 'scheduler_snapshot'
 require_relative 'validation'
 
 module FiberAudit
@@ -19,7 +20,8 @@ module FiberAudit
         :operation,
         :location,
         :execution_context,
-        :started_monotonic_ns
+        :started_monotonic_ns,
+        :scheduler_snapshot
       )
 
       def initialize(pid_source: Process.method(:pid), capacity: MAX_ENTRIES, snapshot_limit: MAX_SNAPSHOT)
@@ -38,7 +40,8 @@ module FiberAudit
         location: nil,
         execution_context: :unknown,
         thread: Thread.current,
-        fiber: Fiber.current
+        fiber: Fiber.current,
+        scheduler_snapshot: nil
       )
         ensure_current_process!
         values = normalize_entry(
@@ -47,7 +50,8 @@ module FiberAudit
           execution_context: execution_context,
           monotonic_ns: monotonic_ns,
           thread: thread,
-          fiber: fiber
+          fiber: fiber,
+          scheduler_snapshot: scheduler_snapshot
         )
 
         @mutex.synchronize do
@@ -90,7 +94,7 @@ module FiberAudit
 
       private
 
-      def normalize_entry(operation:, location:, execution_context:, monotonic_ns:, thread:, fiber:)
+      def normalize_entry(operation:, location:, execution_context:, monotonic_ns:, thread:, fiber:, scheduler_snapshot: nil)
         canonical_operation = Validation.operation(operation)
         unless location.nil? || location.is_a?(Location)
           raise RuntimeContractError, 'location must be a FiberAudit::Runtime::Location or nil'
@@ -103,16 +107,26 @@ module FiberAudit
           raise RuntimeContractError, 'thread and fiber identities are invalid'
         end
 
+        normalized_snapshot = normalize_scheduler_snapshot(scheduler_snapshot)
+
         {
           thread_id: Validation.integer(thread.object_id, 'thread_id'),
           fiber_id: Validation.integer(fiber.object_id, 'fiber_id'),
           operation: canonical_operation,
           location: location,
           execution_context: normalized_context,
-          started_monotonic_ns: Validation.integer(monotonic_ns, 'monotonic_ns')
+          started_monotonic_ns: Validation.integer(monotonic_ns, 'monotonic_ns'),
+          scheduler_snapshot: normalized_snapshot
         }
       end
 
+      def normalize_scheduler_snapshot(value)
+        return value if value.nil?
+        return value if value.is_a?(SchedulerSnapshot)
+
+        raise RuntimeContractError, 'scheduler_snapshot must be a FiberAudit::Runtime::SchedulerSnapshot or nil'
+      end
+
       def ensure_current_process!
         pid = current_pid
         reset_for_process!(pid) unless pid == @owner_pid

data/lib/fiber_audit/runtime/execution_context.rb

@@ -4,73 +4,85 @@ require_relative '../execution_context'
 
 module FiberAudit
   module Runtime
-    # Fiber-local execution context stack.
-    # Uses fiber instance variables for isolation without Thread#[] visibility.
-    # PID-aware to handle fork correctly.
+    # Fiber-local execution context with propagation to child fibers.
+    # Uses Ruby Fiber storage (Fiber[]) for fiber-local state that is
+    # inherited by child fibers at creation, enabling automatic context
+    # propagation across Fiber boundaries.
+    #
+    # Frames are immutable (frozen Data objects) forming a linked list.
+    # Each +with+ call creates a new frame pointing to the parent frame.
+    #
+    # Semantics:
+    # - Child fibers inherit the parent fiber's current context at creation
+    # - Child fiber overrides do not alter parent context
+    # - +clear!+ removes context for the current fiber only
+    # - +clear!+ inside nested +with+ is not undone by the enclosing ensure
+    #   (ensure restores only when its own frame is still the active one)
+    # - Thread isolation is maintained even though Ruby copies Fiber storage to a
+    #   newly created Thread's root Fiber
+    # - PID mismatch (after fork) is treated as empty context
+    # - MAX_DEPTH overflow exposes :unknown rather than stale outer context
     module ExecutionContext
       MAX_DEPTH = 32
-      IVAR_KEY = :@__fiber_audit_execution_context__
-      IVAR_PID_KEY = :@__fiber_audit_execution_context_pid__
+      FRAME_KEY = :__fiber_audit_execution_context_frame__
+
+      # Immutable frame in the context chain. Process and Thread ownership keep
+      # inherited storage from crossing fork or Thread boundaries.
+      Frame = Data.define(:context, :parent, :depth, :pid, :thread_id)
+      private_constant :Frame
 
       class << self
         def current
-          state = current_state
-          return Context::UNKNOWN unless state
-
-          state[:stack].last || Context::UNKNOWN
+          frame = current_frame
+          frame ? frame.context : Context::UNKNOWN
         end
 
         def with(context)
           normalized = validate_context(context)
-          state = ensure_state
-          return yield if state[:stack].size >= MAX_DEPTH
-
-          state[:stack].push(normalized)
+          parent = current_frame
+
+          new_depth = parent ? parent.depth + 1 : 1
+          effective = new_depth > MAX_DEPTH ? Context::UNKNOWN : normalized
+          frame = Frame.new(
+            context: effective,
+            parent: parent,
+            depth: new_depth,
+            pid: Process.pid,
+            thread_id: Thread.current.object_id
+          )
+
+          Fiber[FRAME_KEY] = frame
           begin
             yield
           ensure
-            state[:stack].pop
+            # Only restore if our frame is still the active one.
+            # If clear! was called (or another with replaced it), skip restore.
+            Fiber[FRAME_KEY] = parent if Fiber[FRAME_KEY].equal?(frame)
           end
         end
 
+        def clear!
+          Fiber[FRAME_KEY] = nil
+        end
+
+        # Compatibility alias for clear!.
         def reset!
-          fiber = Fiber.current
-          fiber.remove_instance_variable(IVAR_KEY) if fiber.instance_variable_defined?(IVAR_KEY)
-          fiber.remove_instance_variable(IVAR_PID_KEY) if fiber.instance_variable_defined?(IVAR_PID_KEY)
+          clear!
         end
 
+        # Clear context after fork.
         def after_fork!
-          reset!
+          clear!
         end
 
         private
 
-        def current_state
-          fiber = Fiber.current
-          return nil unless fiber.instance_variable_defined?(IVAR_KEY)
-
-          pid = fiber.instance_variable_defined?(IVAR_PID_KEY) ? fiber.instance_variable_get(IVAR_PID_KEY) : nil
-          return nil unless pid == Process.pid
-
-          { stack: fiber.instance_variable_get(IVAR_KEY), pid: pid }
-        end
-
-        def ensure_state
-          fiber = Fiber.current
-          pid = Process.pid
-
-          if fiber.instance_variable_defined?(IVAR_KEY)
-            stored_pid = fiber.instance_variable_defined?(IVAR_PID_KEY) ? fiber.instance_variable_get(IVAR_PID_KEY) : nil
-            return { stack: fiber.instance_variable_get(IVAR_KEY), pid: pid } if stored_pid == pid
-
-            # PID mismatch - reset
-            reset!
-          end
+        def current_frame
+          frame = Fiber[FRAME_KEY]
+          return nil unless frame&.pid == Process.pid
+          return nil unless frame.thread_id == Thread.current.object_id
 
-          stack = []
-          fiber.instance_variable_set(IVAR_KEY, stack)
-          fiber.instance_variable_set(IVAR_PID_KEY, pid)
-          { stack: stack, pid: pid }
+          frame
         end
 
         def validate_context(value)

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

@@ -7,6 +7,7 @@ require_relative '../execution_context'
 require_relative '../rails_integration'
 require_relative '../recorder'
 require_relative '../redactor'
+require_relative '../scheduler_snapshot'
 
 module FiberAudit
   module Runtime
@@ -27,7 +28,8 @@ module FiberAudit
           :thread_id,
           :fiber_id,
           :measurements,
-          :execution_context
+          :execution_context,
+          :scheduler_snapshot
         )
 
         attr_reader :recorder, :clock, :redactor, :active_operations, :owner_pid, :execution_context_store
@@ -125,13 +127,15 @@ module FiberAudit
             thread = Thread.current
             fiber = Fiber.current
             captured_context = capture_execution_context
+            captured_scheduler_snapshot = capture_scheduler_snapshot
             handle = active_operations.register(
               operation: canonical_operation,
               monotonic_ns: started_ns,
               location: location,
               execution_context: captured_context,
               thread: thread,
-              fiber: fiber
+              fiber: fiber,
+              scheduler_snapshot: captured_scheduler_snapshot
             )
             Observation.new(
               operation: canonical_operation,
@@ -141,7 +145,8 @@ module FiberAudit
               thread_id: thread.object_id,
               fiber_id: fiber.object_id,
               measurements: normalized_measurements,
-              execution_context: captured_context
+              execution_context: captured_context,
+              scheduler_snapshot: captured_scheduler_snapshot
             )
           end
           # rubocop:enable Metrics/BlockLength
@@ -155,6 +160,10 @@ module FiberAudit
           Context::UNKNOWN
         end
 
+        def capture_scheduler_snapshot
+          SchedulerSnapshotCapture.capture
+        end
+
         def emit_start_observation(observation)
           emit_observation(:operation_started, observation, monotonic_ns: observation.started_monotonic_ns)
         rescue StandardError => e
@@ -207,11 +216,14 @@ module FiberAudit
             values.merge!(generated)
           end
           values[:operation_sequence] = observation.handle&.sequence
+          # Include scheduler snapshot measurements (immutable, captured at operation start)
+          values.merge!(observation.scheduler_snapshot.to_measurements) if observation.scheduler_snapshot
           values
         end
 
         def emit_observation(kind, observation, monotonic_ns:, duration_ns: nil, measurements: nil)
           values = measurements || observation.measurements.merge(operation_sequence: observation.handle&.sequence)
+          values = merge_scheduler_measurements_for_emit(values.dup, observation.scheduler_snapshot)
           recorder.record do
             Event.new(
               kind: kind,
@@ -229,6 +241,15 @@ module FiberAudit
           end
         end
 
+        def merge_scheduler_measurements_for_emit(values, scheduler_snapshot)
+          return values unless scheduler_snapshot
+
+          scheduler_snapshot.to_measurements.each do |key, value|
+            values[key.to_sym] = value unless values.key?(key.to_sym)
+          end
+          values
+        end
+
         def normalize_measurements(value)
           raise RuntimeContractError, 'probe measurements must be a Hash' unless value.is_a?(Hash)