rigortype 0.3.2 → 0.3.4

data/lib/rigor/effects/file_collection.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require_relative "summary"
+
+module Rigor
+  module Effects
+    # What one analyzed file contributes to the project's effect graph (ADR-103 WD12).
+    #
+    # The collector produces one of these per file and the runner marshals it back from a fork-pool worker
+    # with the file's diagnostics, so every field is Marshal-clean: frozen Hashes of Strings, {Summary}
+    # values, and `Data` edges. Nothing here holds a Prism node, a `Scope` or an environment.
+    #
+    # It carries four tables:
+    #
+    # - {#summaries} — the **direct** summary of each method the file defines, keyed `Class#m` / `Class.m` /
+    #   `<toplevel>#m` (WD14). A reopening in another file contributes the same key and the two join.
+    # - {#edges} — per method key, the calls that must be resolved against the *project* before they become
+    #   graph edges. Resolution is deferred to the propagator because a file cannot see the whole class
+    #   graph; the collector only records what the typer decided about the receiver.
+    # - {#superclasses} / {#includes} — the ancestry the propagator needs to resolve an edge through
+    #   inherited methods and to find every project-known override of a call's target (the closed-world
+    #   join of WD4).
+    #
+    # Merging is associative and commutative in every table, so folding a run's files in pool-completion
+    # order yields exactly the table sequential analysis yields.
+    class FileCollection
+      # One recorded call, before the project can say which definition it reaches.
+      #
+      # `receiver_class` is the class name the typer had at the call site (nil when it had none — a Dynamic
+      # receiver, or a construct that is not a call). `kind` is `:instance` for a `Nominal` receiver and
+      # `:singleton` for a `Singleton` one. `self_call` marks an implicit-self call, which is the only shape
+      # whose failure to resolve is an `unresolved-self-call` taint rather than silence.
+      Edge = Data.define(:receiver_class, :kind, :selector, :self_call)
+
+      NO_TABLE = {}.freeze
+      private_constant :NO_TABLE
+
+      # The collection a file with nothing to say contributes — a parse failure, a file of constants, or a
+      # run where the collector was never activated.
+      def self.empty(path = nil)
+        new(path: path)
+      end
+
+      attr_reader :path, :summaries, :edges, :superclasses, :includes
+
+      def initialize(path: nil, summaries: NO_TABLE, edges: NO_TABLE,
+                     superclasses: NO_TABLE, includes: NO_TABLE, failed: false)
+        @path = path
+        @summaries = freeze_table(summaries)
+        @edges = freeze_edges(edges)
+        @superclasses = freeze_table(superclasses)
+        @includes = freeze_table(includes)
+        @failed = failed ? true : false
+        freeze
+      end
+
+      # Whether the collector gave up on this file entirely (the fail-soft path). Its methods contribute
+      # nothing rather than contributing a wrong summary; `rigor check` is unaffected either way.
+      def failed?
+        @failed
+      end
+
+      def empty?
+        @summaries.empty? && @edges.empty?
+      end
+
+      # Folds another collection into this one. Summaries join per key, edge lists union, ancestry merges.
+      #
+      # **Fold a whole run with {merge_all}, not with this in a `reduce`.** Every call here rebuilds and
+      # re-freezes the accumulated tables, so folding a run one file at a time costs O(files × methods) —
+      # it was 5.1 s of mastodon's 6.4 s collection overhead and the whole of gitlab's superlinear one
+      # (`docs/notes/20260817-effect-collection-perf.md`). This stays for a two-collection merge, which is
+      # what its cost model fits.
+      def merge(other)
+        return self if other.empty? && !other.failed?
+
+        self.class.merge_all([self, other])
+      end
+
+      # Folds a run's collections in one linear pass: each key's summaries join once, each table is built
+      # once, and the frozen result is constructed once at the end. Order-independent in every table
+      # except `superclasses`, where a later collection's spelling wins exactly as a chain of {merge}
+      # calls would leave it, so a path-sorted fold is reproducible.
+      #
+      # A collection that is {empty?} and not {failed?} contributes nothing, which is {merge}'s own
+      # short-circuit spelled once: a file with no methods and no calls has no summary to fold, and its
+      # ancestry has no unit to attach to.
+      def self.merge_all(collections)
+        summaries = {}
+        edges = {}
+        superclasses = {}
+        includes = {}
+        failed = false
+
+        collections.each do |collection|
+          failed ||= collection.failed?
+          next if collection.empty?
+
+          fold_summaries(summaries, collection.summaries)
+          fold_lists(edges, collection.edges)
+          superclasses.update(collection.superclasses)
+          fold_lists(includes, collection.includes)
+        end
+
+        includes.each_value(&:uniq!)
+        new(path: nil, summaries: summaries, edges: edges,
+            superclasses: superclasses, includes: includes, failed: failed)
+      end
+
+      def self.fold_summaries(into, table)
+        table.each do |key, summary|
+          existing = into[key]
+          into[key] = existing ? existing.join(summary) : summary
+        end
+      end
+      private_class_method :fold_summaries
+
+      # De-duplication is deferred to the single pass at the end of {merge_all} — `freeze_edges` uniqs
+      # and sorts anyway, and uniqing per file is what made the fold quadratic.
+      def self.fold_lists(into, table)
+        table.each do |key, list|
+          existing = into[key]
+          existing ? existing.concat(list) : into[key] = list.dup
+        end
+      end
+      private_class_method :fold_lists
+
+      def ==(other)
+        other.is_a?(FileCollection) && other.summaries == @summaries && other.edges == @edges &&
+          other.superclasses == @superclasses && other.includes == @includes && other.failed? == @failed
+      end
+      alias eql? ==
+
+      def hash
+        [self.class, @summaries, @edges, @superclasses, @includes, @failed].hash
+      end
+
+      private
+
+      def freeze_table(table)
+        return NO_TABLE if table.empty?
+
+        table.transform_values { |value| value.is_a?(Array) ? value.freeze : value }.freeze
+      end
+
+      # Edge lists are sorted so a marshalled worker collection and a sequential one are `==` and the
+      # report they feed is byte-identical. The key is TOTAL over the de-duplicated list — `self_call` is
+      # in it because two edges can otherwise agree on every other field, and `sort_by` is not stable.
+      def freeze_edges(table)
+        return NO_TABLE if table.empty?
+
+        table.transform_values do |list|
+          sorted = list.uniq
+          sorted.sort_by! { |edge| [edge.receiver_class.to_s, edge.kind.to_s, edge.selector, edge.self_call ? 1 : 0] }
+          sorted.freeze
+        end.freeze
+      end
+    end
+  end
+end

