rigortype 0.3.2 → 0.3.4

data/lib/rigor/effects/discharge.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative "label_set"
+
+module Rigor
+  module Effects
+    # `effects.tolerated:` at judgment time — the discharge policy, **per origin** (ADR-103 WD1 / WD14;
+    # normative in `docs/type-specification/effect-labels.md` § Discharge by policy).
+    #
+    # The rule the whole slice turns on: **a bundle is discharged when ANY of its labels is tolerated.**
+    # An origin is one callee or one construct, and its labels are what that one thing does; tolerating
+    # what the origin was *for* frees the transport it came with. `Logger#info` is `io` + `telemetry`, so
+    # `tolerated: [telemetry]` discharges the whole bundle — the project has said "logging is fine", and
+    # the `io` in that bundle is logging. A `File.read` in the same body is a different origin with a
+    # different bundle, and its `io.fs.read` still counts. That is why summaries keep labels per origin at
+    # all ({Summary#bundles}); a flat label set cannot tell the two `io`s apart.
+    #
+    # Discharge is a **judgment**, never a record. The snapshot on disk holds undischarged sets, the
+    # collector attributes undischarged labels, and only the two consumers below subtract:
+    # {EnvelopeCheck} (through {Propagator}'s second lane) and {SnapshotDiff}. `--no-tolerated-effects` is
+    # the audit switch — the same judgment with {NONE} — and is what makes the policy inspectable
+    # (Steins ADR-0084 invariant 3).
+    class Discharge
+      # The identity policy: nothing is tolerated, so nothing is discharged. What
+      # `--no-tolerated-effects` judges with, and what a project that configured no `tolerated:` list
+      # always has.
+      def self.none
+        @none ||= new([])
+      end
+
+      def initialize(tolerated)
+        @tolerated = tolerated.is_a?(LabelSet) ? tolerated : LabelSet.new(Array(tolerated).map(&:to_s))
+        freeze
+      end
+
+      # Whether the policy discharges nothing at all — the fast path every project that wrote no
+      # `tolerated:` list takes, and the reason the second propagation lane costs zero when unconfigured.
+      def inert?
+        @tolerated.empty?
+      end
+
+      # Whether ONE origin's bundle is discharged: some member of it is tolerated (or subsumed by a
+      # tolerated label — `tolerated: [io]` discharges an `io.fs.read` bundle). An empty bundle is
+      # discharged by nothing, and never carries anything to discharge.
+      def discharges?(labels)
+        return false if inert?
+
+        labels.to_a.any? { |label| @tolerated.admits?(label) }
+      end
+
+      # The join of every bundle this policy does NOT discharge — what a judgment reads in place of
+      # {Summary#proven}. A label that arrives through both a discharged and an undischarged origin
+      # survives, because the undischarged origin proves it on its own.
+      def undischarged(bundles)
+        return flatten(bundles) if inert?
+
+        bundles.reduce(LabelSet::EMPTY) do |acc, (_origin, labels)|
+          discharges?(labels) ? acc : acc.join(labels)
+        end
+      end
+
+      private
+
+      def flatten(bundles)
+        bundles.each_value.reduce(LabelSet::EMPTY) { |acc, set| acc.join(set) }
+      end
+    end
+  end
+end

