rigortype 0.1.16 → 0.1.17

data/lib/rigor/analysis/incremental.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Analysis
+    # ADR-46 slice 2 — the pure set-algebra core of the incremental step,
+    # kept side-effect-free and Runner-independent so the soundness
+    # property it encodes is unit-testable without the analysis machinery.
+    #
+    # Given the files that changed since the baseline run and the
+    # baseline's `dependents` index ({Runner#file_dependents}), the
+    # **affected closure** the body tier must re-analyse is the changed set
+    # plus every file that read a declaration or method body from a changed
+    # file. Every other file is served from the per-file diagnostic cache.
+    #
+    # The soundness invariant (the {Runner}-driven `--verify-incremental`
+    # gate and the spec assert it): for an edit whose declaration-structure
+    # fingerprint is unchanged (a method-body edit — no symbol created,
+    # destroyed, moved, or re-parented), the set of files whose diagnostics
+    # actually change is a SUBSET of {affected}. A file outside the closure
+    # whose diagnostics changed would be served stale — a manufactured
+    # false positive/negative, the failure mode this design exists to
+    # prevent. Structural edits (fingerprint changed) are out of this
+    # tier's scope — they widen via the negative-dependency / full fallback
+    # path (slice 3).
+    module Incremental
+      module_function
+
+      # Inverts a per-consumer source map (`consumer → enumerable of source
+      # files it read from`) into the `dependents` index (`source → Set of
+      # consumers that read from it`). The reverse edge the incremental step
+      # walks. Returns a frozen hash of frozen Sets; a missing key reads as
+      # nil (the default proc is dropped before freezing).
+      def invert(sources_by_consumer)
+        index = Hash.new { |hash, key| hash[key] = Set.new }
+        sources_by_consumer.each do |consumer, sources|
+          sources.each { |source| index[source] << consumer }
+        end
+        index.default_proc = nil
+        index.each_value(&:freeze)
+        index.freeze
+      end
+
+      # The closure the body tier re-analyses. `changed` is any Enumerable
+      # of paths; `dependents` maps a source path to the Set of files that
+      # read from it (missing key → no dependents). Returns a frozen Set.
+      def affected(changed, dependents)
+        closure = changed.to_set
+        changed.each { |file| closure.merge(dependents[file] || []) }
+        closure.freeze
+      end
+
+      # ADR-46 slice 4 — inverts a per-consumer symbol-sources map
+      # (`consumer → { source_path → Set<"ClassName#method"> }`) into the
+      # symbol-level dependents index: `[source_path, symbol] → Set<consumer>`.
+      # Used by {affected_with_symbols} to limit fan-out to callers of
+      # symbols that actually changed rather than all callers of the file.
+      def invert_symbols(symbol_sources_by_consumer)
+        index = Hash.new { |h, k| h[k] = Set.new }
+        symbol_sources_by_consumer.each do |consumer, sources_by_file|
+          sources_by_file.each do |source, symbols|
+            symbols.each { |sym| index[[source, sym]] << consumer }
+          end
+        end
+        index.default_proc = nil
+        index.each_value(&:freeze)
+        index.freeze
+      end
+
+      # ADR-46 slice 4 — given a set of changed file paths and two per-file
+      # symbol fingerprint maps (before and after), returns the frozen Set of
+      # `[path, symbol]` pairs whose fingerprints differ (added, removed, or
+      # body-changed).
+      def changed_symbol_pairs(changed_files, fingerprints_before, fingerprints_after)
+        pairs = Set.new
+        changed_files.each do |path|
+          before = fingerprints_before[path] || {}
+          after  = fingerprints_after[path]  || {}
+          (before.keys | after.keys).each do |sym|
+            pairs << [path, sym] if before[sym] != after[sym]
+          end
+        end
+        pairs.freeze
+      end
+
+      # ADR-46 slice 4 — the symbol-granularity affected closure.
+      #
+      # A consumer is included when:
+      # (a) it is itself a changed file,
+      # (b) it has an ancestry dep on a changed file (always re-checked — file-level), or
+      # (c) it has a symbol dep on a `[file, symbol]` pair that changed.
+      #
+      # Consumers that only have symbol deps on a changed file, and none of
+      # their tracked symbols changed, are NOT included — the slice 4 precision win.
+      def affected_with_symbols(changed_files, changed_pairs, symbol_dependents, ancestry_dependents)
+        closure = changed_files.to_set
+        changed_files.each { |file| closure.merge(ancestry_dependents[file] || []) }
+        changed_pairs.each { |pair| closure.merge(symbol_dependents[pair] || []) }
+        closure.freeze
+      end
+
+      # ADR-46 slice 3 — the symbol keys (`"ClassName#method"`) that are
+      # present in a changed file's after-fingerprints but were absent from
+      # its before-fingerprints: a symbol that *appeared* in this edit. A
+      # symbol that merely moved between files still appears here for the
+      # destination file, but its negative-dependents set is empty (nobody
+      # missed a name that already resolved elsewhere), so the over-report
+      # costs nothing. Returns a frozen Set of symbol-key Strings.
+      def appeared_symbols(changed_files, fingerprints_before, fingerprints_after)
+        appeared = Set.new
+        changed_files.each do |path|
+          before = fingerprints_before[path] || {}
+          after  = fingerprints_after[path]  || {}
+          (after.keys - before.keys).each { |sym| appeared << sym }
+        end
+        appeared.freeze
+      end
+
+      # ADR-46 slice 3 — the qualified class/module names *declared* in a
+      # changed file's after-state that were absent from its before-state: a
+      # class that appeared in this edit. (For an added file the before-set
+      # is empty, so every class it declares appears.) A class that merely
+      # moved files still appears here, but its negative-dependents are empty,
+      # so the over-report costs nothing. Returns a frozen Set of qualified
+      # class-name Strings. `decls_before` / `decls_after` map a path to its
+      # Set of declared class names.
+      def appeared_classes(changed_files, decls_before, decls_after)
+        appeared = Set.new
+        changed_files.each do |path|
+          before = decls_before[path] || Set.new
+          after  = decls_after[path]  || Set.new
+          appeared.merge(after - before)
+        end
+        appeared.freeze
+      end
+
+      # ADR-46 slice 3 — the consumers to re-check because a name they
+      # looked up and *missed* (a negative dependency) now resolves. `keys`
+      # is the set of negative-dependency keys (`"toplevel:foo"` /
+      # `"method:C#m"`) the appeared symbols would satisfy; `negative_dependents`
+      # maps each key to the Set of consumers that recorded the miss. Returns
+      # a frozen Set of consumer paths.
+      def negative_closure(keys, negative_dependents)
+        closure = Set.new
+        keys.each { |key| closure.merge(negative_dependents[key] || []) }
+        closure.freeze
+      end
+
+      # The files whose per-file diagnostics differ between two runs.
+      # Each argument maps a path to its diagnostic list; diagnostics are
+      # compared structurally via {Diagnostic#to_h} so identity / ordering
+      # of the objects themselves does not matter. A file present in one
+      # run and absent (zero diagnostics) in the other counts as changed.
+      def changed_files(before_by_file, after_by_file)
+        (before_by_file.keys | after_by_file.keys).each_with_object(Set.new) do |path, changed|
+          before = (before_by_file[path] || []).map(&:to_h)
+          after = (after_by_file[path] || []).map(&:to_h)
+          changed << path unless before == after
+        end.freeze
+      end
+    end
+  end
+end

