rigortype 0.2.9 → 0.3.1

data/lib/rigor/type/difference.rb

@@ -48,6 +48,30 @@ module Rigor
         base.erase_to_rbs
       end
 
+      # True when `removed` is the *empty witness* of `base` — the single value whose removal makes this
+      # difference one of the catalogued `non-empty-*` / `non-zero-int` refinements (`""` for String, `0`
+      # for Integer, `[]` for Array, `{}` for Hash).
+      #
+      # This is the shared recogniser for the whole engine: the display side (`canonical_name` below),
+      # `ShapeDispatch`'s refinement-aware projections, and `MutationWidening`'s invalidation arm all ask
+      # this one question, so the recognised set cannot drift between them.
+      def removes_empty_witness?
+        return false unless base.is_a?(Nominal)
+
+        predicate = EMPTY_WITNESS_PREDICATES[base.class_name]
+        !!predicate && predicate.call(removed)
+      end
+
+      EMPTY_WITNESS_PREDICATES = {
+        "String" => ->(removed) { removed.is_a?(Constant) && removed.value == "" },
+        "Integer" => lambda { |removed|
+          removed.is_a?(Constant) && removed.value.is_a?(Integer) && removed.value.zero?
+        },
+        "Array" => ->(removed) { removed.is_a?(Tuple) && removed.elements.empty? },
+        "Hash" => ->(removed) { removed.is_a?(HashShape) && removed.pairs.empty? }
+      }.freeze
+      private_constant :EMPTY_WITNESS_PREDICATES
+
       def top
         Trinary.no
       end
@@ -80,47 +104,27 @@ module Rigor
       # The recognised set is kept in sync with the imported-built-in catalogue
       # ([`imported-built-in-types.md`](docs/type-specification/imported-built-in-types.md)).
       def canonical_name
-        return nil unless base.is_a?(Nominal)
+        return nil unless removes_empty_witness?
 
-        send(CANONICAL_HANDLERS[base.class_name] || :no_canonical_name)
+        send(CANONICAL_HANDLERS[base.class_name])
       end
 
       CANONICAL_HANDLERS = {
         "String" => :string_canonical_name,
         "Integer" => :integer_canonical_name,
-        "Array" => :array_canonical_name_if_empty,
-        "Hash" => :hash_canonical_name_if_empty
+        "Array" => :array_canonical_name,
+        "Hash" => :hash_canonical_name
       }.freeze
       private_constant :CANONICAL_HANDLERS
 
-      def no_canonical_name
-        nil
-      end
-
       def string_canonical_name
-        return nil unless removed.is_a?(Constant) && removed.value == ""
-
         "non-empty-string"
       end
 
       def integer_canonical_name
-        return nil unless removed.is_a?(Constant) && removed.value.is_a?(Integer) && removed.value.zero?
-
         "non-zero-int"
       end
 
-      def array_canonical_name_if_empty
-        return nil unless removed.is_a?(Tuple) && removed.elements.empty?
-
-        array_canonical_name
-      end
-
-      def hash_canonical_name_if_empty
-        return nil unless removed.is_a?(HashShape) && removed.pairs.empty?
-
-        hash_canonical_name
-      end
-
       def array_canonical_name
         elem = base.type_args.first
         return "non-empty-array" if elem.nil?

data/lib/rigor/type/hash_shape.rb

@@ -11,9 +11,12 @@ module Rigor
     # inhabit the corresponding value types. RBS records correspond to the exact closed subset; Rigor
     # extends that carrier with optional keys, read-only entry views, and an open/closed extra-key policy.
     #
-    # Keys are restricted to Symbol and String values. Exact closed symbol-keyed shapes erase to the RBS
-    # record syntax `{ a: Integer, ?b: String }`; all other shapes degrade to `Hash[K, V]` or raw `Hash`
-    # when no useful bounds are available.
+    # Keys are restricted to value-pinned scalar literals: Symbol, String, Integer, Float, and the
+    # `true` / `false` / `nil` singletons. Exact closed symbol-keyed shapes erase to the RBS record
+    # syntax `{ a: Integer, ?b: String }`; all other shapes degrade to `Hash[K, V]` or raw `Hash` when
+    # no useful bounds are available. Key identity follows Ruby's own `Hash` `eql?` semantics because
+    # the pairs are stored in a native Ruby Hash — `1` and `1.0` are DISTINCT keys (`1.eql?(1.0)` is
+    # false), while `1.0` and `1.00` are the same key.
     #
     # Equality and hashing are structural over the (key -> Rigor::Type) pair set and policy fields. Hash
     # insertion order is preserved by the underlying storage but does NOT affect equality (matching