data/lib/rigor/effects/effect_table.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require_relative "label_set"
+require_relative "summary"
+
+module Rigor
+  module Effects
+    # The whole-project effect graph after propagation: every method key the run collected, with its
+    # direct summary and its transitive closure (ADR-103 WD12).
+    #
+    # An EffectTable is **not a diagnostic and never enters `rigor check`'s stream**. It hangs off the
+    # runner for the report of this slice and the snapshot of #381 to read, exactly as
+    # [ADR-102](../adr/102-unused-code-reachability-report.md) draws the report-versus-diagnostic line.
+    class EffectTable
+      # One method's row.
+      #
+      # `direct` is the {Summary} the collector produced for this method's own body — what a snapshot
+      # records, because a diff over direct summaries stays attributable to the pull request's own lines.
+      # `proven` / `exhaustive` / `causes` are the transitive readings: this method's own labels joined
+      # with every project method it reaches, and the exhaustiveness bit ANDed along the same edges.
+      #
+      # `undischarged` is the same transitive reading with the origin bundles `effects.tolerated:`
+      # discharges removed at their source (#385; {Discharge}) — what a *judgment* reads, where `proven`
+      # is what the record holds. The two are the same set for a project that tolerates nothing, and
+      # `--no-tolerated-effects` is the switch that makes a judgment read `proven` anyway.
+      #
+      # `declared` is the transitive `≤` lane: it travels the same edges as `proven` (ADR-103 WD1), so a
+      # caller two hops above an attributed gem call reads the claim rather than only the taint it left.
+      # The lanes are kept **raw** here — a declared label a proven one already subsumes is dropped where
+      # output is rendered ({LabelSet#excluding_subsumed_by}), never in the table, because a further join
+      # has to see what was actually declared.
+      class Entry < Data.define(:key, :direct, :proven, :undischarged, :declared, :exhaustive, :causes,
+                                :edges)
+        def initialize(undischarged: nil, declared: nil, **rest)
+          super(undischarged: undischarged || rest.fetch(:proven), declared: declared || LabelSet::EMPTY,
+                **rest)
+        end
+
+        # The declared labels worth printing beside `proven` — the rendering rule, in one place so the
+        # report and the snapshot cannot disagree about it.
+        def rendered_declared
+          declared.excluding_subsumed_by(proven)
+        end
+
+        def exhaustive?
+          exhaustive
+        end
+
+        # Whether the report omits this row by default: exhaustive, proving nothing beyond frame-local
+        # mutation, and claiming nothing the proven lane does not already admit ({Summary#trivial?} for
+        # the reasoning behind the declared half). `--full` lists it anyway.
+        def trivial?
+          exhaustive && proven.subsumed_by?(Summary::TRIVIAL_BOUND) && rendered_declared.empty?
+        end
+      end
+
+      EMPTY_ENTRIES = {}.freeze
+      private_constant :EMPTY_ENTRIES
+
+      def self.empty
+        @empty ||= new(EMPTY_ENTRIES)
+      end
+
+      # @param entries [Hash{String => Entry}]
+      def initialize(entries)
+        @entries = entries.sort_by { |key, _| key }.to_h.freeze
+        freeze
+      end
+
+      def [](key)
+        @entries[key]
+      end
+
+      def keys
+        @entries.keys
+      end
+
+      def each(&)
+        @entries.each_value(&)
+      end
+      include Enumerable
+
+      def size
+        @entries.size
+      end
+
+      def empty?
+        @entries.empty?
+      end
+    end
+  end
+end

