rigortype 0.3.8 → 0.4.0

data/lib/rigor/sig_gen/alias_index.rb

@@ -0,0 +1,289 @@
+# frozen_string_literal: true
+
+require_relative "../inference/rbs_type_translator"
+require_relative "type_elaborator"
+
+module Rigor
+  module SigGen
+    # Issue #1002 — the WRITE direction of a project's own type aliases.
+    #
+    # `Generator`'s `alias_expander:` wiring (PR #1000) reads a declared alias: `-> Type::t` in the project's
+    # `sig/` becomes the 22-member union so a proposal can be compared against it. Nothing went the other way,
+    # so a proposal that inferred exactly that union printed all 22 members — output an author cannot paste,
+    # because review rewrites it back into the alias the project already declares.
+    #
+    # This index answers the reverse lookup: given the RBS a proposal erased to, is there a project-declared
+    # alias whose own expansion erases to the same member SET, close enough to the method's own namespace to
+    # be the name a reader expects? The comparison is deliberately a set, not a string: a union missing one
+    # arm is a different type and must keep printing in full.
+    #
+    # A wrong alias name is worse than a long union — it is an RBS claim the author did not make and may not
+    # hold — so every rule below refuses rather than guesses.
+    #
+    # - **Project aliases only.** The candidate `.rbs` files come from the configuration's OWN resolved
+    #   `signature_paths:` (what `Environment.for_project` calls `resolved_paths`), passed in by the caller.
+    #   Deliberately NOT `RbsLoader#signature_paths`: that is `resolved_paths` PLUS plugin signature paths,
+    #   bundler-discovered gem `sig/` directories, the `rbs collection` tree and Rigor's own gem overlays.
+    #   Keyed off the loader, a project that merely bundles a gem shipping RBS aliases would find that gem's
+    #   vocabulary in its proposals. A loaded plugin's own `sig/` is subtracted even when the project wired
+    #   it through `signature_paths:` itself (the #697 shape) — it is the plugin's vocabulary either way.
+    # - **Lossless alias bodies only.** Neither translation nor erasure is injective. `Type::Intersection`
+    #   erases to its FIRST member, `Refined` and `Difference` to their base, a proc type translates to a
+    #   bare `Proc`, and an RBS intersection may not even survive translation. An alias
+    #   `type inter = (Integer & Comparable) | String` therefore reaches the renderer indistinguishable from
+    #   `Integer | String`, and folding a proposal that really is `Integer | String` into `inter` would claim
+    #   an intersection the method never returns — RBS an author cannot accept. So the alias body is checked
+    #   on BOTH sides of translation, each an ALLOW-list ({.lossless_rbs?} over the RBS AST,
+    #   {.lossless?} over the translated carriers). Anything absent — including a form added after this was
+    #   written, and a nested alias reference, whose own body this walk does not see — disqualifies the
+    #   alias. Refusing to fold is always safe; naming the wrong type is not.
+    # - **Namespace proximity.** Type equality is not enough to make a name right for the reader.
+    #   `:positive | :negative` is type-equal to this repository's `Analysis::FactStore::polarity` from
+    #   anywhere in the tree, and naming it inside an unrelated class is a worse proposal than the union. An
+    #   alias is only offered to a method whose owner is inside the alias's own namespace, and the NEAREST
+    #   such alias wins.
+    # - **Unions only.** An alias whose expansion is a single type (`type name = String`) is never folded;
+    #   the noise the issue is about is specifically the long union.
+    # - **Non-generic only.** A generic alias's expansion depends on its arguments, so there is no fixed
+    #   member set to key on.
+    #
+    # A project with no aliases builds an empty index, and an empty index is a no-op: `#fold` returns its
+    # argument, so the rendered output is byte-identical to the pre-#1002 output.
+    class AliasIndex
+      # The carriers whose `erase_to_rbs` is faithful enough to key on. Everything absent is disqualifying,
+      # which is why this is a list of names resolved lazily rather than a `case`: a new carrier is excluded
+      # until someone establishes its erasure round-trips.
+      LOSSLESS_CARRIERS = %i[Top Bot Constant Nominal Singleton Union Tuple Maybe IntegerRange FloatRange].freeze
+      private_constant :LOSSLESS_CARRIERS
+
+      # A proc type translates to a bare `Proc` nominal, losing the signature, so an alias mentioning one
+      # cannot be keyed on its erasure either.
+      PROC_CLASS_NAMES = ["Proc", "::Proc"].freeze
+      private_constant :PROC_CLASS_NAMES
+
+      # The RBS forms whose meaning survives translation AND erasure. Notable absences, each a form that
+      # reaches the renderer looking like something narrower or wider than it is: `Intersection`, `Proc`,
+      # `Record`, `Interface`, `Alias` (its body is expanded during translation, out of this walk's sight),
+      # `untyped` / `void` / `top`, and every context-dependent base (`self`, `instance`, `class`).
+      LOSSLESS_RBS_TYPES = %w[
+        RBS::Types::ClassInstance RBS::Types::ClassSingleton RBS::Types::Union RBS::Types::Optional
+        RBS::Types::Tuple RBS::Types::Literal RBS::Types::Bases::Nil RBS::Types::Bases::Bool
+        RBS::Types::Bases::Bottom
+      ].freeze
+      private_constant :LOSSLESS_RBS_TYPES
+
+      # @return an index with no entries — {#fold} is the identity.
+      def self.empty
+        new({})
+      end
+
+      # @param signature_paths — the project's OWN resolved signature paths.
+      # @param excluded_paths — signature paths that reached the list from somewhere other than the
+      #   author: a loaded plugin's own `sig/`, which #697 lets a project wire through `signature_paths:`
+      #   as well. Those aliases are the plugin's vocabulary, not this project's.
+      #   Fail-soft in the ADR-5 sense: a loader that cannot enumerate aliases, and any alias whose body fails
+      #   to translate, yields an entry-free index rather than an error, because a rendering nicety must never
+      #   fail a run.
+      def self.build(environment:, signature_paths:, excluded_paths: [])
+        loader = environment&.rbs_loader
+        return empty unless loader.respond_to?(:each_type_alias_decl)
+
+        project_files = project_sig_files(signature_paths) - project_sig_files(excluded_paths)
+        return empty if project_files.empty?
+
+        new(collect_entries(loader, project_files, environment))
+      end
+
+      # Every `.rbs` file under the given signature paths, absolute. Directories only, matching `RbsLoader`,
+      # which skips a `signature_paths:` entry that is not a directory.
+      def self.project_sig_files(signature_paths)
+        Array(signature_paths).flat_map do |path|
+          dir = path.is_a?(Pathname) ? path : Pathname(path.to_s)
+          next [] unless dir.directory?
+
+          Dir.glob(dir.join("**", "*.rbs").to_s).map { |p| File.expand_path(p) }
+        end.to_set
+      end
+
+      # `{ member set => entries sorted by declaration position }`. Every alias matching a set is kept, not
+      # just one: which of them is the right NAME depends on the method being rendered, and that is only
+      # known at {#fold} time.
+      def self.collect_entries(loader, project_files, environment)
+        entries = Hash.new { |h, k| h[k] = [] }
+        loader.each_type_alias_decl do |type_name, decl_entry|
+          entry = build_entry(loader, project_files, environment, type_name, decl_entry)
+          entries[entry[:members]] << entry unless entry.nil?
+        end
+        entries.each_value { |list| list.sort_by! { |entry| entry[:order] } }
+        entries.default_proc = nil
+        entries
+      end
+
+      def self.build_entry(loader, project_files, environment, type_name, decl_entry)
+        decl = decl_entry.respond_to?(:decl) ? decl_entry.decl : nil
+        return nil if decl.nil?
+        return nil if decl.respond_to?(:type_params) && !Array(decl.type_params).empty?
+
+        file = declaration_file(decl)
+        return nil unless file && project_files.include?(file)
+
+        members = expanded_members(loader, environment, decl)
+        return nil if members.nil?
+
+        # The ABSOLUTE spelling. RBS resolves a relative type name innermost-first, so a bare
+        # `Deep::Inner::mood` written inside `Deep::Inner` would rebind if the project also declared a
+        # `Deep::Inner::Deep`. The leading `::` says exactly which alias the proposal means.
+        relative = type_name.to_s.delete_prefix("::")
+        { members: members, name: "::#{relative}", namespace: relative.split("::")[0..-2].join("::"),
+          order: [file, declaration_line(decl), relative] }
+      end
+
+      def self.declaration_file(decl)
+        buffer_name = decl.location&.buffer&.name
+        return nil if buffer_name.nil?
+
+        File.expand_path(buffer_name.to_s)
+      rescue StandardError
+        nil
+      end
+
+      def self.declaration_line(decl)
+        decl.location&.start_line || 0
+      rescue StandardError
+        0
+      end
+
+      # nil whenever the alias is not usable as a rendering target: an untranslatable body, a body carrying a
+      # carrier whose erasure loses information, a body that erases to `untyped` (the gradual-consistency
+      # collapse in `Type::Union#erase_to_rbs`, which would otherwise key every such alias on the same
+      # one-member set), or a single-type body.
+      def self.expanded_members(loader, environment, decl)
+        return nil unless lossless_rbs?(decl.type)
+
+        translated = Inference::RbsTypeTranslator.translate(
+          decl.type, self_type: nil, instance_type: nil, type_vars: {}, alias_expander: loader
+        )
+        return nil if translated.nil? || !lossless?(translated)
+
+        erased = TypeElaborator.elaborate(translated, environment: environment).erase_to_rbs
+        members = split_top_level(erased)
+        members.size < 2 ? nil : members
+      rescue StandardError
+        nil
+      end
+
+      # The RBS-AST half of the check, and the one that catches an intersection: `(Integer & Comparable)`
+      # does not necessarily survive translation as a `Type::Intersection`, so by the time the carrier walk
+      # runs there is nothing left to notice.
+      def self.lossless_rbs?(rbs_type)
+        return false unless LOSSLESS_RBS_TYPES.include?(rbs_type.class.name)
+        return true unless rbs_type.respond_to?(:each_type)
+
+        children = []
+        rbs_type.each_type { |child| children << child }
+        children.all? { |child| lossless_rbs?(child) }
+      end
+
+      # The carrier half, a backstop for what translation itself invents (a `Refined` or `Difference` from a
+      # `rigor:` envelope, a bare `Proc` from a proc type reached some other way). Walks the TRANSLATED
+      # tree, so it also sees a construct the RBS walk could not reach.
+      def self.lossless?(type)
+        carrier = type.class.name.to_s.split("::").last&.to_sym
+        return false unless LOSSLESS_CARRIERS.include?(carrier)
+        return false if carrier == :Nominal && PROC_CLASS_NAMES.include?(type.class_name.to_s)
+
+        children_of(type).all? { |child| lossless?(child) }
+      end
+
+      def self.children_of(type)
+        case type
+        when Type::Union then type.members
+        when Type::Tuple then type.elements
+        when Type::Maybe then [type.value_type]
+        when Type::Nominal then type.type_args
+        else []
+        end
+      end
+
+      # Splits an erased RBS string on its TOP-LEVEL `|` separators. Depth tracking keeps a nested union
+      # (`Array[A | B]`) whole, and the quote state keeps a literal string type (`"a | b"`) whole.
+      def self.split_top_level(rendered)
+        members = []
+        current = +""
+        depth = 0
+        quote = nil
+        rendered.each_char do |ch|
+          if quote
+            current << ch
+            quote = nil if ch == quote
+            next
+          end
+
+          case ch
+          when '"', "'" then quote = ch
+          when "(", "[", "{" then depth += 1
+          when ")", "]", "}" then depth -= 1
+          when "|"
+            if depth.zero?
+              members << current.strip
+              current = +""
+              next
+            end
+          end
+          current << ch
+        end
+        members << current.strip
+        members.reject(&:empty?).to_set
+      end
+
+      # The namespaces a method owned by `owner` can name an alias from, INNERMOST FIRST: its own namespace,
+      # then each enclosing one, ending at the top level. `nil`/`""` for a top-level owner still reaches the
+      # top-level namespace, which is where an adopting project's `type` declarations usually live.
+      def self.namespace_chain(owner)
+        segments = owner.to_s.split("::")
+        segments.size.downto(0).map { |i| segments[0...i].join("::") }
+      end
+
+      def initialize(entries)
+        @entries = entries
+      end
+
+      # @param owner — the class or module the rendered member belongs to; `nil` renders unchanged,
+      #   because proximity cannot be judged without it.
+      # @return the alias name when `rendered` is exactly some in-scope project alias's expansion,
+      #   else `rendered` unchanged. Callers can apply this unconditionally.
+      def fold(rendered, owner)
+        return rendered if @entries.empty? || owner.nil? || !rendered.include?("|")
+
+        members = self.class.split_top_level(rendered)
+        return rendered if members.size < 2
+
+        candidates = @entries[members]
+        return rendered if candidates.nil? || candidates.empty?
+
+        nearest(candidates, owner) || rendered
+      end
+
+      def empty?
+        @entries.empty?
+      end
+
+      private
+
+      # "Most specific, then declaration order", the rule the issue asked to have stated and pinned. The
+      # chain index is the distance from the method's own namespace outwards, so an alias declared beside the
+      # method beats one declared in an enclosing namespace, and `candidates` is already in declaration order
+      # ((file, line, name)), which `min_by` keeps as the tie-break. An alias whose namespace does not
+      # enclose the owner at all is not a candidate: it names the right type under a name this reader has no
+      # reason to expect.
+      def nearest(candidates, owner)
+        chain = self.class.namespace_chain(owner)
+        best = candidates.each_with_index.filter_map do |entry, position|
+          distance = chain.index(entry[:namespace])
+          distance.nil? ? nil : [[distance, position], entry[:name]]
+        end.min_by(&:first)
+        best&.last
+      end
+    end
+  end
+end

