necropsy 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: acc21c7bf0937bb810decd0a6df03911149a32fc08146b15a37e74d133b397eb
-  data.tar.gz: 781f39ee1fb14299dbd9bedb6cad792785269517494b1d6c336fdb52674c10c2
+  metadata.gz: c6859ea7acfe1f2357759a87f5f2f2f2b1b487447d34f61d6778164c8362dc6e
+  data.tar.gz: 39f91eb66de04a292f749ba37fc2a9b4ba333ec799c1671716068f9d315f6d96
 SHA512:
-  metadata.gz: cef485cc0bb21d6e684107bb08f7882655ddf24600c9f9d53c744b5ce8a4cf78a460540c6bc9d981e652c6679f12641d34950761ceb1f78d17e8708436afc4d8
-  data.tar.gz: 787d658f3eb89506530b4467d3b7071ed9eccab5a9288b4e023e6b9dbcdd97f6a5b5a7127927d060f698deca80510d0ccd81e059a33990bb0531238d85c95ed4
+  metadata.gz: d7a3f31943091c4e9288d4705e65779f5165ad251fe8f440f3361f1ec1f675035b4d83f6425fbdb6b5b0e88ab1240800bf621d3bc78ad6e624f6c3e6e7eaca96
+  data.tar.gz: f1fa13456a999bb6897f938776dc3884197f01ffafdcab19ba416a6d41727980cb03906a5280cb48a60d245f50f714c61e12adb950134ee06ca71c202e417a55

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,44 @@
+# Changelog
+
+All notable changes to Necropsy are documented in this file.
+
+## Unreleased
+
+No unreleased changes.
+
+## 0.3.0 - 2026-08-13
+
+- Preserve repeated and reopened Ruby definitions as distinct physical graph nodes while retaining logical method names for compatibility; ambiguous runtime references no longer silently select one definition.
+- Record structured call-site resolution, scoped blockers, evidence grades, and analyzer provenance, with conservative adaptation for existing custom static analyzers.
+- Store graph evidence once and expose exact, conservative, and scope-filtered observed views while preserving conservative reachability and the existing nested edge JSON.
+- Separate runtime, test, and external roots; library mode now protects public and protected APIs from dead-code findings, with optional conservative roots for every production file.
+- Separate analysis, repository reference, and report scopes so output filters cannot remove callers from the graph; reference-only Ruby definitions are not reported, and narrowed scans expose entry-point and symlink diagnostics.
+- Block candidates that still appear in unparsed templates or configuration, with bounded file/line/snippet diagnostics and safe limits for common names, generated content, binary files, and oversized inputs.
+- Add `why-not` human and versioned JSON diagnostics covering physical definitions, examined calls and resolutions, blockers, world policy, external text matches, analysis failures, enabled rules, and suggested evidence.
+- Write physical-definition baseline schema v2 while continuing to read logical v1 baselines; CI now stops for an explicit review when a legacy entry maps to multiple definitions.
+- Expose legacy and physical fingerprints additively in JSON and SARIF, and show both logical-symbol and physical-definition candidate views in benchmark output.
+- Fail closed on analyzer, parser, source-revision, reference-scan, and unsafe RTA failures; expose explicit health status, strict-health policy, machine-readable failure reports, and graph self-checks.
+- Harden Ruby semantic traversal and finite value flow for modifier definitions, default arguments, dynamic sends, short-circuit paths, unsupported control flow, reflective hooks, and receiver-aware core protocol calls.
+- Add conservative Rails and framework conventions for generated methods, associations, enums, scopes, callbacks, ActionCable, ActiveJob, Sidekiq, GraphQL, serializers, ViewComponent, routes, ERB, inflections, and structural dependency detection.
+- Add bounded and deterministic external-reference scanning with qualified-owner matching, streaming limits, byte/match/time budgets, unsafe-skip blockers, and safe repository discovery.
+- Add deterministic NDJSON graph export, content-addressed cache metadata, reproducible runtime artifacts, performance distributions, macro-averaged evaluation, AST fuzzing, runtime target oracles, mutation safety harnesses, and a generated semantics matrix.
+
+## 0.2.1 - 2026-08-04
+
+- Prevent unsafe dead-code recommendations when runtime dispatch, source parsing, or an analyzer is incomplete; affected methods are now reported as low-confidence `blocked` findings with the reason and source location.
+- Make the default analysis conservative: RTA no longer deletes broader static edges, runtime observations only prove liveness, and quarantine expiry requests review without increasing deadness confidence.
+- Harden remote Coverband/Redis evidence loading with verified TLS, bounded DNS/connect/read/write/total deadlines, strict payload and RESP limits, safe deserialization, and credential-redacted errors.
+- Add reproducible five-corpus release auditing with reviewed candidate transitions, safety-invariant and adversarial suites, provenance-bound artifacts, and fail-closed wall-time/RSS budgets.
+
+## 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,112 @@
+# Measurements
+
+Measurements are local wall-clock results. Compare runs made on the same machine and Ruby version; absolute timings are not portable.
+
+The reproducible seed under `bench/corpora/v1` supersedes ad hoc commands for new comparisons.
+`bundle exec ruby bench/run.rb` regenerates normalized findings, candidate-union results, corpus
+summaries, wall time, and RSS measurements in one pass. RuboCop remains pinned to 1.75.0 and is
+enabled by setting `NECROPSY_RUBOCOP_CORPUS`; an unavailable checkout is reported as a skip.
+
+## 0.2.1 safety release audit
+
+The versioned audit compares commit `51d490188ae9ad846b4c023f14e252ec624a2d5e`, the first
+integrity-bound five-corpus snapshot, with `3831ce651ed331426413a767824955414529001d` on the same
+Ruby 4.0.0/macOS arm64 environment. RSS is the benchmark process's current resident size after each
+corpus, not a per-corpus isolated peak. Full provenance and candidate-level changes are stored in
+`bench/audits/0.2.1/audit.json`.
+
+| corpus | findings baseline/current | state changes | newly high | wall s baseline/current | RSS KiB baseline/current |
+|---|---:|---:|---:|---:|---:|
+| dynamic evidence | 4 / 4 | 0 | 0 | 0.001 / 0.003 | 52,720 / 51,200 |
+| plain Ruby | 3 / 3 | 0 | 0 | 0.002 / 0.002 | 53,088 / 51,488 |
+| Rails fixture | 4 / 4 | 0 | 0 | 0.004 / 0.004 | 54,272 / 52,656 |
+| RuboCop 1.75.0 | 5,797 / 5,797 | 119 | 0 | 5.196 / 5.281 | 576,256 / 584,432 |
+| self | 78 / 50 | 2 | 0 | 0.217 / 0.423 | 608,448 / 580,480 |
+
+All seven release gates passed. Rails had no candidate changes. RuboCop retained the same candidate
+count; its 119 state changes were conservative transitions to `blocked`, with all nine deterministic
+stratified review samples accepted. The dynamic, parse, ambiguity, and remote-input adversarial
+suites passed 69 examples in total. No new high-confidence candidate or confirmed reviewed false
+positive was introduced.
+
+| 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,16 @@ 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:
+Machine-readable JSON reports use schema v2. The published contract is
+[`schema/necropsy-report-v2.schema.json`](schema/necropsy-report-v2.schema.json).
 
