rigortype 0.3.8 → 0.4.0

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

data/sig/rigor/effects/summary.rbs

@@ -0,0 +1,50 @@
+module Rigor
+  module Effects
+    # One method's direct effect record: the labels its own body contributes, grouped by the origin
+    # that claimed them, plus the declared (`<=`) lane, the exhaustiveness bit, and the taint causes.
+    class Summary
+      TRIVIAL_BOUND: LabelSet
+
+      # The pure-modulo-frame-ownership summary: no origins, nothing declared, exhaustive, untainted.
+      def self.empty: () -> Summary
+
+      # A summary carrying a single taint and no labels — the fail-soft answer for a unit the collector
+      # could not finish.
+      def self.tainted: (String cause, ?String? detail) -> Summary
+
+      # sig-gen gap: #1154 — `initialize` normalizes the `bundles:`/`declared_bundles:` kwargs through
+      # `normalize_bundles` (join-merging per origin), so the readers do not trace to the parameters.
+      attr_reader bundles: Hash[Origin, LabelSet]
+      # sig-gen gap: #1154 — as above.
+      attr_reader declared_bundles: Hash[Origin, LabelSet]
+      # Unmarked residue — `proven`/`declared` are flattened from the bundle tables by `initialize`,
+      # not assigned from a parameter, so #1154 does not cover them (same shape as
+      # `Registry#additional_initializers`).
+      attr_reader declared: LabelSet
+      attr_reader proven: LabelSet
+      # sig-gen gap: #1154 — `causes` are `[cause, detail]` pairs normalized in `initialize`.
+      attr_reader causes: Array[[String, String?]]
+
+      def initialize: (?bundles: Hash[Origin, LabelSet], ?declared_bundles: Hash[Origin, LabelSet],
+                       ?exhaustive: bool, ?causes: Array[[String, String?]], ?unclaimed: bool) -> void
+
+      # Whether every call this method makes was resolved.
+      def exhaustive?: () -> bool
+
+      # Whether this method made a call nothing described — read by `rigor sig-gen`'s annotation
+      # emission alone (#391).
+      def unclaimed?: () -> bool
+
+      # Whether the report omits this row by default (#386).
+      def trivial?: () -> bool
+
+      # Union in every lane — reopenings and multi-file contributors fold through this.
+      def join: (Summary other) -> Summary
+
+      def ==: (untyped other) -> bool
+      alias eql? ==
+      def hash: () -> Integer
+      def inspect: () -> String
+    end
+  end
+end

data/sig/rigor/effects/taint_cause.rbs

@@ -0,0 +1,12 @@
+module Rigor
+  module Effects
+    # The closed enum of reasons a summary is not exhaustive (ADR-103 WD14). A reporting vocabulary,
+    # never a diagnostic one.
+    module TaintCause
+      ALL: Array[String]
+
+      # `cause.to_s` is looked up, so any object is a fair question.
+      def self?.valid?: (untyped cause) -> bool
+    end
+  end
+end

data/sig/rigor/environment.rbs

@@ -15,10 +15,8 @@ module Rigor
     attr_reader hkt_registry: untyped?
     # Issue #784 — `[error_class_name, first_message_line, raw_frame_or_nil, stage]` when either stage of
     # the HKT-registry build raised at its seam (`:scan`, the RBS `type`-alias scan; `:overlay`, the
-    # plugin-manifest aggregation — #791), nil when both built or were never demanded. Declared `untyped?`
-    # like its neighbours:
-    # `rigor sig-gen` emits nothing for this delegating reader, and the tuple shape is documented here.
-    def hkt_scan_failure: () -> untyped?
+    # plugin-manifest aggregation — #791), nil when both built or were never demanded.
+    def hkt_scan_failure: () -> [String, String, String?, Symbol]?
 
     def self.default: () -> Environment
     def self.for_project: (?root: String, ?libraries: Array[String], ?signature_paths: Array[String | _ToPath]?, ?cache_store: untyped?, ?plugin_registry: untyped?, ?dependency_source_index: untyped?, ?rbs_extended_reporter: untyped?, ?boundary_cross_reporter: untyped?, ?source_rbs_synthesis_reporter: untyped?, ?bundler_bundle_path: String?, ?bundler_auto_detect: bool, ?synthetic_method_index: untyped?, ?project_patched_methods: untyped?) -> Environment
