necropsy 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: acc21c7bf0937bb810decd0a6df03911149a32fc08146b15a37e74d133b397eb
-  data.tar.gz: 781f39ee1fb14299dbd9bedb6cad792785269517494b1d6c336fdb52674c10c2
+  metadata.gz: cc6a4c3ecf1f46c6950e6cb91e522d6162e41b1bc1b8e8b2aaa96a75b1ccb575
+  data.tar.gz: b77ffd85970bf4445c287cce8e3727c3e8ba675314ecfc5b9ce5cc8df73cbdf9
 SHA512:
-  metadata.gz: cef485cc0bb21d6e684107bb08f7882655ddf24600c9f9d53c744b5ce8a4cf78a460540c6bc9d981e652c6679f12641d34950761ceb1f78d17e8708436afc4d8
-  data.tar.gz: 787d658f3eb89506530b4467d3b7071ed9eccab5a9288b4e023e6b9dbcdd97f6a5b5a7127927d060f698deca80510d0ccd81e059a33990bb0531238d85c95ed4
+  metadata.gz: 6c86a65179785984b75bf39de3843ae5a2759b1e6c327ec7d9f6cbb88f961b0dfaa4944af69bd4aa602e0d27ac23accc69f62d344b55bd258779271047fd72fb
+  data.tar.gz: a91136e79e7056cc81c816be84b28b77598efc525e28304b530484282b045a5a8c463b0276dbfc487f5db0ee7fdf3c14aa137ed8c542cd94781e90794bb9e18e

data/.rubocop.yml

@@ -0,0 +1,33 @@
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.2
+  SuggestExtensions: false
+  CacheRootDirectory: tmp/rubocop_cache
+  Exclude:
+    - "pkg/**/*"
+    - "tmp/**/*"
+    - "vendor/**/*"
+
+Layout/LineLength:
+  Max: 150
+
+Lint/MissingSuper:
+  Enabled: false
+
+Naming/PredicateMethod:
+  Enabled: false
+
+Metrics:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Style/FetchEnvVar:
+  Enabled: false
+
+Style/HashSyntax:
+  EnforcedShorthandSyntax: never
+
+Style/MultilineBlockChain:
+  Enabled: false

data/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to Necropsy are documented in this file.
+
+## Unreleased
+
+## 0.2.0 - 2026-08-03
+
+- **Breaking:** Reports now omit `low` confidence findings by default, substantially reducing noisy output. Pass `--min-confidence low` to retain the previous output.
+- Improve analysis accuracy for qualified and inherited constants, implicit constructors, ambiguous calls, Ruby protocols, and framework callbacks, including Rails and RuboCop entry points.
+- Speed up analysis of large projects by indexing and caching call-graph resolution and resolving each call site only once.
+- Add `why` and `explain` commands to show shortest reachability paths, uncertainty, nearby live symbols, and confidence-score components in human or JSON output.
+- Add `report.include` and `report.exclude` to limit reported paths without removing code from the call graph, and warn when scan-path filters hide potential entry points.
+- Make CI and dynamic analysis more reliable with corrected ratchet behavior, hardened TracePoint/Coverage/Coverband imports, deterministic report ordering, and line-ending-safe quarantine writes.
+
+## 0.1.0 - 2026-07-09
+
+- Initial implementation.

data/MEASUREMENTS.md

