rigortype 0.3.9 → 0.4.0

data/sig/rigor/effects/effect_table.rbs

@@ -0,0 +1,60 @@
+module Rigor
+  module Effects
+    # The propagated result of the fixpoint walk: every method's direct summary plus the transitive
+    # `proven` / `undischarged` / `declared` lanes, the exhaustiveness bit, and the resolved callee keys.
+    class EffectTable
+      # One row of the closed table.
+      class Entry < ::Data
+        # sig-gen gap: #1150 — `Data.define` member reads carry no type.
+        def key: () -> String
+        # sig-gen gap: #1150
+        def direct: () -> Summary
+        # sig-gen gap: #1150
+        def proven: () -> LabelSet
+        # sig-gen gap: #1150
+        def undischarged: () -> LabelSet
+        # sig-gen gap: #1150
+        def declared: () -> LabelSet
+        # sig-gen gap: #1150
+        def exhaustive: () -> bool
+        # sig-gen gap: #1150 — `causes` are frozen `[cause, detail]` pairs.
+        def causes: () -> Array[[String, String?]]
+        # sig-gen gap: #1150 — resolved callee keys (`"Class#m"` strings).
+        def edges: () -> Array[String]
+        # sig-gen gap: #1150
+        def unclaimed: () -> bool
+
+        # sig-gen gap: #1150 — the custom `initialize` supplies defaults for `undischarged` (=
+        # `proven`), `declared` (= empty) and `unclaimed` (= false); it accepts kwargs only, so the
+        # member constructor has no positional arm.
+        def self.new: (key: String, direct: Summary, proven: LabelSet, exhaustive: bool,
+                       causes: Array[[String, String?]], edges: Array[String],
+                       ?undischarged: LabelSet?, ?declared: LabelSet?, ?unclaimed: bool) -> instance
+        # sig-gen gap: #1150 — as above.
+        def self.[]: (key: String, direct: Summary, proven: LabelSet, exhaustive: bool,
+                      causes: Array[[String, String?]], edges: Array[String],
+                      ?undischarged: LabelSet?, ?declared: LabelSet?, ?unclaimed: bool) -> instance
+
+        def unclaimed?: () -> bool
+
+        # The declared labels worth printing beside `proven` — those the proven lane does not already
+        # admit.
+        def rendered_declared: () -> LabelSet
+
+        def exhaustive?: () -> bool
+        def trivial?: () -> bool
+      end
+
+      def self.empty: () -> EffectTable
+
+      def initialize: (Hash[String, Entry] entries) -> void
+
+      def []: (String key) -> Entry?
+      def keys: () -> Array[String]
+      def each: () { (Entry) -> untyped } -> void
+      include Enumerable[Entry]
+      def size: () -> Integer
+      def empty?: () -> bool
+    end
+  end
+end

data/sig/rigor/effects/envelope.rbs

