necropsy 0.2.0 → 0.3.0

data/bench/review_queue.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'fileutils'
+require 'optparse'
+require 'yaml'
+require_relative '../lib/necropsy'
+
+root = File.expand_path('..', __dir__)
+options = {
+  input: File.join(root, 'bench/golden/v1/reports'),
+  output: File.join(root, 'bench/audits/0.2.1/review_queue.yml'),
+  target: 300
+}
+
+OptionParser.new do |parser|
+  parser.banner = 'Usage: bundle exec ruby bench/review_queue.rb [options]'
+  parser.on('--input DIR', 'Directory containing normalized report JSON files') { |path| options[:input] = path }
+  parser.on('--output PATH', 'Review queue YAML output path') { |path| options[:output] = path }
+  parser.on('--target COUNT', Integer, 'Required reviewed high-candidate target') { |count| options[:target] = count }
+end.parse!
+
+reports = Dir.glob(File.join(File.expand_path(options.fetch(:input), root), '*.json')).to_h do |path|
+  [File.basename(path, '.json'), JSON.parse(File.read(path))]
+end
+raise Necropsy::Error, 'No normalized reports were found for review queue generation' if reports.empty?
+
+queue = Necropsy::Bench::ReviewQueue.new(
+  reports: reports,
+  target_reviewed_high: options.fetch(:target)
+).call
+output = File.expand_path(options.fetch(:output), root)
+FileUtils.mkdir_p(File.dirname(output))
+File.write(output, YAML.dump(queue))
+puts "review queue: #{output} (#{queue.fetch('queued_candidates')} pending entries)"

data/bench/run.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'optparse'
+require_relative '../lib/necropsy'
+require_relative '../lib/necropsy/bench/seed_runner'
+
+root = File.expand_path('..', __dir__)
+options = {
+  manifest: File.join(__dir__, 'corpora/v1/manifest.yml'),
+  output: File.join(root, 'tmp/necropsy-benchmark/v1')
+}
+
+OptionParser.new do |parser|
+  parser.banner = 'Usage: bundle exec ruby bench/run.rb [options]'
+  parser.on('--manifest PATH', 'Corpus manifest path') { |path| options[:manifest] = path }
+  parser.on('--output DIR', 'Generated result directory') { |path| options[:output] = path }
+  parser.on('--update-golden REASON', 'Replace deterministic golden files with an audit reason') do |reason|
+    options[:update_golden_reason] = reason
+  end
+end.parse!
+
+runner = Necropsy::Bench::SeedRunner.new(
+  manifest_path: options.fetch(:manifest),
+  output_dir: options.fetch(:output)
+)
+summary = runner.call(update_golden_reason: options[:update_golden_reason])
+puts "summary: #{File.join(File.expand_path(options.fetch(:output)), 'summary.json')}"
+failed_corpus = summary.fetch('corpora').any? { |corpus| corpus['status'] == 'failed' }
+golden_mismatch = summary.dig('golden', 'status') != 'match'
+precision_failure = summary.dig('precision_gate', 'passed') == false
+exit(failed_corpus || golden_mismatch || precision_failure ? 1 : 0)

data/bench/schema/candidate-union-v1.schema.json

@@ -0,0 +1,70 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/ydah/necropsy/bench/schema/candidate-union-v1.schema.json",
+  "title": "Necropsy candidate union",
+  "type": "object",
+  "required": ["schema_version", "tool_runs", "summary", "candidates"],
+  "properties": {
+    "schema_version": { "const": 1 },
+    "tool_runs": { "type": "object", "additionalProperties": { "$ref": "#/$defs/toolRun" } },
+    "summary": { "type": "object" },
+    "candidates": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/candidate" }
+    }
+  },
+  "$defs": {
+    "toolRun": {
+      "type": "object",
+      "required": ["status"],
+      "properties": {
+        "status": { "enum": ["generated", "snapshot", "skipped"] },
+        "version": { "type": ["string", "null"] },
+        "diagnostic": { "type": "string" },
+        "snapshot_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+        "provenance": { "type": ["object", "string"] }
+      }
+    },
+    "toolResult": {
+      "type": "object",
+      "required": ["candidate"],
+      "properties": {
+        "candidate": { "type": ["boolean", "null"] },
+        "status": { "enum": ["skipped"] },
+        "state": { "type": "string" },
+        "confidence": { "type": "string" },
+        "classification": { "type": "string" }
+      }
+    },
+    "label": {
+      "type": "object",
+      "required": ["value", "rationale"],
+      "properties": {
+        "value": { "enum": ["dead", "alive", "external", "unknown"] },
+        "rationale": { "type": "string", "minLength": 1 },
+        "reviewer": { "type": "string" }
+      }
+    },
+    "candidate": {
+      "type": "object",
+      "required": ["corpus", "id", "tool_results"],
+      "properties": {
+        "corpus": { "type": "string" },
+        "id": { "type": "string" },
+        "path": { "type": "string" },
+        "line": { "type": "integer", "minimum": 1 },
+        "label": { "$ref": "#/$defs/label" },
+        "tool_results": {
+          "type": "object",
+          "required": ["necropsy", "debride", "spoom", "type_aware"],
+          "properties": {
+            "necropsy": { "$ref": "#/$defs/toolResult" },
+            "debride": { "$ref": "#/$defs/toolResult" },
+            "spoom": { "$ref": "#/$defs/toolResult" },
+            "type_aware": { "$ref": "#/$defs/toolResult" }
+          }
+        }
+      }
+    }
+  }
+}