data/lib/rigor/sig_gen/classification.rb

@@ -2,8 +2,9 @@
 
 module Rigor
   module SigGen
-    # The five classifications a candidate method falls into after the generator has compared the inferred
-    # return type against the project's existing RBS.
+    # The classifications a candidate method falls into after the generator has compared the inferred return
+    # type — or, for a member declared inline, the inline declaration (ADR-112 WD4) — against the project's
+    # existing RBS.
     #
     # The strings are the diagnostic-family identifiers ADR-14 reserves under `sig.*`; the MVP carries them as
     # plain symbols on the method candidate and renders the matching identifier in JSON / text output. They are
@@ -15,16 +16,22 @@ module Rigor
       TIGHTER_RETURN = :tighter_return
       EQUIVALENT = :equivalent
       SKIPPED = :skipped
+      # ADR-112 WD4 — a member declared inline by `# @rbs` / `#:` whose `sig/` declaration disagrees with it,
+      # under `--overwrite`: the whole `sig/` member is replaced by the inline line. Produced only when the run
+      # asked for `--overwrite`; without it the same member is refused (`sig.skipped.inline-differs`), because
+      # neither side is presumed right and a slot-by-slot mix of two declarations need not be a declaration.
+      INLINE_OVERWRITE = :inline_overwrite
 
       # The classifications that actually produce a line in a generated `sig/`. Consulted by the renderer,
       # the writer and the generator's own post-passes; it lived as a private constant in the first two,
       # which is one fork too many for a list this load-bearing.