@@ -0,0 +1,97 @@
+module Rigor
+  module Effects
+    # An author-declared upper bound on one method's effect labels (ADR-103 WD1). A `Data` record —
+    # see lib/rigor/effects/envelope.rb for the member semantics.
+    class Envelope < ::Data
+      # {#source} for a bound written in `.rigor.yml` rather than on a declaration.
+      CONFIG_SOURCE: :config_envelope
+
+      # sig-gen gap: #1150 — `Data.define` member reads carry no type; `build` proves each of these.
+      def owner_key: () -> String
+
+      # sig-gen gap: #1150 — as above; `LabelSet::TOP` means "no envelope" (the fail-open reading).
+      def bound: () -> LabelSet
+
+      # sig-gen gap: #1150 — as above; the four documented producers are the closed set.
+      def source: () -> (:pure_annotation | :effect_annotation | :class_annotation | :config_envelope)
+
+      # sig-gen gap: #1150 — as above (`path:line`, the `.rigor.yml` key path, or nil).
+      def location: () -> String?
+
+      # sig-gen gap: #1150 — as above (the author's own annotation text, or nil).
+      def spelling: () -> String?
+
+      # sig-gen gap: #1150 — as above (sorted, de-duplicated by `build`; #384 reads them).
+      def unknown_labels: () -> Array[String]
+
+      # sig-gen gap: #1150 — as above (every token the tag listed, recognised or not).
+      def declared_labels: () -> Array[String]
+
+      # sig-gen gap: #1150 — as above; keyword form mirrors the member declarations.
+      def self.new: (
+        owner_key: String,
+        bound: LabelSet,
+        source: (:pure_annotation | :effect_annotation | :class_annotation | :config_envelope),
+        location: String?,
+        spelling: String?,
+        unknown_labels: Array[String],
+        declared_labels: Array[String]
+      ) -> instance
+      | (
+        String owner_key,
+        LabelSet bound,
+        (:pure_annotation | :effect_annotation | :class_annotation | :config_envelope) source,
+        String? location,
+        String? spelling,
+        Array[String] unknown_labels,
+        Array[String] declared_labels
+      ) -> instance
+
+      # sig-gen gap: #1150 — as above.
+      def self.[]: (
+        owner_key: String,
+        bound: LabelSet,
+        source: (:pure_annotation | :effect_annotation | :class_annotation | :config_envelope),
+        location: String?,
+        spelling: String?,
+        unknown_labels: Array[String],
+        declared_labels: Array[String]
+      ) -> instance
+      | (
+        String owner_key,
+        LabelSet bound,
+        (:pure_annotation | :effect_annotation | :class_annotation | :config_envelope) source,
+        String? location,
+        String? spelling,
+        Array[String] unknown_labels,
+        Array[String] declared_labels
+      ) -> instance
+
+      # Normalising constructor — sorts/dedupes `unknown_labels` and freezes `declared_labels`.
+      def self.build: (
+        owner_key: String,
+        bound: LabelSet,
+        source: (:pure_annotation | :effect_annotation | :class_annotation | :config_envelope),
+        ?location: String?,
+        ?spelling: String?,
+        ?unknown_labels: Array[String],
+        ?declared_labels: Array[String]
+      ) -> Envelope
+
+      # Whether this reads as ⊤ — no bound at all.
+      def top?: () -> bool
+
+      # `label` is `to_s`-compared through {LabelSet#admits?}; `mutate.local` always tolerates.
+      def tolerates?: (untyped label) -> bool
+
+      # The members of `label_set` this envelope does NOT admit, sorted.
+      def exceeded_by: (LabelSet label_set) -> Array[String]
+
+      # Whether the bound was written in `.rigor.yml`.
+      def config?: () -> bool
+
+      # The same bound on another method key — the class-level distribution seam.
+      def rebind: (String key) -> Envelope
+    end
+  end
+end

data/sig/rigor/effects/envelope_index.rbs

@@ -0,0 +1,33 @@
+module Rigor
+  module Effects
+    # The envelopes a call site may import as a `≤` bound (ADR-103 WD6; #386) — per-method
+    # annotation, class-level annotation, `effects.envelopes:`, then the accepted signature stratum.
+    class EnvelopeIndex
+      # The index a run with no declaration of any kind uses — and the fail-soft answer for a build
+      # that raised.
+      def self.empty: () -> EnvelopeIndex
+
+      # Reads every stratum this index serves, once per process. `environment` supplies the accepted
+      # stratum through its RBS loader (nil drops it, fail-quiet); `plugin_facts` is the plugins'
+      # compiled `Effects::PluginFacts` contributions (nil where no plugin set was loaded).
+      def self.build: (configuration: Configuration, ?environment: Rigor::Environment?,
+                       ?plugin_facts: PluginFacts?) -> EnvelopeIndex
+
+      def initialize: (
+        ?method_envelopes: Hash[String, Envelope],
+        ?class_envelopes: Hash[String, Envelope],
+        ?config_entries: Array[ConfigEnvelopes::Entry],
+        ?accepted: Hash[String, Envelope]
+      ) -> void
+
+      # Whether no stratum has anything to say — the scan's fast path.
+      def empty?: () -> bool
+
+      # The envelope bounding `owner`'s `selector`, or nil — never a ⊤ envelope.
+      def []: (String? owner, bool singleton, untyped selector) -> Envelope?
+
+      # Whether ANY stratum carries an annotation for this key — ⊤ envelopes included (#391).
+      def annotated?: (String? owner, bool singleton, untyped selector) -> bool
+    end
+  end
+end