-- Prism-based method collection for `def`, `define_method`, `attr_*`, and `delegate`
-- 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
-- `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
+Necropsy includes:
+
+- Prism-based method collection for ordinary, singleton, delegated, aliased, forwarded, and dynamically defined methods
+- static name resolution and CHA, with rank-only RTA hints from classes instantiated in the scanned program
+- Prism-backed Rails route parsing plus callback, view, component, migration, plain Ruby, and test-suite entry points
+- `unreachable`, `unused`, `blocked`, and `test_only_reachable` classifications
+- confidence levels, compact JSON/YAML reports, SARIF/GitHub output, CI guardrails, dynamic collectors, and benchmarking
 
 ## Installation
 
@@ -29,18 +32,70 @@ Create a baseline:
 bundle exec necropsy baseline --root .
 ```
 
+New baselines use schema v2 and identify each physical method definition. Existing
+schema v1 baselines remain readable, but `necropsy check` accepts only exact physical
+matches. Run `necropsy baseline migrate` to use body/symbol/path hints and produce a
+review report; ambiguous or legacy matches never pass an ordinary check silently.
+
 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 why-not 'LegacyService#unused' --root .
+bundle exec necropsy why-not 'LegacyService#unused' --root . --format json
+bundle exec necropsy explain 'LegacyService#unused' --root .
 ```
 
+`explain` shows every confidence score component and the final confidence
+level. `why-not` emits a refutable `necropsy.why-not.v1` artifact for candidates,
+blocked findings, and test-only definitions. It includes examined call sites and
+resolution statuses, rejected targets, blockers, world/root policy, non-Ruby
+matches, parse/analyzer failures, enabled analyzers and type providers, artifact
+digests, assumptions, risk flags, the recommended review action, and the next
+evidence to collect. Every diagnostic collection reports total, returned, and
+truncated counts, and nested metadata is bounded as well. Missing IDs return
+partial-match suggestions. When a logical symbol ID matches multiple physical
+definitions, all three diagnostic commands list every source location and an
+executable command using its full definition ID.
+
+For compatibility, the existing logical `id` and `fingerprint` remain stable.
+Reports add `logical_fingerprint` and `physical_fingerprint`, while SARIF retains
+the `necropsy` partial fingerprint and adds `necropsyPhysicalDefinition`. Reports
+also include `symbol_id` and `definition_id`; human, GitHub, and SARIF findings
+display or expose the full physical definition ID so reopened or duplicate methods
+can be distinguished.
+
+Runtime artifacts remain backward compatible: collectors keep the legacy
+`nodes` and `edges` fields while adding structured `node_references` and edge
+endpoint references with `definition_id`, `symbol_id`, `file`, and `line` when
+available. Importers prefer structured references and continue to accept v1
+logical-ID artifacts.
+
 Fail CI only for new high-confidence findings:
 
 ```bash
 bundle exec necropsy check --root . --fail-on high
 ```
 
+`check`, baseline writes, quarantine writes, and release benchmarks fail with status
+3 when analysis health is incomplete. Use `--strict-health` to apply the same policy
+to informational analysis/diagnostic commands. A known degraded reason can be
+temporarily admitted by exact code, for example
+`--allow-degraded=reference_scan_incomplete`; invalid health is never admitted.
+
 Record dynamic evidence from a Ruby script:
 
 ```bash
