rigortype 0.3.9 → 0.4.0

data/plugins/rigor-sorbet/lib/rigor/plugin/sorbet.rb

@@ -29,6 +29,14 @@ module Rigor
     # The {TypeTranslator} table documents coverage. Most of Sorbet's vocabulary translates; remaining
     # gaps (`T.proc`, `T::Struct` subclasses, `T.attached_class`, etc.) degrade silently to `Dynamic[top]`.
     #
+    # Issue #1097 — the plugin also ships `sig/sorbet.rbs`, a bundled declaration of the annotation DSL
+    # surface itself: `T`'s type-expression functions, the `T::X[...]` constructors, `T::Sig`'s `sig`
+    # verb (reached via the manifest `rbs_complete_extends:` bridge over `extend T::Sig`), the
+    # `DeclBuilder` the sig block `instance_eval`s on (via `block_as_methods:`), and the
+    # `T::Struct` / `T::Enum` family (via `rbs_complete_ancestors:`). The value-side assertions
+    # (`T.let`/`T.cast`/`T.must`/…) stay recogniser-owned — RBS cannot express "return the asserted
+    # type" — and `T`'s declared surface is intentionally partial behind `open_receivers:`.
+    #
     # Architecture: per-run `Catalog` is built lazily on first access by walking every configured `paths:`
     # entry's `.rb` files plus every `rbi_paths:` entry's `.rbi` files (slice 4) via the plugin's
     # `IoBoundary`. The catalog is frozen after the first build and consulted by the `dynamic_return` rule
@@ -70,7 +78,43 @@ module Rigor
           # effect of recursing into the parent root.
           "rbi_paths" => { kind: :array, default: ["sorbet/rbi"] },
           "enforce_sigil" => { kind: :boolean, default: true }
-        }
+        },
+        # #1097 — bundled sorbet-runtime DSL surface (`sig/sorbet.rbs`). `sig` itself reaches the
+        # class object through `extend T::Sig` (or the `< T::ImmutableStruct` / `< T::Enum`
+        # family, which carry the edge themselves), which is
+        # why `rbs_complete_extends:` — the extend-edge allow-list — carries `T::Sig` /
+        # `T::Helpers` / `T::Generic`, and `rbs_complete_ancestors:` carries the Struct/Enum family
+        # for the subclass bridge.
+        signature_paths: ["sig"],
+        rbs_complete_extends: %w[T::Sig T::Helpers T::Generic],
+        rbs_complete_ancestors: %w[T::Struct T::InexactStruct T::ImmutableStruct T::Enum],
+        # `sig { ... }` bodies are `instance_eval`'d on a `DeclBuilder`
+        # (`T::Private::Methods._run_builder`), so `params` / `returns` / `void` resolve on the
+        # builder, not the enclosing class. `T::Sig::WithoutRuntime.sig` is the direct-call twin —
+        # a singleton method on the module, matching by name equality.
+        block_as_methods: [
+          Rigor::Plugin::Macro::BlockAsMethod.new(
+            receiver_constraint: "T::Sig",
+            method_names: %i[sig],
+            self_type: "T::Private::Methods::DeclBuilder"
+          ),
+          Rigor::Plugin::Macro::BlockAsMethod.new(
+            receiver_constraint: "T::Sig::WithoutRuntime",
+            method_names: %i[sig],
+            self_type: "T::Private::Methods::DeclBuilder"
+          )
+        ],
+        # The declared surface is deliberately partial — `T` is an open module whose runtime
+        # surface is much larger than the DSL (version-dependent internals, `T::Private::*`,
+        # `T::Configuration`, `T::Utils`). Open receivers keep an unmodelled `T.something` opaque
+        # rather than a `call.undefined-method` false positive. `DeclBuilder` is NOT open —
+        # `sig { typo }` is a real bug and stays a diagnostic.
+        open_receivers: %w[T T::Sig T::Sig::WithoutRuntime T::Helpers T::Generic
+                           T::Utils T::Configuration T::Private T::Private::Methods
+                           T::Props T::Props::ClassMethods T::Props::CustomType
+                           T::Types T::Types::Base T::Array T::Hash T::Set
+                           T::Enumerable T::Enumerator T::Range T::Class
+                           T::InexactStruct T::Struct T::ImmutableStruct T::Enum]
       )
 
       def init(services)