@@ -0,0 +1,85 @@
+# Measurements
+
+Measurements are local wall-clock results. Compare runs made on the same machine and Ruby version; absolute timings are not portable.
+
+| date | commit | target | nodes | findings | ratio | seconds |
+|---|---|---|---:|---:|---:|---:|
+| 2026-08-01 | baseline | necropsy | 678 | 246 | 36.3% | 4.33 |
+| 2026-08-01 | +T-01 | necropsy | 678 | 56 | 8.3% | 4.33 |
+| 2026-08-01 | +T-02 | necropsy | 681 | 19 | 2.8% | 4.33 |
+| 2026-08-01 | +T-04,T-05 | necropsy | 681 | 19 | 2.8% | 0.52 |
+| 2026-08-01 | +T-04,T-05 | rubocop 1.75.0 | 8999 | 6039 | 67.1% | 20.50 |
+| 2026-08-02 | +T-06 | necropsy (Ruby 4.0.0) | 683 | 19 | 2.8% | 0.18 |
+| 2026-08-02 | +T-07 | necropsy (Ruby 4.0.0) | 686 | 19 | 2.8% | 0.20 |
+| 2026-08-02 | +T-07 | rubocop 1.75.0 (Ruby 4.0.0) | 8999 | 6029 | 67.0% | 6.53 |
+
+## Ambiguous fallback experiment
+
+RuboCop 1.75.0, Ruby 4.0.0. The limit of four is the smallest value with the lowest bounded finding count. Eight adds edges without reducing findings; unlimited has a small precision gain at a substantial runtime and recall risk.
+
+| ambiguity limit | nodes | edges | findings | medium | low | seconds |
+|---:|---:|---:|---:|---:|---:|---:|
+| 1 (previous behavior) | 8999 | 44313 | 6039 | 1039 | 5000 | 5.96 |
+| 2 | 8999 | 46398 | 6032 | 1292 | 4740 | 6.32 |
+| 4 (selected) | 8999 | 46607 | 6029 | 1789 | 4240 | 6.76 |
+| 8 | 8999 | 46951 | 6029 | 2184 | 3845 | 6.77 |
+| unlimited | 8999 | 70616 | 5931 | 2351 | 3580 | 10.27 |
+
+The 19 self-analysis findings remain unchanged at every tested limit, including the verified dead methods `Necropsy::CallGraph#modules_for` and `Necropsy::EntryPoints::Rails#helper_referenced?`.
+
+## Default reporting threshold
+
+RuboCop 1.75.0 at ambiguity limit four:
+
+| threshold | reported findings |
+|---|---:|
+| `medium` (selected default) | 1789 |
+| `low` (explicit compatibility mode) | 6029 |
+
+## Implicit caller experiment
+
+RuboCop 1.75.0 at ambiguity limit four and the default `medium` reporting threshold:
+
+| rules | reported findings | change |
+|---|---:|---:|
+| none | 1789 | baseline |
+| Ruby hooks and protocols | 1785 | -4 |
+| Ruby rules plus scoped RuboCop `on_*` rule | 1161 | -624 |
+| Rules plus transitive implicit-caller uncertainty | 359 | -802 |
+
+The RuboCop rule is enabled as a built-in framework pack because its ancestor constraint limits it to commissioner-dispatched cop callbacks. The same rule remains configurable for other frameworks through `implicit_callers`.
+
+## Report path experiment
+
+RuboCop 1.75.0 at the default `medium` reporting threshold:
+
+| configuration | graph nodes | raw findings | reported findings | outside `lib/` |
+|---|---:|---:|---:|---:|
+| full scan and report | 8999 | 6029 | 1161 | 4 |
+| `report.include: ["lib/**"]` | 8999 | 6029 | 1157 | 0 |
+| `paths.include: ["lib/**"]` | 8131 | — | 1552 | 0 |
+
+`report.include` preserves the full graph and removes only four out-of-scope reports. `paths.include` removes 868 graph nodes, emits an entry-point warning, and increases reported findings by 34%.
+
+## Debride comparison
+
+Debride 1.15.2 and Necropsy's default `medium` threshold, both restricted to RuboCop 1.75.0's `lib/` definitions. Debride output was mapped back to fully qualified Necropsy node IDs; 19 unmatched debride entries were constants or definitions without an unambiguous method ID.
+
+| set | methods |
+|---|---:|
+| debride | 718 |
+| Necropsy | 355 |
+| both | 39 |
+| debride only | 679 |
+| Necropsy only | 316 |
+
+Twenty alphabetically stable entries from each exclusive set were inspected against RuboCop source and specs.
+
+- Debride-only: 4/20 were probable production-dead compatibility methods (`ConfigLoader.inject_defaults!`, `Alignment#end_of_line_comment`, `AllowedPattern#ignored_line?`, and `AllowedPattern#matches_ignored_pattern?`). The other 16 were a test-only generated writer, public subclass API, node-pattern callback, or commissioner-dispatched `on_*` callbacks.
+- Necropsy-only: 0/20 were probable dead methods. Two `CopsDocumentationGenerator` methods are called through the `STRUCTURE` lambda table and a Rake entry point. The other 18 belong to CLI command subclasses selected through `Base.by_command_name` and constructed dynamically.
+
+The sample shows why the sets overlap only slightly: debride reports Ruby/RuboCop callbacks by name, while Necropsy's remaining false positives cluster around registry-selected classes and callable tables. The next diagnostic priority is therefore witness/explanation support; adding broader survival rules without path evidence would risk hiding the four probable true positives found in the debride-only sample.
+
+## Witness storage
+
+RuboCop 1.75.0 retained 6,029 raw findings and 359 default reports after predecessor paths were added. Wall time was 5.35 seconds and peak RSS was 557.0 MB, below the 600 MB guardrail.

