rigortype 0.1.19 → 0.2.0

data/lib/rigor/type/plain_lattice.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "../trinary"
+
+module Rigor
+  module Type
+    # Supplies the lattice-membership trio for the "plain" carriers — the
+    # concrete value types that are neither a lattice extreme (`Top` /
+    # `Bot` / `Dynamic`) nor a wrapper that computes membership from an
+    # inner type.
+    #
+    # Every such carrier answers `top` / `bot` / `dynamic` with the same
+    # `Trinary.no` ("this value is not that lattice point"), so the trio
+    # lived as a byte-identical copy in a dozen carriers. The extremes
+    # override the relevant member (`Top#top` / `Bot#bot` /
+    # `Dynamic#dynamic` answer `Trinary.yes`) and the delegators (`App`,
+    # `Difference`, `Refined`, `Union`) compute `dynamic` from their inner
+    # type(s); none of those include this module.
+    #
+    # Mirrors the existing {AcceptanceRouter} / `ValueSemantics` mixins —
+    # narrow trait sharing, never carrier inheritance (which the type-object
+    # contract forbids).
+    module PlainLattice
+      def top
+        Trinary.no
+      end
+
+      def bot
+        Trinary.no
+      end
+
+      def dynamic
+        Trinary.no
+      end
+    end
+  end
+end

data/lib/rigor/type/refined.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "prism"
+
 require_relative "../trinary"
 require_relative "../value_semantics"
 require_relative "acceptance_router"
@@ -104,18 +106,31 @@ module Rigor
       # so callers can pass any `Constant#value` without a
       # type-prefilter.
       #
-      # Plugin-contributed predicates land here once ADR-2 is
-      # in flight; today the table is closed over the v0.0.4
-      # built-in catalogue.
+      # Plugin-contributed predicates are not yet wired; today
+      # the table covers the built-in catalogue.
       #
       # Recogniser policy:
       #
-      # - `:numeric` is deliberately conservative — only decimal
-      #   integer and plain-decimal-fraction strings are
-      #   recognised, mirroring `imported-built-in-types.md`'s
-      #   "Rigor's numeric-string predicate" wording. Looser
-      #   forms (scientific, hex, rational) MAY join later
-      #   without breaking the registry contract.
+      # - `:numeric` recognises a string that is a *single Ruby
+      #   numeric literal* — exactly the syntax that, written in
+      #   Ruby source, evaluates to an `Integer` / `Float` /
+      #   `Rational` / `Complex`. The recogniser delegates to the
+      #   real Ruby parser ({Refined.ruby_numeric_literal?} via
+      #   Prism), so it tracks Ruby's grammar precisely: decimal /
+      #   `0x` hex / `0o` (or leading-zero) octal / `0b` binary /
+      #   `0d` decimal integers, underscore digit separators
+      #   (`1_000`), decimal fractions and scientific floats
+      #   (`1.5`, `1E-5`), and the `r` rational / `i` imaginary
+      #   suffixes (`1r`, `2i`, `0xffr`). A single leading sign is
+      #   folded into the literal (`-1`, `+1.5`), but a doubled
+      #   sign (`--1`, `++1`) parses as a unary-operator chain — a
+      #   `CallNode`, not a literal — and is rejected, as are
+      #   multi-dot junk (`1.2.3`), partial literals (`0x`, `1_`),
+      #   whitespace-padded strings, and — crucially — non-ASCII
+      #   "digits" (full-width `１`, superscript `²`, other Unicode
+      #   number characters): Ruby's lexer only accepts `[0-9]` in
+      #   a numeric literal, so those are `CallNode`s too. The
+      #   stricter base-N predicates below remain proper subsets.
       # - `:decimal_int` is "what `Integer(s, 10)` would parse
       #   without remainder" — one or more decimal digits,
       #   optional leading sign, no whitespace, no fractional
@@ -127,20 +142,64 @@ module Rigor
       #   not octal-int-string. This matches the typical user
       #   intent — a refinement marks a string that "looks like
       #   octal", not "happens to be base-8 valid".