@@ -22,7 +25,7 @@ module Rigor
     # See docs/type-specification/rbs-compatible-types.md (records) and
     # docs/type-specification/rigor-extensions.md (hash shape).
     class HashShape
-      ALLOWED_KEY_CLASSES = [Symbol, String].freeze
+      ALLOWED_KEY_CLASSES = [Symbol, String, Integer, Float, TrueClass, FalseClass, NilClass].freeze
       EXTRA_KEY_POLICIES = %i[open closed].freeze
       POLICY_KEYWORDS = %i[required_keys optional_keys read_only_keys extra_keys].freeze
       # A Symbol whose text matches renders as a bare RBS record key (`lang:`) in {#erase_to_rbs};
@@ -128,7 +131,8 @@ module Rigor
         pairs.each_key do |key|
           next if ALLOWED_KEY_CLASSES.any? { |klass| key.is_a?(klass) }
 
-          raise ArgumentError, "HashShape keys must be Symbol or String, got #{key.class}"
+          raise ArgumentError,
+                "HashShape keys must be one of #{ALLOWED_KEY_CLASSES.join(', ')}, got #{key.class}"
         end
       end
 
@@ -190,17 +194,28 @@ module Rigor
         prefix = []
         prefix << "readonly" if read_only_key?(key)
         rendered_key = optional_key?(key) ? "?#{render_key(key)}" : render_key(key)
-        prefix << "#{rendered_key}:"
+        prefix << "#{rendered_key}#{key_separator(key)}"
         "#{prefix.join(' ')} #{value.describe(verbosity)}"
       end
 
       # `describe` is a human-facing display contract (it feeds diagnostic messages, never a parser),
-      # so it keeps the compact `"a":` form for a quoted key. The RBS-erasure path uses
-      # {#erase_key_prefix} instead, which must emit a parseable key.
+      # so it keeps the compact `"a":` form for a quoted key. Non-(Symbol|String) scalar keys render in
+      # the natural hashrocket spelling (`1 => 2`, `1.0 => 4`, `nil => 0`) via {#key_separator}; their
+      # `inspect` is the canonical Ruby literal, so describe stays deterministic. The RBS-erasure path
+      # uses {#erase_key_prefix} instead, which must emit a parseable key.
       def render_key(key)
         case key
         when Symbol then key.to_s
-        when String then key.inspect
+        else key.inspect
+        end
+      end
+
+      # Symbol / String keys keep the compact colon form (`a: 1`, `"k": 2`); every other scalar key uses
+      # the hashrocket (`1 => 2`) — the form the user would have to write in source.
+      def key_separator(key)
+        case key
+        when Symbol, String then ":"
+        else " =>"
         end
       end
 
@@ -230,8 +245,17 @@ module Rigor
         "Hash[#{key_type.erase_to_rbs}, #{value_type.erase_to_rbs}]"
       end
 
+      # Conservative per-key-class bound for the `Hash[K, V]` degradation. Symbol / String / Integer /
+      # Float keys widen to their class nominal; the `true` / `false` / `nil` singletons keep their
+      # literal carrier (the constant IS the class's whole value set, and RBS spells the literal — `nil`
+      # reads better than `NilClass`).
       def hash_erasure_key_type
-        key_types = pairs.keys.map { |key| Type::Combinator.nominal_of(key.class) }
+        key_types = pairs.keys.map do |key|
+          case key
+          when true, false, nil then Type::Combinator.constant_of(key)
+          else Type::Combinator.nominal_of(key.class)
+          end
+        end
         Type::Combinator.union(*key_types)
       end
     end

data/lib/rigor/version.rb

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