data/sig/rigor/effects/file_collection.rbs

@@ -0,0 +1,81 @@
+module Rigor
+  module Effects
+    # The per-file unit of the collection window (ADR-103): the direct summaries, the call edges, and
+    # the as-written ancestry a file contributes. {merge_all} folds a run's collections in one pass.
+    class FileCollection
+      # An ancestry entry that names nothing and can never resolve (#1039).
+      OPAQUE_ANCESTOR: String
+
+      # One recorded call edge: who the receiver's class is, which lane (`:instance` / `:singleton`)
+      # the selector dispatches on, and the bits that decide what an unresolved edge seeds.
+      class Edge < ::Data
+        # sig-gen gap: #1150 — `Data.define` member reads carry no type.
+        def receiver_class: () -> String?
+        # sig-gen gap: #1150
+        def kind: () -> (:instance | :singleton)
+        # sig-gen gap: #1150
+        def selector: () -> String
+        # sig-gen gap: #1150
+        def self_call: () -> bool
+        # sig-gen gap: #1150
+        def super_call: () -> bool
+        # sig-gen gap: #1150
+        def unclaimed: () -> bool
+        # sig-gen gap: #1150
+        def constant_receiver: () -> bool
+        # sig-gen gap: #1150 — the `[cause, detail]` pair an unresolved edge seeds, when the row
+        # named a `taint:`.
+        def taint_if_unresolved: () -> [String, String?]?
+        # sig-gen gap: #1150 — the plugin's lookup-order retry selectors (#1065).
+        def fallback_selectors: () -> Array[String]?
+
+        # sig-gen gap: #1150 — member constructor. The custom `initialize` accepts kwargs only and
+        # defaults every member after `self_call`, so there is no positional arm.
+        def self.new: (receiver_class: String?, kind: (:instance | :singleton), selector: String,
+                       self_call: bool, ?super_call: bool, ?unclaimed: bool,
+                       ?constant_receiver: bool, ?taint_if_unresolved: [String, String?]?,
+                       ?fallback_selectors: Array[String]?) -> instance
+        # sig-gen gap: #1150 — as above.
+        def self.[]: (receiver_class: String?, kind: (:instance | :singleton), selector: String,
+                      self_call: bool, ?super_call: bool, ?unclaimed: bool,
+                      ?constant_receiver: bool, ?taint_if_unresolved: [String, String?]?,
+                      ?fallback_selectors: Array[String]?) -> instance
+      end
+
+      # The collection a file with nothing to say contributes.
+      def self.empty: (?String? path) -> FileCollection
+
+      # sig-gen gap: #1154 — `initialize` freezes the kwarg tables rather than assigning them
+      # verbatim, so sig-gen proposes the default constant's shape for each reader.
+      attr_reader path: String?
+      # sig-gen gap: #1154 — `{ "Class#m" => Summary }`.
+      attr_reader summaries: Hash[String, Summary]
+      # sig-gen gap: #1154 — `{ "Class#m" => [Edge] }`, sorted and de-duplicated.
+      attr_reader edges: Hash[String, Array[Edge]]
+      # sig-gen gap: #1154 — `{ class_name => superclass_name }`, `OPAQUE_ANCESTOR` included.
+      attr_reader superclasses: Hash[String, String]
+      # sig-gen gap: #1154 — `{ class_name => [module_name] }`, include/prepend merged.
+      attr_reader includes: Hash[String, Array[String]]
+
+      def initialize: (?path: String?, ?summaries: Hash[String, Summary],
+                       ?edges: Hash[String, Array[Edge]], ?superclasses: Hash[String, String],
+                       ?includes: Hash[String, Array[String]], ?failed: bool) -> void
+
+      # Whether the collector gave up on this file entirely (the fail-soft path).
+      def failed?: () -> bool
+
+      # Whether this collection contributes nothing.
+      def empty?: () -> bool
+
+      # Two-collection fold — {merge_all} for a whole run.
+      def merge: (FileCollection other) -> FileCollection
+
+      # Folds a run's collections in one linear pass; order-independent except `superclasses`.
+      def self.merge_all: (Enumerable[FileCollection] collections) -> FileCollection
+
+      def ==: (untyped other) -> bool
+      alias eql? ==
+      def hash: () -> Integer
+    end
+  end
+end