@@ -31,8 +29,12 @@ module Rigor
     def nominal_for_name: (String | Symbol name) -> Type::Nominal?
     def singleton_for_name: (String | Symbol name) -> Type::Singleton?
     def constant_for_name: (String | Symbol name) -> Type::t?
+    # sig-gen gap: #1154 — the answer comes through `rbs_loader`, an `attr_reader` over an ivar assigned in
+    # `initialize` from a parameter, which reaches `untyped`.
+    def global_for_name: (String | Symbol name, ?builtin: bool) -> Type::t?
     def class_known?: (String | Symbol name) -> bool
     def rbs_module?: (String | Symbol name) -> bool
+    def singleton_extended_modules: (String | Symbol name) -> Array[String]
     def class_ordering: (String | Symbol lhs, String | Symbol rhs) -> ordering
     def reflection: () -> untyped?
     def missing_rbs_gem_owner: (String | Symbol root_constant_name) -> String?
@@ -53,28 +55,33 @@ module Rigor
       attr_reader libraries: Array[String]
       attr_reader signature_paths: Array[String | _ToPath]
       attr_reader cache_store: untyped?
+      # sig-gen gap: #160 — sig-gen emits no `attr_reader` for the loader's readers; typed as the initializer stores it.
+      attr_reader deferred_signature_paths: Array[Pathname]
 
       def self.default: () -> RbsLoader
       def self.reset_default!: () -> void
-      def self.build_env_for: (libraries: Array[String], signature_paths: Array[String | _ToPath]) -> untyped
+      def self.build_env_for: (libraries: Array[String], signature_paths: Array[String | _ToPath]) -> ::RBS::Environment
       def self.vendored_gem_sig_paths: () -> Array[Pathname]
+      def self.capability_role_sig_paths: () -> ([Pathname] | [])
       def self.vendored_gem_names: () -> Array[String]
 
       def initialize: (?libraries: Array[String], ?signature_paths: Array[String | _ToPath], ?cache_store: untyped?) -> void
       def class_known?: (String | Symbol name) -> bool
       def rbs_module?: (String | Symbol name) -> bool
-      def instance_definition: (String | Symbol class_name) -> untyped?
-      def instance_method: (class_name: String | Symbol, method_name: String | Symbol) -> untyped?
-      def singleton_definition: (String | Symbol class_name) -> untyped?
-      def singleton_method: (class_name: String | Symbol, method_name: String | Symbol) -> untyped?
+      def instance_definition: (String | Symbol class_name) -> ::RBS::Definition?
+      def instance_method: (class_name: String | Symbol, method_name: String | Symbol) -> ::RBS::Definition::Method?
+      def singleton_definition: (String | Symbol class_name) -> ::RBS::Definition?
+      def singleton_method: (class_name: String | Symbol, method_name: String | Symbol) -> ::RBS::Definition::Method?
       def class_type_param_names: (String | Symbol class_name) -> Array[Symbol]
       def project_declared_classes: () -> Set[String]
       def project_declared_class?: (String | Symbol class_name) -> bool
       def class_ordering: (String | Symbol lhs, String | Symbol rhs) -> ordering
       def ancestor_names_for: (String | Symbol class_name) -> Array[String]
+      def singleton_extended_module_names: (String | Symbol class_name) -> Array[String]
       def constant_type: (String name) -> Type::t?
       def constant_names: () -> Array[String]
-      def each_known_class_name: () { (String name) -> void } -> untyped
+      def each_known_class_name: () { (String name) -> void } -> void
+                              | () -> ::Enumerator[String, void]
     end
 
     class RbsHierarchy

