rigortype 0.3.9 → 0.4.1

data/lib/rigor/scope/discovery_index.rb

@@ -15,6 +15,7 @@ module Rigor
       :class_ivars,
       :class_cvars,
       :program_globals,
+      :program_global_seeds,
       :discovered_classes,
       :in_source_constants,
       :discovered_methods,
@@ -24,12 +25,20 @@ module Rigor
       :discovered_def_sources,
       :discovered_singleton_def_sources,
       :discovered_method_visibilities,
+      :discovered_parameter_envelopes,
       :discovered_superclasses,
+      :discovered_deferred_ranges,
+      :discovered_refinements,
+      :discovered_global_write_census,
       :discovered_header_nestings,
       :discovered_includes,
+      :discovered_prepends,
       :discovered_extends,
+      :unpositioned_mixins,
       :discovered_class_sources,
       :constant_sources,
+      :constant_writers,
+      :constant_shadowers,
       :published_constant_names,
       :local_constant_names,
       :published_constant_alias_names,
@@ -37,7 +46,17 @@ module Rigor
       :data_member_layouts,
       :struct_member_layouts,
       :param_inferred_types,
-      :run_generation
+      :run_generation,
+      :patched_line_readers,
+      :clears_last_status,
+      :defines_case_equality,
+      :implicit_self_evidence,
+      :possible_discovered_methods,
+      :possible_discovered_deferred_ranges,
+      :contested_discovered_def_nodes,
+      :contested_discovered_singleton_def_nodes,
+      :contested_discovered_method_visibilities,
+      :contested_discovered_parameter_envelopes
     )
 
     class DiscoveryIndex
@@ -46,6 +65,114 @@ module Rigor
       EMPTY_NAME_SET = Set.new.freeze
       private_constant :EMPTY_NODE_TABLE, :EMPTY_TABLE, :EMPTY_NAME_SET
 