data/lib/rigor/effects/framework_units.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require_relative "file_collection"
+require_relative "label_set"
+require_relative "origin"
+require_relative "summary"
+
+module Rigor
+  module Effects
+    # The framework **edges** a plugin declared, materialised as effect units on the framework class itself
+    # (ADR-103 WD10; design note § 11.2 "Framework edges"; #387).
+    #
+    # `user.save` runs `User`'s `before_save :normalize`; `WelcomeJob.perform_now` runs
+    # `WelcomeJob#perform`; `UserMailer.welcome(u)` runs `UserMailer#welcome`. Each is real, synchronous,
+    # in-process control flow that the *syntax* does not contain, so without the plugin the caller's
+    # summary stops one hop short of the code that actually runs.
+    #
+    # ## Why units on the class rather than edges at the call site
+    #
+    # The call site is in another file. `app/controllers/users_controller.rb` writes `@user.save` and knows
+    # nothing about `User`'s callbacks — those are in `app/models/user.rb`, and a per-file collection window
+    # sees one file at a time. Synthesising `User#save` **where `User` is declared**, with edges to the
+    # callback methods, moves the framework knowledge to the file that has it and leaves the call site an
+    # ordinary edge. The propagator then resolves `(User, :instance, "save")` to the synthetic unit exactly
+    # as it resolves any other, ancestry and closed-world override join included — no second mechanism, no
+    # cross-file harvest, and a `save` on a subclass picks up that subclass's own callbacks for free.
+    #
+    # A project that defines `User#save` itself simply joins with the synthetic unit, which is the honest
+    # reading: an override still runs the callbacks unless it skips them.
+    #
+    # ## What is deliberately not here
+    #
+    # `perform_later` → `perform`. The deferred body runs in another process on another stack, and ADR-103
+    # WD4 fixes attribution to the code rather than to the clock: the enqueue is the effect, and the job's
+    # body belongs to the job's own entry point. {Plugin::EffectEdge::TARGETS} has no spelling for it.
+    module FrameworkUnits
+      IO_DB_READ = LabelSet.new(["io.db.read"]).freeze
+      private_constant :IO_DB_READ
+
+      # ActiveRecord's class-body callback macros, grouped by which persistence selectors run them. The
+      # grouping is coarse on purpose: an effect summary is an **upper bound**, and the cost of attributing
+      # a `before_create` to `save` (which does run it, when the record is new) is nothing, while the cost of
+      # a group fine enough to be wrong somewhere is a missing effect.
+      VALIDATION_MACROS = %w[validate before_validation after_validation].freeze
+
+      SAVE_MACROS = %w[
+        before_save around_save after_save before_create around_create after_create
+        before_update around_update after_update after_touch
+        before_commit after_commit after_rollback
+        after_create_commit after_update_commit after_save_commit
+      ].freeze
+
+      DESTROY_MACROS = %w[
+        before_destroy around_destroy after_destroy after_destroy_commit after_commit after_rollback
+      ].freeze
+
+      # Macros whose literal symbol arguments name methods on the same class. Everything the strategy reads.
+      CALLBACK_MACROS = (VALIDATION_MACROS + SAVE_MACROS + DESTROY_MACROS).uniq.freeze
+
+      # The uniqueness validator is a `SELECT` before the write — the one validation whose effect a reviewer
+      # is entitled to see in a summary. Both spellings Rails accepts.
+      UNIQUENESS_MACRO = "validates_uniqueness_of"
+      VALIDATES_MACRO = "validates"
+      UNIQUENESS_OPTION = "uniqueness"
+
+      # Which selectors run which group. `create` / `create!` are the singleton twins of `save`.
+      SAVE_TRIGGERS = %w[save save! update update! update_attribute touch increment! decrement!].freeze
+      DESTROY_TRIGGERS = %w[destroy destroy! delete].freeze
+      VALIDATION_TRIGGERS = %w[valid? invalid? validate!].freeze
+      SINGLETON_SAVE_TRIGGERS = %w[create create!].freeze
+
+      # `initialize` is not a mailer action, and neither is a method a plugin would want double-counted.
+      NON_ACTION_METHODS = %w[initialize].to_set.freeze
+
+      module_function
+
+      # Every synthetic unit `class_name` earns, as `[key, Summary, edges]` triples.
+      #
+      # @param class_name [String]
+      # @param instance_methods [Array<String>] the instance methods the class body defines, in source order
+      # @param macros [Hash{String=>Array<String>}] receiver-less class-body calls to their literal symbol
+      #   arguments, as the scanner harvested them
+      # @param uniqueness [Boolean] whether the class body declares a uniqueness validator
+      # @param plugin_facts [PluginFacts]
+      def synthesize(class_name:, instance_methods:, macros:, uniqueness:, plugin_facts:)
+        units = []
+        plugin_facts.edges_for(:activerecord_callbacks).each do |edge|
+          next unless plugin_facts.descends_from?(class_name, edge.receiver)
+
+          units.concat(active_record_units(class_name, macros, uniqueness))
+        end
+        plugin_facts.edges_for(:perform_now).each do |edge|
+          next unless plugin_facts.descends_from?(class_name, edge.receiver)
+
+          # `selector` (the edge's `method:`) names the synthesised selector, defaulting to
+          # `perform_now`. The one other value it
+          # ever takes is `perform_later` — and ONLY from a plugin that has read the project's own
+          # `queue_adapter = :inline`, where Rails really does run the job on the caller's stack. That is a
+          # project fact narrowing a transport, not a general edge (ADR-103 WD4).
+          units << unit("#{class_name}.#{edge.selector || :perform_now}", [edge_to(class_name, "perform")])
+        end
+        plugin_facts.edges_for(:mailer_body).each do |edge|
+          next unless plugin_facts.descends_from?(class_name, edge.receiver)
+
+          units.concat(mailer_units(class_name, instance_methods))
+        end
+        units
+      end
+
+      # `save` and friends, edged to the callbacks the class body declared. A trigger with no callbacks and
+      # no uniqueness validator is NOT synthesised: an empty unit would put `User#save` in the snapshot for
+      # every model in the project and say nothing.
+      def active_record_units(class_name, macros, uniqueness)
+        validation = callbacks(macros, VALIDATION_MACROS)
+        save = validation + callbacks(macros, SAVE_MACROS)
+        destroy = callbacks(macros, DESTROY_MACROS)
+        read = uniqueness ? uniqueness_summary(class_name) : nil
+
+        units = []
+        units.concat(triggers(class_name, SAVE_TRIGGERS, save, read, singleton: false))
+        units.concat(triggers(class_name, SINGLETON_SAVE_TRIGGERS, save, read, singleton: true))
+        units.concat(triggers(class_name, VALIDATION_TRIGGERS, validation, read, singleton: false))
+        units.concat(triggers(class_name, DESTROY_TRIGGERS, destroy, nil, singleton: false))
+        units
+      end
+
+      # ActionMailer's class-method-to-instance mapping: `UserMailer.welcome(u)` instantiates the mailer and
+      # runs `#welcome`. One synthetic singleton twin per instance method the mailer defines.
+      def mailer_units(class_name, instance_methods)
+        instance_methods.reject { |name| NON_ACTION_METHODS.include?(name) }.uniq.map do |name|
+          unit("#{class_name}.#{name}", [edge_to(class_name, name)])
+        end
+      end
+
+      def triggers(class_name, selectors, targets, read, singleton:)
+        return [] if targets.empty? && read.nil?
+
+        edges = targets.map { |target| edge_to(class_name, target) }
+        selectors.map { |selector| unit("#{class_name}#{singleton ? '.' : '#'}#{selector}", edges, read) }
+      end
+
+      def callbacks(macros, names)
+        names.flat_map { |name| macros[name] || [] }.uniq
+      end
+
+      # The uniqueness validator's own query. It rides the DECLARED lane with no taint, exactly as every
+      # other first-party plugin contribution does (ADR-103 WD6): the plugin read the app's own
+      # `validates … uniqueness: true` and knows what Rails does with it, but the analyzer did not read a
+      # body, so this is a trusted claim rather than a proof.
+      def uniqueness_summary(class_name)
+        { Origin.plugin("#{class_name}:uniqueness-validator") => IO_DB_READ }
+      end
+
+      def unit(key, edges, declared = nil)
+        [key, Summary.new(declared_bundles: declared || {}), edges]
+      end
+
+      def edge_to(class_name, selector)
+        FileCollection::Edge.new(receiver_class: class_name, kind: :instance, selector: selector,
+                                 self_call: false)
+      end
+
+      private_class_method :active_record_units, :mailer_units, :triggers, :callbacks, :uniqueness_summary,
+                           :unit, :edge_to
+    end
+  end
+end