data/sig/rigor/inference/optimistic_origin.rbs

@@ -0,0 +1,10 @@
+module Rigor
+  module Inference
+    module OptimisticOrigin
+      # sig-gen gap: #1150 — sig-gen types the `BoundMark#miss` member read `untyped`, so it skips this reader
+      # (sig.skipped.untyped-return). The answer is the recorded `true` / `false` / `nil`, or the `UNKNOWN_MISS`
+      # sentinel; declaring it is what lets sig-gen type `Scope#optimistic_local_miss` / `#optimistic_ivar_miss`.
+      def self?.bound_miss: (untyped mark) -> Object?
+    end
+  end
+end

data/sig/rigor/inference.rbs

@@ -23,8 +23,10 @@ module Rigor
       class ClassFrame
         attr_reader name: String
         attr_reader singleton: bool
-        def self.new: (name: String, singleton: bool) -> ClassFrame
-        def initialize: (name: String, singleton: bool) -> void
+        # sig-gen gap: #1150 — `Data.define` members carry no type.
+        attr_reader refinement: bool
+        def self.new: (name: String, singleton: bool, ?refinement: bool) -> ClassFrame
+        def initialize: (name: String, singleton: bool, ?refinement: bool) -> void
       end
 
       def initialize: (scope: Scope, ?tracer: FallbackTracer?, ?on_enter: (^(untyped, Scope) -> void)?, ?class_context: Array[ClassFrame]) -> void
@@ -45,11 +47,7 @@ module Rigor
       def singleton_def?: (untyped def_node) -> bool
       def self_type_for_class_body: (Array[ClassFrame] class_context) -> Type::t?
       def self_type_for_method_body: (singleton: bool) -> Type::t?
-      def qualified_name_for: (untyped constant_path_node) -> String?
-      def render_constant_path: (untyped node) -> String
       def singleton_context_for: (untyped node) -> Array[ClassFrame]
-      def captured_local_writes: (untyped block_node, Scope base_scope) -> Array[Symbol]
-      def block_introduced_locals: (untyped block_node) -> Set[Symbol]
       def drop_captured_narrowing: (untyped block_node, Scope base_scope) -> Scope
       def classify_closure_escape: (untyped call_node) -> closure_classification
       def record_closure_escape_if_any: (untyped node) -> Scope
@@ -108,16 +106,16 @@ module Rigor
       def self?.narrow_non_nil: (Type::t type) -> Type::t
       def self?.narrow_equal: (Type::t type, untyped literal) -> Type::t
       def self?.narrow_not_equal: (Type::t type, untyped literal) -> Type::t
-      def self?.narrow_class: (Type::t type, String class_name, ?exact: bool, ?environment: Environment) -> Type::t
-      def self?.narrow_not_class: (Type::t type, String class_name, ?exact: bool, ?environment: Environment) -> Type::t
+      def self?.narrow_class: (Type::t type, String class_name, ?exact: bool, ?environment: Environment, ?scope: Scope?) -> Type::t
+      def self?.narrow_not_class: (Type::t type, String class_name, ?exact: bool, ?environment: Environment, ?scope: Scope?) -> Type::t
       def self?.narrow_not_refinement: (Type::t current_type, Type::t refinement_type) -> Type::t
       def self?.narrow_for_fact: (Type::t current, untyped fact, untyped environment) -> Type::t
       def self?.predicate_certainty: (Type::t? type) -> (:truthy | :falsey | nil)
-      def self?.class_pattern_certainty: (Type::t subject_type, String class_name, environment: Environment) -> (:yes | :no | :maybe)
+      def self?.class_pattern_certainty: (Type::t subject_type, String class_name, environment: Environment, ?scope: Scope?) -> (:yes | :no | :maybe)
       def self?.value_pattern_certainty: (Type::t subject_type, untyped pattern_value) -> (:yes | :no | :maybe)
       def self?.predicate_scopes: (untyped node, Scope scope) -> [Scope, Scope]
       def self?.case_when_scopes: (untyped subject, Array[untyped] conditions, Scope scope) -> [Scope, Scope]