-      EMITTABLE = [NEW_FILE, NEW_METHOD, TIGHTER_RETURN].freeze
+      EMITTABLE = [NEW_FILE, NEW_METHOD, TIGHTER_RETURN, INLINE_OVERWRITE].freeze
 
       DIAGNOSTIC_IDS = {
         NEW_FILE => "sig.generated.new-file",
         NEW_METHOD => "sig.generated.new-method",
-        TIGHTER_RETURN => "sig.generated.tighter-return"
+        TIGHTER_RETURN => "sig.generated.tighter-return",
+        INLINE_OVERWRITE => "sig.generated.inline-overwrite"
       }.freeze
 
       SKIP_DIAGNOSTIC_IDS = {
@@ -40,7 +47,17 @@ module Rigor
         unresolvable_superclass: "sig.skipped.unresolvable-superclass",
         # Issue #744 — a project subclass overrides this method and its override is NOT emitted, so the
         # declaration would be inherited by a subclass it does not describe.
-        overridden_by_unsigned_subclass: "sig.skipped.overridden-by-unsigned-subclass"
+        overridden_by_unsigned_subclass: "sig.skipped.overridden-by-unsigned-subclass",
+        # ADR-112 WD4 — `sig_gen.inline_declared: skip` is set and the inline reader declares this member, so
+        # a `sig/` copy would be a second declaration of it for a Steep that reads the inline annotations too.
+        inline_declared: "sig.skipped.inline-declared",
+        # ADR-112 WD4 — the member's class, or one it is nested in, is generic by an inline declaration (`# @rbs
+        # generic T`) and `sig/` does not declare it yet. sig-gen writes no class type parameters, and a header
+        # without them fails the class's definition build.
+        inline_generic_class: "sig.skipped.inline-generic-class",
+        # ADR-112 WD4 — the member is declared inline and in `sig/`, and the two disagree. A refusal, not a
+        # skip: `--write` and `--check` exit 1 until a person reconciles them or passes `--overwrite`.
+        inline_differs: "sig.skipped.inline-differs"
       }.freeze
     end
   end