data/sig/rigor/effects/label.rbs

@@ -0,0 +1,26 @@
+module Rigor
+  module Effects
+    # The effect-label grammar and segment-aware prefix subsumption (ADR-103 WD1). Every predicate is
+    # total — a malformed input is answered, never raised on — so the parameters are `untyped` on
+    # purpose.
+    module Label
+      PATTERN: Regexp
+
+      def self?.valid?: (untyped str) -> bool
+
+      # `[]` for a malformed label, the segments otherwise.
+      def self?.segments: (untyped label) -> Array[String]
+
+      def self?.subsumes?: (untyped bound, untyped label) -> bool
+
+      # One segment shallower; nil for a root and for a malformed label.
+      def self?.parent: (untyped label) -> String?
+
+      # Proper ancestors, outermost first; `[]` for a root and for a malformed label.
+      def self?.ancestors: (untyped label) -> Array[String]
+
+      # The outermost segment; nil for a malformed label.
+      def self?.root: (untyped label) -> String?
+    end
+  end
+end

data/sig/rigor/effects/label_set.rbs

@@ -0,0 +1,46 @@
+module Rigor
+  module Effects
+    # An immutable, sorted, de-duplicated set of effect labels (ADR-103 WD1) — the carrier of a
+    # summary lane and of an envelope's bound. `TOP` is the unbounded sentinel: it admits every
+    # label, absorbs every join, and answers `[]` from `to_a`.
+    class LabelSet
+      # `labels` is any enumerable of label Strings (`#to_a` is called on it); `top:` is internal —
+      # it exists to build {TOP} and is not part of the public surface.
+      def initialize: (?untyped labels, ?top: bool) -> void
+
+      TOP: LabelSet
+      EMPTY: LabelSet
+
+      def top?: () -> bool
+
+      # {TOP} is not empty: it records nothing because it stands for everything.
+      def empty?: () -> bool
+
+      # The members, sorted. {TOP} yields `[]` — consult {top?} first.
+      def to_a: () -> Array[String]
+
+      # Exact membership — `include?` is not subsumption ({admits?} is).
+      def include?: (untyped label) -> bool
+
+      # Whether some member subsumes `label`. {TOP} admits every well-formed label.
+      def admits?: (untyped label) -> bool
+
+      # Union — {TOP} absorbs. May return `self`/`other` without allocating.
+      def join: (LabelSet other) -> LabelSet
+
+      # The members `other` does not already admit — the declared lane's rendering rule.
+      def excluding_subsumed_by: (LabelSet other) -> LabelSet
+
+      # The envelope check, modulo policy discharge. {TOP} is bounded only by {TOP}.
+      def subsumed_by?: (LabelSet bound_set) -> bool
+
+      def ==: (untyped other) -> bool
+
+      # `alias eql? ==` — no sig-gen shape for alias rows; unmarked residue.
+      def eql?: (untyped other) -> bool
+
+      def hash: () -> Integer
+      def inspect: () -> String
+    end
+  end
+end

data/sig/rigor/effects/method_key.rbs

@@ -0,0 +1,24 @@
+module Rigor
+  module Effects
+    # The `Owner#selector` / `Owner.selector` key spelling (ADR-103 WD14). `key` parameters accept any
+    # object — every entry point `to_s`s its input — so they are `untyped` on purpose.
+    module MethodKey
+      TEMPLATE_UNIT_PREFIX: String
+
+      # `[owner, separator, selector]`, or nil when `key` is not a method key at all.
+      def self?.split: (untyped key) -> [String, String, String]?
+
+      def self?.valid?: (untyped key) -> bool
+
+      # The owner half of a method key, or nil.
+      def self?.owner: (untyped key) -> String?
+
+      # `view:`-prefixed template-unit keys are NOT method keys (#393).
+      def self?.template_unit?: (untyped key) -> bool
+
+      # The name an `effects.envelopes:` entry selects a key by — the owner class for a method key,
+      # the unit key itself for a template unit.
+      def self?.envelope_owner: (untyped key) -> String?
+    end
+  end
+end

data/sig/rigor/effects/origin.rbs