data/lib/rigor/effects/identity.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+
+require_relative "../cache/descriptor"
+require_relative "catalog"
+require_relative "registry"
+
+module Rigor
+  module Effects
+    # The **effects cache identity** — the second of ADR-103 WD13's "one cache, two identities, one extra
+    # slot" (issue #382; the contract is `docs/internal-spec/effect-summaries.md` § Caching).
+    #
+    # A run has one identity for its diagnostics and one for its effect summaries. The diagnostics identity
+    # is today's and is deliberately untouched by this file: collection is observational, so a diagnostics
+    # entry computed with effects on is valid for a run with effects off and vice versa. The effects
+    # identity is that identity **plus** the three things that change what a summary means without changing
+    # a single analyzed byte:
+    #
+    # - the **vocabulary version** ({Registry#vocabulary_version}) — a rename or a removal re-reads every
+    #   persisted label;
+    # - the **catalogue identity** ({Catalog#identity}, schema + a digest of `data/effects/core.yml`) — an
+    #   audited row moving from `io` to `io.fs.write` re-colours summaries the analyzed source never moved;
+    # - the **`effects:` block digest** — the same value the snapshot header carries, so a `tolerated:` or
+    #   `reach:` edit is one visible regeneration event rather than two silently disagreeing digests;
+    # - the **plugin fact digest** ({PluginFacts#digest}, #387) — the loaded plugins' labels, attributions,
+    #   edges and presets. A plugin upgrade that moves `perform_later` from `io` to `io.db.write` re-colours
+    #   summaries the analyzed source never moved, exactly as a re-audited catalogue row does, and the
+    #   plugin set is otherwise invisible to a key derived from configuration alone.
+    #
+    # This module is the ONE place that answers it. {.digest} is the string form (what the ADR-46 snapshot
+    # payload carries beside `return_summaries`) and {.descriptor} is the {Cache::Descriptor} form (what the
+    # ADR-45 whole-run effects slot is keyed by): the same three inputs, spelled for the two stores.
+    #
+    # Nothing here is consulted when collection is off — no entry is written, no key is perturbed, and the
+    # `effects:` block stays out of `Configuration#to_h` so enabling the feature invalidates no existing
+    # project's diagnostics cache.
+    module Identity
+      # The `configs:` slot the effects identity adds on top of a run's diagnostics key descriptor.
+      CONFIG_KEY = "effects.identity"
+
+      module_function
+
+      # The effects identity as a hex digest — the form a store with no descriptor of its own (the ADR-46
+      # incremental snapshot) carries alongside its payload, and compares verbatim on restore.
+      #
+      # @param configuration [Rigor::Configuration]
+      # @param registry [Registry] the vocabulary whose version participates
+      # @param catalog [Catalog] the catalogue whose identity participates
+      # @return [String] hex SHA-256
+      def digest(configuration:, registry: Registry.default, catalog: Catalog.default, plugin_facts: nil)
+        Digest::SHA256.hexdigest(
+          [
+            "vocabulary:#{registry.vocabulary_version}",
+            "catalog:#{catalog.identity}",
+            "effects:#{config_digest(configuration)}",
+            "plugins:#{plugin_facts&.digest || 'none'}"
+          ].join("\x00")
+        )
+      end
+
+      # The effects identity as a cache KEY descriptor: the run's own diagnostics key descriptor plus one
+      # `configs:` entry carrying {.digest}. Composing (rather than rebuilding) is what makes the effects
+      # slot inherit every diagnostics-invalidating input — engine version, engine source, RBS libraries,
+      # the analyzed-path set — for free, so "the effects identity is the diagnostics identity plus three
+      # things" is a property of the code rather than a claim about it.
+      #
+      # @param base [Cache::Descriptor] the run's diagnostics key descriptor
+      # @return [Cache::Descriptor]
+      def descriptor(base:, configuration:, registry: Registry.default, catalog: Catalog.default,
+                     plugin_facts: nil)
+        Cache::Descriptor.compose(
+          base,
+          Cache::Descriptor.new(
+            configs: [
+              Cache::Descriptor::ConfigEntry.new(
+                key: CONFIG_KEY,
+                value_hash: digest(configuration: configuration, registry: registry, catalog: catalog,
+                                   plugin_facts: plugin_facts)
+              )
+            ]
+          )
+        )
+      end
+
+      # The `effects:` block of `.rigor.yml`, canonicalised (keys sorted at every depth, rendered as JSON)
+      # and hashed. {Snapshot.config_digest} is this method — the snapshot header and the cache identity
+      # MUST agree, and the cheapest way to guarantee that is for there to be one implementation.
+      def config_digest(configuration)
+        Digest::SHA256.hexdigest(JSON.generate(canonicalize(configuration.effects || {})))
+      end
+
+      def canonicalize(value)
+        case value
+        when Hash then value.map { |key, member| [key.to_s, canonicalize(member)] }.sort_by(&:first).to_h
+        when Array then value.map { |member| canonicalize(member) }
+        when Symbol then value.to_s
+        else value
+        end
+      end
+    end
+  end
+end