@@ -441,6 +485,7 @@ module Rigor
       # Frozen empty bundle used when the `:catalog` producer failed (e.g. a project I/O error) so downstream
       # reads see a well-formed shape rather than nil.
       EMPTY_CATALOG_BUNDLE = { catalog: Catalog.new.freeze!, sigil_by_path: {}, parse_errors_by_path: {} }.freeze
+      Ractor.make_shareable(EMPTY_CATALOG_BUNDLE)
       private_constant :EMPTY_CATALOG_BUNDLE
 
       # @param root — directory or single file.

data/plugins/rigor-sorbet/sig/sorbet.rbs

@@ -0,0 +1,277 @@
+# Bundled RBS for the sorbet-runtime annotation DSL (issue #1097).
+#
+# sorbet-runtime ships RBI, not RBS, so none of the annotation surface (`T`, `T::Sig`, the
+# `DeclBuilder` behind `sig { ... }`, the `T::Array[...]` constructors, the `T::Helpers` /
+# `T::Generic` class macros) resolves for the analyzer. This file declares that surface so the
+# DSL *expressions themselves* type; the plugin's `AssertionRecognizer` continues to own the
+# value-sensitive calls (`T.let` / `T.cast` / `T.must` / `T.bind` / `T.assert_type!` /
+# `T.reveal_type` / `T.unsafe`) ahead of this RBS — the signatures here deliberately agree with
+# it (`T.unsafe` stays `untyped`, `T.bind` returns `nil`) for the cases the recognizer declines.
+#
+# Provenance (docs/agents/type-authoring.md): `rigor sig-gen` cannot produce this file — the DSL
+# methods are installed by `Module#extend` hooks and `instance_eval` in sorbet-runtime's source
+# (sorbet-runtime 0.5.11766, `lib/types/{sig,_types,generic,helpers,struct,enum}.rb` and
+# `lib/types/private/methods/decl_builder.rb`), so every entry was hand-derived by reading that
+# source. Members that do not exist at that version's runtime location are deliberately absent.
+#
+# Two Rigor-side mechanisms complete the picture (manifest fields):
+#
+# - `rbs_complete_extends:` — `extend T::Sig` in a class/module body is what puts `sig` on the
+#   class object's singleton; the dispatch bridge resolves those calls through the module's
+#   instance surface declared here.
+# - `block_as_methods:` — `sig`'s block is `instance_eval`'d on a `DeclBuilder`
+#   (`T::Private::Methods.declare_sig` → `DeclBuilder#instance_eval`), so `sig` bodies bind
+#   `self` to `T::Private::Methods::DeclBuilder`, NOT to the enclosing class.
+
+module T
+  # `T::Boolean` is a runtime constant (`T.any(TrueClass, FalseClass)` → a `T::Types::Union`
+  # instance), not a module — it appears in `params`/`returns` argument position as a const read.
+  Boolean: ::T::Types::Union
+
+  # The type-ASSERTION functions (`T.let`, `T.cast`, `T.assert_type!`, `T.bind`, `T.must`,
+  # `T.must_because`, `T.reveal_type`, `T.absurd`, `T.unsafe`) are deliberately NOT declared here.
+  # Their static return is the *asserted* type (the second argument, translated) or the nil-stripped
+  # inner type — semantics RBS cannot express — so the plugin's `AssertionRecognizer` /
+  # `AbsurdRecognizer` owns them ahead of dispatch, and a declined call degrades through `T`'s
+  # `open_receivers:` entry to opaque rather than a wrong `X` reading.
+
+  # Type-expression constructors — used in `params`/`returns` argument position.
+  def self.nilable: (untyped type) -> ::T::Types::Base
+  def self.untyped: () -> ::T::Types::Base
+  def self.noreturn: () -> ::T::Types::Base
+  def self.anything: () -> ::T::Types::Base
+  def self.all: (untyped type_a, untyped type_b, *untyped types) -> ::T::Types::Base
+  def self.any: (untyped type_a, untyped type_b, *untyped types) -> ::T::Types::Base
+  def self.class_of: (untyped arg) -> ::T::Types::Base
+  def self.self_type: () -> ::T::Types::Base
+  def self.attached_class: () -> ::T::Types::Base
+  def self.type_parameter: (::Symbol name) -> ::T::Types::TypeParameter
+  # `type=nil, &blk` — the positional form is a kept-for-migration legacy path (`_types.rb`);
+  # the block form wraps in `T::Private::Types::TypeAlias`.
+  def self.type_alias: (?untyped type) ?{ () -> untyped } -> ::T::Types::Base
+
+  # `T.proc` returns a DeclBuilder in `Modes.proc` (`T::Private::Methods.start_proc`), so the
+  # `T.proc.params(x: Integer).returns(String)` chain resolves through the same builder surface.
+  def self.proc: () -> ::T::Private::Methods::DeclBuilder
+end
+
+# `T::Sig` is a mixin a class EXTENDS (`extend T::Sig`) to gain the class-level `sig` verb —
+# sorbet-runtime does not patch `Module`. `sig` itself returns nil at runtime
+# (`declare_sig` stores the DeclarationBlock and returns nil).
+module T::Sig
+  def sig: (?untyped arg0) ?{ () -> untyped } -> nil
+
+  # `T::Sig::WithoutRuntime.sig { ... }` is a no-op shim for contexts where the runtime wrapper
+  # cannot be installed; it is called ON the module, so `sig` here is a module-singleton method.
+  # `extend T::Sig::WithoutRuntime` installs nothing at runtime, so no instance `sig` is declared.
+  module WithoutRuntime
+    def self.sig: (?untyped arg0) ?{ () -> untyped } -> nil
+  end
+end
+
+# The builder `sig`'s block is `instance_eval`'d on (`DeclBuilder#instance_eval(&blk)` via
+# `T::Private::Methods._run_builder`). Every DSL method returns `self` so the
+# `params(...).returns(...).checked(:always)` chain keeps typing.
+class T::Private::Methods::DeclBuilder
+  def params: (*untyped unused_positional_params, **untyped params) -> self
+  def returns: (untyped type) -> self
+  def void: () -> self
+  def bind: (untyped type) -> self
+  def checked: (untyped level) -> self
+  def on_failure: (*untyped args) -> self
+  def abstract: () -> self
+  def final: () -> self
+  def override: (?allow_incompatible: bool | Symbol) -> self
+  def overridable: () -> self
+  def type_parameters: (*untyped names) -> self
+end
+
+# The `T::X[...]` type constructors are modules with a singleton `[]` (`_types.rb`), returning the
+# corresponding `T::Types::TypedX` instance. The carriers below exist so the constructor's return
+# reads as a real nominal rather than `Dynamic[top]`.
+module T::Array
+  def self.[]: (untyped type) -> ::T::Types::TypedArray
+end
+
+module T::Hash
+  def self.[]: (untyped keys, untyped values) -> ::T::Types::TypedHash
+end
+
+module T::Set
+  def self.[]: (untyped type) -> ::T::Types::TypedSet
+end
+
+module T::Enumerable
+  def self.[]: (untyped type) -> ::T::Types::TypedEnumerable
+end
+
+module T::Enumerator
+  def self.[]: (untyped type) -> ::T::Types::TypedEnumerator
+end
+
+module T::Range
+  def self.[]: (untyped type) -> ::T::Types::TypedRange
+end
+
+module T::Class
+  def self.[]: (untyped type) -> ::T::Types::TypedClass
+end
+
+# Carrier classes for the `T::X[...]` constructors and the `T.*` type-expression functions. The
+# internal `T::Types::*` class names are the runtime classes (`types/types/*.rb`).
+module T::Types
+  class Base
+  end
+
+  class TypedArray < Base
+  end
+
+  class TypedHash < Base
+  end
+
+  class TypedSet < Base
+  end
+
+  class TypedEnumerable < Base
+  end
+
+  class TypedEnumerator < Base
+  end
+
+  class TypedRange < Base
+  end
+
+  class TypedClass < Base
+  end
+
+  class Union < Base
+  end
+
+  class Intersection < Base
+  end
+
+  class TypeParameter < Base
+  end
+
+  class TypeMember < Base
+  end
+
+  class TypeTemplate < Base
+  end
+
+  class Proc < Base
+  end
+end
+
+# `extend T::Helpers` installs the class/module declaration macros (`abstract!`, `interface!`,
+# `final!`, `sealed!`, `requires_ancestor`, `mixes_in_class_methods`). All return void-ish values
+# from `T::Private::{Abstract,Final,Sealed}` bookkeeping (`helpers.rb`).
+module T::Helpers
+  def abstract!: () -> void
+  def interface!: () -> void
+  def final!: () -> void
+  def sealed!: () -> void
+  def mixes_in_class_methods: (::Module mod, *::Module mods) -> void
+  def requires_ancestor: () { () -> untyped } -> void
+end
+
+# `extend T::Generic` installs the type-member macros — `Elem = type_member` is the common shape
+# (`generic.rb`). `[]` is the generic-application stub (`def [](*types); self; end`).
+module T::Generic
+  # `generic.rb` — `extend T::Generic` alone also installs the helper macros: the module
+  # `include`s `T::Helpers` (and `Kernel`), so its instance surface carries `abstract!` et al.
+  include T::Helpers
+
+  def []: (*untyped types) -> self
+  def type_member: (?untyped variance) ?{ () -> untyped } -> ::T::Types::TypeMember
+  def type_template: (?untyped variance) ?{ () -> untyped } -> ::T::Types::TypeTemplate
+  def has_attached_class!: (?untyped variance) ?{ () -> untyped } -> void
+end
+
+# `T::Props` is the property mixin; its `included` hook `extend`s the includer with
+# `ClassMethods` (`mixes_in_class_methods`), which is where `prop` / `const` live. The hook itself
+# is not modelled — `include T::Props` alone does not put `prop` on the class in this
+# declaration either — but the `T::Struct` family below declares the same `extend` edges directly,
+# matching the runtime outcome for `< T::Struct` subclasses.
+module T::Props
+  module ClassMethods
+    def prop: (::Symbol name, untyped cls, **untyped rules) -> void
+    def const: (::Symbol name, untyped cls_or_args, **untyped args) -> void
+    def props: () -> ::Hash[untyped, untyped]
+    def plugins: () -> ::Array[untyped]
+    def decorator: () -> ::T::Props::Decorator
+    def decorator_class: () -> ::Class
+    def validate_prop_value: (untyped prop, untyped val) -> void
+    def plugin: (untyped mod) -> void
+  end
+
+  class Decorator
+  end
+
+  module CustomType
+  end
+
+  module Serializable
+    # `serializable.rb` — lifted onto includers via `mixes_in_class_methods`.
+    module ClassMethods
+      def prop_by_serialized_forms: () -> ::Hash[untyped, untyped]
+      def from_hash: (untyped hash, ?bool strict) -> untyped
+      def from_hash!: (untyped hash) -> untyped
+    end
+  end
+
+  module Plugin
+    # `plugin.rb` — `mixes_in_class_methods(ClassMethods)`; `included` re-registers the plugin
+    # (`child.plugin(self)`), which is what extends `plugin::ClassMethods` onto the target.
+    module ClassMethods
+      def included: (untyped child) -> void
+    end
+  end
+end
+
+# The `T::Struct` family. `struct.rb` has `T::InexactStruct` `include T::Props` (+Serializable,
+# +Constructor); the `mixes_in_class_methods` hooks extend `T::Props::ClassMethods` (then the
+# registered `T::Props::Plugin::ClassMethods`) and `T::Props::Serializable::ClassMethods` onto the
+# class — verified against the runtime singleton ancestry. Neither `T::Sig` nor `T::Helpers` is
+# extended here: `sig` inside a `class Doc < T::Struct` body raises at runtime unless the subclass
+# adds `extend T::Sig` itself (dependabot's `TokenBucket` does exactly that). Only
+# `T::ImmutableStruct` extends `T::Sig` (`struct.rb` — it annotates its own `initialize`). The
+# edges are declared directly so subclasses resolve `prop` / `const` / `from_hash` through the
+# `rbs_complete_ancestors` superclass bridge.
+class T::InexactStruct
+  extend T::Props::ClassMethods
+  extend T::Props::Plugin::ClassMethods
+  extend T::Props::Serializable::ClassMethods
+end
+
+class T::Struct < T::InexactStruct
+end
+
+class T::ImmutableStruct < T::InexactStruct
+  extend T::Sig
+end
+
+# `T::Enum` — `enum.rb` `extend`s `T::Sig` and `T::Props::CustomType`; `enums` `yield`s its block
+# so `X = new` inside keeps the subclass's class-object self.
+class T::Enum
+  extend T::Sig
+  extend T::Props::CustomType
+
+  def self.enums: () { () -> untyped } -> void
+  def serialize: () -> ::String
+end
+
+# Namespace-only declarations so bare const reads (`T::Utils`, `T::Configuration`,
+# `T::Private::Methods`) type as `Singleton[...]` instead of `Dynamic[top]`. Their singleton
+# surface is intentionally NOT modelled — they are covered by `open_receivers:` so calls on them
+# degrade to opaque rather than firing `call.undefined-method` on an unmodelled private API.
+module T::Utils
+end
+
+module T::Configuration
+end
+
+module T::Private
+  module Methods
+  end
+end