@@ -0,0 +1,50 @@
+module Rigor
+  module Effects
+    # Where one bundle of labels in a summary came from (ADR-103 WD14): a callee/construct `name`
+    # plus which `source` coloured it.
+    class Origin < ::Data
+      CONSTRUCT: :construct
+      CATALOGUE: :catalogue
+      ATTRIBUTION: :attribution
+      ENVELOPE: :envelope
+      PLUGIN: :plugin
+
+      # sig-gen gap: #1150 — `Data.define` member reads carry no type; every factory below proves
+      # `name` a `to_s`d String and `source` one of the five constants.
+      def name: () -> String
+
+      # sig-gen gap: #1150 — as above; the five source constants are the closed set.
+      def source: () -> (:construct | :catalogue | :attribution | :envelope | :plugin)
+
+      # sig-gen gap: #1150 — as above.
+      def self.new: (
+        name: String,
+        source: (:construct | :catalogue | :attribution | :envelope | :plugin)
+      ) -> instance
+      | (
+        String name,
+        (:construct | :catalogue | :attribution | :envelope | :plugin) source
+      ) -> instance
+
+      # sig-gen gap: #1150 — as above.
+      def self.[]: (
+        name: String,
+        source: (:construct | :catalogue | :attribution | :envelope | :plugin)
+      ) -> instance
+      | (
+        String name,
+        (:construct | :catalogue | :attribution | :envelope | :plugin) source
+      ) -> instance
+
+      # `name` is `to_s`d, so any object is acceptable — `untyped` is the honest parameter.
+      def self.construct: (untyped name) -> Origin
+      def self.catalogue: (untyped name) -> Origin
+      def self.attribution: (untyped name) -> Origin
+      def self.envelope: (untyped name) -> Origin
+      def self.plugin: (untyped name) -> Origin
+
+      # `"source:name"` — the rendering the report and the JSON payload key on.
+      def to_s: () -> String
+    end
+  end
+end

data/sig/rigor/effects/plugin_facts.rbs