+      # ADR-119 WD1 — each member that may one day admit `possible` or `contested` facts, and the sibling that
+      # holds them. Every copy path reads this one declaration, so a member never travels without its sibling:
+      # {#with} raises on a half pair and {.compact_pairs} drops a pair only when BOTH halves are empty. No
+      # producer fills a sibling yet (the lane-1 carriage), so every sibling is empty and each member keeps its
+      # meaning, the union of its certain and possible facts.
+      #
+      # - `possible_*` has its member's shape and is a subset of it (a `discovered_methods` pair is a
+      #   `{class => {name => kind}}` table).
+      # - `contested_*` is a Set of key paths into its member, one per entry whose value depends on a possible
+      #   fact: `[class, method]`, or `[class, [kind, method]]` for an envelope.
+      #
+      # The members without a sibling here (`discovered_def_sources`, `discovered_singleton_def_sources`) are site
+      # tables (dependency edges, positions, fingerprints): no read takes a definer, visibility, arity or type from
+      # them, and certainty does not move a site. The reads whose answer depends on the site are
+      # `Scope#same_file_top_level_def?` (file identity, independent of certainty), `#singleton_def_shadows_call?`
+      # and `#instance_def_shadows_call?` (a conditional def's site answers "shadows"). Where "shadows" narrows an
+      # answer, the caller pairs it with {#possible_method?}: existence is the method table, certainty is the possible
+      # table alone (ADR-119 C1d-c).
+      SIBLINGS = {
+        discovered_methods: :possible_discovered_methods,
+        discovered_deferred_ranges: :possible_discovered_deferred_ranges,
+        discovered_def_nodes: :contested_discovered_def_nodes,
+        discovered_singleton_def_nodes: :contested_discovered_singleton_def_nodes,
+        discovered_method_visibilities: :contested_discovered_method_visibilities,
+        discovered_parameter_envelopes: :contested_discovered_parameter_envelopes
+      }.freeze
+
+      # Either half of a pair to the other.
+      PARTNERS = SIBLINGS.flat_map { |member, sibling| [[member, sibling], [sibling, member]] }.to_h.freeze
+      private_constant :PARTNERS
+
+      # [#1507](https://github.com/rigortype/rigor/issues/1507) — the kind of fact each member holds, which decides
+      # what a reader may conclude from an entry and which gate covers the member (ADR-119 WD4, proposed). Each
+      # reason describes the table as the code builds it today. `spec/rigor/declaration_facts/member_classes_spec.rb`
+      # fails on a member that is unclassified or classified twice, and checks each class's shape on an index built
+      # from a fixture project; it pins the few misfilings those checks accept.
+      #
+      # - `:set_valued` — names, edges, files or rows whose presence is the fact. A reader asks whether an entry is
+      #   there.
+      # - `:single_valued` — one value per key, which readers use; disagreeing contributions fold by a fixed rule.
+      # - `:typed` — the values are types, which already carry uncertainty in the type lattice.
+      # - `:syntactic` — read off the parse of the analysed file alone, which is their reference.
+      # - `:run_state` — the run's own state, not a fact about the program.
+      # - `:sibling` — the `possible_*` / `contested_*` half of a pair in {SIBLINGS}, which travels with its member.
+      MEMBER_CLASSES = {
+        set_valued: {
+          discovered_classes: "the class and module names the project declares; the value is the name's singleton",
+          discovered_methods: "which names each class answers, and on which side",
+          discovered_refinements: "the methods a refine block adds, keyed by the refined class",
+          discovered_global_write_census: "the names any file aliases, defines or mixes in at the top level",
+          discovered_includes: "the modules each class includes, prepends among them",
+          discovered_prepends: "the modules each class prepends",
+          discovered_extends: "the modules each singleton mixes in; the module itself for module_function",
+          unpositioned_mixins: "per side, the mixin edges each class records whose order is not a fact, or \"*\"",
+          discovered_class_sources: "the files that declare each class, reopenings included",
+          discovered_deferred_ranges: "each file's def and block ranges; def rows add owner and module_function side",
+          constant_sources: "the files that write each constant",
+          constant_writers: "the constant names some write binds, by last segment",
+          constant_shadowers: "the constant names a non-memo write assigns, by last segment",
+          published_constant_names: "the last segments of the constants the project publishes",
+          local_constant_names: "the last segments of the constants the analysed file assigns",
+          published_constant_alias_names: "the file's constants copied straight from a published one",
+          published_constant_ivars: "the ivars each class seeds from a published constant"
+        }.freeze,
+        single_valued: {
+          discovered_def_nodes: "the def node each instance method resolves to",
+          discovered_singleton_def_nodes: "the def node each singleton method resolves to",
+          discovered_def_sources: "the first-seen path:line of each instance method, which readers use",
+          discovered_singleton_def_sources: "the first-seen path:line of each singleton method, which readers use",
+          discovered_method_visibilities: "each method's visibility",
+          discovered_parameter_envelopes: "each method's parameter shape, opaque when contributions disagree",
+          discovered_superclasses: "each class's superclass as written",
+          discovered_header_nestings: "the cref each ancestor name resolves in, an alternatives list when ambiguous",
+          data_member_layouts: "each Data class's member layout",
+          struct_member_layouts: "each Struct class's member layout"
+        }.freeze,
+        typed: {
+          declared_types: "the type each declaration node binds",
+          class_ivars: "the joined type of each ivar's writes, per class",
+          class_cvars: "the joined type of each cvar's writes, per class",
+          program_globals: "the joined type of each global's writes",
+          program_global_seeds: "a declared global's signature type joined with its writes",
+          in_source_constants: "the type each constant's write binds",
+          param_inferred_types: "the union of each parameter's call-site argument types"
+        }.freeze,
+        syntactic: {
+          discovered_def_nestings: "the Module.nesting each def is written in, keyed by node identity",
+          patched_line_readers: "the gets / readline names the file defines through the define_method family",
+          clears_last_status: "whether the analysed file holds a call that may set $? to nil",
+          defines_case_equality: "whether the analysed file holds a define_method naming ===",
+          implicit_self_evidence: "where the file's implicit-self readers sit; built lazily from its tree, never seeded"
+        }.freeze,
+        run_state: {
+          run_generation: "the identity token of the current run"
+        }.freeze,
+        sibling: {
+          possible_discovered_methods: "the names and sides of discovered_methods that only a possible definer gives",
+          possible_discovered_deferred_ranges: "the rows of discovered_deferred_ranges that only a possible fact gives",
+          contested_discovered_def_nodes: "the key paths of discovered_def_nodes that a possible definer may change",
+          contested_discovered_singleton_def_nodes:
+            "the key paths of discovered_singleton_def_nodes that a possible definer may change",
+          contested_discovered_method_visibilities:
+            "the key paths of discovered_method_visibilities that a possible fact may change",
+          contested_discovered_parameter_envelopes:
+            "the key paths of discovered_parameter_envelopes that a possible fact may change"
+        }.freeze
+      }.freeze
+
       # The third value a `discovered_methods` entry can hold, beside `:instance` and `:singleton`. One name may
       # legitimately be defined on both sides of the same class (`def helper` plus a `class << self` twin), and the
       # table is keyed by name alone — so before this existed the second `def` overwrote the first's kind and
