rigortype 0.2.9 → 0.3.1

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

@@ -62,6 +62,17 @@ module Rigor
       narrowing_facts methods: AssertionAnalyzer::SUPPORTED_METHODS do |call_node, scope|
         AssertionAnalyzer.contribution_for(call_node, environment: scope&.environment)&.post_return_facts
       end
+
+      # ADR-88 WD1 — the narrowing facts this plugin contributes are derived purely from each assertion call's
+      # own AST at its call site (`assert_kind_of(String, x)` ⇒ `x` is `String` on the continuation); there is
+      # no cross-file catalog a cached diagnostic could depend on. A change to a file's assertions changes that
+      # file's own content (re-analysed by the incremental graph already). A stable sentinel declares "no
+      # cross-file fact surface", keeping the plugin incremental-capable (a contributing plugin with NO
+      # fact / producer / hook makes the incremental snapshot un-reusable every run); `--verify-incremental`
+      # backstops the claim.
+      def incremental_state_fingerprint
+        "per-file-assertions"
+      end
     end
 
     Rigor::Plugin.register(Minitest)

data/plugins/rigor-pundit/lib/rigor/plugin/pundit/policy_discoverer.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "rigor/source/node_children"
+
 require "prism"
 
 require_relative "policy_index"
@@ -69,7 +71,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_policies(child, lexical_path, &) }
+            node.rigor_each_child { |child| walk_for_policies(child, lexical_path, &) }
           end
         end
 

data/plugins/rigor-rails/lib/rigor-rails.rb

@@ -1,19 +1,18 @@
 # frozen_string_literal: true
 
-# Convenience entry point. `require "rigor-rails"` requires every Tier 1+2 Rails ecosystem plugin in one go,
-# so projects that prefer a single require statement (some `spec_helper` patterns, ad-hoc scripts) do not
-# have to list seven require lines.
+# The Tier 1+2 Rails set, as a single require. Requiring this file registers every member class with
+# `Rigor::Plugin`; the loader's lookup phase then finds them by id when `.rigor.yml` enumerates them.
 #
-# Note: requiring this entry point does NOT mark every plugin as active. The Rigor plugin loader walks
-# `.rigor.yml`'s `plugins:` list and instantiates only the plugins enumerated there. This is per ADR-12
-# WD1's "Gemfile-convenience meta-gem" pattern — users still control which plugins participate in analysis
-# via `.rigor.yml`.
+# UNWIRED — this entry point has no supported use today, and is kept deliberately (ADR-96 WD5) rather
+# than removed. It was ADR-12 WD1's "Gemfile-convenience meta-gem": each plugin was to be its own gem, and
+# `gem "rigor-rails"` was to pull the Rails set into a project's Gemfile in one line. Commit `9769f5fa`
+# dropped the per-plugin gemspecs and ADR-31 settled distribution on the single bundled `rigortype` gem, so
+# there is no `rigor-rails` gem to add to a Gemfile — and `plugins: [rigor-rails]` is rejected by the
+# loader, which requires the members to be enumerated (or one selected with an explicit `id:`).
 #
-# Sub-plugins ARE registered with `Rigor::Plugin` when this file loads (each gem's entry point side-effects
-# a `Plugin.register` call); the loader's lookup phase finds them by id when listed.
-#
-# Adding the gem to a project's Gemfile without listing any plugin in `.rigor.yml` is harmless: the requires
-# happen on `Bundler.require`, but no plugin's `init` / `prepare` / hooks run.
+# ADR-96 WD3 proposes the role this file would fill: `plugins: [rigor-rails]` activating those members
+# whose `target_gems:` are actually in the project's `Gemfile.lock`. If that is rejected, ADR-60 WD1's
+# never-wired-surface criterion applies and this directory goes.
 
 require "rigor-rails-routes"
 require "rigor-rails-i18n"

data/plugins/rigor-rails-routes/lib/rigor/plugin/rails_routes/grape_api_discoverer.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "rigor/source/node_children"
+
 require "prism"
 
 module Rigor