@@ -0,0 +1,141 @@
+module Rigor
+  module Effects
+    # The loaded plugins' effect contributions, compiled once per process (ADR-103): attribution rows
+    # indexed by receiver spelling, framework-edge strategies, label vocabulary, entry-point presets,
+    # and plugin-claimed ancestry.
+    class PluginFacts
+      # How many ancestors the walk visits before giving up — bounds work, not correctness.
+      ANCESTRY_CAP: Integer
+
+      # One compiled attribution row. `discharge` is the RESOLVED grant — `.build` has already
+      # demoted a non-first-party plugin's `true` and recorded a warning.
+      class Row < ::Data
+        # sig-gen gap: #1150 — `Data.define` member reads carry no type.
+        def key: () -> String
+        # sig-gen gap: #1150
+        def labels: () -> LabelSet
+        # sig-gen gap: #1150 — a {Narrowing} handler name, when the call's own arguments settle the
+        # row's answer.
+        def narrow: () -> String?
+        # sig-gen gap: #1150
+        def discharge: () -> bool
+        # sig-gen gap: #1150 — the class a `self`-path row is scoped to.
+        def within: () -> String?
+        # sig-gen gap: #1150 — the taint cause the row seeds where its edge resolves to nothing.
+        def taint: () -> String?
+        # sig-gen gap: #1150
+        def plugin_id: () -> String
+        # sig-gen gap: #1150 — the receiver a UNIT rule has no call node to read off.
+        def receiver: () -> String?
+        # sig-gen gap: #1150 — the {CalleeRule} rule name (#1048), nil when the row records no edge.
+        def callee: () -> String?
+        # sig-gen gap: #1150 — the plugin's lookup-order table for the rule's answer (#1065).
+        def callee_fallbacks: () -> Hash[String, Array[String]]?
+        # sig-gen gap: #1150
+        def responds: () -> bool
+
+        # sig-gen gap: #1150 — member constructor. The custom `initialize` accepts kwargs only and
+        # defaults `receiver` / `callee` / `callee_fallbacks` / `responds`, so there is no
+        # positional arm.
+        def self.new: (key: String, labels: LabelSet, narrow: String?, discharge: bool,
+                       within: String?, taint: String?, plugin_id: String, ?receiver: String?,
+                       ?callee: String?, ?callee_fallbacks: Hash[String, Array[String]]?,
+                       ?responds: bool) -> instance
+        # sig-gen gap: #1150 — as above.
+        def self.[]: (key: String, labels: LabelSet, narrow: String?, discharge: bool,
+                      within: String?, taint: String?, plugin_id: String, ?receiver: String?,
+                      ?callee: String?, ?callee_fallbacks: Hash[String, Array[String]]?,
+                      ?responds: bool) -> instance
+
+        def discharge?: () -> bool
+      end
+
+      # One compiled framework-edge strategy: the base class a plugin pointed the engine at, and
+      # which plugin pointed.
+      class Edge < ::Data
+        # sig-gen gap: #1150 — `Data.define` member reads carry no type. `target` is the closed
+        # {Plugin::EffectEdge::TARGETS} set.
+        def target: () -> (:activerecord_callbacks | :perform_now | :mailer_body)
+        # sig-gen gap: #1150
+        def receiver: () -> String
+        # sig-gen gap: #1150 — nil for a whole-class edge (`method` omitted).
+        def selector: () -> Symbol?
+        # sig-gen gap: #1150
+        def plugin_id: () -> String
+
+        # sig-gen gap: #1150 — member constructor.
+        def self.new: (target: (:activerecord_callbacks | :perform_now | :mailer_body),
+                       receiver: String, selector: Symbol?, plugin_id: String) -> instance
+        | ((:activerecord_callbacks | :perform_now | :mailer_body) target, String receiver,
+           Symbol? selector, String plugin_id) -> instance
+        # sig-gen gap: #1150 — as above.
+        def self.[]: (target: (:activerecord_callbacks | :perform_now | :mailer_body),
+                      receiver: String, selector: Symbol?, plugin_id: String) -> instance
+      end
+
+      # The rows whose `callee:` names a {CalleeRule::UNIT_RULES} rule — applied once per unit.
+      # Unmarked residue: populated by `absorb_attribution`, not assigned from an `initialize`
+      # parameter, so no gap issue covers it (same shape as `Registry#additional_initializers`).
+      attr_reader unit_callee_rows: Array[Row]
+
+      # Human-readable notes about contributions accepted only in part. Surfaced by `rigor effects`;
+      # never a diagnostic. Unmarked residue — accumulated by `absorb`/`extend_registry`.
+      attr_reader warnings: Array[String]
+
+      # `{owner => [labels]}` — what {#extend_registry} folds into the run's vocabulary.
+      # Unmarked residue — built by `absorb`, not an `initialize` parameter.
+      attr_reader labels_by_owner: Hash[String, Array[String]]
+
+      # Every `effect_entry_points:` preset across the loaded set.
+      # Unmarked residue — concatenated by `absorb`, not an `initialize` parameter.
+      attr_reader entry_points: Array[Plugin::EffectEntryPoints]
+
+      # A content digest of every compiled plugin fact; {Identity} folds it in.
+      # Unmarked residue — computed by `compute_digest`, not an `initialize` parameter.
+      attr_reader digest: String
+
+      def self.empty: () -> PluginFacts
+
+      # `superclasses`/`includes` are the project's as-written ancestry tables
+      # (`Scope::DiscoveryIndex#discovered_superclasses` / `#discovered_includes`).
+      def self.build: (Plugin::Registry? plugin_registry, ?superclasses: Hash[String, String]?,
+                       ?includes: Hash[String, Array[String]]?) -> PluginFacts
+
+      # `contributions:` elements are `Plugin::Registry::Contribution` rows.
+      def initialize: (contributions: Array[Plugin::Registry::Contribution],
+                       superclasses: Hash[String, String]?,
+                       ?includes: Hash[String, Array[String]]?) -> void
+
+      def empty?: () -> bool
+
+      # Whether any attribution row exists at all — the scan's fast path.
+      def attributions?: () -> bool
+      def edges?: () -> bool
+
+      # The row colouring `owner`'s `selector`, on `owner` itself or a project ancestor.
+      def class_row: (String? owner, bool singleton, String selector) -> Row?
+
+      # The row colouring receiver `path`'s `selector` (`"Rails.cache"`) — exact, no ancestry walk.
+      def path_row: (String? path, String selector) -> Row?
+
+      # The row colouring `path`'s `selector` for a self-rooted receiver (`"self.flash.now"`) inside
+      # a unit whose class is `owner_class`.
+      def self_path_row: (String? path, String selector, String? owner_class) -> Row?
+
+      # The row colouring `selector` on the RESULT of a call to `producer` (or an ancestor of it).
+      def result_row: (String? producer, String selector) -> Row?
+
+      # The framework-edge strategies of one kind, e.g. every `:activerecord_callbacks` base class
+      # the loaded plugins named.
+      def edges_for: (Symbol target) -> Array[Edge]
+
+      # Whether `class_name` is `ancestor`, or reaches it through the project's own `class … <`
+      # lines and included modules.
+      def descends_from?: (String? class_name, String? ancestor) -> bool
+
+      # `registry` extended with every plugin's `effect_labels:` under its own owner. Rejected
+      # extensions land in {#warnings} instead of raising.
+      def extend_registry: (Registry registry) -> Registry
+    end
+  end
+end