data/lib/rigor/analysis/incremental_session.rb

@@ -0,0 +1,337 @@
+# frozen_string_literal: true
+
+require "digest"
+require_relative "incremental"
+require_relative "../cache/incremental_snapshot"
+require_relative "../inference/scope_indexer"
+
+module Rigor
+  module Analysis
+    # ADR-46 slice 2 — the in-memory incremental orchestrator that composes
+    # the recorded dependency graph ({Runner#file_dependents}), the affected
+    # closure ({Incremental.affected}), and the subset-analysis hook
+    # ({Runner} `analyze_only:`) into a working incremental re-check.
+    #
+    # `#baseline` runs a full analysis with dependency recording and keeps,
+    # per analyzed file, its diagnostics (the cache), its content digest,
+    # and the per-file source set (to maintain the dependents index across
+    # rounds). `#recheck` digests the files again, computes the changed set
+    # ΔF, re-analyzes only `ΔF ∪ dependents[ΔF]`, and serves every other
+    # analyzed file from the cache — the body tier.
+    #
+    # The invariant the verify harness (and the spec) assert: `#recheck`'s
+    # merged diagnostics are byte-identical (as a sorted set) to a full
+    # `--no-cache` re-analysis of the edited tree. This is the
+    # `--verify-incremental` acceptance gate, here without disk persistence
+    # or CLI wiring (the cache is in-process). It models the body tier only:
+    # an edit that adds / removes / moves a *file* is outside the analyzed
+    # set it maintains and falls to a fresh {#baseline} (the structural tier
+    # is a later slice).
+    class IncrementalSession
+      # The outcome of a {#recheck}: the merged diagnostics plus the file
+      # sets, so a caller (or the verify gate) can report what was
+      # re-analyzed versus served from cache.
+      Recheck = Data.define(:diagnostics, :changed, :affected, :reused)
+
+      # @param paths [Array<String>, nil] explicit analysis roots; nil
+      #   (the default) uses the configuration's `paths:`.
+      def initialize(configuration:, paths: nil)
+        @configuration = configuration
+        @paths = paths
+        @cache = {}              # analyzed path => [Diagnostic]
+        @sources = {}            # analyzed path => Set<source path it read from>
+        @digests = {}            # analyzed path => content digest at last analysis
+        @analyzed = []           # the project files analyzed last round
+        @dependents = {}         # inverted @sources (file-level)
+        # ADR-46 slice 4 — symbol-granularity tracking.
+        @symbol_sources = {}     # consumer => { source_path => Set<"ClassName#method"> }
+        @ancestry_sources = {}   # consumer => Set<source_path> (class-ancestry deps)
+        @symbol_fingerprints = {}  # path => { "ClassName#method" => sha256_hex }
+        @symbol_dependents = {}    # [source, symbol] => Set<consumer>
+        @ancestry_dependents = {}  # source => Set<consumer> (inverted ancestry_sources)
+        # ADR-46 slice 3 — negative (missing) dependencies: a consumer that
+        # looked up a name and resolved nothing must be re-checked when that
+        # name later appears (e.g. a `call.unresolved-toplevel` whose target
+        # is defined by a later edit).
+        @missing = {}              # consumer => Set<"kind:name"> it looked up and missed
+        @negative_dependents = {}  # "kind:name" => Set<consumer> (inverted @missing)
+        @class_decls = {}          # path => Set<qualified class name declared in the file>
+      end
+
+      # The project files analyzed at the last baseline / recheck — the set
+      # a verify pass partitions and the merge subtracts the affected
+      # closure from.
+      def analyzed_files
+        @analyzed
+      end
+
+      # Full baseline analysis with recording. Returns the run's
+      # diagnostics; populates the in-process cache + dependency state.
+      def baseline
+        runner = build_runner(record_dependencies: true)
+        diagnostics = run_runner(runner).diagnostics
+        @analyzed = runner.analyzed_files
+        absorb_dependency_graph(runner)
+        @cache = per_file(diagnostics)
+        @digests = @analyzed.to_h { |path| [path, digest(path)] }
+        diagnostics
+      end
+
+      # Re-check after on-disk edits, including files added or removed since
+      # the last run (the structural tier). Re-analyzes only the affected
+      # closure and serves the rest from cache; refreshes the cache +
+      # dependency state so a subsequent #recheck sees the new world.
+      def recheck
+        previous = @analyzed
+        current = current_files
+        added = current - previous
+        removed = previous - current
+        changed = (current & previous).reject { |path| digest(path) == @digests[path] }
+        affected = affected_closure(changed, added, removed)
+        analyze_set = affected & current
+        runner = build_runner(analyze_only: analyze_set, record_dependencies: true)
+        fresh = run_runner(runner).diagnostics
+        reused = (current & previous) - affected.to_a
+        merged = fresh + reused.flat_map { |path| @cache[path] || [] }
+        absorb(runner, fresh, current, analyze_set, removed)
+        Recheck.new(diagnostics: merged, changed: changed.to_set, affected: affected, reused: reused.to_set)
+      end
+
+      # The frozen set of files a #recheck must re-analyse: the
+      # symbol/ancestry-granularity closure of the changed files (slice 4),
+      # the added files themselves, the consumers of any symbol / class that
+      # *appeared* in a changed OR added file (slice 3 — a now-defined
+      # `call.unresolved-toplevel` target or `def.override-*` ancestor), and
+      # the consumers of every removed file (which now miss what it provided).
+      # An added file has no before-state, so all its symbols / classes appear.
+      def affected_closure(changed, added, removed)
+        scan = changed + added
+        new_fps = symbol_fingerprints_for(scan)
+        new_class_decls = class_declarations_for(scan)
+        changed_pairs = Incremental.changed_symbol_pairs(changed, @symbol_fingerprints, new_fps)
+        base = if changed_pairs.any? || changed.any? { |f| @ancestry_dependents[f] }
+                 Incremental.affected_with_symbols(changed, changed_pairs, @symbol_dependents, @ancestry_dependents)
+               else
+                 Incremental.affected(changed, @dependents)
+               end
+        closure = base | added.to_set | negative_affected(scan, new_fps, new_class_decls)
+        removed.each { |path| closure |= @dependents[path] || Set.new }
+        closure.freeze
+      end
+
+      # The current project file set (cheap directory expansion, no analysis),
+      # used to detect files added / removed since the last run.
+      def current_files
+        runner = build_runner
+        @paths ? runner.analysis_file_set(@paths) : runner.analysis_file_set
+      end
+
+      # Verification engine (the `--verify-incremental` gate): with NO
+      # source edit, re-analyze `subset` fresh and serve every other
+      # analyzed file from the baseline cache. Because nothing on disk
+      # changed, the merged result MUST equal a full analysis — so this
+      # exercises the subset-analysis and cache-merge paths against a
+      # known-good oracle (a full `--no-cache` run) for an arbitrary
+      # partition, without mutating session state. Returns the merged
+      # diagnostics.
+      def reanalyze_subset(subset)
+        affected = subset.to_set
+        runner = build_runner(analyze_only: affected)
+        fresh = run_runner(runner).diagnostics
+        reused = @analyzed - affected.to_a
+        fresh + reused.flat_map { |path| @cache[path] || [] }
+      end
+
+      # Cross-process incremental run (the `--incremental` flag's engine).
+      # With a disk `snapshot` whose `fingerprint` matches, restore the
+      # prior per-file state and `#recheck` (re-analyze only the changed
+      # closure, serve the rest from the restored cache); otherwise run a
+      # full `#baseline`. Either way, persist the updated snapshot for the
+      # next process. Returns `[diagnostics, warm]` — `warm` is true when a
+      # snapshot was restored. A nil `fingerprint` (uncomputable inputs)
+      # disables persistence: a plain full run.
+      def run_incremental(snapshot:, fingerprint:)
+        restored = fingerprint && snapshot.load(fingerprint: fingerprint)
+        if restored
+          restore(restored)
+          diagnostics = recheck.diagnostics
+          warm = true
+        else
+          diagnostics = baseline
+          warm = false
+        end
+        snapshot.save(fingerprint: fingerprint, payload: to_payload) if fingerprint
+        [diagnostics, warm]
+      end
+
+      private
+
+      # Adopt a persisted snapshot's per-file state as this session's
+      # baseline (the warm-start path).
+      def restore(payload)
+        @analyzed = payload.analyzed
+        @cache = payload.cache
+        @sources = payload.sources
+        @digests = payload.digests
+        @dependents = Incremental.invert(@sources)
+        # ADR-46 slice 4 — restore symbol-granularity state if present in the
+        # payload (absent in snapshots written before slice 4 → fall back to
+        # file-level dependents, which is always sound).
+        @symbol_sources    = payload.symbol_sources    || {}
+        @ancestry_sources  = payload.ancestry_sources  || {}
+        @symbol_fingerprints = payload.symbol_fingerprints || {}
+        # ADR-46 slice 3 — restore negative edges if present (absent in
+        # pre-slice-3 snapshots → empty, which only loses the appeared-symbol
+        # re-check refinement; the fingerprint still drops the snapshot on a
+        # file add/remove, so it is never unsound).
+        @missing           = payload.missing || {}
+        @class_decls       = payload.class_decls || {}
+        @symbol_dependents = Incremental.invert_symbols(@symbol_sources)
+        @ancestry_dependents = Incremental.invert(@ancestry_sources)
+        @negative_dependents = Incremental.invert(@missing)
+      end
+
+      def to_payload
+        Cache::IncrementalSnapshot::Payload.new(
+          cache: @cache, sources: @sources, digests: @digests, analyzed: @analyzed,
+          symbol_sources: @symbol_sources, ancestry_sources: @ancestry_sources,
+          symbol_fingerprints: @symbol_fingerprints, missing: @missing,
+          class_decls: @class_decls
+        )
+      end
+
+      # Fold a #recheck's fresh results back into the cache + graph so the
+      # session is correct across multiple edits: the analyzed set gets fresh
+      # diagnostics + digests + dependency edges, removed files are evicted
+      # from every map, and the analyzed-file list advances to `current`.
+      def absorb(runner, fresh, current, analyze_set, removed)
+        removed.each { |path| forget(path) }
+        @analyzed = current
+        fresh_by_file = per_file(fresh)
+        analyze_set.each do |path|
+          @cache[path] = fresh_by_file[path] || []
+          @digests[path] = digest(path)
+        end
+        absorb_dependency_graph(runner)
+      end
+
+      # Evict a removed file from every per-file map so its stale diagnostics
+      # are never served and it drops out of the inverted dependency indexes.
+      def forget(path)
+        @cache.delete(path)
+        @digests.delete(path)
+        @sources.delete(path)
+        @symbol_sources.delete(path)
+        @ancestry_sources.delete(path)
+        @missing.delete(path)
+        @symbol_fingerprints.delete(path)
+        # @class_decls is wholesale-replaced from the (removed-excluding)
+        # pre-pass in absorb_dependency_graph, and is frozen, so no delete.
+      end
+
+      # Fold a runner's dependency recording (file-level and symbol-level) back
+      # into the session's graph state. Rebuilds all derived indexes.
+      def absorb_dependency_graph(runner)
+        runner.file_dependencies.each do |path, record|
+          @sources[path] = record.sources.dup
+          @symbol_sources[path]   = record.symbol_sources.transform_values(&:dup)
+          @ancestry_sources[path] = record.ancestry_sources.dup
+          @missing[path]          = record.missing.dup
+        end
+        @dependents          = Incremental.invert(@sources)
+        @symbol_dependents   = Incremental.invert_symbols(@symbol_sources)
+        @ancestry_dependents = Incremental.invert(@ancestry_sources)
+        @negative_dependents = Incremental.invert(@missing)
+        @symbol_fingerprints.merge!(runner.symbol_fingerprints)
+        # Wholesale replace (the subset runner's pre-pass is complete): a file
+        # that lost its last class must drop out of the map so a later re-add
+        # registers as an appearance.
+        @class_decls = runner.class_declarations
+      end
+
+      # Compute per-symbol body fingerprints for `paths` via a quick indexing
+      # re-pass (Prism parse + def extraction, no type inference). Returns a
+      # hash of the form `{ path => { "ClassName#method" => sha256_hex } }`.
+      # Used by {#recheck} to detect which symbols in a changed file actually
+      # changed, so only their callers are added to the affected closure.
+      def symbol_fingerprints_for(paths)
+        return {} if paths.empty?
+
+        index = Inference::ScopeIndexer.discovered_def_index_for_paths(paths)
+        def_nodes   = index[:def_nodes]
+        def_sources = index[:def_sources]
+        result = Hash.new { |h, k| h[k] = {} }
+        def_sources.each do |class_name, methods|
+          methods.each do |method_sym, path_line|
+            path = path_line.split(":", 2).first
+            node = def_nodes.dig(class_name, method_sym)
+            next unless node
+
+            result[path]["#{class_name}##{method_sym}"] =
+              Digest::SHA256.hexdigest(node.location.slice)
+          end
+        end
+        result.transform_values(&:freeze).freeze
+      end
+
+      # ADR-46 slice 3 — the consumers to re-check because a symbol that
+      # appeared in a changed file resolves a prior missed lookup. Maps each
+      # appeared `"ClassName#method"` to the negative-dependency key it would
+      # satisfy (`toplevel:foo` for a top-level def, `method:C#m` otherwise),
+      # then unions the recorded negative-dependents of those keys.
+      def negative_affected(changed, new_fingerprints, new_class_decls)
+        appeared_methods = Incremental.appeared_symbols(changed, @symbol_fingerprints, new_fingerprints)
+        appeared_classes = Incremental.appeared_classes(changed, @class_decls, new_class_decls)
+        keys = appeared_methods.map { |symbol| negative_key_for(symbol) }
+        keys.concat(appeared_classes.map { |klass| "class:#{klass.split('::').last}" })
+        Incremental.negative_closure(keys, @negative_dependents)
+      end
+
+      # The qualified class/module names declared in `paths`, via the same
+      # quick indexing re-pass {#symbol_fingerprints_for} uses (Prism parse +
+      # declaration extraction, no inference). `{ path => Set<class name> }`.
+      def class_declarations_for(paths)
+        return {} if paths.empty?
+
+        index = Inference::ScopeIndexer.discovered_def_index_for_paths(paths)
+        result = Hash.new { |hash, key| hash[key] = Set.new }
+        index[:class_sources].each do |class_name, files|
+          files.each { |file| result[file] << class_name }
+        end
+        result.transform_values(&:freeze).freeze
+      end
+
+      TOP_LEVEL_KEY = Inference::ScopeIndexer::TOP_LEVEL_DEF_KEY
+      private_constant :TOP_LEVEL_KEY
+
+      def negative_key_for(symbol)
+        class_name, method = symbol.split("#", 2)
+        class_name == TOP_LEVEL_KEY ? "toplevel:#{method}" : "method:#{symbol}"
+      end
+
+      def build_runner(**)
+        Runner.new(configuration: @configuration, cache_store: nil, **)
+      end
+
+      # Run the runner over the session's explicit paths (or, when none were
+      # given, the configuration's `paths:` via `Runner#run`'s default).
+      def run_runner(runner)
+        @paths ? runner.run(@paths) : runner.run
+      end
+
+      # Group diagnostics by their file path, keeping only those whose path
+      # is an analyzed project file — run-level streams (the gem-RBS info
+      # diagnostic, keyed on `.rigor.yml`) are recomputed fresh every run
+      # and must not be served from the per-file cache.
+      def per_file(diagnostics)
+        diagnostics.group_by(&:path).slice(*@analyzed)
+      end
+
+      def digest(path)
+        Digest::SHA256.hexdigest(File.read(path))
+      rescue StandardError
+        "missing"
+      end
+    end
+  end
+end