@@ -60,6 +187,55 @@ module Rigor
       # as written, and no ancestor name can be nil.
       UNKEYED_HEADER_NESTING = nil
 
+      # Issue #986 — a bucket entry is normally ONE chain (`["Wrap"]`, innermost first). When the
+      # compact-header rename pass lands two declarations of one class on a single key and both wrote the
+      # same raw ancestor name in DIFFERENT crefs, the entry is instead the LIST of those chains —
+      # `[["Wrap"], []]` — because no union of them is Ruby's answer for either site. `Scope` resolves each
+      # alternative and declines outright when they name two different project classes: which one wins
+      # depends on the runtime load order of the two `include`s, which static analysis cannot know, so
+      # picking either is unsound. A chain's entries are Strings and an alternatives list's are Arrays, so
+      # the two shapes cannot be confused.
+      def self.ambiguous_header_nesting?(entries)
+        entries.first.is_a?(Array)
+      end
+
+      # Issue #992 — the two class-wide keys a `discovered_parameter_envelopes` bucket can carry beside its
+      # `[kind, method_name]` entries. Their PRESENCE is the fact; the value is always
+      # `Source::ParameterEnvelope::OPAQUE`, so a bucket folds under the one join every other entry does.
+      # Symbols, because every per-method key is an Array and neither can collide with the other.
+      #
+      # The class marks below and {ENVELOPE_PROJECT_WIDE} are presence facts read only to decline a read; they are
+      # never a contested path. Contested envelope paths are always `[class, [kind, name]]`.
+      #
+      # - {ENVELOPE_MODULE_MARK}: the name is declared with `module` (or `Const = Module.new do … end`) somewhere
+      #   in the project. An instance of it is an instance of an unknown includer.
+      # - {ENVELOPE_DYNAMIC_MARK}: the class body rewrites its method table in a way no literal argument names
+      #   (`class_eval`, a computed `define_method`, `send`, a non-constant mixin), or a constant-receiver form
+      #   of those names it from outside.
+      # - {ENVELOPE_OBJECT_EXTENDED_MARK}: some method body passes the module to `extend`, so an object of any
+      #   class may carry its instance methods ahead of that class's own.
+      # - {ENVELOPE_REFINED_MARK}: a `refine` block refines the class, which redefines its methods wherever a `using`
+      #   is in effect. Issue #1367 splits it from {ENVELOPE_DYNAMIC_MARK}, which it used to share: an implicit
+      #   conversion (`to_str`, `to_int`) ignores a refinement, so the `global.*` rules must tell the two apart.
+      #   Every reader that asks whether a surface is rewritten reads both ({.rewritten_surface?}).
+      ENVELOPE_MODULE_MARK = :"<module>"
+      ENVELOPE_DYNAMIC_MARK = :"<dynamic>"
+      ENVELOPE_OBJECT_EXTENDED_MARK = :"<object-extended>"
+      ENVELOPE_REFINED_MARK = :"<refined>"
+
+      # Whether an envelope bucket says the project rewrites the class's method table beyond its literal names: a
+      # dynamic rewrite, or a refinement.
+      def self.rewritten_surface?(bucket)
+        bucket.key?(ENVELOPE_DYNAMIC_MARK) || bucket.key?(ENVELOPE_REFINED_MARK)
+      end
+
+      # Issue #992 — the class key a WHOLE-PROJECT discovery pass adds to `discovered_parameter_envelopes`
+      # (`ScopeIndexer#finalize_def_index`), with an empty bucket. A single file's walk alone — `run_source`,
+      # the LSP `prebuilt:` scope — sees one `def` and cannot see the reopening, subclass or `class_eval` in
+      # another file that would make it opaque, so `call.wrong-arity` reads an envelope only when this key is
+      # present. Not a constant character, so no class can be named it.
+      ENVELOPE_PROJECT_WIDE = "<project-wide>"
+
       # The shared all-empty index `Scope.empty` (and every scope that never sees a seeding pass) points at — one
       # allocation per process.
       EMPTY = new(
@@ -67,6 +243,12 @@ module Rigor
         class_ivars: EMPTY_TABLE,
         class_cvars: EMPTY_TABLE,
         program_globals: EMPTY_TABLE,
+        # Issue #1362 — for each global in `program_globals` that Ruby's own signatures declare (`$VERBOSE: bool?`,
+        # `$stdout: IO`), its declared type joined with its writes in the file: what every method body and the top
+        # level start from, under the ADR-58 `:global` mark. Any other global starts from its `program_globals` entry,
+        # which keeps the writes alone for the consumers that compare against them (the mark's gates, and `$;` for
+        # `split`). Filled by `Inference::ScopeIndexer.index` from the file's own tree only.
+        program_global_seeds: EMPTY_TABLE,
         discovered_classes: EMPTY_TABLE,
         in_source_constants: EMPTY_TABLE,
         discovered_methods: EMPTY_TABLE,
@@ -87,7 +269,37 @@ module Rigor
         discovered_def_sources: EMPTY_TABLE,
         discovered_singleton_def_sources: EMPTY_TABLE,
         discovered_method_visibilities: EMPTY_TABLE,
+        # Issue #992 — `{qualified class name => {[kind, method_name] => Source::ParameterEnvelope}}`, the
+        # parameter envelope of every method the declaration walk records, plus {ENVELOPE_MODULE_MARK} /
+        # {ENVELOPE_DYNAMIC_MARK}. Written beside `discovered_methods` by one recorder, so an `alias` / `attr_*`
+        # / `define_method` name is always present here as `OPAQUE`, and folded across files and reopenings
+        # with `Source::ParameterEnvelope.merge`: one value per name, a real envelope only while every
+        # contribution agrees. Read by `call.wrong-arity` for a method no signature declares.
+        discovered_parameter_envelopes: EMPTY_TABLE,
         discovered_superclasses: EMPTY_TABLE,
+        # Issue #1097 — `{file path => [[start_offset, end_offset, name, kind, owner], ...]}`, every
+        # `def` / block / lambda body range in the file. `Scope#*_def_shadows_call?` reads it to tell
+        # an eager class-body call (orderable by offset against a same-name, same-owner def entry)
+        # from a deferred one (contained in any range — it runs at invocation time, when every
+        # class-body def exists). Def entries carry the method name, the `:instance` / `:singleton` /
+        # `:both` (module_function) kind, and the qualified owner; block / lambda rows and defs nested
+        # inside another deferred range carry nils and answer only the containment half. Plain data,
+        # so the ADR-85 seed bundle round-trips it unchanged.
+        discovered_deferred_ranges: EMPTY_TABLE,
+        # Issue #1120 — `{refined class name => {method name => [refining module names]}}`, the instance
+        # methods a `refine X do … end` block defines. They are not X's methods everywhere: Ruby activates them
+        # only lexically after a `using` of the refining module, so `call.undefined-method` reads this table
+        # together with the call site's file ({Analysis::CheckRules::LexicalMethodSites}) and never through
+        # `discovered_methods`. A refinement a `Module.new { … }` block defines has no nameable module; it is
+        # keyed by the name the walk gives the block's owner. Plain data, so the ADR-85 seed bundle
+        # round-trips it unchanged.
+        discovered_refinements: EMPTY_TABLE,
+        # Issue #1367 — the project's `Inference::GlobalWriteCensus`: the globals any `alias` names, the
+        # `write` / `to_str` / `to_int` / hatch names any file defines (inside a refinement or not), and the
+        # modules a top-level mixin names, over every file and inside method bodies too. The `global.*` write rules
+        # read it. The project pre-pass seeds the whole project's census and `Inference::ScopeIndexer.index` adds the
+        # analysed file's own. Plain data, so the ADR-85 seed bundle round-trips it unchanged.
+        discovered_global_write_census: EMPTY_NAME_SET,
         # Issue #682 — `{qualified class name => Module.nesting where its declaration HEADER is written}`,
         # innermost first and EXCLUDING the declaration's own entry. Read by `Scope#ancestor_name_candidates`,
         # which resolves a superclass / include name in that cref instead of peeling the subclass's qualified
@@ -102,18 +314,54 @@ module Rigor
         # a name no site recorded under its own key.
         discovered_header_nestings: EMPTY_TABLE,
         discovered_includes: EMPTY_TABLE,
+        # Issue #1123 — `{qualified class or module name => [module names it `prepend`s, as written]}`,
+        # stored in instance-ancestor SEARCH order (nearest prepend first), the `discovered_extends`
+        # convention. The instance-side twin `discovered_includes` holds the same names — prepends
+        # included — in that order too since #1173: prepends ahead of includes, each nearest-first. The
+        # kind still cannot be told apart there, so `Scope#user_def_through_ancestors` reads the wedge
+        # from here. An absent entry means "prepends nothing", which is the un-preprended behaviour
+        # every scope had before it existed.
+        discovered_prepends: EMPTY_TABLE,
         # Issue #898 — the singleton-side twin of `discovered_includes`: `{qualified class or module name =>
         # [module names it `extend`s, as written]}`, built by the same `ScopeIndexer` walk that #526 already
         # ran to fold an extended module's instance defs onto the extending class's singleton. #526 consumed
         # the table inside the indexer and threw it away; `Narrowing` needs it to survive onto the scope,
         # because `Singleton[C]`'s ancestry is exactly what `extend` writes and nothing else records it.
         discovered_extends: EMPTY_TABLE,
+        # `{qualified class or module name => {include: [names], extend: [names]}}` — the mixin edges of the three
+        # tables above whose ORDER is not a fact, per side (`:include` is the instance side, `include` and
+        # `prepend`; `:extend` the singleton side). An edge is listed when it is written anywhere but as a direct
+        # statement of the class's own body (or its `class << self` body) in a declaration that is itself a
+        # direct statement — inside a `def`, a block, a conditional, or a conditional or deferred declaration —
+        # or in the receiver form, and when it shares an argument list with a name the walk could not record
+        # (`Inference::ScopeIndexer::MixinAccumulator`). A mixin call the walk cannot record at all (`include
+        # helper`, `include(*MODS)`, `send(:include, M)`, `self.include M`, `C.include(M)`,
+        # `singleton_class.include M`, a call on a `self.included(base)`-style hook's parameter, an `*_eval` block on
+        # one or on an opaque receiver whose body mixes a module in) lists the name
+        # `"*"` on the side it reshapes: that side of the owner has no known order. An edge written both ways
+        # is listed. Folded by union. A reader that depends on the order of a class's ancestors MUST decline
+        # when the owner it asks about, or any ancestor it walks through, lists anything on the side it reads;
+        # the three tables themselves are unchanged.
+        unpositioned_mixins: EMPTY_TABLE,
+        # The files that declare each class, reopenings included. Seeded on every run: the ADR-46 recording
+        # accessors read it for their class edges, and an ancestor-order reader reads whether a class is
+        # declared in more than one file, where the order of its mixins across the files is load order.
         discovered_class_sources: EMPTY_TABLE,
         # Issue #644 — `{qualified constant name => Set[declaring file]}`, the write attribution behind the
         # cross-file value-constant table. Read only by `Scope#record_constant_dependency` during ADR-46
         # dependency recording, so the runner seeds it only on a recording run; every other run leaves it
         # empty and the edge costs one nil check.
         constant_sources: EMPTY_TABLE,
+        # Issue #617 — the censused names that bind (any write other than a memo `||=`, or memos of the
+        # segment in two files), grouped by LAST SEGMENT, wildcard keys (`*::LIMIT`) under their segment.
+        # `Scope#bound_constant_names` reads it for a constant compound write whose plain read resolves to
+        # nothing: such a name is bound, just not to a value the analyzer carries. Seeded on every run, because
+        # the question is a typing one rather than a recording one.
+        constant_writers: EMPTY_TABLE,
+        # Issue #1290 — the censused names some write other than a memo `||=` assigns, grouped by LAST SEGMENT.
+        # `Scope#shadowing_constant_names` reads it for the lexical ladder: a candidate no source types but this
+        # table holds is where Ruby's lookup stops. Seeded on every run beside `constant_writers`.
+        constant_shadowers: EMPTY_TABLE,
         # Issue #644 — the two halves of `Scope#published_constant?`, the question
         # {Analysis::CheckRules::PublishedConstantGuard} asks. `published_constant_names` is the LAST
         # SEGMENTS of the project-wide published table (run-wide, seeded by the runner);
@@ -147,8 +395,109 @@ module Rigor
         # cross a run boundary (LSP / ADR-62 warm-loop re-runs land in a fresh bucket). Nil on scopes that
         # never see the runner seed (single-file probes, `run_source` before the seed applies): the memo
         # falls back to today's per-file `discovered_def_nodes` identity for those.
-        run_generation: nil
+        run_generation: nil,
+        # Issue #1359 — the `gets` / `readline` names this file patches in through the `define_method` family
+        # (`$stdin.define_singleton_method(:gets) { … }`, `IO.define_method(:gets)`, `alias_method :gets, :x`, or a
+        # computed name, which may be either), which `Inference::LastLine.reads_line?` declines on, as it does on a
+        # name `BlockCallTiming.project_defines_anywhere?` finds. Filled by `Inference::ScopeIndexer.index` from the
+        # file's own tree only.
+        patched_line_readers: EMPTY_NAME_SET,
+        # Issue #1360 — true when this file holds a call that may set `$?` to nil (`Inference::LastStatus.clears?`: a
+        # `wait`-family call with a flags argument, or `waitall`), which may run between any subprocess and a read of
+        # `$?`, so `Inference::LastStatus.after` binds it nowhere in the file. Filled by `Inference::ScopeIndexer.index`
+        # from the file's own tree only.
+        clears_last_status: false,
+        # Issue #1360 — true when this file holds a `define_method` or `define_singleton_method` call whose literal
+        # name is `===` (`Inference::ErrorInfo.defines_case_equality?`), which may give a class the singleton `===`
+        # `rescue` matches with; the class it lands on is not recorded, so no rescued class binds `$!` in the file.
+        # Filled by `Inference::ScopeIndexer.index` from the file's own tree only.
+        defines_case_equality: false,
+        # Issue #1415 — the file's evidence about the `self` its implicit-self `gets` / `readline` readers run with
+        # (`Inference::LastLine::SelfEvidence`, read on the first ask), which `Inference::LastLine.reads_line?` reads
+        # them by. Filled by `Inference::ScopeIndexer.index` from the file's own tree only; nil, where no file was
+        # indexed, declines every such reader.
+        implicit_self_evidence: nil,
+        # ADR-119 WD1 — the siblings of the members {SIBLINGS} pairs, empty until a producer admits a possible fact.
+        possible_discovered_methods: EMPTY_TABLE,
+        possible_discovered_deferred_ranges: EMPTY_TABLE,
+        contested_discovered_def_nodes: EMPTY_NAME_SET,
+        contested_discovered_singleton_def_nodes: EMPTY_NAME_SET,
+        contested_discovered_method_visibilities: EMPTY_NAME_SET,
+        contested_discovered_parameter_envelopes: EMPTY_NAME_SET
       )