-      def self?.analyse: (untyped node, Scope scope) -> untyped
+      def self?.analyse: (untyped node, Scope scope) -> [Scope, Scope]?
       def self?.subclass_of?: (String rigor_class_name, String target_class_name, untyped context) -> bool
       def self?.class_ordering: (String lhs, String rhs, untyped context) -> Symbol
       def self?.trusted_equality_literal?: (untyped literal) -> bool
@@ -162,7 +160,6 @@ module Rigor
 
     module ScopeIndexer
       def self?.index: (untyped root, default_scope: Scope) -> Hash[untyped, Scope]
-      def self?.build_declaration_overrides: (untyped root) -> Hash[untyped, Type::t]
       def self?.build_declaration_artifacts: (untyped root) -> [Hash[untyped, Type::t], Hash[String, Type::t]]
       def self?.build_in_source_constants: (untyped root, Scope default_scope) -> Hash[String, Type::t]
       def self?.record_declarations: (untyped node, Array[String] qualified_prefix, Hash[untyped, Type::t] identity_table, Hash[String, Type::t] discovered) -> void
@@ -175,9 +172,7 @@ module Rigor
       def self?.collect_class_decls: (untyped node, Array[String] qualified_prefix, Hash[String, Type::t] accumulator) -> void
       def self?.constant_writes_for_file: (untyped root) -> Hash[String, untyped]
       def self?.constant_literal_value: (untyped rvalue) -> Array[untyped]?
-      def self?.finalize_constant_writes: (Hash[String, Hash[String, untyped]] writes) -> [Hash[String, Type::t], Hash[String, Set[String]]]
-      def self?.qualified_name_for: (untyped constant_path_node) -> String?
-      def self?.render_constant_path: (untyped node) -> String
+      def self?.finalize_constant_writes: (Hash[String, Hash[String, untyped]] writes) -> [Hash[String, Type::Constant], Hash[String, Set[String]]]
       def self?.propagate: (untyped node, Hash[untyped, Scope] table, Scope parent_scope) -> void
     end
 

data/sig/rigor/plugin/additional_initializer.rbs

@@ -0,0 +1,36 @@
+module Rigor
+  module Plugin
+    # ADR-38 declaration — methods/def-blocks that establish ivar state like `initialize` does, so
+    # the read-before-write nil soundness gate does not widen their ivars. See
+    # lib/rigor/plugin/additional_initializer.rb for the full contract.
+    class AdditionalInitializer
+      # sig-gen gap: #1154 — `attr_reader` rows over ivars assigned from `initialize` parameters are
+      # skipped (untyped return); the constructor validates `receiver_constraint` is a non-empty
+      # String and normalizes both lists with `map(&:to_sym)`, so the stored types are hand-written.
+      attr_reader receiver_constraint: String
+
+      # sig-gen gap: #1154 — as above.
+      attr_reader methods: Array[Symbol]
+
+      # sig-gen gap: #1154 — as above.
+      attr_reader block_methods: Array[Symbol]
+
+      # The validators accept Symbol or non-empty String elements; `initialize` normalizes to
+      # Symbol before storing. At least one of `methods:`/`block_methods:` must be non-empty.
+      def initialize: (receiver_constraint: String, ?methods: Array[Symbol | String], ?block_methods: Array[Symbol | String]) -> void
+
+      def covers_method?: (Symbol method_name) -> bool
+
+      def covers_block_method?: (Symbol method_name) -> bool
+
+      def to_h: () -> Hash[String, String | Array[String]]
+
+      def ==: (untyped other) -> bool
+
+      # `alias eql? ==` — the alias row has no sig-gen shape, so it stays unmarked residue.
+      def eql?: (untyped other) -> bool
+
+      def hash: () -> Integer
+    end
+  end
+end