data/lib/rigor/effects/entry_points.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Effects
+    # The named entry-point presets `effects.snapshot.reach:` may adopt (ADR-103 WD14).
+    #
+    # `reach:` entries are of two kinds, told apart syntactically:
+    #
+    # - a **path glob** — anything carrying a glob or path character (`* ? [ ] / .`) — matched against the
+    #   project-relative file a method is defined in, with the `rigor unused --entry-point` semantics
+    #   (`File.fnmatch?` with `File::FNM_PATHNAME`, so `**` is the only way across a directory boundary);
+    # - a **preset name** — a bare `[a-z0-9_-]+` token — resolved here to the globs the preset stands for.
+    #
+    # Presets are named by the plugin that models a framework — rigor-actionpack's controller actions,
+    # rigor-activejob's `perform`, rigor-actionmailer's mailer methods, rigor-actioncable's channels —
+    # through the `effect_entry_points:` manifest field (#387), and registered here through
+    # {.register_all} once the plugin set is loaded. `Configuration` checks only that a `reach:` entry is
+    # SHAPED like a preset name; the existence check runs where the snapshot expands it, which is the
+    # first point at which the registered set is complete.
+    #
+    # Registration is process-global and happens before a snapshot is built, in the parent process — the
+    # same shape the other CLI-time registries take. Nothing here crosses a fork or a Ractor boundary.
+    module EntryPoints
+      # What makes a `reach:` entry a path glob rather than a preset name. Kept deliberately wide: a name
+      # that looks at all like a path is read as one, because a mistyped preset that matched a file would
+      # be the confusing failure.
+      GLOB_CHARACTERS = %r{[*?\[\]/.]}
+
+      # What a preset name may be spelled with, so a malformed name is rejected at registration rather
+      # than becoming an unfindable key.
+      NAME_PATTERN = /\A[a-z0-9][a-z0-9_-]*\z/
+
+      class Error < StandardError
+      end
+
+      @presets = {}
+
+      class << self
+        # Whether `entry` is a path glob rather than a preset name.
+        def glob?(entry)
+          GLOB_CHARACTERS.match?(entry)
+        end
+
+        # Registers `name` as standing for `globs`. Re-registering the same name with the same globs is a
+        # no-op, so a plugin loaded twice in one process does not raise.
+        def register(name, globs)
+          key = name.to_s
+          raise Error, "not a well-formed entry-point preset name: #{key.inspect}" unless NAME_PATTERN.match?(key)
+
+          patterns = Array(globs).map(&:to_s).uniq.sort.freeze
+          existing = @presets[key]
+          return key if existing == patterns
+          raise Error, "entry-point preset already registered with different globs: #{key.inspect}" if existing
+
+          @presets[key] = patterns
+          key
+        end
+
+        def known?(name)
+          @presets.key?(name.to_s)
+        end
+
+        # Whether `entry` is spelled like a preset name at all — the shape check `Configuration` runs at
+        # load, before any plugin has had the chance to register one.
+        def name?(entry)
+          NAME_PATTERN.match?(entry)
+        end
+
+        # Registers every `effect_entry_points:` preset the loaded plugins declare. Idempotent per name +
+        # glob set, so two runs in one process (the spec suite, the LSP) do not collide; two plugins
+        # claiming one name with different globs is a genuine conflict and raises.
+        def register_all(presets)
+          Array(presets).each { |preset| register(preset.name, preset.globs) }
+        end
+
+        # Every registered preset name, sorted. Empty in this slice.
+        def names
+          @presets.keys.sort.freeze
+        end
+
+        # The globs `name` stands for, or `nil` when nothing registered it.
+        def globs_for(name)
+          @presets[name.to_s]
+        end
+
+        # Drops every registration. For specs only — production code registers and never unregisters.
+        def reset!
+          @presets = {}
+        end
+      end
+    end
+  end
+end