data/README.md

@@ -5,13 +5,13 @@ collects method definitions with Prism, adds call-edge evidence from static and
 optional dynamic analyzers, then runs reachability from framework and configured
 entry points.
 
-The first implementation includes:
+Necropsy includes:
 
-- Prism-based method collection for `def`, `define_method`, `attr_*`, and `delegate`
+- Prism-based method collection for ordinary, singleton, delegated, aliased, forwarded, and dynamically defined methods
 - static name resolution, CHA, and RTA-style filtering over instantiated classes
-- Rails route/callback/view-helper/component, plain Ruby, and test-suite entry point providers
+- Prism-backed Rails route parsing plus callback, view, component, migration, plain Ruby, and test-suite entry points
 - `unreachable`, `unused`, and `test_only_reachable` classifications
-- confidence levels, JSON/YAML/human/SARIF/GitHub reports, baseline/check guardrails, quarantine suggestions, TracePoint recording, and a bench evaluator
+- confidence levels, compact JSON/YAML reports, SARIF/GitHub output, CI guardrails, dynamic collectors, and benchmarking
 
 ## Installation
 
@@ -33,8 +33,25 @@ Run a report:
 
 ```bash
 bundle exec necropsy analyze --root . --format human
+bundle exec necropsy analyze --root . --min-confidence low # include exploratory findings
+bundle exec necropsy --version
 ```
 
+Reports omit `low` confidence findings by default. Pass `--min-confidence low`
+to retain the pre-0.2 behavior.
+
+Inspect why a symbol is alive or dead, including the shortest evidenced path,
+nearby alive node, and unresolved dispatch notes:
+
+```bash
+bundle exec necropsy why 'MyService#call' --root .
+bundle exec necropsy why 'MyService#call' --root . --format json
+bundle exec necropsy explain 'LegacyService#unused' --root .
+```
+
+`explain` shows every confidence score component and the final confidence
+level. Missing symbol IDs return partial-match suggestions.
+
 Fail CI only for new high-confidence findings:
 
 ```bash
@@ -63,6 +80,9 @@ Evaluate against a gold standard:
 bundle exec necropsy bench --root . --gold-standard gold.yml --ablation
 ```
 