data/sig/rigor/plugin/base.rbs

@@ -17,11 +17,11 @@ class Rigor::Plugin::Base
   def self.producer: (untyped id, ?watch: untyped, ?serialize: untyped, ?deserialize: untyped, ?generation_cap: untyped) { (untyped params) -> untyped } -> Symbol
   def self.producers: () -> Hash[Symbol, untyped]
 
-  def self.node_rule: (untyped node_type) { (*untyped) -> untyped } -> untyped
+  def self.node_rule: (untyped node_type) { (*untyped) -> untyped } -> Class
   def self.node_rules: () -> Array[untyped]
 
-  def self.node_file_context: () { (untyped root, untyped scope) -> untyped } -> untyped
-  def self.node_file_context_block: () -> untyped
+  def self.node_file_context: () { (untyped root, untyped scope) -> untyped } -> void
+  def self.node_file_context_block: () -> (^(untyped root, untyped scope) -> untyped)?
 
   def self.dynamic_return: (?receivers: (Array[String] | ^() -> Array[String])?, ?methods: (Array[untyped] | ^() -> Array[untyped])?, ?file_methods: (^(untyped path) -> Array[untyped])?) { (untyped call_node, untyped scope) -> untyped } -> nil
   def self.dynamic_returns: () -> Array[untyped]
@@ -44,22 +44,45 @@ class Rigor::Plugin::Base
   def init: (untyped services) -> nil
   def prepare: (untyped services) -> nil
   def diagnostics_for_file: (path: untyped, scope: untyped, root: untyped) -> Array[untyped]
+  # authored: hook-contract widening — the element type comes from a plugin gem sig-gen never
+  # sees, so no engine work would let it answer; the declared `Array[Rigor::Plugin::TemplateUnit]`
+  # over a bare-`[]` default body is the author's contract.
+  def template_units_for_file: (path: untyped, source: untyped) -> Array[untyped]
+  # authored: hook-contract widening — the element type comes from a plugin gem sig-gen never
+  # sees, so no engine work would let it answer; the declared record contract over a bare-`[]`
+  # default body is the author's.
+  def declared_members: (untyped class_name) -> Array[untyped]
 
   # Engine-executed dispatch over the declared DSLs.
   def node_rule_diagnostics: (path: untyped, scope: untyped, root: untyped) -> Array[untyped]
-  def dynamic_return_type: (call_node: untyped, scope: untyped, receiver_type: untyped) -> untyped
+  # sig-gen gap: #1007 — the true `return result if result` branch (base.rb:594) flows through an
+  # `instance_exec`'d, plugin-supplied Proc that sig-gen's inference does not fold into the return
+  # join, so it proposes the literal fallback `nil` instead of the honest contract.
+  def dynamic_return_type: (call_node: untyped, scope: untyped, receiver_type: untyped) -> Rigor::Type::t?
   def narrowing_facts_for: (call_node: untyped, scope: untyped) -> Array[untyped]
 
   # Authoring helpers.
-  def diagnostic: (untyped node, path: untyped, message: untyped, ?severity: untyped, ?rule: untyped, ?location: untyped) -> untyped
+  def diagnostic: (untyped node, path: untyped, message: untyped, ?severity: untyped, ?rule: untyped, ?location: untyped) -> Rigor::Analysis::Diagnostic
   def diagnostics_for: (untyped violations, path: untyped, ?node: untyped) -> Array[untyped]
   def read_fact: (plugin_id: untyped, name: untyped) -> untyped
   def producer_value: (untyped id, ?params: untyped) -> untyped
   def producer_error: (untyped id) -> untyped
+  def disclose_once: (untyped key, message: untyped, ?severity: untyped, ?rule: untyped) -> nil
+  def emit_once: (untyped key, untyped diagnostics) -> nil
+  def run_disclosure_records: () -> Array[untyped]
   def manifest: () -> Rigor::Plugin::Manifest
   def signature_paths: () -> Array[String]