@@ -106,7 +108,7 @@ module Rigor
             end
           end
 
-          node.compact_child_nodes.each { |child| walk(child, prefix_path, declarations, superclasses) }
+          node.rigor_each_child { |child| walk(child, prefix_path, declarations, superclasses) }
         end
 
         def record_class(node, qualified, declarations, superclasses)

data/plugins/rigor-rails-routes/lib/rigor/plugin/rails_routes/helper_discoverer.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "rigor/source/node_children"
+
 require "prism"
 
 module Rigor
@@ -87,7 +89,7 @@ module Rigor
           def visit_program_children(node)
             return unless node.respond_to?(:compact_child_nodes)
 
-            node.compact_child_nodes.each do |child|
+            node.rigor_each_child do |child|
               case child
               when Prism::ModuleNode, Prism::ClassNode
                 visit_module_or_class(child)

data/plugins/rigor-rails-routes/lib/rigor/plugin/rails_routes/routes_parser.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "rigor/source/node_children"
+
 require "prism"
 require "rigor/source/literals"
 
@@ -371,7 +373,7 @@ module Rigor
           when Prism::CallNode
             interpret_call(node, context)
           else
-            node.compact_child_nodes.each { |child| interpret(child, context) }
+            node.rigor_each_child { |child| interpret(child, context) }
           end
         end
 
@@ -526,7 +528,7 @@ module Rigor
           return unless node.is_a?(Prism::Node)
 
           yield node
-          node.compact_child_nodes.each { |child| walk_for_alias_pattern(child, &) }
+          node.rigor_each_child { |child| walk_for_alias_pattern(child, &) }
         end
 
         def first_block_parameter_name(block_node)
@@ -545,7 +547,7 @@ module Rigor
           body = node.block&.body
           return if body.nil?
 
-          body.compact_child_nodes.each { |child| interpret(child, context) }
+          body.rigor_each_child { |child| interpret(child, context) }
         end
 
         def handle_namespace(node, context)
@@ -625,7 +627,7 @@ module Rigor
           return [] if body.nil?
 
           skips = []
-          body.compact_child_nodes.each do |child|
+          body.rigor_each_child do |child|
             next unless child.is_a?(Prism::CallNode) && child.name == :skip_controllers
             next if child.receiver
 
@@ -748,7 +750,7 @@ module Rigor
             body = context.concern_body(concern_name)
             next if body.nil?
 
-            body.compact_child_nodes.each { |child| interpret(child, context) }
+            body.rigor_each_child { |child| interpret(child, context) }
           end
         end
 

data/plugins/rigor-rbs-inline/lib/rigor/plugin/rbs_inline.rb

@@ -8,9 +8,10 @@ require "rigor/plugin"
 # name: T`, `# @rbs return: T`, attribute `#:`, …) and contributes the result to the analysis environment
 # through the `source_rbs_synthesizer:` manifest hook.
 #
-# By default (WD2) only files starting with the upstream `# rbs_inline: enabled` magic comment are
-# processed; a host context can flip this off by setting `require_magic_comment: false` in the plugin
-# config (WD10).
+# Since ADR-93 WD1 the default is `require_magic_comment: false`: a file is processed whenever it actually
+# carries an annotation (see {Synthesizer#annotated?}), with only the upstream `# rbs_inline: disabled`
+# directive opting a file out. Set `require_magic_comment: true` to restore the old ADR-32 WD2 gate that
+# processed only files opening with `# rbs_inline: enabled`.
 module Rigor
   module Plugin
     # The plugin gem requires `rbs/inline` at load time; without the upstream library the synthesizer can't
@@ -35,9 +36,24 @@ module Rigor
       # env-build time. Returns the synthesised RBS source as a String, or `nil` when the file contributes
       # nothing (no magic comment in the default mode, empty annotation set, parse error per WD6).
       class Synthesizer