data/lib/rigor/analysis/rule_catalog.rb

@@ -78,6 +78,29 @@ module Rigor
           since: "0.0.1"
         ),
 
+        CheckRules::RULE_SELF_UNDEFINED_METHOD => Entry.new(
+          id: CheckRules::RULE_SELF_UNDEFINED_METHOD,
+          summary: "Implicit-self call resolves to no method on a confidently-closed class.",
+          fires_when: [
+            "The call is an implicit-self call (no explicit receiver) inside a class body.",
+            "The engine's own resolution (RBS dispatch + the user-class ancestor walk) found nothing.",
+            "The enclosing class is a STANDALONE project class: no superclass and no `include`/`prepend`.",
+            "It defines no `method_missing` and no dynamic `attr_*(*splat)` accessor.",
+            "It is not a plugin-declared open receiver (ADR-26)."
+          ],
+          does_not_fire_when: [
+            "The enclosing scope is a `module` (a mixin contract — methods may come from includers).",
+            "The class has a superclass or mixes in a module (surface extends beyond this file — a later slice).",
+            "`self` is `Dynamic` / top-level (the gradual guarantee), or the method exists via any project signal.",
+            "Off in every shipped profile pending the external corpus FP gate — opt in via `severity_overrides:`."
+          ],
+          suppression: "`# rigor:disable call.self-undefined-method`, or enable/disable via " \
+                       "`severity_overrides: { call.self-undefined-method: warning }` in `.rigor.yml`.",
+          severity_authored: :warning,
+          severity_by_profile: { lenient: :off, balanced: :off, strict: :off },
+          since: "0.1.17"
+        ),
+
         CheckRules::RULE_WRONG_ARITY => Entry.new(
           id: CheckRules::RULE_WRONG_ARITY,
           summary: "Call's positional argument count is outside the declared overloads' envelope.",
@@ -226,6 +249,31 @@ module Rigor
           since: "0.1.2"
         ),
 