data/lib/rigor/sig_gen/declaration_equivalence.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "rbs"
+
+module Rigor
+  module SigGen
+    # ADR-112 WD4 — whether a method's inline declaration and its `sig/` declaration say the same thing, so that
+    # `rigor sig-gen` refuses (or, under `--overwrite`, replaces) only a real disagreement (#1076).
+    #
+    # Two declarations are compared as types, not text. What is ignored, because RBS gives it no meaning:
+    #
+    # - parameter names (`(String)` and `(String s)`);
+    # - how a union is spelled: member order, `T?` for `T | nil`, `bool` for `true | false`, nesting;
+    # - a name written absolute or relative, when both resolve to the same constant — `::Foo` and `Foo` inside
+    #   `module NS` are the same only if `NS` declares no `Foo` of its own ({#initialize}'s `resolve`).
+    #
+    # What is kept: overload order (RBS picks the first overload that matches, so `A | B` and `B | A` can
+    # answer a call differently), method type parameters as named, and everything else about the shape.
+    class DeclarationEquivalence
+      # @param resolve — maps a type name as written (`String`, `::Foo`, `Bar::Baz`) to the name it denotes,
+      #   in the namespace both declarations sit in.
+      def initialize(resolve:)
+        @resolve = resolve
+      end
+
+      def same?(left, right)
+        left.size == right.size && left.zip(right).all? { |a, b| method_type(a) == method_type(b) }
+      end
+
+      # The overloads with their returns left out, for comparing what an author wrote against a member whose
+      # return is inferred.
+      def same_parameters?(left, right)
+        left.size == right.size && left.zip(right).all? do |a, b|
+          method_type(a, with_return: false) == method_type(b, with_return: false)
+        end
+      end
+
+      private
+
+      def method_type(method_type, with_return: true)
+        [
+          method_type.type_params.map { |param| param.name.to_s },
+          function(method_type.type, with_return: with_return),
+          block(method_type.block)
+        ]
+      end
+
+      def block(block)
+        return nil if block.nil?
+
+        [block.required, function(block.type), block.self_type && type(block.self_type)]
+      end
+
+      def function(function, with_return: true)
+        returned = with_return ? type(function.return_type) : nil
+        return [:untyped_function, returned] if function.is_a?(::RBS::Types::UntypedFunction)
+
+        [
+          function.required_positionals.map { |param| type(param.type) },
+          function.optional_positionals.map { |param| type(param.type) },
+          function.rest_positionals && type(function.rest_positionals.type),
+          function.trailing_positionals.map { |param| type(param.type) },
+          keywords(function.required_keywords),
+          keywords(function.optional_keywords),
+          function.rest_keywords && type(function.rest_keywords.type),
+          returned
+        ]
+      end
+
+      def keywords(map)
+        map.map { |name, param| [name.to_s, type(param.type)] }.sort
+      end
+
+      def type(node)
+        case node
+        when ::RBS::Types::Optional, ::RBS::Types::Union, ::RBS::Types::Bases::Bool then union(node)
+        when ::RBS::Types::ClassInstance then [:instance, @resolve.call(node.name.to_s), types(node.args)]
+        when ::RBS::Types::ClassSingleton then [:singleton, @resolve.call(node.name.to_s)]
+        when ::RBS::Types::Interface, ::RBS::Types::Alias then named(node)
+        else composite(node)
+        end
+      end
+
+      # An interface or alias is compared by its written name, a leading `::` aside: those names are rarely
+      # nested, and the environment question this class asks of a class name has no counterpart for them.
+      def named(node)
+        [:named, node.name.to_s.delete_prefix("::"), types(node.args)]
+      end
+
+      def composite(node)
+        case node
+        when ::RBS::Types::Tuple then [:tuple, types(node.types)]
+        when ::RBS::Types::Record then [:record, record_fields(node)]
+        when ::RBS::Types::Intersection then [:intersection, types(node.types).sort_by(&:inspect)]
+        when ::RBS::Types::Proc then [:proc, function(node.type), block(node.block)]
+        else [:other, node.to_s]
+        end
+      end
+
+      def types(nodes)
+        nodes.map { |node| type(node) }
+      end
+
+      def record_fields(node)
+        required = node.fields.map { |key, field| [key.to_s, true, type(field)] }
+        optional = node.respond_to?(:optional_fields) ? node.optional_fields : {}
+        (required + optional.map { |key, field| [key.to_s, false, type(field)] }).sort_by(&:inspect)
+      end
+
+      def union(node)
+        members = union_members(node).uniq.sort_by(&:inspect)
+        members.size == 1 ? members.first : [:union, members]
+      end
+
+      # `true` / `false` / `nil` canonicalise as their literal spellings do (`[:other, "true"]`), so `bool` and
+      # `true | false`, or `T?` and `T | nil`, land on the same members.
+      def union_members(node)
+        case node
+        when ::RBS::Types::Union then node.types.flat_map { |member| union_members(member) }
+        when ::RBS::Types::Optional then union_members(node.type) + [[:other, "nil"]]
+        when ::RBS::Types::Bases::Bool then [[:other, "true"], [:other, "false"]]
+        else [type(node)]
+        end
+      end
+    end
+  end
+end