-        # @param require_magic_comment [Boolean] when `true` (the default, WD2), only files with
-        #   `# rbs_inline: enabled` at the top are processed. When `false` (WD10 host-context override),
-        #   every file is treated as if it carried the magic comment.
+        # An RDoc directive comment: `#:` followed by a bare word (RDoc allows a hyphen, as in `:call-seq:`)
+        # and a closing colon. RDoc predates rbs-inline by about two decades and `#:<name>:` is
+        # indistinguishable from an rbs-inline `#: <type>` assertion to upstream's parser, which reads the
+        # directive name as a type alias — `def f #:nodoc:` becomes `def f: () -> nodoc`, a type nothing
+        # declares (upstream issue: https://github.com/soutaro/rbs-inline/issues/248).
+        #
+        # Matching on shape rather than a name list covers all 17 directives the Ruby docs list
+        # (https://docs.ruby-lang.org/ja/latest/library/rdoc.html) with nothing to maintain, and none of
+        # `#: () -> void`, `#: String`, `#:Integer`, `#: bool`, `#:my_alias`, `#: { name: String }`,
+        # `#: (name: String) -> void`, `#: Integer?`, `#[Integer]` or `# @rbs x: String` matches it: a valid
+        # RBS type never starts with a bare lowercase word that is immediately closed by a colon. Only the
+        # space-free spelling is affected; `# :nodoc:` never reaches upstream's annotation grammar.
+        RDOC_DIRECTIVE_COMMENT = /\A#:[a-z_][\w-]*:/
+
+        # @param require_magic_comment [Boolean] when `false` (the default since ADR-93 WD1), the magic
+        #   comment is not required and the file is processed only if it actually carries an annotation — see
+        #   {#annotated?}. When `true` (the old ADR-32 WD2 gate), only files opening with
+        #   `# rbs_inline: enabled` are processed, and upstream's opt-in semantics apply verbatim.
         def initialize(require_magic_comment:)
           @require_magic_comment = require_magic_comment
           freeze
@@ -55,6 +71,9 @@ module Rigor
           return nil if source.empty?
 
           result = ::Prism.parse(source)
+          _, result = neutralize_rdoc_directives(source, result)
+          return nil if !@require_magic_comment && !annotated?(result)
+
           # `opt_in: true` is rbs-inline's "require the magic comment" mode (per upstream parser.rb:62).
           # The plugin's `require_magic_comment:` config knob maps directly onto it.
           parsed = ::RBS::Inline::Parser.parse(result, opt_in: @require_magic_comment)
@@ -71,6 +90,56 @@ module Rigor
           # message, without crashing analysis.
           [:error, "#{e.class}: #{e.message.to_s.lines.first.to_s.strip}"]
         end