data/lib/rigortype.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# Nothing in an application should ever load Rigor: it is a command-line tool
+# that reads a project from the outside, not a library (ADR-27). This file
+# exists only because `Bundler.require` — the default for every Gemfile entry,
+# and what Rails runs at boot — requires a gem by its *gem* name, `rigortype`,
+# while the library entry point is `rigor.rb`.
+#
+# Without this file that call raises a bare `LoadError` naming `rigortype`, so
+# a `bundle add rigortype` succeeds and the *next* `rails s` dies with no
+# explanation of what went wrong or what to do instead. The file is a guardrail,
+# not an entry point: it warns and defines nothing. `require "rigor"` remains
+# the (analyzer-internal) way in.
+warn(<<~MESSAGE)
+  rigortype: `require "rigortype"` does nothing — Rigor is a command-line tool, not a library.
+
+  This usually means Rigor is in your Gemfile, where `Bundler.require` loads it at boot. Rigor
+  analyses your project from the outside and runs on its own Ruby, so a Gemfile entry constrains
+  your application's Ruby and dependency resolution without giving you anything. Remove it and
+  install Rigor independently: https://github.com/rigortype/rigor/blob/master/docs/install.md
+
+  To keep the Gemfile entry anyway, mark it `gem "rigortype", require: false` — that silences
+  this warning, but the resolution constraints remain.
+MESSAGE

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "rigor/source/node_children"
+
 require "prism"
 
 require_relative "channel_index"
@@ -76,7 +78,7 @@ module Rigor
           when Prism::ClassNode then visit_class(node, lexical_path, &)
           when Prism::ModuleNode then visit_module(node, lexical_path, &)
           else
-            node.compact_child_nodes.each { |child| walk_for_channels(child, lexical_path, &) }
+            node.rigor_each_child { |child| walk_for_channels(child, lexical_path, &) }
           end
         end
 
@@ -138,7 +140,7 @@ module Rigor
             end
           end
 
-          node.compact_child_nodes.each do |child|
+          node.rigor_each_child do |child|
             names, dynamic = collect_stream_registrations(child, names: names, dynamic: dynamic)
           end
           [names, dynamic]

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

@@ -42,6 +42,25 @@ module Rigor
     #   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.
+    #
+    # ## `#receive(data)` protocol contract (ADR-28)
+    #
+    # ActionCable's `Connection::Subscriptions#perform_action` dispatches an incoming message to the
+    # action named by the payload's `"action"` key, defaulting to `:receive` when that key is absent —
+    # i.e. `#receive(data)` is the framework-documented catch-all handler for messages with no explicit
+    # action. Either way the single positional argument is always the `ActiveSupport::JSON.decode` of the
+    # client-sent payload, which is a JSON object and therefore a `Hash` by convention (the bundled JS
+    # client only ever calls `perform(action, data = {})` with an object). This plugin declares a
+    # path-scoped protocol contract (`method_name: :receive`, `param_types: [{index: 0, type_name:
+    # "Hash"}]`) so `data` types as `Hash` instead of `Dynamic[Top]` inside a channel's `#receive` body.
+    #
+    # Deliberately narrower than Hanami's `#handle`: custom action methods (`def speak(data)`) also
+    # receive the decoded Hash, but their names are project-chosen, not a single fixed Symbol a
+    # `ProtocolContract` can name — only `:receive` is a framework-reserved, uniformly-shaped method name.
+    # Per ADR-28, the contract is path-scoped, not class-scoped: any `#receive(data)` defined anywhere
+    # under the (possibly multi-root) `channel_search_paths` is typed, even on a stray non-channel class
+    # that happens to live in that directory — the same accepted-risk shape as `rigor-hanami`'s
+    # `#handle`.
     class Actioncable < Rigor::Plugin::Base
       manifest(
         id: "actioncable",
@@ -53,7 +72,15 @@ module Rigor
             kind: :array,
             default: ["ApplicationCable::Channel", "ActionCable::Channel::Base"]
           }
-        }
+        },
+        protocol_contracts: [
+          Rigor::Plugin::ProtocolContract.new(
+            path_glob: "app/channels/**/*.rb",
+            method_name: :receive,
+            param_types: [{ index: 0, type_name: "Hash" }]
+            # return_type_name: nil — receive's return value is discarded by the framework dispatcher.
+          )
+        ]
       )
 
       # `watch:` covers every `.rb` file under the channel search paths so the cache invalidates when
@@ -70,6 +97,20 @@ module Rigor
       def init(_services)
         @channel_search_paths = Array(config.fetch("channel_search_paths")).map(&:to_s)
         @channel_base_classes = Array(config.fetch("channel_base_classes")).map(&:to_s)
+
+        # ADR-28 WD5 — `channel_search_paths` is user-configurable and may name multiple roots; retarget
+        # the manifest's default `app/channels/**/*.rb` glob to the actual configured root(s) so the
+        # contract neither goes inert on a project that renames/adds channel directories nor (more
+        # importantly, per the project's false-positive discipline) risks matching an unrelated `#receive`
+        # outside them. `File::FNM_EXTGLOB` (enabled by `Registry#contracts_for_path`) makes a `{a,b}`
+        # brace group a single valid glob for multiple roots.
+        @protocol_contracts = manifest.protocol_contracts.map { |c| c.with_path_glob(channel_search_glob) }
+      end
+
+      # ADR-28 — override so the per-project `channel_search_paths` config reaches both the engine's
+      # parameter-provision tier and this plugin's own path-scoped reasoning.
+      def protocol_contracts
+        @protocol_contracts || manifest.protocol_contracts
       end
 
       # File-level only: the load-error emission. Per-call broadcast validation runs over the