data/lib/rigor/sig_gen/effect_annotation.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+require_relative "../effects/config_envelopes"
+require_relative "../effects/label_set"
+require_relative "../effects/method_key"
+require_relative "../effects/summary"
+
+module Rigor
+  module SigGen
+    # ADR-103 WD9 / ADR-14's reserved annotation-emission slot — decides whether a generated signature
+    # carries `%a{pure}` or `%a{rigor:v1:effect …}`, and records WHY when it does not.
+    #
+    # The whole module is one decision applied per method, and every branch of it exists to keep a WRONG
+    # annotation off the page. An emitted annotation is not a hint: the effects opt-in reads it back as an
+    # envelope and enforces it on the method and on everything the method reaches, so a `%a{pure}` sig-gen
+    # invented is a false contract that manufactures `effect.envelope-exceeded` on correct code. That is why
+    # the gates below are all one-directional — each of them can only suppress an emission.
+    #
+    # The gates, in order:
+    #
+    # 0. **Already declared** — the method's own signature, its class's, an `effects.envelopes:` entry
+    #    (by `namespace:` OR by `match:`), or an rbs-inline `# @rbs %a{…}` states a bound. The author has
+    #    spoken and sig-gen has nothing to add; writing its own answer over that would silently replace a
+    #    contract with an inference. `withheld-declared`. This is a DIFFERENT lane from gate 5: an
+    #    envelope on the method ITSELF goes to {Effects::EnvelopeCheck} and never enters the summary's
+    #    `≤` lane, so the table cannot see it. An annotation carrying an unknown label counts: it reads
+    #    as ⊤ and bounds nothing, but the author still wrote about this method, and replacing their typo
+    #    with `%a{pure}` would delete the only thing `effect.unknown-label` has to point at.
+    # 1. **No summary** — the method is not an effect unit this run collected. Nothing is emitted and nothing
+    #    is reported: the absence is about the run, not about the method.
+    # 2. **Non-exhaustive** ({Effects::Summary#exhaustive?} false) — the summary reads "these effects, and
+    #    possibly more", which is precisely the claim an envelope must not make. `withheld-non-exhaustive`.
+    # 3. **Policy-discharged** — the transitive proven lane and the `effects.tolerated:` judgment disagree,
+    #    so some part of this method's footprint is only invisible because the project agreed to ignore it.
+    #    `docs/type-specification/effect-labels.md` § Discharge by policy, invariant 4 ("emission uses
+    #    undischarged sets") and ADR-10 WD7's "opportunistic shapes never round-trip" are the same rule:
+    #    a tolerated `telemetry` origin does not earn a written `%a{pure}`. `withheld-tolerated`.
+    # 4. **Unclaimed callee** ({Effects::EffectTable::Entry#unclaimed?}) — the method, or something it
+    #    reaches, called something NOTHING described: no catalogue row, no plugin row, no envelope, and no
+    #    project definition the closure could read. The summary is exhaustive, because every call
+    #    RESOLVED — but "every call resolved" and "every callee's footprint is known" are different
+    #    questions, and only the second one licenses a written bound. `withheld-unclaimed-callee`.
+    # 5. **A surviving declared label** ({Effects::EffectTable::Entry#trivial?}) — the proven lane is empty
+    #    and the `≤` lane is not, which is a method whose callee stated a bound the analyzer never proved
+    #    away. `%a{pure}` there would contradict a claim the project already carries.
+    #    `withheld-declared`.
+    # 6. **Proven pure** — exhaustive, undischarged, claimed, and nothing outside `{mutate.local}` in
+    #    either lane. `%a{pure}`, the ecosystem's existing purity spelling (design § 6.3), which hands
+    #    Steep users better narrowing.
+    # 7. **Proven effectful** — the same, with real labels. `%a{rigor:v1:effect …}` only when the caller
+    #    asked for envelopes; otherwise nothing, because the labelled spelling is Rigor's own and writing
+    #    it into a project's `sig/` unbidden is a bigger commitment than a purity tag.
+    module EffectAnnotation
+      # The `sig.*` telemetry identifiers for this emission, alongside {Classification::DIAGNOSTIC_IDS} and
+      # {Classification::SKIP_DIAGNOSTIC_IDS}. Documented in `docs/type-specification/diagnostic-policy.md`
+      # and `docs/handbook/11-sig-gen.md` with the rest of the `sig.*` family.
+      DIAGNOSTIC_IDS = {
+        # An annotation was rendered onto the proposal.
+        emitted: "sig.effect.emitted",
+        # Withheld: the proven footprint and the `effects.tolerated:` judgment disagree.
+        withheld_tolerated: "sig.effect.withheld-tolerated",
+        # Withheld: some call this method reaches could not be resolved.
+        withheld_non_exhaustive: "sig.effect.withheld-non-exhaustive",
+        # Withheld: some call it reaches resolved, and nothing anywhere says what that callee does.
+        withheld_unclaimed_callee: "sig.effect.withheld-unclaimed-callee",
+        # Withheld: the `≤` lane carries a label the proven lane does not already admit.
+        withheld_declared: "sig.effect.withheld-declared",
+        # Write-time: the target declaration already carries annotations, so its bytes were left alone.
+        left_unreadable: "sig.effect.left-unreadable"
+      }.freeze
+
+      module_function
+
+      # The effect-unit key for a sig-gen candidate, in {Effects::MethodKey}'s spelling.
+      def key_for(class_name, method_name, kind)
+        return nil if class_name.nil?
+
+        "#{class_name}#{kind == :singleton ? '.' : '#'}#{method_name}"
+      end
+
+      # Turns one {Effects::EffectTable::Entry} into the annotation lines to render and the reason to report.
+      #
+      # @param declared — whether the method already carries an authored bound of its own
+      #   ({Effects::EnvelopeIndex}); see gate 0.
+      # @return `[Array<String> annotations, Symbol|nil reason]`. An empty
+      #   array with a `nil` reason is "nothing to say about this method".
+      def decide(entry, envelopes: false, declared: false)
+        return [[], :withheld_declared] if declared
+        return [[], nil] if entry.nil?
+        return [[], :withheld_non_exhaustive] unless entry.exhaustive?
+        return [[], :withheld_tolerated] unless entry.proven == entry.undischarged
+        return [[], :withheld_unclaimed_callee] if entry.unclaimed?
+        # `trivial?` is the report's own "nothing to say about this method" test, and it is the emission
+        # test too: exhaustive, nothing beyond `mutate.local` proven, and NOTHING SURVIVING in the `≤`
+        # lane. The last conjunct is what a bare `proven.subsumed_by?` misses — a callee's imported
+        # envelope lands in the declared lane with no taint and no proven label, so a method whose whole
+        # body is one `Remote.fetch` reads `[] ≤ [io.net.http]` while proving nothing at all.
+        return [["%a{pure}"], :emitted] if entry.trivial?
+        return [[], :withheld_declared] if entry.proven.subsumed_by?(Effects::Summary::TRIVIAL_BOUND)
+        return [[], nil] unless envelopes
+        # A surviving declared label is not spelled either. The envelope grammar carries ONE bound per
+        # declaration and has no way to say "proves this, claims that", so writing the proven set alone
+        # would publish a bound narrower than the claim the project already carries.
+        return [[], :withheld_declared] unless entry.rendered_declared.empty?
+        # `top?` is the unbounded reading: it names no labels, so there is no envelope to spell.
+        return [[], nil] if entry.proven.top? || entry.proven.empty?
+
+        [["%a{rigor:v1:effect #{entry.proven.to_a.join(', ')}}"], :emitted]
+      end
+
+      # Per-run lookup over an {Effects::EffectTable}. Built by the CLI when the project's `effects:` opt-in
+      # is on, and `nil` otherwise — which is what makes effects-off output byte-identical to a run before
+      # this feature existed.
+      class Annotator
+        NO_ENTRIES = [].freeze
+        private_constant :NO_ENTRIES
+
+        # @param envelope_index — the run's {Effects::EnvelopeIndex}, so
+        #   gate 0 can see a bound the author already wrote. `nil` skips that half of the gate.
+        # @param config_envelopes — the project's
+        #   `effects.envelopes:` entries. Passed SEPARATELY from the index because the index drops every
+        #   entry without a `namespace:` (it serves call-site import, and a `match:` glob is a fact about
+        #   where a class is defined that a per-file collection window cannot see). Emission can see it:
+        #   a sig-gen candidate carries the defining file it came from, which is exactly what
+        #   {Effects::ConfigEnvelopes.selects?} matches a `match:` entry against.
+        def initialize(table:, envelopes: false, envelope_index: nil, config_envelopes: NO_ENTRIES)
+          @table = table
+          @envelopes = envelopes
+          @envelope_index = envelope_index
+          @config_envelopes = config_envelopes
+          freeze
+        end
+
+        # @param path — the `.rb` file the def came from, for a `match:`-selected
+        #   `effects.envelopes:` entry.
+        # @return `[Array<String>, Symbol|nil]` — see {EffectAnnotation.decide}.
+        def annotate(class_name:, method_name:, kind:, path: nil)
+          key = EffectAnnotation.key_for(class_name, method_name, kind)
+          return [[], nil] if key.nil?
+
+          EffectAnnotation.decide(
+            @table[key], envelopes: @envelopes,
+                         declared: declared?(class_name, method_name, kind, path)
+          )
+        end
+
+        private
+
+        def declared?(class_name, method_name, kind, path)
+          annotated?(class_name, method_name, kind) || config_selected?(class_name, path)
+        end
+
+        def annotated?(class_name, method_name, kind)
+          return false if @envelope_index.nil?
+
+          @envelope_index.annotated?(class_name, kind == :singleton, method_name.to_s)
+        end
+
+        # `namespace:` entries are answered by the index too; asking here as well costs one scan over a
+        # handful of entries and keeps the `match:` half from being a second, differently-shaped answer.
+        def config_selected?(class_name, path)
+          return false if @config_envelopes.empty? || class_name.nil?
+
+          @config_envelopes.any? { |entry| Effects::ConfigEnvelopes.selects?(entry, class_name, match_paths(path)) }
+        end
+
+        # Every spelling of the candidate's file a `match:` glob might be written against.
+        #
+        # A glob is matched `Dir.pwd`-relative (`ConfigEnvelopes.for_classes` defaults `project_root:` to
+        # the same thing, so the two sides agree and both agree with `rigor check`), while a candidate's
+        # path is whatever the invocation named: relative when `paths:` supplied it, absolute when the
+        # user typed one, and neither when it arrives through a symlink — `sig-gen alias/presented.rb`
+        # where `alias` links to `lib` is a real invocation, and the glob its author wrote says `lib/`.
+        #
+        # All three are tried rather than one canonical form. Normalising to the real path alone would
+        # break a project whose own `paths:` entry is the symlink (the glob would then be written against
+        # the link), and normalising to `Dir.pwd` alone is what let the symlink through.
+        def match_paths(path)
+          [path, relative_path(path), relative_path(real_path(path))].compact.uniq
+        end
+
+        def relative_path(path)
+          return nil if path.nil?
+
+          expanded = File.expand_path(path.to_s)
+          root = "#{File.expand_path(Dir.pwd)}#{File::SEPARATOR}"
+          expanded.start_with?(root) ? expanded.delete_prefix(root) : nil
+        end
+
+        # Resolved through every symlink on the way, or nil when the file is gone — a candidate names a
+        # file the generator just read, so a miss here is a race rather than a shape to handle.
+        def real_path(path)
+          return nil if path.nil?
+
+          File.realpath(path.to_s)
+        rescue SystemCallError
+          nil
+        end
+      end
+    end
+  end
+end