data/lib/rigor/effects/label.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Effects
+    # The effect-label grammar and the subsumption relation over it (ADR-103 WD1; normative in
+    # `docs/type-specification/effect-labels.md`).
+    #
+    # A label is a dot-path of lowercase segments — `io`, `io.net.http`, `nondet.time`. The relation
+    # that matters is **segment-aware prefix subsumption**: `io` admits `io.net.http` and rejects
+    # `iota`. Every method here is pure and total; a malformed input is answered, never raised on,
+    # so a caller can ask `valid?` and the rest in either order.
+    module Label
+      # `label = segment { "." segment }`, `segment = [a-z][a-z0-9]*`. Deliberately narrow: no
+      # underscores, no hyphens, no uppercase, no empty segment, no trailing dot. The same grammar
+      # is the RFC's `label` production, so a label spells identically in Steins and Rigor.
+      PATTERN = /\A[a-z][a-z0-9]*(?:\.[a-z][a-z0-9]*)*\z/
+
+      SEPARATOR = "."
+      private_constant :SEPARATOR
+
+      module_function
+
+      # Whether `str` is a well-formed label. Anything that is not a String is not.
+      def valid?(str)
+        str.is_a?(String) && PATTERN.match?(str)
+      end
+
+      # The label's segments, outermost first: `"io.net.http"` -> `["io", "net", "http"]`.
+      # A malformed label yields an empty array rather than a partial parse.
+      def segments(label)
+        return [].freeze unless valid?(label)
+
+        label.split(SEPARATOR).freeze
+      end
+
+      # Whether `bound` admits `label` under segment-aware prefix subsumption. A label subsumes
+      # itself; `io` subsumes `io.net.http`; `io` does NOT subsume `iota`, because the match is on
+      # segment boundaries and not on characters.
+      def subsumes?(bound, label)
+        return false unless valid?(bound) && valid?(label)
+        return true if bound == label
+
+        label.start_with?("#{bound}#{SEPARATOR}")
+      end
+
+      # The label one segment shallower, or `nil` for a root (and for a malformed label).
+      def parent(label)
+        return nil unless valid?(label)
+
+        index = label.rindex(SEPARATOR)
+        return nil unless index
+
+        label[0, index]
+      end
+
+      # The label's proper ancestors, outermost first and excluding the label itself:
+      # `"io.net.http"` -> `["io", "io.net"]`. A root has no ancestors.
+      def ancestors(label)
+        parts = segments(label)
+        return [].freeze if parts.length <= 1
+
+        result = []
+        prefix = nil
+        parts[0...-1].each do |segment|
+          prefix = prefix ? "#{prefix}#{SEPARATOR}#{segment}" : segment
+          result << prefix
+        end
+        result.freeze
+      end
+
+      # The label's outermost segment — the root whose ownership the registry checks.
+      def root(label)
+        segments(label).first
+      end
+    end
+  end
+end