+JSON and YAML omit the full call graph by default. Add `--include-graph` when
+nodes, edges, evidence, and entry points are needed in machine-readable output.
+
 Example configuration:
 
 ```yaml
@@ -77,10 +97,22 @@ analyzers:
     trace_point:
       source: tmp/necropsy_trace_point.yml
   custom:
-    - "MyCompany::GraphqlEntryAnalyzer"
+    - class: "MyCompany::GraphqlEntryAnalyzer"
+      require: "config/necropsy/graphql_entry_analyzer"
 cache:
   enabled: true
-  path: .necropsy_cache/scan.yml
+  path: .necropsy_cache/scan.json
+resolution:
+  ambiguity_limit: 4 # use "unlimited" to retain every same-name candidate
+implicit_callers:
+  - name_pattern: "^on_"
+    owner_ancestors: ["RuboCop::Cop::Base"]
+    reason: "RuboCop Commissioner callback"
+paths:
+  exclude: ["app/legacy/**/*.rb"]
+report:
+  include: ["app/**", "lib/**"]
+  exclude: ["lib/generated/**"]
 entry_points:
   extra:
     - "PublicApi::*"
@@ -91,17 +123,35 @@ quarantine:
   days: 30
 bench:
   precision_threshold: 0.85
+logging:
+  verbose: false
 ```
 
 The scan cache is invalidated when scanned Ruby files or configuration values
 change.
 
+When a call receiver cannot be resolved exactly, Necropsy conservatively keeps
+up to `resolution.ambiguity_limit` same-name candidates alive. The default of
+four is based on the RuboCop 1.75.0 measurements in `MEASUREMENTS.md`.
+
+Ruby VM hooks and common protocol methods receive lower confidence because
+their callers may not appear in source. Add `implicit_callers` rules for
+framework or application callbacks; `owner_ancestors` is optional.
+
+`paths.include` narrows the source files used to construct the call graph and
+can remove executables, tests, routes, and other entry points. Use
+`report.include` and `report.exclude` when the full project should be analyzed
+but only selected application paths should be reported. Necropsy warns when a
+configured `paths.include` excludes detected entry-point files.
+
 Dynamic inputs may provide `executed` or `nodes` entries with method IDs,
 `edges` with `caller_id`/`callee_id`, and an `observation` hash. SARIF and
 GitHub Actions annotations are available via `--format sarif` and
 `--format github`.
 
-Coverband file, Redis string, and Redis hash exports are supported. Rails route
+Coverband file, Redis string, and Redis hash exports are supported. Redis URLs
+may include an ACL username and password; `connect_timeout` and `read_timeout`
+can be set in the Coverband analyzer configuration. Rails route
 entry point detection covers common `resources`, `resource`, `namespace`,
 `scope`, `controller`, `concerns`, `draw`, `mount`, `root`, and verb route
 forms.
@@ -112,7 +162,9 @@ the finding is raised to `certain`.
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then run
+`bundle exec rake` for the specs and RuboCop checks. Use `bin/console` for an
+interactive prompt.
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 

data/Rakefile

@@ -1,8 +1,10 @@
 # frozen_string_literal: true
 
 require 'bundler/gem_tasks'
+require 'rubocop/rake_task'
 require 'rspec/core/rake_task'
 
 RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new
 
-task default: :spec
+task default: %i[spec rubocop]

data/lib/necropsy/analyzers/dynamic/coverage_collector.rb

@@ -63,11 +63,21 @@ module Necropsy
 
         def coverage_result(started:)
           return Coverage.result(stop: true, clear: true) if started && Coverage.running?
-          return Coverage.peek_result if Coverage.respond_to?(:peek_result) && Coverage.running?
+
+          if Coverage.respond_to?(:peek_result) && Coverage.running?
+            result = Coverage.peek_result
+            return result if method_coverage?(result)
+
+            warn 'Necropsy coverage collector found Coverage already running without methods: true; no methods were recorded.'
+          end
 
           {}
         end
 