data/sig/rigor/analysis/baseline.rbs

@@ -6,26 +6,88 @@ module Rigor
       class LoadError < ::StandardError
       end
 
+      # Tuple-shaped bucket key so rule-ID rows and message-pattern rows coexist: `message_regex` is
+      # `nil` for rule-ID rows and a `Regexp` for message-pattern rows; `rule` and `file` are always
+      # present (parse_row raises without them; the generator's group key carries both). `count`
+      # intentionally shadows `Struct#count` — PHPStan-compatible field name.
+      class Bucket < ::Struct[untyped]
+        # sig-gen gap: #1183 — Struct member types are not inferred from construction sites; every
+        # member row in this class (and the keyword ctor below) is hand-written.
+        def file: () -> String
+        # sig-gen gap: #1183 — as above.
+        def rule: () -> String
+        # sig-gen gap: #1183 — as above.
+        def message_regex: () -> Regexp?
+        # sig-gen gap: #1183 — as above.
+        def count: () -> Integer
+        # sig-gen gap: #1183 — as above.
+        def file=: (String) -> String
+        # sig-gen gap: #1183 — as above.
+        def rule=: (String) -> String
+        # sig-gen gap: #1183 — as above.
+        def message_regex=: (Regexp?) -> Regexp?
+        # sig-gen gap: #1183 — as above.
+        def count=: (Integer) -> Integer
+        # sig-gen gap: #1183 — as above.
+        def self.new: (?file: String, ?rule: String, ?message_regex: Regexp?, ?count: Integer) -> instance
+        # sig-gen gap: #1183 — as above.
+        def self.[]: (?file: String, ?rule: String, ?message_regex: Regexp?, ?count: Integer) -> instance
+      end
+
+      # One bucket's drift state for `audit`. `status` is the four-way verdict `status_for` returns;
+      # `delta` is `actual_count - bucket.count` (positive = over threshold).
+      class DriftRow < ::Struct[untyped]
+        # sig-gen gap: #1183 — Struct member types are not inferred from construction sites; as above.
+        def bucket: () -> Bucket
+        # sig-gen gap: #1183 — as above.
+        def actual_count: () -> Integer
+        # sig-gen gap: #1183 — as above.
+        def status: () -> (:within | :over | :cleared | :reducible)
+        def delta: () -> Integer
+        # sig-gen gap: #1183 — as above.
+        def bucket=: (Bucket) -> Bucket
+        # sig-gen gap: #1183 — as above.
+        def actual_count=: (Integer) -> Integer
+        # sig-gen gap: #1183 — as above.
+        def status=: (:within | :over | :cleared | :reducible) -> (:within | :over | :cleared | :reducible)
+        # sig-gen gap: #1183 — as above.
+        def self.new: (?bucket: Bucket, ?actual_count: Integer, ?status: :within | :over | :cleared | :reducible) -> instance
+        # sig-gen gap: #1183 — as above.
+        def self.[]: (?bucket: Bucket, ?actual_count: Integer, ?status: :within | :over | :cleared | :reducible) -> instance
+      end
+
       # Load a baseline file from disk.
       # Returns `nil` when `path` is nil (no baseline configured).
       # Raises {LoadError} on malformed or unsupported content.
       def self.load: (::String? path, ?project_root: ::String) -> Baseline?
 
       # Build a baseline from a current run's diagnostic stream.