data/sig/rigor/effects/registry.rbs

@@ -0,0 +1,68 @@
+module Rigor
+  module Effects
+    # The effect-label vocabulary: which spellings are recognised, which have been retired, and who
+    # may open a new root (ADR-103 WD2; normative in `docs/type-specification/effect-labels.md`).
+    # A frozen value object; {#with} returns a new one rather than mutating.
+    class Registry
+      class Error < StandardError
+      end
+
+      # An added label whose root neither exists already nor belongs to the extender.
+      class OwnershipError < Error
+      end
+
+      # An added label that is not well-formed under {Label::PATTERN}.
+      class InvalidLabelError < Error
+      end
+
+      DATA_PATH: String
+
+      # How far a misspelling may be from a known label before {#suggest} declines to guess.
+      SUGGESTION_DISTANCE_CAP: Integer
+
+      # The shared registry as shipped, memoised per process.
+      def self.default: () -> Registry
+
+      # The vocabulary one run works in: the shipped registry plus `effects.labels:` and every
+      # loaded plugin's `effect_labels:` (ADR-103 WD2 / #385 / #387). Fail-soft: a rejected
+      # extension degrades to the shipped vocabulary.
+      def self.for_configuration: (Configuration configuration, ?plugin_facts: PluginFacts?) -> Registry
+
+      # Build a registry from a registry-shaped YAML file. Missing or unreadable data degrades to
+      # an empty vocabulary (fail-open).
+      def self.load_file: (untyped path) -> Registry
+
+      # sig-gen gap: #1154 — `attr_reader` over an ivar assigned in `initialize` from the
+      # parameter of the same name; sig-gen proposes `untyped` for it.
+      attr_reader vocabulary_version: Integer
+      # sig-gen gap: #1154 — every declared label, sorted; implied ancestors are recognised by
+      # {#known?} but not listed here.
+      attr_reader labels: Array[String]
+      # The roots of the vocabulary — the outermost segments {#with} treats as already owned.
+      # Unmarked residue: `@roots` is computed from `@known` in `initialize`, not assigned from a
+      # parameter, so #1154 does not cover it.
+      attr_reader roots: Array[String]
+      # sig-gen gap: #1154 — one line per root, from the data file's `descriptions:`.
+      attr_reader descriptions: Hash[String, String]
+
+      def initialize: (vocabulary_version: Integer, labels: Array[untyped],
+                       ?retired: Hash[untyped, untyped],
+                       ?descriptions: Hash[untyped, untyped]) -> void
+
+      # Whether the vocabulary recognises `label`: an exact row, or an ancestor of one.
+      def known?: (untyped label) -> bool
+
+      # The nearest recognised label to a misspelling within {SUGGESTION_DISTANCE_CAP} edits, or
+      # nil when nothing is close enough.
+      def suggest: (untyped label) -> String?
+
+      # The replacement labels for a retired spelling, or nil when it was never retired.
+      def retired: (untyped label) -> Array[String]?
+
+      # A new registry carrying `labels` on top of this one. `owner` is the identity opening a
+      # root — a plugin id, or a first-party plugin's framework root; nil is the project, which
+      # may open any root.
+      def with: (labels: Array[untyped], owner: String?) -> Registry
+    end
+  end
+end