+        CheckRules::RULE_UNREACHABLE_CLAUSE => Entry.new(
+          id: CheckRules::RULE_UNREACHABLE_CLAUSE,
+          summary: "A `case` / `when` clause the flow engine's narrowing proves can never match.",
+          fires_when: [
+            "The subject is a `case <local>` (`LocalVariableReadNode`), the only shape the engine narrows.",
+            "Every `when` condition is a class / module constant (`when String` / `when MyClass`).",
+            "The clause's narrowed body subject is `Type::Bot` — disjoint from the subject (`when String` " \
+            "over an `Integer`) or already exhausted by an earlier clause (prior-exhaustion)."
+          ],
+          does_not_fire_when: [
+            "The subject's type at case entry is `Dynamic` (disjointness is never provable under gradual " \
+            "`Dynamic`, preserving the gradual guarantee) or already `Bot` (dead code, not a clause error).",
+            "A `when` condition is not a class / module constant — `when nil`, ranges, regexps, and " \
+            "arbitrary expressions are out of the WD1 scope.",
+            "The clause sits inside a `WhileNode` / `UntilNode` / `ForNode` / `BlockNode` (mutation tracking " \
+            "through those is incomplete), or its body is empty (no useful location)."
+          ],
+          suppression: "`# rigor:disable unreachable-clause` on the dead-clause body line.",
+          severity_authored: :warning,
+          # ADR-47 WD4: balanced stays :info (one notch below its `flow.*`
+          # siblings' :warning) until the regression-corpus FP gate is green.
+          severity_by_profile: { lenient: :info, balanced: :info, strict: :warning },
+          since: "0.1.17"
+        ),
+
         CheckRules::RULE_DEAD_ASSIGNMENT => Entry.new(
           id: CheckRules::RULE_DEAD_ASSIGNMENT,
           summary: "Local variable assigned in a method body but never read.",