-      def self.from_diagnostics: (untyped diagnostics, ?match_mode: :rule | :message) -> Baseline
+      def self.from_diagnostics: (untyped diagnostics, ?match_mode: :rule | :message, ?project_root: ::String | ::Pathname) -> Baseline
 
-      attr_reader buckets: untyped
+      # Always an Array of Bucket — `initialize` freezes what it is given and every caller hands it
+      # Bucket instances (parse_row rows, from_diagnostics groups, `without`'s reject, or `[]`).
+      # sig-gen gap: #1154 — an `attr_reader` over an ivar assigned in `initialize` from a parameter
+      # is skipped (untyped return); the element type is hand-written.
+      attr_reader buckets: Array[Bucket]
 
-      def initialize: (untyped buckets) -> void
+      # `project_root` is `Pathname.new`'d, so a `Pathname` is accepted as well as a `String`
+      # (`without` re-passes the stored Pathname).
+      def initialize: (Array[Bucket] buckets, ?project_root: ::String | ::Pathname) -> void
 
       # Apply the baseline filter. Returns [surfaced_diagnostics, silenced_count].
-      def filter: (untyped diagnostics) -> [untyped, ::Integer]
+      # `diagnostics` stays `untyped`: `Analysis::Diagnostic`'s sig is partial (no `qualified_rule`),
+      # so a tighter param would put `diag.qualified_rule` behind an unsigned member. The declared
+      # `[Array[untyped], Integer]` diverges from sig-gen's inference
+      # (`[Array[untyped], untyped] | [untyped, 0]` — the literal seed and the accumulated local are
+      # unproven); the `Integer` count is the author's intent.
+      def filter: (untyped diagnostics) -> [Array[untyped], ::Integer]
 