-  def protocol_contracts: () -> untyped
+  # Defaults to `manifest.protocol_contracts`; a plugin MAY override to fold per-project config in,
+  # but the contract (an Array of ProtocolContract) holds either way.
+  def protocol_contracts: () -> Array[Rigor::Plugin::ProtocolContract]
+  # The ADR-103 effect surfaces delegate to the manifest by default; a plugin MAY override
+  # `effect_attributions` to fold per-project config in, but the contract holds either way.
+  def effect_labels: () -> Array[String]
+  def effect_attributions: () -> Array[Rigor::Plugin::EffectAttribution]
+  def effect_edges: () -> Array[Rigor::Plugin::EffectEdge]
+  def effect_entry_points: () -> Array[Rigor::Plugin::EffectEntryPoints]
+  def effect_ancestry: () -> Array[Rigor::Plugin::EffectAncestry]
   def io_boundary: () -> Rigor::Plugin::IoBoundary
-  def cache_for: (untyped producer_id, ?params: untyped, ?descriptor: untyped) -> untyped
+  def cache_for: (untyped producer_id, ?params: untyped, ?descriptor: untyped) -> Proc
   def plugin_entry: () -> untyped
 end

data/sig/rigor/plugin/effect_ancestry.rbs

@@ -0,0 +1,27 @@
+module Rigor
+  module Plugin
+    # One `effect_ancestry:` row: an ancestry edge the plugin's own gem introduces and the project's
+    # source never writes down (ADR-103 WD17, #465). `parent:` need only be a true ancestor, not the
+    # immediate superclass. Bundled plugins only — `Effects::PluginFacts` enforces it. Frozen value
+    # object.
+    class EffectAncestry
+      # sig-gen gap: #1154 — validated in `initialize` from the parameter of the same name
+      # (`to_s`-normalized, frozen), so sig-gen proposes the raw parameter shape.
+      attr_reader child: String
+      # sig-gen gap: #1154 — same shape as `child`.
+      attr_reader parent: String
+      # sig-gen gap: #1154 — same shape; `why:` is required and validated non-empty.
+      attr_reader why: String
+
+      def initialize: (child: untyped, parent: untyped, why: untyped) -> void
+
+      def to_h: () -> Hash[String, untyped]
+
+      def ==: (untyped other) -> bool
+      # `alias eql? ==` — the alias row has no sig-gen shape, so it stays unmarked
+      # residue.
+      def eql?: (untyped other) -> bool
+      def hash: () -> Integer
+    end
+  end
+end

data/sig/rigor/plugin/effect_attribution.rbs