+
+      # The siblings of an all-empty index, `{sibling name => empty value}`, frozen: what a def-index with no
+      # possible fact carries, and a Runner's initial state. Copy it (`dup`) before mutating.
+      EMPTY_SIBLINGS = SIBLINGS.each_value.to_h { |sibling| [sibling, EMPTY.public_send(sibling)] }.freeze
+
+      # The all-empty value of a paired member or sibling.
+      def self.empty_value(name)
+        EMPTY.public_send(name)
+      end
+
+      def self.empty_siblings = EMPTY_SIBLINGS
+
+      # ADR-119 WD1 — `tables` (a `with(**)` argument Hash) with every pair either complete or absent: a pair whose
+      # halves are both missing, nil or empty is dropped, any other pair carries BOTH halves (the half that was
+      # absent or nil becomes its empty value). Dropping members one at a time would strand a non-empty sibling,
+      # and passing a half would make {#with} raise. Entries outside {SIBLINGS} pass through untouched.
+      def self.compact_pairs(tables)
+        tables.each_with_object({}) do |(name, table), out|
+          partner = PARTNERS[name]
+          next out[name] = table if partner.nil?
+          next if out.key?(name)
+
+          other = tables[partner]
+          next if blank_table?(table) && blank_table?(other)
+
+          out[name] = table.nil? ? empty_value(name) : table
+          out[partner] = other.nil? ? empty_value(partner) : other
+        end
+      end
+
+      # Whether `name` is a member or sibling of {SIBLINGS}.
+      def self.paired?(name)
+        PARTNERS.key?(name)
+      end
+
+      def self.blank_table?(table)
+        table.nil? || table.empty?
+      end
+      private_class_method :blank_table?
+
+      # The six siblings as `{sibling name => table}`, for a caller that rebuilds the paired members and carries
+      # their siblings over unchanged.
+      def sibling_tables
+        SIBLINGS.each_value.to_h { |sibling| [sibling, public_send(sibling)] }
+      end
+
+      # ADR-119 WD1/WD2 — whether `class_name` answers `method_name` on `kind` only through a `possible` fact
+      # (`possible_discovered_methods`, empty until a producer admits one). Internal to the candidate-set read.
+      def possible_method?(class_name, method_name, kind)
+        recorded = possible_discovered_methods[class_name.to_s]&.[](method_name.to_sym)
+        recorded == kind || (!recorded.nil? && recorded == METHOD_KIND_BOTH)
+      end
+
+      # ADR-119 WD1 — whether `path` (`[class, name]`, or `[class, [kind, name]]` for an envelope) is a contested
+      # entry of `member`, one of the single-valued members {SIBLINGS} pairs. Internal to the candidate-set read.
+      def contested?(member, path)
+        public_send(SIBLINGS.fetch(member)).include?(path)
+      end
+
+      # Data's `with`, except that a paired member and its sibling are accepted only TOGETHER (ADR-119 WD1): a
+      # caller that rebuilt one without the other would leave the sibling describing the old table, so it
+      # raises instead. A call with no change returns the receiver.
+      def with(**changes)
+        return self if changes.empty?
+
+        changes.each_key do |name|
+          partner = PARTNERS[name]
+          next if partner.nil? || changes.key?(partner)
+
+          raise ArgumentError, "DiscoveryIndex#with: #{name} and #{partner} change together; #{partner} is missing"
+        end
+        super
+      end
     end
   end
 end