@@ -63,9 +118,42 @@ Evaluate against a gold standard:
 bundle exec necropsy bench --root . --gold-standard gold.yml --ablation
 ```
 
+Benchmark JSON keeps the existing logical-ID metrics and adds `identity_views`.
+The legacy view groups by `symbol_id`; the physical view lists every
+`definition_id` and both fingerprints, so duplicate definitions cannot disappear
+from review totals.
+
+Benchmark precision is measured from actionable `unreachable`/`unused` findings only.
+`blocked` and `test_only_reachable` remain visible diagnostics but are not removal candidates.
+The additive `quality` and `by_category` objects report candidate precision/count/LOC,
+known-positive recall, blocked and unknown rates, and rule/risk counts. A run with zero
+candidates fails the evaluator's `candidate_yield` release check instead of receiving perfect
+precision. The legacy `Report#dead_methods` API is unchanged; integrations that need the stricter
+set can use `Report#actionable_candidates`.
+
+Non-analyzer features can be compared with the same evaluator by supplying already analyzed
+on/off reports. This keeps feature configuration outside the metric engine while producing a
+physical-definition candidate diff and metric deltas:
+
+```ruby
+Necropsy::Bench::Evaluator.new(
+  report: feature_on_report,
+  gold_standard_path: 'gold.yml',
+  feature_ablation: {
+    'receiver_flow' => { on: feature_on_report, off: feature_off_report }
+  }
+).call
+```
+
+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
+analysis:
+  world: application # application | library
+  load_roots: known # known | all
 analyzers:
   static: [name_resolution, cha, rta]
   dynamic:
@@ -73,14 +161,40 @@ analyzers:
       source: tmp/necropsy_coverage.yml
       min_observation_days: 30
     coverband:
-      source: redis://prod-redis:6379/2?key=coverband
+      source: rediss://prod-redis:6379/2?key=coverband
+      connect_timeout: 5
+      read_timeout: 5
+      total_timeout: 15
+      max_response_bytes: 16777216
+      max_bulk_bytes: 8388608
+      max_array_elements: 100000
+      max_resp_depth: 16
+      max_keys: 1000
+      max_payload_depth: 64
     trace_point:
       source: tmp/necropsy_trace_point.yml
   custom:
-    - "MyCompany::GraphqlEntryAnalyzer"
+    - class: "MyCompany::GraphqlEntryAnalyzer"
+      require: "config/necropsy/graphql_entry_analyzer"
+      trusted: true # executes Ruby in the Necropsy process
+rta:
+  pruning: rank_only # legacy pruning marks analysis invalid and cannot pass check
 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:
+  analyze: ["**/*.rb", "Rakefile", "**/*.rake", "bin/*", "exe/*", "*.gemspec"]
+  reference: ["**/*"]
+  exclude: ["app/legacy/**/*.rb"]
+report:
+  include: ["app/**", "lib/**"]
+  exclude: ["lib/generated/**"]
 entry_points:
   extra:
     - "PublicApi::*"
@@ -89,30 +203,133 @@ ci:
   baseline: .necropsy_baseline.yml
 quarantine:
   days: 30
+  expiry: warn # warn | fail | ignore
 bench:
   precision_threshold: 0.85
+logging:
+  verbose: false
 ```
 
-The scan cache is invalidated when scanned Ruby files or configuration values
-change.
+The scan cache is invalidated when analyzed Ruby files, reference files, or
+configuration values change.
+
+`analysis.world: application` uses executable, framework, and configured roots.
+Use `library` when callers may live outside the repository: every non-test
+public or protected method becomes an `external` root, while private methods
+remain eligible for review. `analysis.load_roots: all` is an opt-in conservative
+mode that treats every non-test Ruby file top level as a runtime root when load
+status cannot be established. Root domain, reason, and provenance are included
+in graph JSON and `why` paths.
+
+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`. If a
+runtime call has more candidates, Necropsy records a message- and owner-scoped
+blocker instead of treating the empty target set as proof of deadness. Matching
+definitions are reported as `blocked` with the call site, scope, and reason;
+they never receive `high` or `certain` confidence. Unresolved calls found only
+in test files remain diagnostic evidence and do not block production candidates.
+
+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.
+
+Source discovery has three independent scopes. `paths.analyze` selects Ruby
+definitions eligible for findings. `paths.reference` defaults to the whole
+repository and keeps Ruby callers outside the analysis scope in the graph;
+definitions found only there are never reported as dead-code findings. It also
+inventories non-Ruby files for conservative reference checks. `report.include`
+and `report.exclude` only filter output and never remove graph nodes or edges.
+When `paths.analyze` is omitted, the existing conventional Ruby source set
+(`*.rb`, `*.rake`, the root `Rakefile` and gem specifications, and Ruby
+executables directly under `bin/` or `exe/`) remains the analysis scope.
+
+`paths.exclude` continues to remove files from the analysis scope, while the
+legacy `paths.include` key remains an alias for `paths.analyze`. Narrowing the
+analysis scope can hide entry points, so reports include scope diagnostics and
+Necropsy warns when detected executables, tests, routes, or task files are left
+outside it. Repository discovery rejects symlinks and paths that resolve outside
+the project root. If `paths.reference` excludes non-test Ruby files that may
+contain callers, findings are conservatively `blocked` and the report lists the
+excluded count and sample until the reference scope is expanded.
+
+For otherwise actionable candidates, Necropsy also scans reference-scope files
+that are not Ruby. Unexplained method names in templates, YAML, GraphQL SDL, and
+scheduler configuration become `unparsed_external_reference` blockers with the
+matching file, line, and snippet. Common names such as `call` or `run` require a
+review more often because safety takes precedence over yield; benchmark results
+identify formats that merit a dedicated parser. The scanner is a portable Ruby
+fallback with no `rg` dependency. It ignores comments, generated/tool metadata,
+and binary formats. Files from 1–16 MiB are streamed. Generated, unreadable,
+larger, or budget-truncated runtime inputs are never treated as negative evidence:
+they add a global blocker, degraded health, and bounded provenance diagnostics.
 
 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