data/docs/impv_implementation_matrix.md

@@ -0,0 +1,179 @@
+# `.idea/impv.md` implementation matrix
+
+Reviewed against the working implementation on 2026-08-12. “Safe equivalent” means the proposed
+mechanism was not copied literally, but its removal-safety or operability goal is enforced by a
+smaller reviewed contract. “No-go” is an explicit adversarial decision with a reconsideration gate
+in the linked ADR; it does not mean silently deferred work.
+
+## 1–38: finite flow, Ruby semantics, and health
+
+| # | Disposition | Evidence and decision |
+|---:|---|---|
+| 1 | Implemented | Dynamic send reads argument zero only; adversarial later literals, splats, forwarding, and finite names are covered in `flow_interpreter_spec.rb`. |
+| 2 | Implemented | Unsupported/control-flow writes invalidate exact local facts in `flow_interpreter.rb`; monotonic safety specs compare candidate sets. |
+| 3 | Implemented | No-else `if` joins the pre-branch environment. |
+| 4 | Implemented | Case predicates/guards are evaluated and the unmatched path is joined. |
+| 5 | Implemented | `and`/`or` use short-circuit path joins rather than unconditional right-side effects. |
+| 6 | Implemented | Lambda capture uses an isolated environment; construction does not mutate outer locals. |
+| 7 | Implemented | Return/break/next/raise-like termination is represented by transfer state and unreachable tails do not refine facts. |
+| 8 | Implemented | Hash splats and unknown keys make the container partial/unknown. |
+| 9 | Implemented | Symbol and string keys remain distinct and finite candidate keys are joined. |
+| 10 | Implemented | `.new` is exact only for a proven core constructor path; overridden/unknown constructors remain hints. |
+| 11 | Implemented | Modifier `private def`/`protected def` visits the nested definition without changing ambient visibility. |
+| 12 | Implemented | Modifier `module_function def` creates the private instance definition and physical singleton copy without leaking mode. |
+| 13 | Implemented | Positional and keyword default expressions are visited in method caller context. |
+| 14 | Implemented | Every semantic call handler returns `CallTraversal(receiver, arguments, block)`; wrong contracts raise. |
+| 15 | Implemented | Dynamic `define_method` gets an owner-scoped blocker and isolated synthetic body. |
+| 16 | Implemented | `class << Constant` uses the constant singleton owner; a dynamic expression is blocked. |
+| 17 | Implemented | Dynamic `def receiver.name` is isolated behind a dynamic singleton-definition blocker. |
+| 18 | Implemented | Dynamic superclass expressions are visited and never substituted with `Object`. |
+| 19 | Implemented | Scanner context carries lexical nesting separately from the definition owner. |
+| 20 | Implemented | Pattern matching is ancestry control flow; unknown semantic shapes fail closed via the generated semantics matrix. |
+| 21 | Implemented | `class_exec`, `module_exec`, and `instance_exec` use bounded owners or a synthetic blocked context. |
+| 22 | Implemented | Dynamic attr/delegate/Forwardable/Struct/Data names emit generated-surface blockers and still traverse inputs. |
+| 23 | Safe equivalent | `remove_method`/`undef_method` are activation blockers, so stale definitions are never treated as exact. Full activation simulation is intentionally not claimed. |
+| 24 | Implemented | Alias/module-function relations retain physical source definitions when provable; ambiguity keeps duplicate/activation blockers. |
+| 25 | Implemented | Visibility mutation considers physical definitions and retains uncertainty when activation order is not closed. |
+| 26 | Implemented | Literal callback `if:`/`unless:` method names become callback roots; static disablement and dynamic conditions are distinguished. |
+| 27 | Implemented | Callback blocks receive synthetic rooted definitions. |
+| 28 | Implemented | Dynamic routes use owner, namespace, message, or global residual scope based on known context. |
+| 29 | Implemented | Route read/encoding/parse failures create global `rails_route_health` blockers and degraded health. |
+| 30 | Implemented | Oversized, unreadable, generated, and budget-skipped runtime references create a global blocker and degraded health. |
+| 31 | Implemented | Discovery records unreadable paths and symlinks with domain provenance; unsafe runtime omissions block findings. |
+| 32 | Implemented | `analysis_health` separates degraded/invalid analysis from findings; check, baseline, write quarantine, and release bench fail closed. |
+| 33 | Implemented | Analyzer results are validated on a staged graph and committed atomically. |
+| 34 | Implemented | Cache read/write rescue boundaries cannot execute the scan block twice. |
+| 35 | Implemented | Pre/post source snapshots must match; a concurrent change makes analysis invalid. |
+| 36 | Implemented | Normal check accepts exact v2 identity only; non-exact legacy migration produces an explicit review report. |
+| 37 | Implemented | Baseline, ratchet, check, and benchmark gates use actionable classifications only. |
+| 38 | Implemented | `bench --check` returns nonzero when release criteria fail. |
+
+## 39–72: graph semantics and additional static analysis
+
+| # | Disposition | Evidence and decision |
+|---:|---|---|
+| 39 | Implemented | `paths.test` configures test domains, including `features/` and nested engine layouts. |
+| 40 | Implemented | File-root identity is path/load-unit based; content digest is separate provenance. |
+| 41 | Implemented | Definition and call-site identity schemas are versioned and reported with Ruby/Prism/tool versions. |
+| 42 | Implemented | `load_graph.rb` adds only literal require/require_relative/autoload evidence and blocks unresolved load targets. |
+| 43 | Implemented | Unrooted load units with side-effectful bodies are emitted as bounded diagnostics. |
+| 44 | No-go | Shadow classification without a closed activation witness is unsafe; duplicates remain physical and blocked. See `necropsy_scope_decisions.md`. |
+| 45 | Implemented | Runtime/test definition indexes are separate for ambiguity fallback. |
+| 46 | Implemented | Partial/unknown resolutions use the smallest proven owner/namespace/message residual scope. |
+| 47 | Safe equivalent | A flow-budget miss falls back at the affected site; only an unscoped semantic loss can widen a blocker. |
+| 48 | Implemented | Dynamic ancestry is owner/descendant or namespace scoped; only Object/Kernel/unknown surfaces go global. |
+| 49 | Implemented | CHA delegates lookup order to the canonical CallGraph APIs. |
+| 50 | Implemented | Singleton lookup does not fall back to the owner's instance surface. |
+| 51 | Implemented | Include/prepend/extend have distinct instance and singleton lookup relations. |
+| 52 | No-go | Default RTA is non-pruning, so a second root-seeded fixed point has no safety benefit absent measured precision gain. See `necropsy_scope_decisions.md`. |
+| 53 | Implemented | Legacy RTA pruning adds invalid health; CI cannot allow it as a degraded exception. |
+| 54 | Safe equivalent | Factory-name evidence is rank-only and cannot refute targets; exact construction still requires receiver/core-constructor proof. |
+| 55 | Implemented | Core protocol summaries transform receivers/arguments/elements and encode block-state semantics; user methods with the same name do not trigger them. |
+| 56 | Implemented | Derived protocol operations are first-class call sites with identities, resolutions, blockers, and diagnostics. |
+| 57 | Implemented | Unresolved dispatch derives owner-scoped `method_missing` and implicit-private `respond_to_missing?` calls, respecting overrides. |
+| 58 | Safe equivalent | Name-only discounts were narrowed to VM hooks/core protocols; concrete implicit operations produce edges and numeric scores remain ranking only. |
+| 59 | Safe equivalent | Resolution status/scope, health, world policy, blockers, and evidence grade form the actionability claims; confidence numbers cannot override them. |
+| 60 | Implemented | Only analyzers declaring `complete_resolution` capability may emit a complete resolution. |
+| 61 | No-go | An RBS provider lacks a reviewed stale/conflicting-signature target corpus; syntax fixtures are insufficient. See `necropsy_type_facts_adr.md`. |
+| 62 | No-go | Sorbet/RBI ingestion has the same unproven open-world contract and a larger generated-RBI surface. See the type-facts ADR. |
+| 63 | No-go | Demand-driven interprocedural points-to is excluded from removal decisions until the type/alias/load-order gate is met. |
+| 64 | No-go | Interprocedural return summaries are not promoted without a purity/mutation corpus; local return facts stay bounded. |
+| 65 | No-go | Argument-to-parameter propagation is not promoted without dispatch and mutation labels; call arguments remain recorded evidence. |
+| 66 | No-go | Constructor ivar summaries are not promoted without aliasing/reopen coverage. |
+| 67 | Safe equivalent | Literal Proc/lambda/block values flow locally and fail closed at method boundaries; interprocedural promotion follows the type-facts gate. |
+| 68 | No-go | Cross-file constant facts require proven activation/load order; literal local containers and class objects remain available without that claim. |
+| 69 | No-go | Physical definitions remain the removal/review unit; cycle collapsing can hide mixed-risk members. See `necropsy_scope_decisions.md`. |
+| 70 | No-go | Per-definition why-not already exposes boundary sites/blockers; cluster frontier awaits the documented review-time gate. |
+| 71 | Implemented | Why-not emits bounded, structured `suggested_next_evidence` for receiver, route, parser, runtime, and caller gaps. |
+| 72 | Safe equivalent | Typed load evidence and unrooted-load diagnostics keep activation distinct without a second mutable graph; split only at the ADR gate. |
+
+## 73–96: Rails, frameworks, and external references
+
+| # | Disposition | Evidence and decision |
+|---:|---|---|
+| 73 | Implemented | Rails-generated definitions are excluded from removal findings and summarized by source macro. |
+| 74 | Safe equivalent | Both enum declaration forms, prefix/suffix, scopes, and instance-method flags are modeled; dynamic/version-dependent forms block the owner instead of guessing. |
+| 75 | Implemented | Belongs-to/has-one and collection associations generate distinct APIs; invalid collection build/create methods are not invented. |
+| 76 | Implemented | Attribute, class/mattr/cattr, store, and store_accessor declarations share generated-method handling and are never removal candidates. |
+| 77 | Implemented | Rails scope and enum scopes are singleton generated methods; literal scope bodies attach calls to the generated definition. |
+| 78 | Safe equivalent | Prism first verifies route DSL calls and static argument shapes; regex is restricted to the verified call slice. Unrelated Ruby strings cannot root routes. |
+| 79 | Implemented | Canonical inflection blocks are parsed structurally for literal irregular/acronym/uncountable declarations; unsupported plural rules globally block pruning. |
+| 80 | Implemented | Only executable ERB regions are parsed with Prism; HTML and ERB comments cannot root/block methods. |
+| 81 | No-go | Pretending generic token extraction is a sound Haml/Slim/Jbuilder/Builder parser is rejected; unparsed inputs remain conservative blockers. See scope decisions. |
+| 82 | Implemented | ActionCable hooks plus stream block/callback registrations are owner-scoped roots. |
+| 83 | Implemented | ActiveJob/Sidekiq perform, serialization hooks, retry/discard, retry-in, and exhausted blocks are rooted declaratively. |
+| 84 | Implemented | GraphQL resolver/subscription hooks and static `field` resolver methods are rooted; dynamic field methods block the GraphQL owner. |
+| 85 | Safe equivalent | AMS, Blueprinter, and ViewComponent use the shared rule schema; generic presenter rooting is rejected because it has no runtime contract. |
+| 86 | Implemented | Convention rule matching runs for every method family, not only `on_*`. |
+| 87 | Implemented | Rule count is validated before any truncation and excess input is rejected. |
+| 88 | Implemented | Gemfile/gemspec Prism calls and exact lock records enable non-Rails packs; comments/ordinary strings do not. |
+| 89 | Implemented | Gemspec name and require_paths are parsed from the `Gem::Specification.new` block to find primary API files. |
+| 90 | Safe equivalent | Format-aware strong contexts/comments/qualified owners reduce noise, while a generic barrier only adds uncertainty. Dedicated parsers require the ADR conformance gate. |
+| 91 | Implemented | Text files up to the bounded streaming limit are scanned line by line. |
+| 92 | Implemented | Global byte, match, and monotonic-time budgets degrade health instead of silently truncating. |
+| 93 | Implemented | Qualified owner references block only the matching physical owner. |
+| 94 | Implemented | Common short names require symbol/string, qualified, ERB, or structured DSL context. |
+| 95 | No-go | A `trusted_generated` bypass would convert provenance into unsafe negative evidence; generated skips instead block globally. See scope decisions. |
+| 96 | Safe equivalent | Skip reason, file/domain samples, counts, blocker source, and stable config key are report/why-not provenance; YAML source-line retention is not required for safety. |
+
+## 97–129: contracts, CLI, and performance
+
+| # | Disposition | Evidence and decision |
+|---:|---|---|
+| 97 | Implemented | Top-level analysis health has complete/degraded/invalid status and structured reasons. |
+| 98 | Implemented | Findings=1, configuration/execution=2, analysis health=3. |
+| 99 | Implemented | Strict health and exact degraded-reason allowlists apply to every analysis command; invalid is never allowed. |
+| 100 | Implemented | Reports include source snapshot and tool/runtime/config/identity provenance. |
+| 101 | Safe equivalent | Packaged v2 JSON Schema, compatibility fields, migration notes, and schema specs define the compatibility policy without a second policy format. |
+| 102 | Implemented | SARIF reachability witnesses are codeFlows. |
+| 103 | Implemented | SARIF blocker/reference locations are relatedLocations. |
+| 104 | Implemented | Summary separates actionable, diagnostic, blocked, and health counts. |
+| 105 | Implemented | Check and health failures preserve JSON/YAML/NDJSON/SARIF/GitHub output; machine reports include structured health. |
+| 106 | Implemented | `baseline migrate` is explicit; normal check will not silently migrate. |
+| 107 | Implemented | Baseline writes use temporary write, fsync, and atomic rename. |
+| 108 | Implemented | Duplicate identities and unknown classification/confidence values are rejected. |
+| 109 | Implemented | Quarantine annotations carry and exactly match physical fingerprints at the definition. |
+| 110 | Implemented | Generated methods from one macro are grouped into one macro diagnostic/annotation unit. |
+| 111 | Implemented | Quarantine writes recheck source digests and atomically replace files. |
+| 112 | Implemented | `--as-of` and SOURCE_DATE_EPOCH provide reproducible time. |
+| 113 | Implemented | Fractions, days, limits, timeouts, and finite-number constraints are validated. |
+| 114 | Implemented | Static analyzer uniqueness and dependency order are validated. |
+| 115 | Safe equivalent | Model constructors bound enums/numbers/text/metadata; current producers are versioned and legacy is explicitly normalized to stable `unversioned`. See scope decisions. |
+| 116 | Implemented | Custom analyzers require `trusted: true`, validate capabilities/results, and apply through the atomic staging contract. |
+| 117 | No-go | A per-file fact cache failed the measured scan-share gate. See `necropsy_performance_adr.md`. |
+| 118 | Implemented | Cache identity includes tool, Ruby engine/version, Prism, definition, call-site, config, inventory, and file content digests. |
+| 119 | Implemented | Find-based discovery streams and prunes excluded directories before descent. |
+| 120 | Safe equivalent | Fixed generated/cache directories are pruned at every depth; `paths.exclude` is not pruned because excluded Ruby still belongs to the default reference safety scope. |
+| 121 | Implemented | Reverse subclass index and descendant cache avoid repeated whole-class scans. |
+| 122 | Implemented | Instance and singleton lookup chains are cached and invalidated with graph indexes. |
+| 123 | Implemented | Reachability and descendant traversal use head-index queues with stable ordering. |
+| 124 | Implemented | Message, accepted/rejected target, and resolution indexes back why-not queries. |
+| 125 | Implemented | Baseline comparison preindexes physical/logical fingerprints, body, symbol, and path. |
+| 126 | Implemented | Benchmark gold labels are preindexed. |
+| 127 | Implemented | NDJSON streams report, nodes, calls, edges, evidence, and metadata without nesting the graph payload. |
+| 128 | No-go | Process-parallel parse is below the scan-share gate and adds worker/parity failure modes. See the performance ADR. |
+| 129 | No-go | Candidate-specific template/reference caching is below its p95 share gate and risks stale blockers. See the performance ADR. |
+
+## 130–148: adversarial tests and evaluation
+
+| # | Disposition | Evidence and decision |
+|---:|---|---|
+| 130 | Implemented | Metamorphic identity specs cover comments, whitespace, unrelated definitions, ordering, and cache modes. |
+| 131 | Implemented | Safety invariants assert unknown syntax, parse errors, dynamic routes, and unreadable references cannot increase actionable candidates. |
+| 132 | Implemented | CLI integration covers analyzer execution, validation, capability, and atomic-apply failures. |
+| 133 | Implemented | Source mutation during scan/snapshot makes health invalid. |
+| 134 | Implemented | Dynamic-send fixtures cover later literals, splats, keywords, forwarding, and finite symbols. |
+| 135 | Implemented | Flow fixtures cover no-else, short circuit, loops, lambda, transfer, rescue, op assignment, hash splat, and multi-key joins. |
+| 136 | Implemented | Modifier, attr visibility, singleton constant, and dynamic singleton fixtures are present. |
+| 137 | Implemented | CHA/RTA fixtures cover lookup surfaces, puts arguments, container elements, block states, sort/sort_by, and user-name collisions. |
+| 138 | Implemented | Deterministic generated Ruby programs compare static targets with TracePoint runtime targets as a test oracle only. |
+| 139 | Implemented | CI covers supported Ruby versions and a locked minimum Prism suite for identity, lookup, blockers, and report contracts. |
+| 140 | Implemented | Deterministic AST-shape mutation/fuzz specs assert no crash, unbounded canonicalization, or unsafe finding growth. |
+| 141 | Implemented | Candidate-union evaluation reports per-project metrics and macro averages, not only micro totals. |
+| 142 | Implemented | Reviewed labels require reviewer, rationale, reviewed_at, and source_revision provenance. |
+| 143 | Safe equivalent | Static analyzer ablation enumerates every built-in analyzer; the release precision gate requires every declared default feature's on/off evidence and improvement. |
+| 144 | Implemented | Safety mutation harness breaks parse, scope, health, and positive-only constraints and requires the corpus to detect each mutant. |
+| 145 | Implemented | Repeated samples gate p95/max wall time, RSS, allocations, and artifact size. |
+| 146 | Implemented | `--self-check` validates resolution scope, derived-call resolution, evidence relations, node endpoints, and blocker/actionable exclusion. |
+| 147 | Implemented | Runtime collectors and CLI artifact IDs accept injected clock/random sources and are deterministic under SOURCE_DATE_EPOCH. |
+| 148 | Implemented | `semantics` enumerates every installed Prism node plus Ruby hooks and Rails DSL states; unknown/future nodes default unsupported. |