+
+        private
+
+        # True when the file carries at least one rbs-inline annotation. Gates the magic-comment-free mode,
+        # and is the difference between "honour annotations wherever they are" and "fabricate signatures for
+        # code nobody annotated" — upstream's opt-out mode does the latter, emitting a full
+        # `def f: (untyped x) -> untyped` skeleton for EVERY unannotated def. Rigor trusts an accepted
+        # signature over body inference, so those skeletons would replace real inferred types with `untyped`:
+        # measured on mail (zero annotations) as 26 → 42 diagnostics, i.e. the mode actively fought the
+        # analysis on exactly the projects that write no annotations. The spec binds Rigor to treat
+        # annotations as type sources "whenever present" (`overview.md` § "Compatibility hierarchy"); it does
+        # not ask for untyped shadows of unannotated code.
+        #
+        # Detection delegates to upstream's own `AnnotationParser` rather than scanning for `#:` / `@rbs`
+        # with a regexp: the annotation grammar is upstream's to define (ADR-32 WD3), and this keeps a doc
+        # comment that merely mentions `@rbs`, or a URL containing `#:`, from opting a file in. A file with
+        # the magic comment keeps upstream's semantics verbatim — the author opted that file in explicitly,
+        # skeletons and all, which is what `rbs-inline --output` would generate for it.
+        def annotated?(prism_result)
+          ::RBS::Inline::AnnotationParser.parse(prism_result.comments)
+                                         .any? { |parsed| parsed.each_annotation.any? }
+        end
+
+        # Rewrite every RDoc directive comment to its spaced spelling (`#:nodoc:` -> `# :nodoc:`) so
+        # upstream's annotation grammar never sees it, and re-parse. Two reasons this happens here rather
+        # than in {#annotated?}: the directive must not gate a file in, AND it must not reach the synthesis,
+        # because one mis-parsed directive takes the whole class down with it. `def f #:nodoc:` renders as
+        # `def f: (untyped x) -> nodoc`; `nodoc` resolves to nothing, `RBS::DefinitionBuilder` raises
+        # `NoTypeFoundError` for the class, and every real annotation in that class is silently lost —
+        # measured on a class whose `#: (String) -> Integer` method fell back to body inference because a
+        # sibling method carried `#:nodoc:`. `fileutils.rb` alone carries 29 of these.
+        #
+        # The rewrite touches comment text only, so it cannot change what Ruby does; it shifts columns
+        # within the comment, which nothing downstream reads (the synthesized RBS is fresh text with its own
+        # buffer). Prism decides what is a comment, so a `#:nodoc:` inside a string literal stays put. Files
+        # without a directive re-parse nothing.
+        def neutralize_rdoc_directives(source, prism_result)
+          offsets = prism_result.comments.filter_map do |comment|
+            location = comment.location
+            # `start_character_offset`, not `start_offset`: the latter counts BYTES while `String#insert`
+            # indexes CHARACTERS, so on a file with any multi-byte content the space lands mid-word and
+            # rewrites `#:nodoc:` to `#:n odoc:` — still a directive to upstream, and now a corrupted one.
+            location.start_character_offset if RDOC_DIRECTIVE_COMMENT.match?(location.slice)
+          end
+          return [source, prism_result] if offsets.empty?
+
+          # Back to front, so each insertion leaves the earlier offsets valid.
+          rewritten = offsets.sort.reverse.inject(source.dup) { |acc, offset| acc.insert(offset + 1, " ") }
+          [rewritten, ::Prism.parse(rewritten)]
+        end
       end
 
       manifest(
@@ -87,11 +156,16 @@ module Rigor
       # override (returned by `#manifest`, which `Plugin::Registry#source_rbs_synthesizers` consults via
       # `plugin.manifest.source_rbs_synthesizer`).
       #
-      # ADR-32 WD10 — `require_magic_comment` defaults to `true`. Setting it to `false` in `.rigor.yml`
-      # flips the synthesizer into "process every file" mode.
+      # ADR-93 WD1 — `require_magic_comment` defaults to `false`: annotations are official type sources
+      # "always parsed whenever present" per the binding spec (overview.md § Compatibility hierarchy), so
+      # a file is processed when it actually carries an annotation, with the magic comment not required.
+      # The magic-comment-free mode is annotation-presence-gated (see {Synthesizer#annotated?}), so an
+      # unannotated file contributes nothing and the flip cannot regress it. Set `require_magic_comment:
+      # true` in `.rigor.yml` to restore the ADR-32 opt-in behaviour; `# rbs_inline: disabled` remains the
+      # per-file opt-out either way (honoured by upstream unconditionally).
       def initialize(services:, config: {})
         super
-        @require_magic_comment = config.fetch("require_magic_comment", true) ? true : false
+        @require_magic_comment = config.fetch("require_magic_comment", false) ? true : false
         @synthesizer = Synthesizer.new(require_magic_comment: @require_magic_comment)
         # Build the per-instance manifest eagerly (before `freeze`) so the registry's repeated reads
         # return the same object and we don't need to mutate a frozen instance later.

data/plugins/rigor-rbs-inline/lib/rigor-rbs-inline.rb

@@ -3,16 +3,20 @@
 # rigor-rbs-inline — ingests rbs-inline-shaped comments (`# @rbs name: T`, `#: () -> T`, `# @rbs return: T`,
 # attribute `#:`, ivars, generics, override, …) as RBS contributions to the analysis environment.
 #
-# Per ADR-32 the plugin gates per file on the upstream `# rbs_inline: enabled` magic comment by default. A
-# host context that owns the entire analysis scope (e.g. the ADR-29 browser playground) can set
-# `require_magic_comment: false` in the plugin config to skip the gate — every file the synthesizer sees is
-# treated as if it carried the magic comment.
+# Since ADR-93 WD1 the plugin defaults to `require_magic_comment: false`: annotations are official type
+# sources wherever present, gated only on a file actually carrying one, with `# rbs_inline: disabled` the
+# per-file opt-out. ADR-93 WD2 default-wires this plugin from `Configuration.load` when the upstream
+# `rbs-inline` library is resolvable, so most projects need no `plugins:` entry at all. Restore the old
+# ADR-32 magic-comment gate, or opt out of the auto-wire, through config:
 #
 #     # .rigor.yml
 #     plugins:
 #       - id: rigor-rbs-inline
 #         config:
-#           require_magic_comment: false   # default true
+#           require_magic_comment: true    # default false — restore the ADR-32 magic-comment gate
+#       # or disable the auto-wired default entirely:
+#       # - gem: rigor-rbs-inline
+#       #   enabled: false
 #
 # The plugin depends on the upstream `rbs-inline` gem; Rigor's core `rigortype` gemspec stays zero-dep per
 # ADR-0 / ADR-32 WD1.

data/plugins/rigor-rspec/lib/rigor/plugin/rspec/let_scope_index.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "rigor/source/node_children"
+
 require "prism"
 require "rigor/source/literals"
 
@@ -89,7 +91,7 @@ module Rigor
             return
           end
 
-          node.compact_child_nodes.each do |child|
+          node.rigor_each_child do |child|
             collect(child, anchor: anchor, accumulator: accumulator)
           end
         end

data/plugins/rigor-rspec/lib/rigor/plugin/rspec/scope_walker.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "rigor/source/node_children"
+
 require "prism"
 require "rigor/source/literals"
 
@@ -70,7 +72,7 @@ module Rigor
           if rspec_describe_call?(node)
             scopes << build_scope(node, kind: :rspec_describe)
           else
-            node.compact_child_nodes.each { |child| walk_top_level(child, scopes) }
+            node.rigor_each_child { |child| walk_top_level(child, scopes) }
           end
         end
 

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

@@ -97,6 +97,17 @@ module Rigor
         let_binding_return_type(call_node, scope)
       end
 
+      # ADR-88 WD1 — both contributions are per-file: the matcher narrowing facts come from the call's own AST,
+      # and the `let`-binding return types come from each spec file's OWN `describe`/`let` structure (`let` is
+      # file-scoped). A spec file's edit changes its own content (re-analysed already). The one cross-file input
+      # — the optional factorybot `:factory_index` fact this plugin consumes — is itself an ADR-9 publication
+      # captured in the incremental fact-surface digest via factorybot's own channel, so it need not appear
+      # here. A stable sentinel declares "no OWN cross-file fact surface", keeping the plugin
+      # incremental-capable; `--verify-incremental` backstops the claim.
+      def incremental_state_fingerprint
+        "per-file-lets"
+      end
+
       private
 
       # The `file_methods:` gate set — every `let` / `subject` name the file declares anywhere. A safe

data/plugins/rigor-rspec-rails/lib/rigor/plugin/rspec_rails/http_status_codes.rb

@@ -43,7 +43,10 @@ module Rigor
 
           require "rack/utils"
           @rack_status_symbols = Rack::Utils::SYMBOL_TO_STATUS_CODE.keys.to_set.freeze
-        rescue LoadError, StandardError
+        rescue ::LoadError, ::StandardError
+          # `::`-qualified: in this lexical scope a bare `LoadError` resolves to `Rigor::Plugin::LoadError`
+          # (the plugin-loading error, a StandardError), so the real `::LoadError` (a ScriptError) from a
+          # failed require would escape instead of declining.
           @rack_status_symbols = nil
         end
       end

data/plugins/rigor-sidekiq/lib/rigor/plugin/sidekiq/worker_discoverer.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "rigor/source/node_children"
+
 require "prism"
 
 require_relative "worker_index"
@@ -67,7 +69,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_workers(child, lexical_path, &) }
+            node.rigor_each_child { |child| walk_for_workers(child, lexical_path, &) }
           end
         end
 