+Reports retain logical method names while the graph distinguishes repeated or
+reopened definitions with physical `definition_id` values. Graph consumers and
+custom analyzer authors upgrading to the structured resolution model should
+follow the [0.3.0 migration guide](docs/migrations/0.3.0.md).
+
+The adversarial disposition of every item in the implementation review is recorded
+in the [148-item implementation matrix](docs/impv_implementation_matrix.md). Explicit
+no-go decisions include measurable reconsideration gates rather than hidden backlog.
+
+The graph keeps one interned evidence store and derives `exact`, `conservative`,
+and scope-filtered `observed` edge views on demand. Normal analysis and the
+serialized `edges` view use the conservative projection, preserving legacy
+reachability. Serialized edges retain nested `evidences` and additionally
+reference the top-level `evidence_records` through stable `evidence_ids`.
+
+Runtime evidence is positive-only: executed methods and the endpoints of
+observed edges are kept alive, while an unobserved method never becomes a new
+finding and never receives higher confidence. Observation duration and
+environment remain informational metadata. `min_observation_days` is a
+read-compatibility no-op and cannot change candidates, classifications, or
+confidence. The `unused` state remains only for reading and aggregating legacy
+schemas; positive-only analysis does not produce new `unused` findings. Reports
+include attempted, matched, and unmatched evidence counts plus a bounded
+unmatched sample.
+
+Schema v1 payloads may omit the analyzed source revision. Their positive
+evidence is accepted for liveness for compatibility, but an omitted revision is
+marked `source_revision_status: unknown` and is never treated as proof that
+unobserved code is dead. When `source_revision` is supplied, it is retained in
+the evidence scope so an exact projection can require a matching revision. Use
+evidence recorded from the same checkout.
+
+Coverband file, Redis string, and Redis hash exports are supported. Redis URLs
+may include an ACL username and password. `rediss://` uses the system CA store,
+TLS peer verification, SNI, and post-connect hostname verification; URI
+credentials are redacted from loader errors. Connect, read, and total timeouts,
+response and bulk bytes, RESP array size/depth, key count, and payload depth all
+have the bounded defaults shown above and 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.
 
-`necropsy quarantine --write` adds `# necropsy:quarantine since=YYYY-MM-DD`.
-When the configured quarantine window expires and no alive evidence appears,
-the finding is raised to `certain`.
+`necropsy quarantine --write` adds
+`# necropsy:quarantine since=YYYY-MM-DD fingerprint=PHYSICAL_FINGERPRINT`.
+The annotation applies only to the immediately following physical definition
+when its fingerprint matches. Legacy annotations without a fingerprint require
+review and can be upgraded in place with `quarantine --write`.
+Use `--as-of YYYY-MM-DD` or `SOURCE_DATE_EPOCH` to make quarantine expiry,
+annotation dates, and baseline timestamps reproducible.
+Expiry never changes a finding's classification, score, or confidence. Instead,
+the finding receives a `quarantine_review_required` diagnostic. The `check`
+command warns by default; set `quarantine.expiry` to `fail` to make an expired
+annotation fail CI, or to `ignore` to suppress the operational check. An invalid
+`since` date is reported as `quarantine_invalid_date` without changing deadness.
 
 ## 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/bench/README.md