data/docs/migrations/0.2.1.md

@@ -0,0 +1,57 @@
+# Migrating to 0.2.1
+
+Version 0.2.1 favors a visible unknown state over a potentially unsafe deletion recommendation.
+Most projects need no configuration change, but candidate counts and CI output can change.
+
+## Findings and confidence
+
+Methods affected by unresolved runtime dispatch, incomplete Ruby source, or an analyzer failure now
+appear as low-confidence `blocked` findings. They remain visible even when the normal report threshold
+omits low-confidence dead-code candidates. JSON, human, GitHub, SARIF, `why`, and `explain` output
+include the matching blocker or source diagnostic.
+
+RTA is rank-only by default and no longer removes broader static call edges. A temporary compatibility
+setting restores the old destructive pruning while a project compares results:
+
+```yaml
+rta:
+  pruning: legacy
+```
+
+Remove that setting after review; `rank_only` is the safe default.
+
+## Runtime evidence and quarantine
+
+Coverage, TracePoint, and Coverband payloads only provide positive liveness evidence. An unobserved
+method is not made more likely to be dead, and `dynamic.min_observation_days` no longer affects
+classification. This intentionally has no compatibility switch because absence from a partial runtime
+sample is not deletion evidence.
+
+Quarantine expiry also no longer increases a finding's score. It is an operational review signal:
+
+```yaml
+quarantine:
+  expiry: warn # warn | fail | ignore
+```
+
+`fail` changes the check command's exit status for expired reviews; it does not change analysis.
+
+## Remote Coverband/Redis sources
+
+`rediss://` now requires peer and hostname verification using the system CA store. Redis evidence is
+bounded by DNS/connect/read/total deadlines and key, response, bulk, array, nesting, and payload limits.
+Invalid limits are rejected during configuration. Credentials are redacted from domain errors.
+
+If a private deployment previously depended on an unverified certificate, install its CA in the system
+trust store before upgrading. Disabling TLS verification is not supported.
+
+## Auditing the change
+
+The five-corpus safety audit can be reproduced from a clean worktree:
+
+```shell
+NECROPSY_RUBOCOP_CORPUS=/path/to/rubocop-1.75.0 bundle exec ruby bench/audit.rb
+```
+
+The command fails closed for stale reports, incomplete review policy, incompatible performance
+provenance, missing RSS, failed adversarial suites, or unreviewed new high-confidence candidates.