@@ -91,6 +132,15 @@ module Rigor
 
       private
 
+      # Builds the `#receive` contract's `path_glob` from the configured `channel_search_paths`. A single
+      # root becomes a plain `**/*.rb` glob; multiple roots become an `FNM_EXTGLOB` brace group so every
+      # configured root — and only a configured root — is covered.
+      def channel_search_glob
+        roots = @channel_search_paths.map { |p| p.chomp("/") }
+        base = roots.length == 1 ? roots.first : "{#{roots.join(',')}}"
+        "#{base}/**/*.rb"
+      end
+
       def load_error_diagnostic(path)
         error = producer_error(:channel_index)
         Rigor::Analysis::Diagnostic.new(

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "rigor/source/node_children"
+
 require "prism"
 require "rigor/source/literals"
 
@@ -97,7 +99,7 @@ module Rigor
           when Prism::ClassNode then visit_class(node, lexical_path, &)
           when Prism::ModuleNode then visit_module(node, lexical_path, &)
           else
-            node.compact_child_nodes.each { |child| walk_for_mailers(child, lexical_path, &) }
+            node.rigor_each_child { |child| walk_for_mailers(child, lexical_path, &) }
           end
         end
 
@@ -124,7 +126,7 @@ module Rigor
           return [] if body.nil?
 
           names = []
-          body.compact_child_nodes.each do |node|
+          body.rigor_each_child do |node|
             next unless node.is_a?(Prism::CallNode) && node.receiver.nil? && node.name == :include
 
             (node.arguments&.arguments || []).each do |arg|
@@ -158,7 +160,7 @@ module Rigor
             inner = local_name ? lexical_path + [local_name.delete_prefix("::")] : lexical_path
             collect_module_actions(node.body, inner, accumulator) if node.body
           else
-            node.compact_child_nodes.each { |child| collect_module_actions(child, lexical_path, accumulator) }
+            node.rigor_each_child { |child| collect_module_actions(child, lexical_path, accumulator) }
           end
         end
 
@@ -231,7 +233,7 @@ module Rigor
           private_names = []
           callback_names = []
 
-          body.compact_child_nodes.each do |node|
+          body.rigor_each_child do |node|
             next unless node.is_a?(Prism::CallNode) && node.receiver.nil?
 
             args = (node.arguments&.arguments || []).filter_map do |arg|

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "rigor/source/node_children"
+
 require "prism"
 
 require_relative "controller_index"
@@ -89,7 +91,7 @@ module Rigor
 
             walk_declarations(node.body, namespace: inner_namespace, &)
           else
-            node.compact_child_nodes.each do |child|
+            node.rigor_each_child do |child|
               walk_declarations(child, namespace: namespace, &)
             end
           end
@@ -142,7 +144,7 @@ module Rigor
           return accumulator unless node.is_a?(Prism::Node)
 
           accumulator << node.name if node.is_a?(Prism::DefNode) && node.receiver.nil?
-          node.compact_child_nodes.each { |child| collect_def_names(child, accumulator) }
+          node.rigor_each_child { |child| collect_def_names(child, accumulator) }
           accumulator
         end
 
@@ -160,7 +162,7 @@ module Rigor
             end
           end
 
-          node.compact_child_nodes.each { |child| collect_include_targets(child, accumulator) }
+          node.rigor_each_child { |child| collect_include_targets(child, accumulator) }
           accumulator
         end
 

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "rigor/source/node_children"
+
 require "prism"
 
 require_relative "job_index"
@@ -66,7 +68,7 @@ module Rigor
           when Prism::ClassNode then visit_class(node, lexical_path, &)
           when Prism::ModuleNode then visit_module(node, lexical_path, &)
           else
-            node.compact_child_nodes.each { |child| walk_for_jobs(child, lexical_path, &) }
+            node.rigor_each_child { |child| walk_for_jobs(child, lexical_path, &) }
           end
         end
 
@@ -118,7 +120,7 @@ module Rigor
         def lookup_perform_def(body)
           return nil if body.nil?
 
-          body.compact_child_nodes.each do |node|
+          body.rigor_each_child do |node|
             next unless node.is_a?(Prism::DefNode) && node.name == :perform
             next if node.receiver.is_a?(Prism::SelfNode)
 

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "rigor/source/node_children"
+
 require "prism"
 
 module Rigor
@@ -50,7 +52,7 @@ module Rigor
           return if node.nil?
 
           yield node
-          node.compact_child_nodes.each { |child| walk(child, &) }
+          node.rigor_each_child { |child| walk(child, &) }
         end
 
         def visit_call(node)

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "rigor/source/node_children"
+
 require "prism"
 require "rigor/source/literals"
 
@@ -140,7 +142,7 @@ module Rigor
           when Prism::ModuleNode
             visit_module(node, lexical_path, &)
           else
-            node.compact_child_nodes.each { |child| walk_for_classes(child, lexical_path, &) }
+            node.rigor_each_child { |child| walk_for_classes(child, lexical_path, &) }
           end
         end
 
@@ -256,7 +258,7 @@ module Rigor
         def lookup_table_name_override(body)
           return nil if body.nil?
 
-          body.compact_child_nodes.each do |node|
+          body.rigor_each_child do |node|
             next unless node.is_a?(Prism::CallNode) && node.name == :table_name=
             next unless node.receiver.is_a?(Prism::SelfNode)
 

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "rigor/source/node_children"
+
 require "prism"
 
 module Rigor
@@ -66,7 +68,7 @@ module Rigor
 
           yield node if node.is_a?(Prism::CallNode) && node.name == :create_table && node.receiver.nil?
 
-          node.compact_child_nodes.each { |child| collect_create_table_calls(child, &) }
+          node.rigor_each_child { |child| collect_create_table_calls(child, &) }
         end
 
         def parse_create_table(call_node)
@@ -118,7 +120,7 @@ module Rigor
             return
           end
 
-          node.compact_child_nodes.each { |child| collect_column_calls(child, &) }
+          node.rigor_each_child { |child| collect_column_calls(child, &) }
         end
 
         def parse_column(call_node)

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "rigor/source/node_children"
+
 require "prism"
 
 module Rigor
@@ -32,7 +34,7 @@ module Rigor
           return if node.nil?
 
           yield node
-          node.compact_child_nodes.each { |child| walk(child, &) }
+          node.rigor_each_child { |child| walk(child, &) }
         end
 
         def visit_call(node)

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "rigor/source/node_children"
+
 require "prism"
 require "rigor/source/literals"
 
@@ -77,7 +79,7 @@ module Rigor
           when Prism::ModuleNode
             visit_module(node, lexical_path, &)
           else
-            node.compact_child_nodes.each { |child| walk(child, lexical_path, &) }
+            node.rigor_each_child { |child| walk(child, lexical_path, &) }
           end
         end
 
@@ -105,7 +107,7 @@ module Rigor
           return [] if body.nil?
 
           rows = []
-          body.compact_child_nodes.each do |node|
+          body.rigor_each_child do |node|
             next unless node.is_a?(Prism::CallNode)
 
             kind = ATTACHMENT_METHODS[node.name]

data/plugins/rigor-dry-types/lib/rigor/plugin/dry_types.rb

@@ -63,12 +63,28 @@ module Rigor
         produces: [:dry_type_aliases]
       )
 