data/lib/rigor/effects/envelope.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative "label_set"
+require_relative "summary"
+
+module Rigor
+  module Effects
+    # An author-declared upper bound on one method's effect labels (ADR-103 WD1; normative in
+    # `docs/type-specification/effect-labels.md` § Effect envelopes).
+    #
+    # Four facts and one seam:
+    #
+    # - {#owner_key} — the method key the envelope binds (`Class#m` / `Class.m`). A class-level
+    #   envelope is read once and {#rebind}ed onto each method of that class discovery knows.
+    # - {#bound} — the {LabelSet} the method's proven labels must be subsumed by. {LabelSet::TOP}
+    #   means "no envelope": the fail-open reading a tag carrying an unknown label degrades to.
+    # - {#source} — which spelling produced it: `:pure_annotation` (`%a{pure}`),
+    #   `:effect_annotation` (`%a{rigor:v1:effect …}` on the method), `:class_annotation` (either
+    #   spelling on the class / module declaration, which is also what {#rebind} stamps — what matters
+    #   downstream is that the bound was distributed rather than written on the method) or
+    #   `:config_envelope` (an `effects.envelopes:` entry, {ConfigEnvelopes}). The last one survives
+    #   {#rebind}: a configured envelope is distributed by construction, so "distributed" is not the
+    #   fact worth stamping — where it was written is.
+    # - {#location} — `path:line` of the annotation, or `.rigor.yml effects.envelopes[N]` for a
+    #   configured one, so the diagnostic can name where the bound was written; {#spelling} is the
+    #   author's own text, quoted back verbatim.
+    # - {#unknown_labels} — the well-formed-but-unrecognised spellings that made this envelope read
+    #   ⊤ ([#384](https://github.com/rigortype/rigor/issues/384)'s `effect.unknown-label` reads it).
+    #   Empty otherwise.
+    # - {#declared_labels} — every token the tag listed, in source order, recognised or not (empty
+    #   for `%a{pure}`, whose bound is written by its spelling rather than by a list). It is what
+    #   answers "was some OTHER member of this list known?", one of the four signals
+    #   {LabelIntent} reads intent off.
+    #
+    # `mutate.local` is tolerated by **every** envelope, `%a{pure}` included: a method may freely
+    # mutate what its own frame allocated and never let escape.
+    class Envelope < Data.define(:owner_key, :bound, :source, :location, :spelling, :unknown_labels,
+                                 :declared_labels)
+      NO_LABELS = [].freeze
+      private_constant :NO_LABELS
+
+      # {#source} for a bound written in `.rigor.yml` rather than on a declaration.
+      CONFIG_SOURCE = :config_envelope
+
+      def self.build(owner_key:, bound:, source:, location: nil, spelling: nil, unknown_labels: NO_LABELS,
+                     declared_labels: NO_LABELS)
+        new(
+          owner_key: owner_key, bound: bound, source: source, location: location,
+          spelling: spelling, unknown_labels: unknown_labels.uniq.sort.freeze,
+          declared_labels: declared_labels.dup.freeze
+        )
+      end
+
+      # Whether this reads as ⊤ — no bound at all. An unknown label degrades the whole tag here, so a
+      # typo suppresses findings rather than inventing them (the fail-open rule).
+      def top?
+        bound.top?
+      end
+
+      # Whether `label` is inside the bound. `mutate.local` always is.
+      def tolerates?(label)
+        bound.admits?(label) || Summary::TRIVIAL_BOUND.admits?(label)
+      end
+
+      # The members of `label_set` this envelope does NOT admit, sorted. One diagnostic per member.
+      def exceeded_by(label_set)
+        return NO_LABELS if top?
+
+        label_set.to_a.reject { |label| tolerates?(label) }
+      end
+
+      # Whether the bound was written in `.rigor.yml` rather than on a declaration.
+      def config?
+        source == CONFIG_SOURCE
+      end
+
+      # The same bound, attached to another method key — how a class-level envelope reaches each
+      # method of its class. The source becomes `:class_annotation`, because the distribution is the
+      # fact the diagnostic has to explain; a configured envelope keeps its own source, because for it
+      # distribution is the only mode there is and `.rigor.yml` is the fact worth naming.
+      def rebind(key)
+        config? ? with(owner_key: key) : with(owner_key: key, source: :class_annotation)
+      end
+    end
+  end
+end