-      # Report bucket-level drift for each recorded baseline bucket.
-      def audit: (untyped diagnostics) -> untyped
+      # Report bucket-level drift for each recorded baseline bucket — one DriftRow per bucket, in
+      # baseline-file order.
+      def audit: (untyped diagnostics) -> Array[DriftRow]
 
       # Return a new Baseline with the given buckets removed.
-      def without: (untyped buckets_to_drop) -> Baseline
+      def without: (Array[Bucket] buckets_to_drop) -> Baseline
 
       # Serialise to a YAML string.
       def to_yaml: () -> ::String

data/sig/rigor/analysis/fact_store.rbs

@@ -2,7 +2,7 @@ module Rigor
   module Analysis
     module CheckRules
       def self?.diagnose: (path: String, root: untyped, scope_index: Hash[untyped, Scope]) -> Array[Diagnostic]
-      def self?.build_node_collectors: (String path, untyped scope_index) -> Hash[Symbol, untyped]
+      def self?.build_node_collectors: (String path, untyped scope_index, ?untyped root) -> Hash[Symbol, untyped]
       def self?.node_collector_driver: (Hash[Symbol, untyped] collectors) -> untyped
       def self?.shadow_verify_converged_collectors: (String path, untyped root, untyped scope_index, Hash[Symbol, untyped]? collectors) -> void
       def self?.filter_suppressed: (Array[Diagnostic] diagnostics, comments: untyped, disabled_rules: Array[String]) -> Array[Diagnostic]