-      # Walks every project file once during `prepare(services)` to build the alias table, then publishes
-      # via the ADR-9 fact store. The walk is bounded by the configured `paths:` surface; each file's
-      # parse error degrades to "no contribution" without polluting the user-visible diagnostic stream.
+      # Cached alias-table producer (ADR-60 WD3 record-and-validate). The scan Prism-parses every `.rb` file
+      # under the project's `paths:` tree to find `include Dry.Types()` declarations — an expensive pass that
+      # ran on EVERY invocation (cold and warm) because `#prepare` called {AliasScanner.scan} directly, with
+      # no cache. It now rides `cache_for`: a warm run re-globs + re-digests the watched tree (cheap SHA over
+      # file bytes, no AST build) and reuses the cached table instead of re-parsing. This is the dominant win
+      # even for a project that ships no dry-types module — the parse still has to run to prove that, and now
+      # the empty result is cached too.
+      #
+      # `watch:` covers exactly the files the scan reads: one glob per project `paths:` entry, co-extensive
+      # with {#scannable_paths}. A {Cache::Descriptor::GlobEntry} digests every file matching its glob, so a
+      # content edit, a file addition, and a file removal anywhere under those paths all move the digest and
+      # invalidate the entry. The scan reads no file individually through the `IoBoundary`, so the evaluated
+      # `watch:` globs are the entire dependency descriptor — and they fully cover the scan's input.
+      producer :dry_type_aliases, watch: -> { alias_watch_globs } do |_params|
+        AliasScanner.scan(paths: scannable_paths)
+      end
+
+      # Builds the (cached) alias table and publishes it via the ADR-9 fact store. `producer_value` runs the
+      # producer through `cache_for` and memoises the result — including a rescued nil — for the run.
       def prepare(services)