@@ -0,0 +1,92 @@
+# Reproducible benchmark seed
+
+Run the version 1 corpus from the repository root:
+
+```shell
+bundle exec ruby bench/run.rb
+```
+
+The command writes normalized reports, the candidate union, and a performance summary to
+`tmp/necropsy-benchmark/v1`. The normalized reports omit machine-specific roots and timing data;
+the separate summary records wall time, phase allocations, resolution-cache counts, and peak RSS
+(or current RSS when the platform does not expose a process high-water mark). Its `golden.status` is `match`, `drift`, or `missing`, with every
+changed deterministic artifact listed under `golden.differences`.
+
+The manifest pins five corpus roles: this repository, RuboCop 1.75.0, a plain Ruby fixture, a Rails
+fixture, and a positive dynamic-evidence fixture. The small fixtures are in `spec/fixtures`; set
+`NECROPSY_RUBOCOP_CORPUS` to an existing RuboCop 1.75.0 checkout to enable that external corpus.
+RuboCop is fixed to tag `v1.75.0` and commit `9c2bc8eb11e269f1cf47113041a1be3ff615f68b`;
+a checkout at another commit fails before analysis. Missing external corpora are recorded as
+explicit skips rather than downloaded automatically, but omission causes golden drift and a
+nonzero exit once the pinned RuboCop result is present in the golden set. All five manifest entries
+are required for golden updates; an incomplete run raises an error before touching existing golden
+files. Pinned Git corpora must also have no tracked working-tree changes.
+
+The comparison-tool YAML files are versioned review seeds, not claims from a fresh tool execution.
+They exercise the candidate-union schema for Necropsy, Debride, Spoom, and a type-aware analyzer
+without requiring those tools to be installed. Replace them with pinned output snapshots when a
+comparison is rerun. A missing snapshot and executable produces an explicit skipped tool result.
+
+Deterministic golden files live in `bench/golden/v1`. Drift is printed and exits nonzero. Updating
+them requires an audit reason; `metadata.json` binds that reason to every artifact digest:
+
+```shell
+bundle exec ruby bench/run.rb --update-golden 'explain the intentional finding drift'
+```
+
+Review `candidate_union.json` before accepting drift. Labels use `dead`, `alive`, `external`, or
+`unknown`, and every reviewed label includes a rationale. A label that does not match an actual
+candidate from a generated Necropsy report or a versioned comparison snapshot is rejected.
+
+Normalized report schema version 1 remains compatible and now has additive measurement fields.
+Each finding declares `candidate` versus `diagnostic`, physical `definition_id`, LOC, category,
+unknown status, rule hits, risks, and blockers. The `quality` object provides the corresponding
+counts and rates. Report include/exclude scope is applied before these fields are aggregated.
+Blocked and test-only findings never become Necropsy candidates in `candidate_union.json`, though
+they remain available under `summary.necropsy_diagnostics`.
+
+`summary.tool_metrics` separates candidate-union precision from known-positive recall and reports
+candidate count and measured LOC overall and by category. Add an optional `category` to reviewed
+labels to define stable error strata. A separate top-level `known_positives` list in the labels
+file may include methods missed by every tool; when omitted, reviewed `dead` labels are the
+backward-compatible recall set. Each known positive requires its own rationale. `unknown` labels
+are not treated as either true or false
+positives. When a tool produces no candidates, precision is `null` with
+`precision_status: no_candidates`; yield remains zero, so an empty result cannot claim 100%
+precision. External snapshots without LOC remain valid and expose `candidate_loc_measured_count`
+instead of inventing a method size.
+
+## 0.2.1 safety release audit
+
+The release audit compares all five current corpus reports with the first integrity-bound
+five-corpus snapshot, reviews deterministic Rails/RuboCop differences, runs the dynamic, parse,
+ambiguity, and remote-input adversarial suites, and enforces wall-time and RSS budgets:
+
+```shell
+NECROPSY_RUBOCOP_CORPUS=/path/to/rubocop-1.75.0 \
+  bundle exec ruby bench/audit.rb
+```
+
+Run it from a clean worktree. The command binds generated reports to the exact Git revision and to
+the benchmark manifest and audit-config digests. It also records Ruby, OS, command, and RSS
+measurement provenance, and fails closed when those values are incompatible with the saved
+baseline. `--skip-benchmark` is intended only for an immediate rerun: it verifies the saved report
+digests and all source provenance before accepting existing output. `--skip-adversarial` records
+the suites as not run and cannot pass the release gate.
+
+The reviewed input policy and baseline performance measurement live under
+`bench/audits/0.2.1`. A passing run writes `audit.json` and `audit.md` there; neither an empty policy
+nor an unknown review outcome is accepted.
+
+The 1.0 public accuracy claim remains fail-closed until the independent review target is met. Generate
+the deterministic, explicitly pending queue with:
+
+```shell
+bundle exec ruby bench/review_queue.rb
+```
+
+The committed `bench/audits/0.2.1/review_queue.yml` contains 300 actionable rows from all five
+corpora, but it contains no labels, outcomes, or reviewer identities. Its `claim_gate_passed` value is
+therefore `false`; editing the queue alone cannot satisfy the gate. Add independently reviewed labels
+to the benchmark review input, rerun the audit, and publish precision and known-positive recall
+separately.