data/lib/rigor/effects/envelope_check.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require_relative "envelope"
+require_relative "effect_table"
+require_relative "method_key"
+require_relative "path_finder"
+
+module Rigor
+  module Effects
+    # Judges each method's declared envelope against what the run actually proved (ADR-103 WD1 / WD8;
+    # #383). The one place `effect.envelope-exceeded` is decided.
+    #
+    # Three rules make this FP-safe, and each is load-bearing:
+    #
+    # - **It reads the PROVEN lane only**, never the declared one and never taint. A non-exhaustive
+    #   summary reads "these effects, and possibly more" and contributes no finding of its own; what
+    #   it *did* prove is still proven, so a proven label outside the bound still fires. That is "as
+    #   strict as proven" ([robustness-principle.md](../../../docs/type-specification/robustness-principle.md)),
+    #   and it is why an unresolved call can never manufacture one.
+    # - **The bound binds the method's CODE, transitively.** The envelope is a contract about what the
+    #   method does, and a repository that calls a helper that calls `Net::HTTP` does perform HTTP. So
+    #   the comparison is against {EffectTable::Entry#proven} — the fixpoint's closure over project
+    #   callees — not against the unit's own direct summary.
+    # - **`mutate.local` is tolerated by every envelope**, `%a{pure}` included ({Envelope#tolerates?}).
+    #
+    # **`effects.tolerated:` discharges, per origin** (#385). The comparison reads
+    # {EffectTable::Entry#undischarged} rather than `proven`: the propagator has already dropped every
+    # origin bundle the policy discharges and closed the rest over the graph, so a `pure`-declared method
+    # that logs is silent under `tolerated: [telemetry]` while the `File.read` two lines down still fires.
+    # `apply_tolerated: false` — `--no-tolerated-effects` — judges against `proven` instead, which is the
+    # audit switch that makes the policy inspectable rather than invisible.
+    module EnvelopeCheck
+      # One (method, exceeding label) pair. `chain` is the shortest project-method path from the
+      # method to whatever proves the label and `origin` is the callee key or construct at its end —
+      # the same explanation `rigor effects explain` prints, so the diagnostic tells a reader where to
+      # look rather than only that something is wrong.
+      Finding = Data.define(:key, :label, :envelope, :path, :line, :chain, :origin)
+
+      # The discovery tables a finding's POSITION is read from, as one value — `discovered_def_sources`
+      # (`{class => {method_sym => "path:line"}}`), its `def self.x` mirror, and `discovered_class_sources`
+      # (`{class => Set[path]}`), the fallback for a method with no Ruby `def` at all. Kept together so the
+      # check's own signature stays about the judgment rather than about where a `def` lives.
+      class Positions < Data.define(:def_sources, :singleton_def_sources, :class_sources)
+        NONE = {}.freeze
+        private_constant :NONE
+
+        def self.empty
+          @empty ||= build
+        end
+
+        def self.build(def_sources: nil, singleton_def_sources: nil, class_sources: nil)
+          new(def_sources: def_sources || NONE, singleton_def_sources: singleton_def_sources || NONE,
+              class_sources: class_sources || NONE)
+        end
+
+        # Where a finding about `key` goes: the Ruby `def`, from the discovery tables (ADR-103 WD14 chose
+        # the `def` over the `.rbs` line deliberately — `# rigor:disable` reads only Ruby comments). A
+        # method with no `def` at all is a synthesized accessor, and the class's own source is the closest
+        # thing to a position it has.
+        #
+        # It lives on the value rather than in {EnvelopeCheck} because {LiskovCheck} positions its
+        # findings identically, and two spellings of "where the fix goes" would eventually disagree.
+        #
+        # @return [Array(String, Integer)] `[path, line]`; `[nil, 1]` for a key with no owner.
+        def for(key)
+          class_name, separator, selector = MethodKey.split(key)
+          return [nil, 1] if class_name.nil?
+
+          table = separator == "." ? singleton_def_sources : def_sources
+          site = table.dig(class_name, selector.to_sym)
+          return split_site(site) if site
+
+          [Array(class_sources[class_name]).first, 1]
+        end
+
+        private
+
+        def split_site(site)
+          path, _, line = site.to_s.rpartition(":")
+          return [site.to_s, 1] if path.empty?
+
+          [path, line.to_i.positive? ? line.to_i : 1]
+        end
+      end
+
+      NO_FINDINGS = [].freeze
+      private_constant :NO_FINDINGS
+
+      module_function
+
+      # @param table [EffectTable] the run's propagated graph.
+      # @param method_envelopes [Hash{String => Envelope}] per-method envelopes, as written.
+      # @param class_envelopes [Hash{String => Envelope}] class- / module-level envelopes, to distribute.
+      # @param config_envelopes [Hash{String => Envelope}] `effects.envelopes:` entries already resolved
+      #   to the classes they select ({ConfigEnvelopes.for_classes}), to distribute at the lowest precedence.
+      # @param positions [Positions] the discovery tables a finding's `def` position is read from.
+      # @param apply_tolerated [Boolean] false judges against the undischarged-by-policy `proven` lane —
+      #   the `--no-tolerated-effects` audit switch.
+      # @return [Array<Finding>] sorted by position then key then label, so a run explains identically twice.
+      def run(table:, method_envelopes:, class_envelopes:, config_envelopes: {},
+              positions: Positions.empty, apply_tolerated: true)
+        envelopes = distribute(table, method_envelopes, class_envelopes, config_envelopes)
+        return NO_FINDINGS if envelopes.empty?
+
+        findings = []
+        envelopes.each do |key, envelope|
+          collect(findings, table, key, envelope, positions, apply_tolerated)
+        end
+        findings.sort_by { |f| [f.path.to_s, f.line, f.key, f.label] }.freeze
+      end
+
+      # Resolves the per-method envelope for every unit the table knows, **nearest wins**:
+      #
+      #     per-method annotation  >  class-level annotation  >  `effects.envelopes:` entry
+      #
+      # The two class-shaped strata distribute identically — an envelope keyed by a class name reaches
+      # every method key of THAT Ruby class, so a subclass's keys never match and a module distributes to
+      # its own methods only — and are applied in that order, so a written annotation always wins over a
+      # convention. Which config entry a class matched was already decided by {ConfigEnvelopes.for_classes}.
+      #
+      # Public because {LiskovCheck} resolves the *ancestor's* envelope by exactly these rules: an
+      # inherited bound has to be the same bound the ancestor is itself held to, or the two checks would
+      # disagree about what the author wrote.
+      def distribute(table, method_envelopes, class_envelopes, config_envelopes)
+        resolved = {}
+        unless class_envelopes.empty? && config_envelopes.empty?
+          keys_by_class(table).each do |class_name, keys|
+            envelope = class_envelopes[class_name] || config_envelopes[class_name]
+            next if envelope.nil?
+
+            keys.each { |key| resolved[key] = envelope.rebind(key) }
+          end
+        end
+        method_envelopes.each { |key, envelope| resolved[key] = envelope if table[key] }
+        resolved
+      end
+
+      # `{class name => [method key]}` over the units the run collected — the "every method discovery
+      # knows" of the class-level distribution rule, including reopenings in other files and the
+      # synthesized `attr_*` / `define_method` members the effects scanner adds.
+      def keys_by_class(table)
+        table.keys.each_with_object({}) do |key, out|
+          owner = MethodKey.owner(key)
+          next if owner.nil?
+
+          (out[owner] ||= []) << key
+        end
+      end
+
+      def collect(findings, table, key, envelope, positions, apply_tolerated)
+        return if envelope.top?
+
+        entry = table[key]
+        return if entry.nil?
+
+        exceeding = envelope.exceeded_by(apply_tolerated ? entry.undischarged : entry.proven)
+        return if exceeding.empty?
+
+        path, line = positions.for(key)
+        exceeding.each do |label|
+          trail = PathFinder.shortest(table, symbol: key, label: label)
+          findings << Finding.new(
+            key: key, label: label, envelope: envelope, path: path, line: line,
+            chain: trail&.chain || [key].freeze, origin: trail&.origin
+          )
+        end
+      end
+
+      private_class_method :keys_by_class, :collect
+    end
+  end
+end