+        def method_coverage?(result)
+          result.values.any? { |coverage| coverage.is_a?(Hash) && coverage.key?(:methods) }
+        end
+
         def write_payload(result:, started_at:, finished_at:)
           payload = {
             'nodes' => executed_nodes(result).sort,
@@ -99,7 +109,7 @@ module Necropsy
           content = file.read
           return {} if content.empty?
 
-          YAML.load(content) || {}
+          YAML.safe_load(content, aliases: false) || {}
         rescue Psych::Exception
           {}
         end

data/lib/necropsy/analyzers/dynamic/coverage_importer.rb

@@ -56,12 +56,16 @@ module Necropsy
         attr_reader :config
 
         def load_payload(path)
+          raise Error, "Coverage source does not exist: #{path}" unless File.file?(path)
+
           case File.extname(path)
           when '.json'
             JSON.parse(File.read(path))
           else
-            YAML.load_file(path) || {}
+            YAML.safe_load_file(path, aliases: false) || {}
           end
+        rescue JSON::ParserError, Psych::Exception => e
+          raise Error, "Could not parse coverage source #{path}: #{e.message}"
         end
       end
     end

data/lib/necropsy/analyzers/dynamic/coverband_importer.rb

@@ -52,12 +52,16 @@ module Necropsy
           return load_redis_payload(source) if source.start_with?('redis://', 'rediss://')
 
           path = File.expand_path(source, root)
+          raise Error, "Coverband source does not exist: #{path}" unless File.file?(path)
+
           case File.extname(path)
           when '.json'
             JSON.parse(File.read(path))
           else
-            YAML.load_file(path) || {}
+            YAML.safe_load_file(path, aliases: true) || {}
           end
+        rescue JSON::ParserError, Psych::Exception => e
+          raise Error, "Could not parse Coverband source #{path}: #{e.message}"
         end
 
         def load_redis_payload(source)
@@ -145,6 +149,8 @@ module Necropsy
 
       class RedisPayloadLoader
         DEFAULT_PATTERN = 'coverband*'
+        DEFAULT_CONNECT_TIMEOUT = 5.0
+        DEFAULT_READ_TIMEOUT = 5.0
 
         def initialize(source:, config:)
           @uri = URI(source)
@@ -166,8 +172,12 @@ module Necropsy
         attr_reader :uri, :config, :socket
 
         def connect
-          tcp_socket = TCPSocket.new(uri.host, uri.port || 6379)
+          tcp_socket = Socket.tcp(uri.host, uri.port || 6379, connect_timeout: connect_timeout)
+          apply_read_timeout(tcp_socket)
           @socket = uri.scheme == 'rediss' ? tls_socket(tcp_socket) : tcp_socket
+        rescue SystemCallError, SocketError, IO::TimeoutError => e
+          tcp_socket&.close
+          raise Error, "Could not connect to Redis at #{uri.host}:#{uri.port || 6379}: #{e.message}"
         end
 
         def tls_socket(tcp_socket)
@@ -181,7 +191,10 @@ module Necropsy
         def authenticate
           return unless uri.password
 
-          command('AUTH', uri.password)
+          password = URI.decode_www_form_component(uri.password)
+          return command('AUTH', password) unless uri.user
+
+          command('AUTH', URI.decode_www_form_component(uri.user), password)
         end
 
         def select_database
@@ -214,6 +227,8 @@ module Necropsy
         def command(*parts)
           socket.write(redis_command(parts))
           read_response
+        rescue IOError, SystemCallError, OpenSSL::SSL::SSLError => e
+          raise Error, "Redis connection failed: #{e.message}"
         end
 
         def payload_for_key(key)
@@ -225,44 +240,83 @@ module Necropsy
         end
 
         def redis_command(parts)
-          ["*#{parts.length}", *parts.flat_map { |part| ["$#{part.to_s.bytesize}", part.to_s] }].join("\r\n") + "\r\n"
+          "#{["*#{parts.length}", *parts.flat_map { |part| ["$#{part.to_s.bytesize}", part.to_s] }].join("\r\n")}\r\n"
         end
 
         def read_response
-          prefix = socket.read(1)
+          prefix = read_exact(1)
           case prefix
           when '+'
-            socket.gets("\r\n").delete_suffix("\r\n")
+            read_line
           when '-'
-            raise Error, socket.gets("\r\n").delete_suffix("\r\n")
+            raise Error, read_line
           when ':'
-            socket.gets("\r\n").to_i
+            read_line.to_i
           when '$'
             read_bulk_string
           when '*'
-            Array.new(socket.gets("\r\n").to_i) { read_response }
+            length = read_line.to_i
+            return nil if length.negative?
+
+            Array.new(length) { read_response }
           else
             raise Error, "Unsupported Redis response prefix #{prefix.inspect}"
           end
         end
 
         def read_bulk_string
-          length = socket.gets("\r\n").to_i
+          length = read_line.to_i
           return nil if length.negative?
 
+          value = read_exact(length)
+          read_exact(2)
+          value
+        end
+
+        def read_line
+          line = socket.gets("\r\n")
+          raise Error, 'Redis closed the connection while reading a response' unless line
+
+          line.delete_suffix("\r\n")
+        end
+
+        def read_exact(length)
           value = socket.read(length)
-          socket.read(2)
+          raise Error, 'Redis closed the connection while reading a response' unless value&.bytesize == length
+
           value
         end
 
+        def connect_timeout
+          Float(config.fetch('connect_timeout', DEFAULT_CONNECT_TIMEOUT))
+        rescue ArgumentError, TypeError
+          DEFAULT_CONNECT_TIMEOUT
+        end
+
+        def read_timeout
+          Float(config.fetch('read_timeout', DEFAULT_READ_TIMEOUT))
+        rescue ArgumentError, TypeError
+          DEFAULT_READ_TIMEOUT
+        end
+
+        def apply_read_timeout(tcp_socket)
+          seconds = read_timeout
+          timeout = [seconds.to_i, ((seconds % 1) * 1_000_000).to_i].pack('l_2')
+          tcp_socket.setsockopt(Socket::SOL_SOCKET, Socket::SO_RCVTIMEO, timeout)
+        end
+
         def parse_payload(value)
           return nil if value.nil? || value.empty?
 
           JSON.parse(value)
         rescue JSON::ParserError
-          YAML.load(value)
-        rescue Psych::SyntaxError
-          Marshal.load(value)
+          parse_yaml_payload(value)
+        end
+
+        def parse_yaml_payload(value)
+          YAML.safe_load(value, aliases: false)
+        rescue Psych::Exception, ArgumentError, EncodingError => e
+          raise Error, "Invalid Redis coverage payload: #{e.message}"
         end
 
         def parse_hash_payload(entries)

data/lib/necropsy/analyzers/dynamic/trace_point_collector.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'securerandom'
+require 'fileutils'
 require 'time'
 require 'yaml'
 
@@ -12,13 +13,22 @@ module Necropsy
           new(root: root, output: output, sample_rate: sample_rate).record(&)
         end
 
-        def initialize(root:, output:, sample_rate: 1.0)
+        def self.install_at_exit(root:, output:, sample_rate: 1.0, merge: false, run_id: nil)
+          new(root: root, output: output, sample_rate: sample_rate, merge: merge, run_id: run_id).install_at_exit
+        end
+
+        def initialize(root:, output:, sample_rate: 1.0, merge: false, run_id: nil)
           @root = File.expand_path(root)
           @output = output
           @sample_rate = sample_rate.to_f
+          raise Error, 'sample_rate must be between 0.0 and 1.0' unless @sample_rate.between?(0.0, 1.0)
+
           @nodes = {}
           @edges = {}
-          @stack = []
+          @stacks = {}.compare_by_identity
+          @lock = Mutex.new
+          @merge = merge
+          @run_id = run_id
         end
 
         def record
@@ -31,27 +41,55 @@ module Necropsy
           write_payload(started_at: started_at, finished_at: Time.now.utc)
         end
 
+        def install_at_exit
+          started_at = Time.now.utc
+          tracer = TracePoint.new(:call, :return) { |event| capture(event) }
+          tracer.enable
+          at_exit do
+            tracer.disable
+            write_payload(started_at: started_at, finished_at: Time.now.utc)
+          rescue StandardError => e
+            warn "Necropsy TracePoint collector failed: #{e.message}"
+          end
+        end
+
         private
 
-        attr_reader :root, :output, :sample_rate, :nodes, :edges, :stack
+        attr_reader :root, :output, :sample_rate, :nodes, :edges, :stacks, :lock, :run_id
+
+        def merge?
+          @merge
+        end
 
         def capture(event)
           return unless project_path?(event.path)
-          return if sample_rate < 1.0 && SecureRandom.random_number > sample_rate
 
           node_id = node_id_for(event)
           return unless node_id
 
-          if event.event == :return
-            stack.pop if stack.last == node_id
-            return
+          lock.synchronize do
+            stack = stacks[Thread.current] ||= []
+            if event.event == :return
+              unwind_stack(stack, node_id)
+              stacks.delete(Thread.current) if stack.empty?
+              return
+            end
+
+            sampled = sample_rate >= 1.0 || (sample_rate.positive? && SecureRandom.random_number < sample_rate)
+            caller_id = stack.last&.first if stack.last&.last
+            if sampled
+              nodes[node_id] = true
+              edges[[caller_id, node_id]] = true if caller_id
+            end
+            stack << [node_id, sampled]
           end
+        end
 
-          caller_id = stack.last
-          nodes[node_id] = true
-          edges[[caller_id, node_id]] = true if caller_id
+        def unwind_stack(stack, node_id)
+          index = stack.rindex { |frame| frame.first == node_id }
+          return unless index
 
-          stack << node_id
+          stack.slice!(index..)
         end
 
         def project_path?(path)
@@ -88,7 +126,64 @@ module Necropsy
               'sample_rate' => sample_rate
             }
           }