data/sig/rigor/analysis/project_scan.rbs

@@ -0,0 +1,74 @@
+module Rigor
+  module Analysis
+    # Frozen snapshot of the project-wide pre-pass state the runner consumes — see
+    # lib/rigor/analysis/project_scan.rb for the full ownership/invalidation contract.
+    class ProjectScan < ::Data
+      # sig-gen gap: #1150 — `Data.define` member reads carry no type; `build_project_scan` fills
+      # this slot with the prepared `Plugin::Loader` result.
+      def plugin_registry: () -> Rigor::Plugin::Registry
+
+      # sig-gen gap: #1150 — as above (`DependencySourceInference::Builder.build` output, or
+      # `Index::EMPTY` when no dependencies are configured).
+      def dependency_source_index: () -> DependencySourceInference::Index
+
+      # `Inference::SyntheticMethodIndex` — the class is not yet declared under `sig/` (#1181
+      # backlog), so `untyped` is the honest member type for now.
+      def synthetic_method_index: () -> untyped
+
+      # `Inference::ProjectPatchedMethods` — unsigned like the slot above.
+      def project_patched_methods: () -> untyped
+
+      # sig-gen gap: #1150 — as above (`plugin_prepare_diagnostics` collects the
+      # `plugin_prepare_error_diagnostic` `Diagnostic`s, `[]` under pool mode).
+      def plugin_prepare_diagnostics: () -> Array[Analysis::Diagnostic]
+
+      # sig-gen gap: #1150 — as above. The pre-eval scanner deliberately emits a Hash shape (it
+      # must not depend on the analysis layer); the runner translates each row to a `Diagnostic`
+      # at the call site.
+      def pre_eval_diagnostics: () -> Array[{ path: String, line: Integer, column: Integer, severity: Symbol, rule: String, message: String }]
+
+      # `Analysis::TemplateUnits` — unsigned (#1181 backlog), kept `untyped`.
+      def template_units: () -> untyped
+
+      # sig-gen gap: #1150 — as above; constructor keywords mirror the member declarations.
+      def self.new: (
+        plugin_registry: Rigor::Plugin::Registry,
+        dependency_source_index: DependencySourceInference::Index,
+        synthetic_method_index: untyped,
+        project_patched_methods: untyped,
+        plugin_prepare_diagnostics: Array[Analysis::Diagnostic],
+        pre_eval_diagnostics: Array[{ path: String, line: Integer, column: Integer, severity: Symbol, rule: String, message: String }],
+        template_units: untyped
+      ) -> instance
+      | (
+        Rigor::Plugin::Registry plugin_registry,
+        DependencySourceInference::Index dependency_source_index,
+        untyped synthetic_method_index,
+        untyped project_patched_methods,
+        Array[Analysis::Diagnostic] plugin_prepare_diagnostics,
+        Array[{ path: String, line: Integer, column: Integer, severity: Symbol, rule: String, message: String }] pre_eval_diagnostics,
+        untyped template_units
+      ) -> instance
+
+      # sig-gen gap: #1150 — as above.
+      def self.[]: (
+        plugin_registry: Rigor::Plugin::Registry,
+        dependency_source_index: DependencySourceInference::Index,
+        synthetic_method_index: untyped,
+        project_patched_methods: untyped,
+        plugin_prepare_diagnostics: Array[Analysis::Diagnostic],
+        pre_eval_diagnostics: Array[{ path: String, line: Integer, column: Integer, severity: Symbol, rule: String, message: String }],
+        template_units: untyped
+      ) -> instance
+      | (
+        Rigor::Plugin::Registry plugin_registry,
+        DependencySourceInference::Index dependency_source_index,
+        untyped synthetic_method_index,
+        untyped project_patched_methods,
+        Array[Analysis::Diagnostic] plugin_prepare_diagnostics,
+        Array[{ path: String, line: Integer, column: Integer, severity: Symbol, rule: String, message: String }] pre_eval_diagnostics,
+        untyped template_units
+      ) -> instance
+    end
+  end
+end