data/lib/rigor/scope/resolution_chain/relevance.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+module Rigor
+  class Scope
+    class ResolutionChain
+      # ADR-119 WD2 — per-name relevance, the narrowing of an unsettled chain (#1591). A {Mark} says a node's mixin
+      # edges have no known order; the chain still answers a question about ONE method name when the module the
+      # mark names cannot answer that name, because with no fork every entry reached the chain by a single route,
+      # so a module of unknown presence or position adds or removes only its own closure's entries and moves no
+      # other entry's first occurrence. A closure that cannot answer the name therefore cannot move its first
+      # definer. {ResolutionChain#settle} asks it under `unknown_for:`; nothing else does.
+      #
+      # - A named entry `Q` (not `"*"`) is discharged for `n` when every entry of `Q`'s own instance chain (its
+      #   closure) is clean: (i) a project entry, or an external one RBS knows whose declaration lacks `n`
+      #   (the test `SourceArity#external_mixin_lacks_method?` applies); (ii) no project entry carries the dynamic
+      #   mark, lists `"*"` on the instance side or the mark's, or records `method_missing`; (iii) no project
+      #   entry records `n` in `discovered_methods` (either kind) or in `discovered_method_visibilities`.
+      # - A multi-file mark names no entry: it is discharged when at most one of the node's edges' closures is
+      #   not clean. A mark that is both listed and multi-file must pass both rules.
+      # - An ambiguous spelling (`:arity` only: several project modules a compact-header collision left as the
+      #   spelling's meaning, #986) is discharged when every one of them is clean; any candidate that fails fails it.
+      # - `"*"` and a truncated closure are never discharged.
+      #
+      # The verdict and the edges it read are memoised per `[mark, name]` in the flavor's bucket and the edges are
+      # replayed on every call while a dependency recording is active (ADR-46): per tested project entry its class
+      # edge and the negative method edge on `Owner#name`, per tested external the negative class edge on the last
+      # segment of its spelling, so a new file declaring the module re-checks the consumer.
+      module Relevance
+        WILDCARD = "*"
+
+        # The singleton hooks Ruby calls while a module enters (or is asked to enter) another's ancestry. A module
+        # that defines one can add methods to the includer, extender or prepender with nothing the tables record
+        # on the module (`def self.included(base) = base.attr_reader(:foo)`), so no closure holding one can be
+        # said not to answer a name.
+        HOOKS = %i[included extended prepended inherited append_features extend_object prepend_features].freeze
+
+        module_function
+
+        def discharged?(scope, chain, mark, name)
+          name = name.to_sym
+          memo = ResolutionChain.relevance_memo(scope, chain.flavor)
+          verdict, edges = memo[[mark, name]] ||= compute(scope, chain.flavor, mark, name)
+          replay(scope, edges) if Analysis::DependencyRecorder.active?
+          verdict
+        end
+
+        def compute(scope, flavor, mark, name)
+          context = Context.new(scope, flavor, mark, name)
+          verdict = !mark.listed.include?(WILDCARD) && listed_discharged?(context) && multi_file_discharged?(context)
+          [verdict, context.edges.uniq.freeze].freeze
+        end
+
+        def listed_discharged?(context)
+          mark = context.mark
+          mark.listed.all? { |raw| context.closure_clean?(raw) }
+        end
+
+        def multi_file_discharged?(context)
+          mark = context.mark
+          return true unless mark.multi_file
+
+          edges = context.edge_names
+          edges.count { |raw| !context.closure_clean?(raw) } <= 1
+        end
+
+        def replay(scope, edges)
+          edges.each do |kind, value|
+            case kind
+            when :class then ResolutionChain.record_class(scope, value)
+            when :method then Analysis::DependencyRecorder.read_missing(:method, value)
+            when :external then Analysis::DependencyRecorder.read_missing(:class, value)
+            end
+          end
+        end
+
+        # True only for an ancestor the project does not declare that RBS knows and whose declaration lacks `name`
+        # (`SourceArity#external_mixin_lacks_method?`); an unknown one, or one that has it, may answer.
+        def external_lacks?(scope, candidates, name)
+          known = candidates.find { |candidate| Rigor::Reflection.rbs_class_known?(candidate, scope: scope) }
+          return false if known.nil?
+
+          Rigor::Reflection.instance_method_definition(known, name, scope: scope).nil?
+        rescue StandardError
+          false
+        end
+
+        # One verdict's working state: the scope, the resolver, and the edges the tests read.
+        class Context
+          attr_reader :mark, :edges
+
+          def initialize(scope, flavor, mark, name)
+            @scope = scope
+            @flavor = flavor
+            @mark = mark
+            @name = name
+            @resolver = ResolutionChain.resolver_for(scope, flavor)
+            @edges = []
+          end
+
+          # The raw names of the node's own edges on the side the mark covers.
+          def edge_names
+            discovery = @scope.discovery
+            table = @mark.kind == :extend ? discovery.discovered_extends : discovery.discovered_includes
+            table[@mark.node] || EMPTY_NAMES
+          end
+
+          # Whether the closure of the module `raw` names from the marked node cannot answer the name.
+          def closure_clean?(raw)
+            resolved = @resolver.resolve(@mark.node, raw)
+            case resolved
+            when String then project_closure_clean?(resolved)
+            when Array then resolved.all? { |name| project_closure_clean?(name) }
+            else external_clean?(@resolver.candidates(@mark.node, raw), raw)
+            end
+          end
+
+          private
+
+          def project_closure_clean?(module_name)
+            chain = ResolutionChain.for(@scope, module_name, :instance, @flavor)
+            return false if chain.truncated?
+
+            chain.entries.all? do |entry|
+              entry.external? ? external_clean?(entry.candidates, entry.raw) : project_clean?(entry)
+            end
+          end
+
+          def project_clean?(entry)
+            owner = entry.name
+            @edges << [:class, owner] << [:method, "#{owner}##{@name}"]
+            return false if Scope::DiscoveryIndex.rewritten_surface?(@scope.parameter_envelopes_of(owner))
+            return false if wildcard_listed?(owner)
+            return false if @scope.discovered_method?(owner, :method_missing, :instance)
+            return false if HOOKS.any? { |hook| @scope.discovered_method?(owner, hook, :singleton) }
+
+            !records_name?(owner)
+          end
+
+          def wildcard_listed?(owner)
+            sides = @scope.discovery.unpositioned_mixins[owner]
+            return false if sides.nil?
+
+            [:include, @mark.kind].uniq.any? { |side| sides[side]&.include?(WILDCARD) }
+          end
+
+          def records_name?(owner)
+            @scope.discovered_method?(owner, @name, :instance) || @scope.discovered_method?(owner, @name, :singleton) ||
+              !@scope.discovered_method_visibility(owner, @name).nil?
+          end
+
+          # An ancestor the project does not declare: only a module RBS knows, whose declaration lacks the name,
+          # is evidence it does not define it (`SourceArity#external_mixin_lacks_method?`).
+          def external_clean?(candidates, raw)
+            @edges << [:external, raw.to_s.split("::").last]
+            Relevance.external_lacks?(@scope, candidates, @name)
+          end
+        end
+        private_constant :Context
+
+        EMPTY_NAMES = [].freeze
+        private_constant :EMPTY_NAMES
+      end
+    end
+  end
+end