data/lib/rigor/effects/envelope_index.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require_relative "config_envelopes"
+require_relative "envelope"
+require_relative "method_key"
+require_relative "registry"
+require_relative "signature_sources"
+
+module Rigor
+  module Effects
+    # The envelopes a **call site** may import as a `≤` bound, looked up by the callee the typer named
+    # (ADR-103 WD6; #386; normative in `docs/type-specification/effect-labels.md` § The declared lane at
+    # call sites).
+    #
+    # {EnvelopeCheck} asks "what bounds THIS method's body?" and answers it from the project's own
+    # declarations alone, because that is the stratum a contract can be checked against. This index asks
+    # the other question — "what does the thing I am calling promise?" — and so reads one stratum more:
+    # an **accepted signature**'s annotation, from the built RBS environment. WD6's trust ladder puts
+    # both on the discharging side, and the two questions are kept in two objects because only the first
+    # one may ever produce a finding.
+    #
+    # Four sources, nearest-first, exactly the check's precedence with the accepted stratum appended:
+    #
+    #     per-method annotation  >  class-level annotation  >  `effects.envelopes:`  >  accepted signature
+    #
+    # The carrier is **nominal**: the lookup is by the receiver's *static* class name as the typer
+    # projected it (or, for an implicit-self call, by the unit's own class), never by walking ancestors.
+    # A structural interface erases to `Dynamic[top]` today and has nothing to attach a bound to
+    # ([ADR-103](../../../docs/adr/103-effect-labels.md) WD6); an inherited envelope reaches an override
+    # through `effect.liskov-widened` instead, which is a judgment rather than an import.
+    #
+    # Two bounds of the slice, both deliberate:
+    #
+    # - An `effects.envelopes:` entry selected by **`match:`** does not participate here. A path glob is
+    #   a fact about where a class is *defined*, which a per-file collection window cannot see without
+    #   the whole-project class-source table; `namespace:` needs only the name and does participate. The
+    #   entry still bounds its own classes' methods for {EnvelopeCheck} and the Liskov check.
+    # - Lookup is by the *exact* owner. `repo.find` on a receiver typed `PgRepo` does not import
+    #   `Repo#find`'s bound.
+    #
+    # Values are Marshal-clean ({Envelope} over frozen Strings and {LabelSet}s), because the index is
+    # built per process — the parent and each fork-pool worker build their own from the same
+    # configuration and the same signature content, so the two agree without a channel to keep in sync.
+    class EnvelopeIndex
+      NO_ENVELOPES = {}.freeze
+      private_constant :NO_ENVELOPES
+
+      NO_ENTRIES = [].freeze
+      private_constant :NO_ENTRIES
+
+      # The index a run with no declaration of any kind uses — and the fail-soft answer for a build that
+      # raised. Every lookup on it is one `empty?` read.
+      def self.empty
+        @empty ||= new
+      end
+
+      # Reads every stratum this index serves, once per process.
+      #
+      # @param configuration [Rigor::Configuration]
+      # @param plugin_facts [Rigor::Effects::PluginFacts, nil] the loaded plugins' effect contributions
+      #   (#387); their `effect_labels:` join the vocabulary an annotation is read against, so a gem's
+      #   `%a{rigor:v1:effect rails.activejob.enqueue}` resolves rather than reading as unknown.
+      # @param environment [Rigor::Environment, nil] the run's environment. Its loader supplies the
+      #   rbs-inline / plugin `virtual_rbs` buffers and the built RBS environment the accepted stratum is
+      #   read from; without one, both are simply absent (the fail-quiet direction — a missing `≤` bound
+      #   costs precision, never a finding).
+      # @return [EnvelopeIndex]
+      def self.build(configuration:, environment: nil, plugin_facts: nil)
+        # Required here rather than at the top of the file: the reader pulls in the whole
+        # `RbsExtended` surface, and this build runs only under an `effects:` block.
+        require_relative "../rbs_extended/envelope_scanner"
+
+        registry = Registry.for_configuration(configuration, plugin_facts: plugin_facts)
+        loader = environment&.rbs_loader
+        scan = RbsExtended::EnvelopeScanner.scan(
+          sources: SignatureSources.collect(
+            signature_paths: configuration.signature_paths, virtual_rbs: loader&.virtual_rbs
+          ),
+          registry: registry
+        )
+        new(
+          method_envelopes: scan.method_envelopes, class_envelopes: scan.class_envelopes,
+          config_entries: ConfigEnvelopes.build(entries: configuration.effects_envelopes, registry: registry),
+          accepted: accepted_for(loader, registry)
+        )
+      rescue StandardError
+        empty
+      end
+
+      # The accepted stratum — every `%a{pure}` / `%a{rigor:v1:effect …}` on a method definition in the
+      # **built** RBS environment: a gem's shipped signatures, Rigor's bundled overlays, core RBS.
+      #
+      # It is read-only by construction. Nothing here can bound a project method's body, because the
+      # contract check ({EnvelopeCheck}) reads {RbsExtended::EnvelopeScanner}'s project-source tables and
+      # never this one; what an accepted signature can do is state what a call into it promises. The
+      # project's own signatures are in the built environment too and therefore appear here as well —
+      # harmlessly, since the project strata are consulted first and both discharge.
+      def self.accepted_for(loader, registry)
+        return NO_ENVELOPES if loader.nil?
+
+        RbsExtended::EnvelopeScanner.from_loader(loader: loader, registry: registry)
+      rescue StandardError
+        NO_ENVELOPES
+      end
+      private_class_method :accepted_for
+
+      def initialize(method_envelopes: NO_ENVELOPES, class_envelopes: NO_ENVELOPES,
+                     config_entries: NO_ENTRIES, accepted: NO_ENVELOPES)
+        @method_envelopes = method_envelopes.freeze
+        @class_envelopes = class_envelopes.freeze
+        @config_entries = config_entries.reject { |entry| entry.namespace.nil? }.freeze
+        @accepted = accepted.freeze
+        @config_cache = {}
+        freeze
+      end
+
+      # Whether no stratum has anything to say. The scan's fast path: a project with no envelope of any
+      # kind pays one predicate per call site and nothing else.
+      def empty?
+        @method_envelopes.empty? && @class_envelopes.empty? && @config_entries.empty? && @accepted.empty?
+      end
+
+      # The envelope bounding `owner`'s `selector`, or nil.
+      #
+      # @param owner [String] the receiver's static class name, as the typer projected it
+      # @param singleton [Boolean] whether the call is `Owner.selector` rather than `Owner#selector`
+      # @param selector [String]
+      # @return [Envelope, nil] never a ⊤ envelope: a bound that bounds nothing is not a bound, and
+      #   importing it would both add nothing and discharge a taint on the strength of a typo.
+      def [](owner, singleton, selector)
+        return nil if owner.nil? || empty?
+
+        key = "#{owner}#{singleton ? '.' : '#'}#{selector}"
+        envelope = @method_envelopes[key] || @class_envelopes[owner] || config_envelope(owner) ||
+                   @accepted[key]
+        return nil if envelope.nil? || envelope.top?
+
+        envelope
+      end
+
+      private
+
+      # The first `namespace:` entry selecting `owner`, memoised per class name — one call site's owner
+      # is asked for once per site and a project has a handful of entries.
+      def config_envelope(owner)
+        return nil if @config_entries.empty?
+
+        if @config_cache.key?(owner)
+          @config_cache[owner]
+        else
+          entry = @config_entries.find { |candidate| ConfigEnvelopes.namespace_match?(candidate.namespace, owner) }
+          @config_cache[owner] = entry && ConfigEnvelopes.envelope_for(entry, owner)
+        end
+      end
+    end
+  end
+end