data/lib/rigor/effects/label_intent.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require_relative "label"
+
+module Rigor
+  module Effects
+    # Whether an unrecognised effect label is evidence of a **typo** rather than of a word that was
+    # never meant to be a label at all (ADR-103 WD1; normative in
+    # `docs/type-specification/effect-labels.md` § Unknown labels).
+    #
+    # The degradation an unknown label causes is silent by construction — the tag reads ⊤ and stops
+    # bounding anything — so a paired diagnostic is the only thing that keeps the fail-open rule
+    # honest. But the diagnostic cannot fire on every unrecognised spelling: a vocabulary is open by
+    # design (`effects.labels:`, a plugin's own root), so an unknown word is as likely to be a label
+    # this project has not registered yet as it is to be a misspelling. Reporting both would put a
+    # finding on correct-by-intent code, which is the direction the false-positive budget is not
+    # allowed to run ([ADR-5](../../../docs/adr/5-robustness-principle.md)).
+    #
+    # Intent is therefore read off four signals, any one of which is enough:
+    #
+    # 1. **A near miss** — the spelling is within {Registry::SUGGESTION_DISTANCE_CAP} edits of a
+    #    label the registry knows (`io.bd` against `io.db`).
+    # 2. **A known sibling** — another member of the same comma-separated list is recognised, so the
+    #    list as a whole is demonstrably written in this vocabulary.
+    # 3. **A dotted path** — the token carries two or more segments (`io.netw`). Nothing but a label
+    #    is spelled that way; a project opening its own root writes a bare word first.
+    # 4. **A retired spelling** — the registry's `retired:` table names it, so the author wrote a
+    #    label that WAS correct and a vocabulary bump moved it.
+    #
+    # A lone far-off word (`%a{rigor:v1:effect database}`) matches none of them and stays silent
+    # everywhere. It still degrades the tag to ⊤ — the reading never depends on this module.
+    module LabelIntent
+      # How many dot-separated segments make a token unmistakably label-shaped (signal 3).
+      MULTI_SEGMENT_ARITY = 2
+
+      module_function
+
+      # Whether reporting `token` as an unknown label is justified.
+      #
+      # @param token [String] the spelling as written.
+      # @param registry [Rigor::Effects::Registry, nil] the vocabulary AFTER plugin load; `nil` (no
+      #   vocabulary at all) makes every token unjudgeable and therefore silent.
+      # @param siblings [Array<String>] the other tokens of the same list / the same config value.
+      # @return [Boolean]
+      def evident?(token, registry, siblings: [])
+        return false if registry.nil?
+        return false unless Label.valid?(token)
+        return false if registry.known?(token)
+
+        retired?(token, registry) || near_miss?(token, registry) ||
+          multi_segment?(token) || known_sibling?(token, registry, siblings)
+      end
+
+      def retired?(token, registry)
+        !Array(registry.retired(token)).empty?
+      end
+
+      def near_miss?(token, registry)
+        !registry.suggest(token).nil?
+      end
+
+      def multi_segment?(token)
+        Label.segments(token).length >= MULTI_SEGMENT_ARITY
+      end
+
+      def known_sibling?(token, registry, siblings)
+        Array(siblings).any? { |sibling| sibling != token && registry.known?(sibling.to_s) }
+      end
+
+      private_class_method :retired?, :near_miss?, :multi_segment?, :known_sibling?
+    end
+  end
+end