@@ -133,7 +135,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-sorbet/lib/rigor/plugin/sorbet/catalog_walker.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "rigor/source/node_children"
+
 require "prism"
 
 require_relative "method_signature"
@@ -58,7 +60,7 @@ module Rigor
             # A `def` not preceded by a `sig` is fine; we just don't record anything for it. The
             # interesting case is in `walk_statements`, which pairs sig+def.
           else
-            node.compact_child_nodes.each do |child|
+            node.rigor_each_child do |child|
               walk_node(child, state, lexical_path: lexical_path, in_singleton_class: in_singleton_class)
             end
           end

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

@@ -116,6 +116,18 @@ module Rigor
         errors.map { |error| parse_error_diagnostic(path, error) }
       end
 
+      # ADR-88 WD2 — the per-run catalog is an ADR-60 record-and-validate producer. Before this it was rebuilt
+      # unconditionally on every `--incremental` recheck (parse + walk every `.rb` / `.rbi` sig tree); as a
+      # producer it is cached to disk keyed on the plugin config, with `watch:` covering the scanned trees so an
+      # added / removed / edited sig file recomputes it. The producer VALUE (a Marshal-clean bundle of the
+      # catalog + the sigil map + the parse-error tuples) is what ADR-88 WD1 digests into the incremental
+      # fact-surface fingerprint, so a sig edit OUTSIDE `signature_paths:` invalidates the snapshot for free.
+      # The bundle is returned (not written to ivars) because a cache HIT does not run the block — the sigil map
+      # and parse errors would otherwise be lost on the warm path.
+      producer :catalog, watch: -> { catalog_watch_globs } do |_params|
+        build_catalog_bundle
+      end
+
       # ADR-52 slice 4 — per-call return-type path via the method-name-gated `dynamic_return` DSL. The
       # recognised name set is only known at run time (the catalog's `def` names come from the lazy
       # catalog build), so it is declared as a callable: the engine `instance_exec`s it once per run on