@@ -0,0 +1,66 @@
+module Rigor
+  module Plugin
+    # One `effect_attributions:` row: the receiver spelling, the selector, and the labels the call
+    # contributes to the declared lane — plus the optional `narrow:`/`callee:`/`taint:`/`responds:`
+    # modifiers the engine owns the strategy for (#393/#1048/#1065). Frozen value object.
+    class EffectAttribution
+      # A receiver spelled as a `Constant::Path` — the class-name form.
+      CLASS_NAME: Regexp
+      # A receiver path: a constant head followed by one or more sends (`Rails.cache`).
+      RECEIVER_PATH: Regexp
+      # A self path: implicit self followed by one or more receiver-less sends (`self.flash.now`).
+      SELF_PATH: Regexp
+      # What a self path is rooted at, once the `self.` head is stripped.
+      SELF_HEAD: String
+      # The taint causes a plugin row may name — a closed subset of `Effects::TaintCause::ALL`.
+      TAINT_CAUSES: Array[String]
+
+      # sig-gen gap: #1154 — normalized/validated in `initialize` from the parameter of the same
+      # name (`to_s`-coerced, frozen), so sig-gen proposes the raw parameter shape.
+      attr_reader receiver: String
+      # sig-gen gap: #1154 — `to_sym`-normalized from the `method:` parameter.
+      attr_reader method: Symbol
+      attr_reader singleton: bool
+      # sig-gen gap: #1154 — `Array()`-normalized, deduplicated and frozen from `labels:`.
+      attr_reader labels: Array[String]
+      # sig-gen gap: #1154 — `to_s`-normalized from the `narrow:` parameter.
+      attr_reader narrow: String?
+      attr_reader discharge: bool
+      # sig-gen gap: #1154 — `to_s`-normalized from the `within:` parameter.
+      attr_reader within: String?
+      attr_reader on_result: bool
+      # sig-gen gap: #1154 — `to_s`-normalized from the `taint:` parameter.
+      attr_reader taint: String?
+      # sig-gen gap: #1154 — `to_s`-normalized from the `callee:` parameter.
+      attr_reader callee: String?
+      # sig-gen gap: #1154 — normalized from the `callee_fallbacks:` parameter.
+      attr_reader callee_fallbacks: Hash[String, Array[String]]?
+      attr_reader responds: bool
+      # sig-gen gap: #1154 — `to_s`-normalized from the `why:` parameter.
+      attr_reader why: String
+
+      # The coercion-facing constructor: every parameter is `to_s`/`to_sym`/`Array()`-normalized,
+      # so `untyped` is the honest parameter type throughout.
+      def initialize: (receiver: untyped, method: untyped, labels: untyped, why: untyped,
+                       ?singleton: untyped, ?narrow: untyped, ?discharge: untyped,
+                       ?within: untyped, ?on_result: untyped, ?taint: untyped, ?callee: untyped,
+                       ?callee_fallbacks: untyped, ?responds: untyped) -> void
+
+      # Whether {#receiver} is a receiver path (`Rails.cache`) rather than a class name or a
+      # self path.
+      def receiver_path?: () -> bool
+      # Whether {#receiver} is a self path (`self.flash.now`).
+      def self_path?: () -> bool
+
+      # The key an origin and a report spell this row as.
+      def key: () -> String
+      def to_h: () -> Hash[String, untyped]
+
+      def ==: (untyped other) -> bool
+      # `alias eql? ==` — the alias row has no sig-gen shape, so it stays unmarked
+      # residue.
+      def eql?: (untyped other) -> bool
+      def hash: () -> Integer
+    end
+  end
+end

data/sig/rigor/plugin/effect_edge.rbs

@@ -0,0 +1,33 @@
+module Rigor
+  module Plugin
+    # One `effect_edges:` row: a framework-edge strategy naming the base `receiver` a plugin points
+    # the engine at, the `target` strategy slot, and an optional method-level `selector`. Frozen
+    # value object.
+    class EffectEdge
+      # The closed set of framework-edge strategies the engine implements.
+      TARGETS: Array[Symbol]
+
+      # sig-gen gap: #1154 — validated/normalized in `initialize` from the parameter of the same
+      # name, so sig-gen proposes the raw parameter shape.
+      attr_reader receiver: String
+      # sig-gen gap: #1154 — `to_sym`-normalized from the `method:` parameter.
+      attr_reader method: Symbol?
+      attr_reader singleton: bool
+      # sig-gen gap: #1154 — validated against `TARGETS` in `initialize`.
+      attr_reader target: (:activerecord_callbacks | :perform_now | :mailer_body)
+      # sig-gen gap: #1154 — `to_s`-normalized from the `why:` parameter.
+      attr_reader why: String
+
+      def initialize: (receiver: untyped, target: untyped, why: untyped, ?method: untyped,
+                       ?singleton: untyped) -> void
+
+      def to_h: () -> Hash[String, untyped]
+
+      def ==: (untyped other) -> bool
+      # `alias eql? ==` — the alias row has no sig-gen shape, so it stays unmarked
+      # residue.
+      def eql?: (untyped other) -> bool
+      def hash: () -> Integer
+    end
+  end
+end