data/docs/migrations/0.3.0.md

@@ -0,0 +1,207 @@
+# Migrating to 0.3.0
+
+Version 0.3.0 introduces physical definition identities and structured call-site resolution. The
+changes are additive for normal report consumers, but integrations that inspect the optional graph
+or implement custom analyzers should review the compatibility rules below.
+
+## Report and graph JSON
+
+The existing top-level report keys and legacy logical method name remain available. Definition
+objects now include both identities:
+
+- `id` and `symbol_id` are the logical name, such as `Billing::Charge#call`.
+- `definition_id` is the physical definition identity and is stable across comment-only and line-only
+  edits. Reopened classes and repeated definitions have distinct physical IDs.
+- `body_digest` and `ordinal` support review and future migration when a physical ID changes.
+
+Graph edges, call-site callers, runtime matches, and entry points use physical definition IDs so that
+one logical name never silently selects one of several definitions. `CallSite` keeps `caller_id` for
+existing readers and also emits the explicit alias `caller_definition_id`; both contain the same
+physical ID. Call sites additionally emit `call_site_id`.
+
+Readers should ignore unknown keys, treat versioned IDs as opaque strings, and use `symbol_id` when
+grouping physical definitions by their legacy logical name. Readers that previously assumed a single
+node per logical name must handle more than one definition. Ambiguous runtime references are reported
+as ambiguous instead of being assigned to the first definition.
+
+The optional graph payload also adds `resolutions`, `resolution_conflicts`, and a single interned
+evidence store. Existing edge objects and nested `evidences` remain present. The following additive
+fields let new readers avoid duplicating evidence payloads:
+
+- `edge_projection` names the projection used by the legacy `edges` array (`conservative`).
+- `edge_relations` contains physical caller/callee IDs and stable `evidence_ids`.
+- `evidence_records` contains each evidence payload once.
+- `evidence_collisions` reports IDs that were supplied with conflicting payloads.
+
+Existing evidence fields (`analyzer`, `kind`, `weight`, `details`, and `metadata`) remain present;
+provenance fields are additive. Numeric `weight` is retained for display compatibility but must not
+be interpreted as call resolution completeness. A conflicting evidence ID is quarantined, its graph
+references are removed, and a conservative blocker is emitted instead of selecting one payload.
+
+## Evidence graph projections
+
+The graph stores one physical edge relation and its evidence IDs, then derives views at query time:
+
+- `conservative` includes exact, conservative, heuristic, observed, and grade-less legacy positive
+  evidence. It is the default for reachability and preserves pre-0.3.0 reachability behavior.
+- `exact` includes exact evidence plus observed evidence only when the query supplies a revision and
+  the evidence scope has the same revision.
+- `observed` includes only positive observed evidence and may be filtered by any supplied scope keys.
+
+Unknown or partial residual relations remain scoped blockers; they are not expanded into speculative
+mass edges. Legacy grade-less evidence is never promoted based on numeric weight and appears only in
+the conservative projection. Callers using the Ruby API can pass `projection:` and `scope:` to graph
+edge queries and the reachability engine.
+
+## World mode and root domains
+
+The default remains `analysis.world: application`. Set `analysis.world: library` for gems and other
+open-world libraries whose callers may be outside the repository. In library mode, every non-test
+public or protected method is an `external` root; private methods are not implicitly protected.
+Configured entry-point patterns are runtime roots in application mode and external roots in library
+mode.
+
+Roots now carry `runtime`, `test`, or `external` domains. Reachability keeps all three path sets
+separate. Runtime and external walks cannot enter or bridge through test definitions, while a test
+walk may still reach production definitions under test. The existing
+`EntryPoint` constant and `node_id` accessor remain available; graph JSON adds `definition_id`,
+`domain`, and `evidence` to each entry-point object. The `why` command reports the root domain,
+reason, and provenance for its witness path.
+
+`analysis.load_roots: known` is the compatibility default. Set it to `all` to conservatively root the
+top-level block of every non-test analyzed Ruby file when the load graph is unknown. This can reduce
+candidate yield, but avoids treating class-body registration reached from an unknown load unit as
+dead. The scan cache schema is updated automatically.
+
+## Analysis, reference, and report scopes
+
+Source and output filtering are now explicit and independent:
+
+```yaml
+paths:
+  analyze: ["app/**", "lib/**"]
+  reference: ["**/*"]
+report:
+  include: ["app/**"]
+  exclude: ["app/generated/**"]
+```
+
+- `paths.analyze` selects Ruby definitions eligible for findings.
+- `paths.reference` selects repository files used to discover callers and references. It defaults to
+  the whole repository. Ruby files in this scope are parsed into the graph, but their definitions are
+  not findings unless they are also in the analysis scope. Non-Ruby files are retained for reference
+  barriers.
+- `report.include` and `report.exclude` only select displayed findings; they do not change graph
+  nodes, edges, roots, or reachability.
+
+When `paths.analyze` is omitted, Necropsy preserves the pre-0.3.0 conventional Ruby scan scope.
+Other Ruby sources found by the repository-wide reference scan can still contribute callers without
+becoming findings themselves.
+
+`paths.include` remains a compatibility alias for `paths.analyze`, and `paths.exclude` still removes
+files from the analysis scope. Migrate `paths.include` to `paths.analyze` to make that intent clear.
+When an analysis filter leaves a detected executable, test, route, task, or gem specification outside
+the scope, Necropsy emits a warning and adds an `analysis_scope` report diagnostic. The diagnostic
+also lists reference-only Ruby files and symlinks ignored during safe repository discovery.
+If an explicit `paths.reference` leaves non-test Ruby files outside both scopes, all otherwise-dead
+findings receive a `reference_scope_incomplete` blocker. The diagnostic reports excluded caller
+counts and bounded samples; expand the reference scope before treating those findings as candidates.
+
+Graph JSON adds `source_domains` (`analyze` or `reference`) and `scope_diagnostics`. These are
+additive fields. Cache entries now include all selected reference files, so changing a non-Ruby
+reference invalidates the scan cache automatically.
+
+## Non-Ruby reference barrier
+
+After static reachability and before final scoring, Necropsy scans non-Ruby files selected by
+`paths.reference` for otherwise-actionable method candidates. It recognizes direct method names,
+symbol and string forms, lower-camel GraphQL-style names, and owner-qualified hints such as
+`Billing::Charge#capture`. A match adds a definition-scoped `unparsed_external_reference` blocker,
+so the method moves to `blocked` instead of remaining a dead-code candidate. Blocker metadata and
+`why` / `explain` output include the matching file, line, match kind, and bounded source snippet.
+
+The implementation uses a portable Ruby scanner and does not require ripgrep. Common names such as
+`call` and `run` intentionally produce more blockers when they appear as bare text; safety takes
+precedence over candidate yield until benchmark evidence justifies a dedicated parser. Parsed Ruby
+files are excluded because their calls and references already flow through the graph. Whole-line and
+inline comments, generated paths or generated comment headers, benchmark/tool metadata, known binary
+extensions, NUL-containing files, invalid UTF-8, and files over 1 MiB are not searched. Reports expose
+deterministic scanned/matched counts plus bounded skip reasons and samples; test-fixture matches are
+retained as test-domain diagnostics and do not block runtime candidates.
+
+## Refutable `why-not` diagnostics
+
+Use `necropsy why-not SYMBOL` for a candidate, blocked finding, or test-only definition. Human output
+is intended for review; `--format json` emits the versioned `necropsy.why-not.v1` artifact. Its stable
+top-level fields include the physical definition and same-name definitions, incoming call sites,
+resolution status and rejected targets, matching and unknown/partial blockers, world/root policy,
+non-Ruby matches, parse/analyzer failures, enabled analyzers and type providers, assumptions, and
+suggested next evidence. `artifact_context` records the tool version, definition body digest,
+configuration digest, and a bounded snapshot digest of the complete analyzed/reference source
+inventory; an unavailable or size-limited snapshot is explicit rather than omitted. The artifact
+also records risk flags, a recommended action, and a reachability witness or explicit absence
+summary. Every collection reports total, returned, and truncated counts, including nested metadata.
+
+Logical symbols with multiple physical definitions remain ambiguous. The diagnostic lists an
+executable `why-not` command for each definition ID, so reviewers can inspect each body independently.
+Missing symbols retain the existing partial-match suggestions.
+
+## Resolution and blockers
+
+Every native static analyzer can return a `ResolutionRecord` per call site. Its status has explicit
+semantics:
+
+- `complete`: the target set is complete under the recorded assumptions; an empty set is valid.
+- `partial`: known targets exist, but more targets may exist in the structured `unknown_scope`.
+- `unknown`: no usable target was enumerated; the structured `unknown_scope` remains authoritative.
+
+Every declared target must also have a corresponding physical graph edge from the call-site caller.
+A missing edge is treated as an invalid resolution and blocks that physical target rather than making
+it eligible as unreachable.
+
+Partial and unknown results create scoped blockers. They are not converted into evidence that a
+method is dead. Conflicting or malformed analyzer records are retained as diagnostics and produce
+conservative blockers over the smallest safe scope. Evidence and resolutions record producer,
+producer version, assumptions, grade, relation, source, and scope.
+
+## Custom analyzer compatibility
+
+Existing `AnalyzerResult` constructors and existing edge/alive evidence continue to work. For a
+static analyzer that omits `resolutions` (the legacy value is `nil`), Necropsy derives only
+conservative `partial` or `unknown` records:
+
+- an edge is associated with a call site only when its physical caller and either its `call_site_id`
+  or complete legacy call-site metadata identify exactly one site;
+- logical target names that resolve to multiple physical definitions are not guessed;
+- evidence weight never upgrades an adapted result to `complete`.
+
+Native analyzers should return `resolutions: []` when an intentionally empty native result is desired,
+or return explicit records with stable `call_site_id` and physical target IDs. Dynamic analyzers remain
+positive-only and are not adapted into static completeness claims.
+
+Legacy RTA pruning removes only the individual name-resolution or CHA evidence IDs rejected for the
+analyzed call site. Evidence from observations or other producers on the same physical edge remains
+attached, so pruning one producer cannot erase an independently supported relation.
+
+The scan cache schema is versioned and is invalidated automatically. No manual cache removal or
+configuration change is required.
+
+## Baseline schema v2
+
+`necropsy baseline` now writes schema v2. Each entry stores the physical fingerprint,
+`definition_id`, `body_digest`, `symbol_id`, and source path alongside the legacy logical
+fingerprint. Existing schema v1 files are still read and are never rewritten by `check`.
+
+Migration matching is deterministic and conservative: exact physical ID or fingerprint first,
+then body digest, then the logical symbol and path hint. Classification remains part of the match.
+If a step produces more than one current physical definition, `check` prints every candidate and
+fails. Review those definitions and regenerate the baseline; Necropsy does not select the first
+candidate. Removing the v2 baseline and restoring a v1 file restores the legacy reader path.
+
+The report's existing `fingerprint` remains the logical fingerprint for JSON compatibility.
+`logical_fingerprint` and `physical_fingerprint` are additive fields, and the top-level
+`compatibility.finding_fingerprints` note documents their roles. SARIF likewise retains
+`partialFingerprints.necropsy` and adds `necropsyPhysicalDefinition`, with both values repeated in
+result properties. Benchmark JSON retains its legacy logical metrics and adds `identity_views` with
+logical-symbol and physical-definition candidate inventories; repeated definitions count separately
+in the physical view.

data/docs/migrations/0.4.0.md

@@ -0,0 +1,13 @@
+# Custom analyzer trust declaration
+
+Custom analyzers execute Ruby code in the Necropsy process. They must now use a mapping with an explicit trust declaration:
+
+```yaml
+analyzers:
+  custom:
+    - class: Company::Analyzer
+      require: config/company_analyzer.rb
+      trusted: true
+```
+
+The former string form is rejected. `trusted: true` means that the analyzer and its required file are allowed to execute with the same privileges as Necropsy; it does not weaken result validation or atomic result application.