@@ -389,35 +401,69 @@ module Rigor
         end
       end
 
+      # ADR-88 WD2 — resolve the catalog from the `:catalog` producer (disk-cached) and unpack its Marshal-clean
+      # bundle into the ivars the return-type / sigil-gate / parse-error paths read. `producer_value` memoises
+      # per instance and rescues a producer failure to nil, hence the empty-bundle fallback.
       def ensure_catalog
         return @catalog if @catalog_built
 
+        bundle = producer_value(:catalog) || EMPTY_CATALOG_BUNDLE
+        @catalog = bundle[:catalog]
+        @sigil_by_path = bundle[:sigil_by_path]
+        @parse_errors_by_path = bundle[:parse_errors_by_path]
+        @catalog_built = true
+        @catalog
+      end
+
+      # ADR-88 WD2 — the `watch:` coverage for the `:catalog` producer: the `.rb` sig trees + the `.rbi` trees.
+      # An added / removed file under either invalidates the cached bundle even though the block globbed the
+      # tree itself. Evaluated at `cache_for` time (after `#init`), so `@configured_paths` / `@rbi_paths` are set.
+      def catalog_watch_globs
+        [[@configured_paths, "**/*.rb"], [@rbi_paths, "**/*.rbi"]]
+      end
+
+      # ADR-88 WD2 — build the Marshal-clean catalog bundle the `:catalog` producer caches. Harvests the `.rb`
+      # sig trees then the `.rbi` trees (last-wins ordering preserved from the ivar-mutating original) and
+      # returns `{ catalog:, sigil_by_path:, parse_errors_by_path: }`.
+      def build_catalog_bundle
         catalog = Catalog.new