data/sig/rigor/effects/config_envelopes.rbs

@@ -0,0 +1,100 @@
+module Rigor
+  module Effects
+    # `effects.envelopes:` entries resolved against the label vocabulary — the configured stratum of
+    # the envelope precedence (ADR-103 WD1).
+    module ConfigEnvelopes
+      CONFIG_PATH: String
+
+      # One entry, resolved against the vocabulary. `bound` is `LabelSet::TOP` when some member of
+      # `effect:` is unrecognised — the fail-open rule.
+      class Entry < ::Data
+        # sig-gen gap: #1150 — `Data.define` member reads carry no type; `build` proves each of these.
+        def index: () -> Integer
+
+        # sig-gen gap: #1150 — as above (path glob, or nil when `namespace:` is set).
+        def match: () -> String?
+
+        # sig-gen gap: #1150 — as above (constant-path glob, or nil when `match:` is set).
+        def namespace: () -> String?
+
+        # sig-gen gap: #1150 — as above (`LabelSet::TOP` on an unrecognised label).
+        def bound: () -> LabelSet
+
+        # sig-gen gap: #1150 — as above (the `effect:` list exactly as written).
+        def labels: () -> Array[String]
+
+        # sig-gen gap: #1150 — as above (well-formed spellings the registry did not know).
+        def unknown_labels: () -> Array[String]
+
+        # sig-gen gap: #1150 — as above; keyword form mirrors the member declarations.
+        def self.new: (
+          index: Integer,
+          match: String?,
+          namespace: String?,
+          bound: LabelSet,
+          labels: Array[String],
+          unknown_labels: Array[String]
+        ) -> instance
+        | (
+          Integer index,
+          String? match,
+          String? namespace,
+          LabelSet bound,
+          Array[String] labels,
+          Array[String] unknown_labels
+        ) -> instance
+
+        # sig-gen gap: #1150 — as above.
+        def self.[]: (
+          index: Integer,
+          match: String?,
+          namespace: String?,
+          bound: LabelSet,
+          labels: Array[String],
+          unknown_labels: Array[String]
+        ) -> instance
+        | (
+          Integer index,
+          String? match,
+          String? namespace,
+          LabelSet bound,
+          Array[String] labels,
+          Array[String] unknown_labels
+        ) -> instance
+
+        # `.rigor.yml effects.envelopes[N]` — the location spelling diagnostics name.
+        def location: () -> String
+
+        # The bound quoted back in the config's own spelling.
+        def spelling: () -> String
+
+        def top?: () -> bool
+      end
+
+      # `entries` are the shape-validated `Configuration#effects_envelopes` rows (String-keyed
+      # Hashes); `registry` is the `Effects::Registry` vocabulary — unsigned, so `untyped`.
+      def self?.build: (entries: Array[Hash[String, untyped]], registry: untyped) -> Array[Entry]
+
+      # One envelope per selected class, keyed by class name. `sources` is `Runner#effect_sources`'s
+      # shape; `project_root` is what those paths are relativised against.
+      def self?.for_classes: (
+        entries: Array[Entry],
+        class_names: Array[String],
+        ?sources: Hash[String, Array[String]],
+        ?project_root: String
+      ) -> Hash[String, Envelope]
+
+      # The {Envelope} one entry puts on one class.
+      def self?.envelope_for: (Entry entry, String class_name) -> Envelope
+
+      # Whether one entry selects a class — `paths` is `Array()`d, so `untyped` is honest.
+      def self?.selects?: (Entry entry, String class_name, untyped paths) -> bool
+
+      # `File.fnmatch?` with `FNM_PATHNAME` — the ADR-28 path-glob shape.
+      def self?.path_match?: (String glob, String path) -> bool
+
+      # Constant-path glob over the `::`-separated FQN; both arguments are `to_s`d.
+      def self?.namespace_match?: (untyped glob, untyped class_name) -> bool
+    end
+  end
+end