-      NUMERIC_STRING_PATTERN = /\A-?\d+(?:\.\d+)?\z/
       DECIMAL_INT_STRING_PATTERN = /\A-?\d+\z/
       OCTAL_INT_STRING_PATTERN = /\A-?(?:0[oO][0-7]+|0[0-7]+)\z/
       HEX_INT_STRING_PATTERN = /\A-?0[xX][0-9a-fA-F]+\z/
-      private_constant :NUMERIC_STRING_PATTERN, :DECIMAL_INT_STRING_PATTERN,
+      private_constant :DECIMAL_INT_STRING_PATTERN,
                        :OCTAL_INT_STRING_PATTERN, :HEX_INT_STRING_PATTERN
 
+      # Prism node classes that represent a numeric literal. A
+      # string is a numeric-string exactly when the parser reduces
+      # the whole input to a single one of these (the leading sign
+      # is already folded into the literal by the parser).
+      NUMERIC_LITERAL_NODES = [
+        Prism::IntegerNode,
+        Prism::FloatNode,
+        Prism::RationalNode,
+        Prism::ImaginaryNode
+      ].freeze
+      private_constant :NUMERIC_LITERAL_NODES
+
+      # Cheap pre-filter applied before invoking the parser: every
+      # Ruby numeric literal starts with an ASCII digit, optionally
+      # preceded by exactly one sign. Strings that fail this never
+      # reach Prism (the common non-numeric case stays allocation-
+      # and parse-free).
+      NUMERIC_LITERAL_PREFIX = /\A[+-]?\d/
+      private_constant :NUMERIC_LITERAL_PREFIX
+
+      # @param value [Object] typically a `Constant#value`
+      # @return [Boolean] true when `value` is a String that is a
+      #   single, complete Ruby numeric literal. Total over
+      #   arbitrary input — never raises (Prism reports malformed
+      #   input through `errors`, it does not throw).
+      def self.ruby_numeric_literal?(value)
+        return false unless value.is_a?(String)
+        return false if value.empty?
+        # A numeric literal carries no whitespace; reject any
+        # leading / trailing / interior space so the *whole* string
+        # must be the literal (Prism would otherwise accept a
+        # trailing-space `"1 "`).
+        return false if value.match?(/\s/)
+        return false unless value.match?(NUMERIC_LITERAL_PREFIX)
+
+        result = Prism.parse(value)
+        return false unless result.errors.empty?
+
+        body = result.value.statements&.body
+        return false unless body && body.size == 1
+
+        node = body.first
+        NUMERIC_LITERAL_NODES.any? { |klass| node.is_a?(klass) }
+      end
+
       PREDICATES = {
         lowercase: ->(v) { v.is_a?(String) && v == v.downcase },
         not_lowercase: ->(v) { v.is_a?(String) && v != v.downcase },
         uppercase: ->(v) { v.is_a?(String) && v == v.upcase },
         not_uppercase: ->(v) { v.is_a?(String) && v != v.upcase },
-        numeric: ->(v) { v.is_a?(String) && NUMERIC_STRING_PATTERN.match?(v) },
-        not_numeric: ->(v) { v.is_a?(String) && !NUMERIC_STRING_PATTERN.match?(v) },
+        numeric: ->(v) { ruby_numeric_literal?(v) },
+        not_numeric: ->(v) { v.is_a?(String) && !ruby_numeric_literal?(v) },
         decimal_int: ->(v) { v.is_a?(String) && DECIMAL_INT_STRING_PATTERN.match?(v) },
         octal_int: ->(v) { v.is_a?(String) && OCTAL_INT_STRING_PATTERN.match?(v) },
         hex_int: ->(v) { v.is_a?(String) && HEX_INT_STRING_PATTERN.match?(v) },

data/lib/rigor/type/singleton.rb

@@ -3,6 +3,7 @@
 require_relative "../trinary"
 require_relative "../value_semantics"
 require_relative "acceptance_router"
+require_relative "plain_lattice"
 
 module Rigor
   module Type
@@ -34,17 +35,7 @@ module Rigor
         "singleton(#{class_name})"
       end
 
-      def top
-        Trinary.no
-      end
-
-      def bot
-        Trinary.no
-      end
-
-      def dynamic
-        Trinary.no
-      end
+      include Rigor::Type::PlainLattice
 
       include Rigor::Type::AcceptanceRouter
 

data/lib/rigor/type/struct_class.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require_relative "../trinary"
+require_relative "../value_semantics"
+require_relative "acceptance_router"
+require_relative "plain_lattice"
+
+module Rigor
+  module Type
+    # The class object produced by `Struct.new(:x, :y)` (ADR-48 Struct
+    # follow-up). The mutable sibling of {DataClass}: it models the *class*
+    # (the value bound to `Point` in `Point = Struct.new(:x, :y)`, or the
+    # anonymous superclass in `class Point < Struct.new(:x, :y)`), carrying
+    # the ordered member-name list so `Point.new(...)` can materialise a
+    # {StructInstance}.
+    #
+    # `keyword_init` records the `Struct.new(..., keyword_init: true)` flag
+    # so `.new` only materialises a precise instance for the matching call
+    # form — a positional `.new(1, 2)` on a `keyword_init: true` struct, or
+    # a keyword `.new(x: 1)` on a positional struct, is a different runtime
+    # shape and must degrade rather than fold a wrong member map.
+    #
+    # `class_name` carries the binding name when known (the named-subclass
+    # form) and is `nil` for the anonymous result of a bare `Struct.new(...)`
+    # before it is assigned to a constant.
+    #
+    # Equality and hashing are structural over the member list, the class
+    # name, and the keyword-init flag.
+    #
+    # See docs/adr/48-data-struct-value-folding.md § "Struct follow-up".
+    class StructClass
+      attr_reader :members, :class_name, :keyword_init
+
+      # @param members [Array<Symbol>] ordered member names.
+      # @param class_name [String, nil] the bound class name, or nil for
+      #   the anonymous `Struct.new(...)` result.
+      # @param keyword_init [Boolean] the `keyword_init:` flag.
+      def initialize(members, class_name = nil, keyword_init: false)
+        unless members.is_a?(Array) && members.all?(Symbol)
+          raise ArgumentError, "members must be an Array of Symbols, got #{members.inspect}"
+        end
+        unless class_name.nil? || (class_name.is_a?(String) && !class_name.empty?)
+          raise ArgumentError, "class_name must be a non-empty String or nil, got #{class_name.inspect}"
+        end
+
+        @members = members.dup.freeze
+        @class_name = class_name&.freeze
+        @keyword_init = keyword_init ? true : false
+        freeze
+      end
+
+      def describe(_verbosity = :short)
+        return "singleton(#{class_name})" if class_name
+
+        "Struct.new(#{members.map(&:inspect).join(', ')})"
+      end
+
+      def erase_to_rbs
+        "singleton(#{class_name || 'Struct'})"
+      end
+
+      include Rigor::Type::PlainLattice
+
+      include Rigor::Type::AcceptanceRouter
+
+      include Rigor::ValueSemantics
+
+      value_fields :members, :class_name, :keyword_init
+
+      def inspect
+        "#<Rigor::Type::StructClass #{describe(:short)}>"
+      end
+    end
+  end
+end

data/lib/rigor/type/struct_instance.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require_relative "../trinary"
+require_relative "../value_semantics"
+require_relative "acceptance_router"
+require_relative "plain_lattice"
+
+module Rigor
+  module Type
+    # A `Struct.new` value instance (ADR-48 Struct follow-up) —
+    # `Point.new(1, 2)`. The mutable sibling of {DataInstance}: a closed,
+    # total, class-tagged member map (member name -> value type),
+    # HashShape-shaped but nominal.
+    #
+    # Unlike {DataInstance}, a `Struct` instance is **mutable** — `s.x = v`,
+    # `s[:x] = v`, and escape can invalidate the member map. The folding
+    # tier therefore only projects member reads off a **fresh** instance
+    # (the transient receiver of a `.new(...).x` / `.with(...).x` chain,
+    # which provably cannot have been mutated between materialisation and
+    # the read); a read off a *stored* binding degrades to `Dynamic[top]`
+    # rather than fold a possibly-stale member value. Promoting the
+    # fold to mutation-free bound locals is the deferred slice 3 (see ADR).
+    #
+    # That mutability-gating lives in the dispatch tier (`StructFolding`),
+    # not the carrier: the carrier itself just records the member map. Like
+    # {DataInstance}, non-folded methods project to the `Struct` nominal (or
+    # the tagged class) through {RbsDispatch}'s `receiver_descriptor`, so
+    # non-member calls resolve without mis-firing undefined-method.
+    #
+    # Equality and hashing are structural over the (member -> type) map and
+    # the class name.
+    #
+    # See docs/adr/48-data-struct-value-folding.md § "Struct follow-up".
+    class StructInstance
+      attr_reader :members, :class_name
+
+      # @param members [Hash{Symbol => Rigor::Type}] ordered member -> type
+      #   map. Every declared member is present (Struct instances are total).
+      # @param class_name [String, nil] the tagging class name, or nil for
+      #   an instance of an anonymous `Struct.new(...)` class.
+      def initialize(members, class_name = nil)
+        unless members.is_a?(Hash) && members.each_key.all?(Symbol)
+          raise ArgumentError, "members must be a Hash with Symbol keys, got #{members.inspect}"
+        end
+        unless class_name.nil? || (class_name.is_a?(String) && !class_name.empty?)
+          raise ArgumentError, "class_name must be a non-empty String or nil, got #{class_name.inspect}"
+        end
+
+        @members = members.dup.freeze
+        @class_name = class_name&.freeze
+        freeze
+      end
+
+      # @return [Array<Symbol>] ordered member names.
+      def member_names
+        members.keys
+      end
+
+      # @return [Rigor::Type, nil] the member's value type, or nil when the
+      #   name is not a declared member.
+      def member_type(name)
+        members[name]
+      end
+
+      def describe(verbosity = :short)
+        rendered = members.map { |name, type| "#{name}: #{type.describe(verbosity)}" }
+        "#{class_name || 'Struct'}(#{rendered.join(', ')})"
+      end
+
+      # Erases to the tagging class nominal (conservative: the structural
+      # members are not RBS-expressible as a class instance). The
+      # anonymous case erases to the `Struct` supertype.
+      def erase_to_rbs
+        name = class_name
+        return "Struct" if name.nil?
+
+        name
+      end
+
+      include Rigor::Type::PlainLattice
+
+      include Rigor::Type::AcceptanceRouter
+
+      include Rigor::ValueSemantics
+
+      value_fields :members, :class_name
+
+      def inspect
+        "#<Rigor::Type::StructInstance #{describe(:short)}>"
+      end
+    end
+  end
+end

data/lib/rigor/type/tuple.rb

@@ -3,6 +3,7 @@
 require_relative "../trinary"
 require_relative "../value_semantics"
 require_relative "acceptance_router"
+require_relative "plain_lattice"
 
 module Rigor
   module Type
@@ -17,10 +18,9 @@ module Rigor
     #
     # Slice 5 phase 1 introduces the carrier and surfaces it from the
     # `ArrayNode` literal handler when every element is a non-splat
-    # value. Tuple-aware refinements for `tuple[0]`, `tuple.first`, and
-    # destructuring assignment are deferred to Slice 5 phase 2; they
-    # will run as a higher-priority dispatch tier above
-    # {Rigor::Inference::MethodDispatcher::RbsDispatch}.
+    # value. Tuple-aware refinements (`tuple[0]`, `tuple.first`,
+    # destructuring) are implemented in `ShapeDispatch`, which runs
+    # above {Rigor::Inference::MethodDispatcher::RbsDispatch}.
     #
     # Equality and hashing are structural across an ordered, frozen
     # element list. The empty Tuple `Tuple[]` is permitted; the array
@@ -53,17 +53,7 @@ module Rigor
         "[#{elements.map(&:erase_to_rbs).join(', ')}]"
       end
 
-      def top
-        Trinary.no
-      end
-
-      def bot
-        Trinary.no
-      end
-
-      def dynamic
-        Trinary.no
-      end
+      include Rigor::Type::PlainLattice
 
       include Rigor::Type::AcceptanceRouter
 

data/lib/rigor/type.rb

@@ -21,6 +21,8 @@ require_relative "type/tuple"
 require_relative "type/hash_shape"
 require_relative "type/data_class"
 require_relative "type/data_instance"
+require_relative "type/struct_class"
+require_relative "type/struct_instance"
 require_relative "type/union"
 require_relative "type/difference"
 require_relative "type/refined"

data/lib/rigor/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Rigor
-  VERSION = "0.1.19"
+  VERSION = "0.2.0"
 end

data/plugins/rigor-actioncable/lib/rigor/plugin/actioncable/channel_discoverer.rb

@@ -26,7 +26,7 @@ module Rigor
       #   `stream_for` call) so the analyzer knows it can't
       #   be sure of every stream name.
       #
-      # Limitations (intentional for v0.1.0):
+      # Intentional limitations:
       #
       # - Direct-superclass match only.
       # - Public-vs-private is not tracked; the framework

data/plugins/rigor-actioncable/lib/rigor/plugin/actioncable/channel_index.rb

@@ -69,9 +69,9 @@ module Rigor
         # True when at least one discovered channel uses a
         # dynamic stream registration. The analyzer treats
         # this as "we can't be sure any literal name is
-        # missing" and downgrades unknown-stream from
-        # `:warning` to `:info` (or drops it entirely;
-        # current behaviour: skip warnings).
+        # missing" and skips the `unknown-stream` warning
+        # entirely — absence of a literal match doesn't prove
+        # the name is wrong.
         def any_dynamic_streams?
           @entries.any?(&:dynamic_streams)
         end

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

@@ -41,7 +41,7 @@ module Rigor
     #    `stream_for record`) — the absence of a literal
     #    match doesn't prove absence.
     #
-    # ## Limitations (v0.1.0)
+    # ## Limitations
     #
     # - **Direct-superclass match only.** Indirect
     #   inheritance (`AdminChannel < BaseChannel <
@@ -51,8 +51,8 @@ module Rigor
     #   ActionCable actions are invoked from JS via
     #   `subscription.perform("action_name", data)`; we
     #   don't analyse JS so the action-method index is
-    #   currently informational only (future cross-plugin
-    #   handoff to a hypothetical JS-side analyzer).
+    #   informational only (deferred: cross-plugin handoff
+    #   to a JS-side analyzer).
     # - **`broadcast_to` arity isn't checked.** The method
     #   takes any record + any data hash; there's no
     #   useful arity envelope.

data/plugins/rigor-actionmailer/lib/rigor/plugin/actionmailer/mailer_discoverer.rb

@@ -301,19 +301,11 @@ module Rigor
             [entry.method_name, entry]
           end
 
-          # Merge in actions from include'd modules. The
-          # discoverer pre-collected every module's defs as
-          # `module_actions` keyed by fully-qualified module
-          # name. We resolve each include against that map —
-          # tries the full include name first, then walks down
-          # the class's lexical chain looking for a nested
-          # match (e.g. `Emails::Issues` inside `class Notify`
-          # at top-level resolves to top-level `Emails::Issues`).
-          # Includes we cannot resolve are silently skipped;
-          # the per-mailer `unresolved_includes?` predicate
-          # below (consumed by the analyzer) downgrades
-          # `unknown-action` to silence when any include is
-          # unresolved.
+          # Merge actions from include'd modules (pre-collected
+          # in `module_actions` keyed by fully-qualified name).
+          # Unresolvable includes are tracked; `unresolved_includes?`
+          # (consumed by the analyzer) downgrades `unknown-action`
+          # to silence when any include remains unresolved.
           unresolved_includes = []
           includes.each do |include_name|
             inc_actions = module_actions[include_name]

data/plugins/rigor-actionpack/lib/rigor/plugin/actionpack/analyzer.rb

@@ -33,9 +33,8 @@ module Rigor
         # Phase 2 — filter-chain DSL methods. Each takes a
         # variadic list of filter names (Symbols / Strings) plus
         # optional `only:` / `except:` / `if:` / `unless:`
-        # modifiers. The validation key is the filter NAMES; the
-        # modifiers are accepted but their action-name argument
-        # is not yet validated (Phase 2.5).
+        # modifiers. Only the filter NAMES are validated; the
+        # `only:`/`except:` action-name arguments are not (deferred).
         FILTER_DSL_METHODS = %i[
           before_action after_action around_action
           skip_before_action skip_after_action skip_around_action
@@ -43,18 +42,14 @@ module Rigor
         ].freeze
 
         # Phase 3 — render-target template extensions checked in
-        # priority order. The first six cover the templating
-        # engines used by the projects this plugin is regularly
-        # exercised against: ERB (Rails default — `.html.erb`,
-        # `.text.erb`), HAML (Mastodon, Solidus admin —
-        # `.html.haml`), Slim, and JSON (`.json.jbuilder` plus a
-        # raw `.json.erb` for hand-rolled API responses). When a
-        # template exists under any of these extensions, the
-        # missing-template diagnostic stays silent.
-        # Configurable extension list is queued — see the
-        # `external-author plugin SKILL` track (v0.2.0). For now
-        # this set is wide enough to cover the surveyed real-world
-        # projects without leaking FPs.
+        # priority order. Covers the engines used by surveyed
+        # projects: ERB (Rails default — `.html.erb`, `.text.erb`),
+        # HAML (Mastodon, Solidus admin — `.html.haml`), Slim, and
+        # JSON (`.json.jbuilder` plus `.json.erb` for hand-rolled API
+        # responses). When a template exists under any of these
+        # extensions, the missing-template diagnostic stays silent.
+        # A configurable extension list is deferred; this set is wide
+        # enough to cover surveyed real-world projects without FPs.
         RENDER_TEMPLATE_EXTENSIONS = %w[
           .html.erb
           .text.erb
@@ -167,8 +162,7 @@ module Rigor
         # list (looked up via the model_index fact published by
         # `rigor-activerecord`). Calls whose `:require` argument is a
         # non-literal Symbol are passed through; namespaced models
-        # (`params.require(:admin_user)` → `Admin::User`) are deferred to a
-        # Phase 1.5 follow-up.
+        # (`params.require(:admin_user)` → `Admin::User`) are deferred.
         #
         # @param call_node [Prism::Node]
         # @param model_index [Hash{String => Hash}]

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

@@ -68,17 +68,14 @@ module Rigor
     class Actionpack < Rigor::Plugin::Base
       manifest(
         id: "actionpack",
-        # Bumped 2026-06-02 — ADR-37 node_rule migration. The four
-        # phases (helper / filter / render / strong-params) now run
-        # per-call over the engine-owned walk instead of the
-        # hand-rolled `diagnostics_for_file` traversal; the enclosing
-        # controller is read from the node-rule `NodeContext` ancestors.
-        # Nested-module qualification is preserved — a
-        # `module Admin; class DomainBlocksController; end` file still
+        # ADR-37: the four phases (helper / filter / render /
+        # strong-params) run per-call over the engine-owned walk;
+        # the enclosing controller is read from the node-rule
+        # `NodeContext` ancestors. Nested-module qualification is
+        # preserved — `module Admin; class DomainBlocksController`
         # resolves as `Admin::DomainBlocksController` (matching the
-        # `ControllerDiscoverer`), so render paths
-        # (`admin/domain_blocks/new`) and filter-chain validation on
-        # nested controllers are unchanged.
+        # `ControllerDiscoverer`), so render paths and filter-chain
+        # validation on nested controllers are correct.
         version: "0.8.0",
         description: "Validates Action Pack route-helper calls and filter chains inside controllers.",
         config_schema: {

data/plugins/rigor-activejob/lib/rigor/plugin/activejob/job_index.rb

@@ -12,8 +12,9 @@ module Rigor
       # (`Float::INFINITY` for the upper bound when `*args`
       # is present). `keyword_required` lists any required
       # keyword arguments — Active Job supports keyword args
-      # but they're rare in user code, so the analyzer only
-      # validates positional arity for v0.1.0.
+      # but they're rare in user code, so the analyzer
+      # validates positional arity only (keyword arity
+      # validation is deferred).
       class JobIndex
         Entry = Data.define(:class_name, :min_arity, :max_arity, :keyword_required) do
           # Flexible-friendly textual form of the arity for

data/plugins/rigor-activerecord/lib/rigor/plugin/activerecord/model_discoverer.rb

@@ -227,8 +227,8 @@ module Rigor
         # Recognised single-instance and collection association
         # DSL methods. The kind drives the eventual return-type
         # contribution: singular associations narrow to
-        # `Nominal[Target] | nil`, plural ones currently degrade
-        # to the RBS envelope (relation types are a future track).
+        # `Nominal[Target] | nil`, plural ones narrow to
+        # `ActiveRecord::Relation[Target]`.
         #
         # `composed_of` value-object aggregations and
         # `delegated_type` roles are folded in here too — both
@@ -447,8 +447,8 @@ module Rigor
 
         # `scope :active, -> { ... }`. Records the scope name
         # only (the body is intentionally NOT introspected —
-        # scopes return ActiveRecord::Relation, which Rigor
-        # doesn't carry a precise type for yet).
+        # the caller contributes `ActiveRecord::Relation[Model]`
+        # based on the name alone via `class_scope_return_type`).
         def lookup_scopes(body)
           return [] if body.nil?
 

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

@@ -75,10 +75,9 @@ module Rigor
           "model_base_classes" => { kind: :array, default: %w[ApplicationRecord ActiveRecord::Base] }
         },
         produces: [:model_index],
-        # ADR-25 — the bundled `ActiveRecord::Relation` RBS, the
-        # type `flow_contribution_for`'s relation-typed call sites
-        # (`has_many` accessors, `Model.where`, scopes) dispatch
-        # against.
+        # ADR-25 — the bundled `ActiveRecord::Relation` RBS that
+        # relation-typed call sites (`has_many` accessors,
+        # `Model.where`, scopes) dispatch against.
         signature_paths: ["sig"],
         # ADR-26 — `ActiveRecord::Relation` is an "open" receiver:
         # it delegates an unbounded set of user-defined scopes /
@@ -89,7 +88,7 @@ module Rigor
       )
 
       # The class the bundled `sig/active_record/relation.rbs`
-      # describes; `flow_contribution_for` contributes
+      # describes; `dynamic_return` contributes
       # `ActiveRecord::Relation[Model]` for relation-returning
       # call sites (`has_many` accessors, `Model.where`, scopes).
       RELATION_CLASS_NAME = "ActiveRecord::Relation"
@@ -261,9 +260,8 @@ module Rigor
         names
       end
 
-      # The migrated body of the legacy `flow_contribution_for` —
-      # same resolution order, returning the bare type the
-      # `dynamic_return` contract expects.
+      # Resolution body for `dynamic_return` — same four-path
+      # order, returning the bare type the contract expects.
       def contribution_return_type(call_node, scope)
         return nil unless call_node.is_a?(Prism::CallNode)
 

data/plugins/rigor-activestorage/lib/rigor/plugin/activestorage/analyzer.rb

@@ -11,13 +11,11 @@ module Rigor
       # plugin recognised so users can verify the model →
       # attachment mapping the plugin sees.
       #
-      # No `:error` diagnostics in this slice — the
-      # `dynamic_return` return-type narrowing carries
-      # the type-checking value; surfacing unknown attachment
-      # names as errors requires a coupled receiver-class
-      # narrowing pass that the integration spec doesn't yet
-      # rely on. A future slice can add `unknown-attachment`
-      # similar to `rigor-activerecord`'s `unknown-column`.
+      # No `:error` diagnostics here — the `dynamic_return`
+      # return-type narrowing carries the type-checking value.
+      # An `unknown-attachment` rule (similar to
+      # `rigor-activerecord`'s `unknown-column`) is deferred:
+      # it requires a coupled receiver-class narrowing pass.
       class Analyzer
         attr_reader :diagnostics