+        sigil_by_path = {}
+        parse_errors_by_path = {}
         # Project source — `.rb` only.
-        @configured_paths.each { |root| harvest_path(root, catalog, extensions: %w[.rb]) }
+        @configured_paths.each { |root| harvest_path(root, catalog, sigil_by_path, parse_errors_by_path, %w[.rb]) }
         # Sorbet RBI tree — `.rbi` only. Slice 4 of ADR-11.
-        @rbi_paths.each { |root| harvest_path(root, catalog, extensions: %w[.rbi]) }
+        @rbi_paths.each { |root| harvest_path(root, catalog, sigil_by_path, parse_errors_by_path, %w[.rbi]) }
         catalog.freeze!
-        @catalog = catalog
-        @catalog_built = true
-        catalog
+        { catalog: catalog, sigil_by_path: sigil_by_path, parse_errors_by_path: parse_errors_by_path }
       end
 
+      # 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
+      private_constant :EMPTY_CATALOG_BUNDLE
+
       # @param root [String] directory or single file.
       # @param catalog [Catalog]
+      # @param sigil_by_path [Hash{String=>Symbol}] accumulator: harvested file → detected sigil level.
+      # @param parse_errors_by_path [Hash{String=>Array<Hash>}] accumulator: file → `{kind:,line:,column:}` tuples.
       # @param extensions [Array<String>] file extensions to accept (e.g. `[".rb"]` for project source,
       #   `[".rbi"]` for Sorbet RBI tree).
-      def harvest_path(root, catalog, extensions:)
+      def harvest_path(root, catalog, sigil_by_path, parse_errors_by_path, extensions)
         absolute = canonicalize(root)
         if File.directory?(absolute)
           extensions.each do |ext|
+            # ADR-88 WD2 — deterministic fold order matters now that the catalog VALUE is digested into the
+            # incremental fact-surface fingerprint: a duplicate `(class, method, kind)` sig's last-wins winner
+            # must not vary by machine / run. `Dir.glob` sorts its results by default on Ruby 3.0+, so the fold
+            # order is already stable (the slice-1 comment's "filesystem order" caveat predates that default);
+            # this walk relies on it rather than re-sorting.
             Dir.glob(File.join(absolute, "**", "*#{ext}")).each do |path|
-              harvest_file(canonicalize(path), catalog)
+              harvest_file(canonicalize(path), catalog, sigil_by_path, parse_errors_by_path)
             end
           end
         elsif File.file?(absolute) && extensions.any? { |ext| absolute.end_with?(ext) }
           # `paths:` may list individual files (the demos do this); walk them directly rather than skipping.
-          harvest_file(absolute, catalog)
+          harvest_file(absolute, catalog, sigil_by_path, parse_errors_by_path)
         end
       end
 
@@ -432,7 +478,7 @@ module Rigor
         expanded
       end
 
-      def harvest_file(path, catalog)
+      def harvest_file(path, catalog, sigil_by_path, parse_errors_by_path)
         contents = io_boundary.read_file(path)
         return if contents.nil?
 
@@ -441,7 +487,7 @@ module Rigor
         # Per-call-site assertion gating consults this map at recognition time. Recorded BEFORE the
         # ignored short-circuit so a `# typed: ignore` file still reports its level to the gate (the gate
         # then chooses to suppress assertions there too — `ignore` is stricter than `false`).
-        @sigil_by_path[path] = level
+        sigil_by_path[path] = level
         return if SigilDetector.ignored?(level)
 
         result = Prism.parse(contents)
@@ -460,13 +506,23 @@ module Rigor
                       end
 
         errors = CatalogWalker.walk(root: result.value, catalog: sig_catalog, path: path)