-        aliases = AliasScanner.scan(paths: scannable_paths(services))
-        return if aliases.empty?
+        aliases = producer_value(:dry_type_aliases)
+        return if aliases.nil? || aliases.empty?
 
         services.fact_store.publish(
           plugin_id: manifest.id,
@@ -86,7 +102,7 @@ module Rigor
       # Resolves the project's `paths:` to a flat list of `.rb` files the scanner walks. Mirrors
       # `Analysis::Runner`'s `expand_paths` floor; we don't need the runner's full exclude/sort surface
       # because the alias table is a union — any duplicate scan is a no-op.
-      def scannable_paths(services)
+      def scannable_paths
         @scannable_paths ||= services.configuration.paths.flat_map do |entry|
           if File.directory?(entry)
             Dir.glob(File.join(entry, "**", "*.rb"), sort: true)
@@ -97,6 +113,22 @@ module Rigor
           end
         end.uniq.freeze
       end
+
+      # The `watch:` glob tuples covering the scan's entire input — one `[root, pattern]` per project `paths:`
+      # entry. A directory entry watches its whole `**/*.rb` subtree; a single-file `.rb` entry watches
+      # exactly that file (`[dir, basename]`). Roots are expanded to absolute paths by
+      # `Plugin::Base#watch_glob_entries`, so a relative CLI path (`app/models`) re-validates against the same
+      # tree from the project root on the next run. Co-extensive with {#scannable_paths}: every `.rb` the scan
+      # would read is watched, so any edit / addition / removal under those paths invalidates the cache.
+      def alias_watch_globs
+        services.configuration.paths.filter_map do |entry|
+          if File.directory?(entry)
+            [entry, "**/*.rb"]
+          elsif File.file?(entry) && entry.end_with?(".rb")
+            [File.dirname(entry), File.basename(entry)]
+          end
+        end
+      end
     end
 
     Rigor::Plugin.register(DryTypes)

data/plugins/rigor-factorybot/lib/rigor/plugin/factorybot/factory_discoverer.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "rigor/source/node_children"
+
 require "prism"
 require "rigor/source/literals"
 
@@ -86,7 +88,7 @@ module Rigor
             visit_factory(node, &)
             return
           end
-          node.compact_child_nodes.each { |child| walk_for_factories(child, &) }
+          node.rigor_each_child { |child| walk_for_factories(child, &) }
         end
 
         def factory_call?(node)

data/plugins/rigor-hanami/lib/rigor/plugin/hanami/action_checker.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "rigor/source/node_children"
+
 require "prism"
 
 module Rigor
@@ -65,7 +67,7 @@ module Rigor
           case node
           when Prism::DefNode then defs << node
           when Prism::ClassNode, Prism::ModuleNode then nil # nested scopes own their own defs
-          else node.compact_child_nodes.each { |child| collect_direct_defs(child, defs) }
+          else node.rigor_each_child { |child| collect_direct_defs(child, defs) }
           end
         end
 

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

@@ -122,6 +122,16 @@ module Rigor
         carried_type(receiver_type, call_node.name)
       end
 
+      # ADR-88 WD1 — the `dynamic_return` contribution is a PURE STRUCTURAL projection of the receiver's own
+      # carrier type args (`Result[T, E]#unwrap → T`), computed per call from the receiver type the engine
+      # already resolved; it reads no cross-file catalog. (The `Enum` nested-class emission rides the ADR-16
+      # macro substrate / synthetic-method scanner, a separate pre-pass, not this `dynamic_return`.) A stable
+      # sentinel declares "no cross-file fact surface", keeping the plugin incremental-capable; the
+      # `--verify-incremental` gate backstops the claim.
+      def incremental_state_fingerprint
+        "structural-carriers"
+      end
+
       private
 
       # @return [Rigor::Type, nil] the receiver's inferred type, or nil when the engine raises on a synthetic