-          File.write(output, payload.to_yaml)
+          payload['observation']['run_id'] = run_id if run_id
+          FileUtils.mkdir_p(File.dirname(output))
+          merge? ? write_merged_payload(payload) : File.write(output, payload.to_yaml)
+        end
+
+        def write_merged_payload(payload)
+          File.open(output, File::RDWR | File::CREAT, 0o644) do |file|
+            file.flock(File::LOCK_EX)
+            existing = trace_payload_for_current_run(read_payload(file), payload)
+            merged = merge_payload(existing, payload)
+            file.rewind
+            file.truncate(0)
+            file.write(merged.to_yaml)
+            file.flush
+          end
+        end
+
+        def read_payload(file)
+          file.rewind
+          content = file.read
+          return {} if content.empty?
+
+          YAML.safe_load(content, aliases: false) || {}
+        rescue Psych::Exception
+          {}
+        end
+
+        def trace_payload_for_current_run(existing, payload)
+          current_run = payload.dig('observation', 'run_id')
+          return existing unless current_run
+          return existing if existing.empty? || existing.dig('observation', 'run_id') == current_run
+
+          {}
+        end
+
+        def merge_payload(left, right)
+          edges = (Array(left['edges']) + Array(right['edges'])).uniq do |edge|
+            [edge['caller_id'], edge['callee_id']]
+          end
+          left_observation = left.fetch('observation', {})
+          right_observation = right.fetch('observation', {})
+          observation = left_observation.merge(right_observation)
+          observation['started_at'] = [left_observation['started_at'], right_observation['started_at']].compact.min
+          observation['finished_at'] = [left_observation['finished_at'], right_observation['finished_at']].compact.max
+          observation['days'] = [left_observation['days'].to_i, right_observation['days'].to_i, 1].max
+          observation['processes'] = process_count(left_observation) + process_count(right_observation)
+          {
+            'nodes' => (Array(left['nodes']) + Array(right['nodes'])).uniq.sort,
+            'edges' => edges,
+            'observation' => observation
+          }
+        end
+
+        def process_count(observation)
+          return observation['processes'].to_i if observation['processes']
+          return 0 if observation.empty?
+
+          1
         end
       end
     end