-        @parse_errors_by_path[path] = errors unless errors.empty?
+        # ADR-88 WD2 — store Marshal-clean `{kind:, line:, column:}` tuples, not the `ParseError` (it holds a
+        # live Prism node the producer bundle could not serialise). `diagnostics_for_file` rebuilds the
+        # diagnostic from the tuple, at the same 1-based line / `start_column + 1` position `from_node` gave.
+        parse_errors_by_path[path] = errors.map { |error| parse_error_tuple(error) } unless errors.empty?
       rescue Plugin::AccessDeniedError, Errno::ENOENT
         # Skip files outside the trusted read scope or that vanished between glob and read; the plugin
         # produces no output for them.
         nil
       end
 
+      # ADR-88 WD2 — the Marshal-clean position tuple for a `CatalogWalker::ParseError`, capturing the node's
+      # location at harvest time so the producer bundle carries no live Prism node.
+      def parse_error_tuple(error)
+        location = error.node.location
+        { kind: error.kind, line: location.start_line, column: location.start_column + 1 }
+      end
+
       # Emits a `plugin.sorbet.absurd-reachable` warning for the `T.absurd(x)` call recorded in
       # `@reachable_absurd_nodes` during inference; the node rule above does the identity match and pop.
       def absurd_diagnostic(path, call_node)
@@ -535,11 +591,15 @@ module Rigor
         )
       end
 
+      # ADR-88 WD2 — `error` is a Marshal-clean `{kind:, line:, column:}` tuple (the pre-computed node
+      # location), not a Prism-node-bearing `ParseError`; build the diagnostic directly at that position (the
+      # `line` / `column` `from_node` would have derived).
       def parse_error_diagnostic(path, error)
-        Rigor::Analysis::Diagnostic.from_node(
-          error.node,
+        Rigor::Analysis::Diagnostic.new(
           path: path,
-          message: parse_error_message(error.kind),
+          line: error[:line],
+          column: error[:column],
+          message: parse_error_message(error[:kind]),
           severity: :warning,
           rule: "parse-error"
         )

data/sig/prism_node_children.rbs

@@ -0,0 +1,9 @@
+# Declares the reopening `Rigor::Source::NodeChildren` performs at load: a compiled `#rigor_each_child` is defined on
+# every concrete `Prism::*Node` class (allocation-free equivalent of `compact_child_nodes.each`). Declared on the
+# abstract base so every subclass resolves; the runtime definition is per-concrete-class, generated from
+# `Prism::Reflection` in lib/rigor/source/node_children.rb.
+module Prism
+  class Node
+    def rigor_each_child: () { (Prism::Node) -> void } -> void
+  end
+end

data/sig/rigor/cache.rbs

@@ -14,6 +14,12 @@ module Rigor
     # PRODUCER_ID constant and a private `self.compute(loader)`.
     class RbsCacheProducer
       def self.fetch: (loader: untyped, store: untyped) -> untyped
+
+      # The generation cap this producer declares to `Cache::Store#evict!`
+      # (issue #151). `rigor sig-gen` infers the literal `2` from the base
+      # body; the contract is the wider `Integer`, since a subclass may
+      # override it.
+      def self.generation_cap: () -> Integer
     end
   end
 end

data/sig/rigor/inference/void_origin.rbs

@@ -0,0 +1,18 @@
+module Rigor
+  module Inference
+    # `VoidOrigin = Data.define(:class_name, :method_name, :kind)`. Declared as a `::Data` subclass because
+    # that is the shape the runtime actually builds; `sig-gen` cannot yet read a `Data.define` assignment
+    # (it reports the block body's `#label` against the enclosing namespace and drops the members).
+    class VoidOrigin < ::Data
+      attr_reader class_name: String
+      attr_reader method_name: Symbol
+      attr_reader kind: Symbol
+
+      def self.new: (class_name: String, method_name: Symbol, kind: Symbol) -> instance
+                  | (String class_name, Symbol method_name, Symbol kind) -> instance
+
+      # A human-facing `Class#method` / `Class.method` label for the diagnostic message.
+      def label: () -> String
+    end
+  end
+end