rigortype 0.3.0 → 0.3.1

data/docs/handbook/appendix-liskov.md

@@ -571,8 +571,10 @@ model"](appendix-type-theory.md#what-rigor-does-not-model) records.
   authoring the declared contracts `def.return-type-mismatch` checks
   against.
 - [Chapter 8 — Understanding errors](08-understanding-errors.md) for
-  the `def.return-type-mismatch` / `call.argument-type-mismatch`
-  rules and severity profiles.
+  what the `def.*` family claims, and
+  [manual — Diagnostics](../manual/04-diagnostics.md) for the
+  `def.return-type-mismatch` / `call.argument-type-mismatch`
+  entries and the severity profiles.
 
 If you want to compare against another *tool* rather than the
 *principle*, the sibling appendices cover

data/docs/handbook/appendix-phpstan.md

@@ -72,8 +72,10 @@ in another tab, almost every advanced refinement transfers.
 ## The `@phpstan-assert` family
 
 PHPStan's assertion-narrowing PHPDoc tags map directly onto
-Rigor's `RBS::Extended` directive grammar. Chapter 7 covers
-the table in depth; here it is again for reference:
+Rigor's `RBS::Extended` directive grammar. This is the mapping;
+[Chapter 7](07-rbs-and-extended.md) works the Rigor side
+through examples, and the directive reference itself is
+[manual — RBS::Extended annotations](../manual/16-rbs-extended-annotations.md):
 
 | PHPStan PHPDoc | Rigor RBS::Extended | Effect |
 | --- | --- | --- |
@@ -149,7 +151,8 @@ Rigor has two baseline mechanisms: a **managed** baseline
 the next `rigor check` via the `baseline:` config key — the
 closest match to PHPStan's `--baseline`), and a **lightweight**
 ad-hoc snapshot (`rigor diff` over a `--format=json` dump).
-Chapter 8 has the walkthrough.
+[Manual — Baselines](../manual/06-baseline.md) walks through
+both.
 
 The `includes:` semantics also match PHPStan's: declaration
 order, later overrides earlier, the current file's keys win
@@ -322,11 +325,15 @@ You probably do not need to read the rest of this appendix
 section sequentially. Three useful pointers:
 
 - [Chapter 7 — RBS and `RBS::Extended`](07-rbs-and-extended.md)
-  has the full directive grammar, including the PHPStan-mapping
-  table that this page summarises.
+  works the directive grammar through examples; the reference
+  table is
+  [manual — RBS::Extended annotations](../manual/16-rbs-extended-annotations.md).
 - [Chapter 8 — Understanding errors](08-understanding-errors.md)
-  covers the rule catalogue, severity profiles, baseline
-  diffing — every PHPStan onboarding analogue.
+  explains how to read a diagnostic and which knob to reach
+  for; the catalogue, severity profiles and baselines — every
+  PHPStan onboarding analogue — are
+  [manual — Diagnostics](../manual/04-diagnostics.md) and
+  [manual — Baselines](../manual/06-baseline.md).
 - [Chapter 9 — Plugins](09-plugins.md) for the
   Type-Specifying / Dynamic-Return analogues.
 

data/docs/handbook/appendix-steep.md

@@ -321,8 +321,10 @@ section sequentially. Three useful pointers:
   if you want to see how the directive grammar layers on top
   of the RBS you already write.
 - [Chapter 8 — Understanding errors](08-understanding-errors.md)
-  for the rule catalogue, severity profiles, and baseline
-  diffing — the analogue to Steep's diagnostic config.
+  for how to read a diagnostic, and
+  [manual — Diagnostics](../manual/04-diagnostics.md) for the
+  rule catalogue and severity profiles — the analogue to
+  Steep's diagnostic config.
 - [`docs/notes/20260503-steep-cross-check-triage.md`](../notes/20260503-steep-cross-check-triage.md)
   for a worked side-by-side run of Steep and Rigor on the
   same project (the project itself).

data/docs/handbook/appendix-type-theory.md

@@ -1651,7 +1651,9 @@ practical companion:
   for the directive grammar that lets you teach Rigor about a
   custom predicate.
 - [Chapter 8 — Understanding errors](08-understanding-errors.md)
-  for the rule catalogue (the user-visible end of the trinary
+  for how a diagnostic reads, and
+  [manual — Diagnostics](../manual/04-diagnostics.md) for the
+  rule catalogue (the user-visible end of the trinary
   certainty).
 
 If you want to compare against another *tool* rather than the

data/docs/manual/02-cli-reference.md

@@ -479,6 +479,7 @@ so a skill can never be shadowed by a verb.
 
 ```sh
 rigor skill [<name>] [--full <name>] [--path <name>] [--list] [--describe]
+rigor skill describe [--deep]
 ```
 
 | Form | Purpose |
@@ -488,6 +489,33 @@ rigor skill [<name>] [--full <name>] [--path <name>] [--list] [--describe]
 | `--full <name>` | Print the `SKILL.md` body **followed by every `references/*.md` inline** — the complete, version-current procedure in one call. This is what a skill's "First: load the version-current copy" directive points at, so a copy vendored into a project (e.g. via `npx skills add`) re-fetches its current steps from the installed gem instead of following a frozen copy. |
 | `--path <name>` | Print the single-line absolute `SKILL.md` path, suitable as input to a file-reading tool. |
 | `--describe` | Probe the project's state (config / baseline / `sig/` / CI — presence only, never runs `rigor check`) and recommend the next skill to run. Also spelled `describe`; surfaced top-level as [`rigor describe`](#rigor-describe) below. |
+| `describe --deep` | The same report, except it **runs `rigor check` first** and routes the headline recommendation on the result. Opt-in, because it costs a full analysis and writes `.rigor/cache` — the un-flagged form stays presence-only and side-effect-free. |
+
+### `describe --deep`
+
+By default the recommendation comes from a presence-only probe, so it can
+tell that a project *has* a config but not whether the analysis is
+healthy. `--deep` runs the check for you and lets the result pick the
+headline, using the same routing the `## For the agent` section already
+teaches:
+
+| Deep check result | Headline becomes |
+| --- | --- |
+| RBS environment built to 0 classes, or a `configuration-error` diagnostic | `rigor-doctor` — the analysis is hollow until the setup is fixed. |
+| Call sites resolving to the project's own definitions (reopened core / gem classes), as at least a third of the errors | `rigor-monkeypatch-resolve` — list them in `pre_eval:` and they clear wholesale. |
+| Any remaining error diagnostics | `rigor-baseline-reduce`. Proven monkey-patch sites below that share are still reported here, so the finding survives even when the headline stays on the larger problem. |
+| Clean, or the project has no config yet | Unchanged — the presence-only recommendation stands. |
+
+If the check **cannot run at all** (no config, an unloadable plugin, a
+malformed config) `--deep` does not fail and does not pretend the project
+is clean: it reports what went wrong, falls back to the presence-only
+recommendation, and points you at `rigor doctor`. It deliberately does
+*not* route on weaker signals — "framework calls typing as `Dynamic`" is
+still a judgement call left to you and your agent.
+
+```sh
+rigor skill describe --deep   # also: rigor describe --deep
+```
 
 The verb spellings `rigor skill list` / `print <name>` / `path <name>`
 were **removed in v0.3.0** — the positional slot is a skill name, so
@@ -511,6 +539,10 @@ It reports a presence-only project-state probe (does a `.rigor.yml`,
 recommended next skill. It is read-only and side-effect-free — it never
 runs `rigor check`. Identical output to `rigor skill describe`.
 
+`rigor describe --deep` forwards to
+[`rigor skill describe --deep`](#rigor-skill), which opts into running the
+check first — slow, and it writes the cache.
+
 ## `rigor docs`
 
 Print the documentation bundled inside the `rigortype` gem

data/docs/manual/04-diagnostics.md

@@ -97,7 +97,21 @@ re-stamps it for the run. Three profiles, set with the
 | --- | --- |
 | `lenient` | Only proven diagnostics are errors; uncertain ones drop to `warning` / `info`. For incremental adoption on legacy code. |
 | `balanced` *(default)* | Most rules `error`; `dump.type` `info`; uncertain rules `warning`. |
-| `strict` | Nearly every rule is an `error` — the exceptions are `call.self-undefined-method` (stays `off`, opt-in only) and `flow.unreachable-clause` (`warning`, pending its false-positive gate). CI-friendly. |
+| `strict` | Nearly every rule is an `error`. The exceptions: `call.self-undefined-method` and `static.value-use.void` stay `off` (both opt-in only), `flow.unreachable-clause` stays `warning` pending its false-positive gate, and the three `suppression.*` rules stay `warning` — a stale suppression comment is worth telling you about, but it is not a reason to fail a build. CI-friendly. |
+
+Under `balanced`, the rules that do **not** emit as `error`
+are:
+
+| Severity | Rules |
+| --- | --- |
+| `warning` | `call.unresolved-toplevel`, `def.ivar-write-mismatch`, `def.return-type-mismatch`, `def.override-visibility-reduced`, `def.override-return-widened`, `def.override-param-narrowed`, `flow.unreachable-branch`, `flow.always-truthy-condition`, `flow.dead-assignment`, `flow.duplicate-hash-key`, `flow.return-in-ensure`, `flow.shadowed-rescue-clause`, `suppression.unknown-rule`, `suppression.empty`, `suppression.unknown-marker` |
+| `info` | `flow.unreachable-clause`, `dump.type` |
+| `off` | `call.self-undefined-method`, `static.value-use.void` |
+
+Everything else emits as `error`. For one rule under all three
+profiles, `rigor explain <rule>` prints `Authored severity:` and
+`Severity by profile:` — that output is generated from the rule
+catalogue itself, so it is the per-rule source of truth.
 
 For finer control, `severity_overrides:` maps a rule ID or a
 family to one of `error`, `warning`, `info`, or `off`:
@@ -109,7 +123,15 @@ severity_overrides:
   call: warning
 ```
 
-A rule-specific override beats a family override.
+A rule-specific override beats a family override. `off` drops
+the diagnostic from the result entirely, which makes
+`severity_overrides:` the lighter-touch sibling of `disable:`
+below — both silence a rule; the override reads as "this one
+rule, at this severity" alongside the rest of the profile.
+
+YAML reserves the bareword `off` as a boolean. If an override
+that names it seems not to apply, quote it — `"off"` — and the
+same for `on`.
 
 ## Machine-readable output (`--format json`)
 
@@ -198,7 +220,10 @@ config.merge(extra)  # rigor:disable call.undefined-method
 ```
 
 It accepts qualified IDs, family wildcards (`call`), a
-comma- or space-separated list, or `all`.
+comma- or space-separated list, or `all`. The comment must sit
+on the line the diagnostic points at; there is no
+`disable-block` form, so an expression spread over several
+lines needs the comment on each line that fires.
 
 A marker that cannot work is flagged rather than silently
 ignored: a token that names no known rule (a typo like
@@ -217,7 +242,14 @@ suppressible like any other rule.
 
 **In-source, whole file.** `# rigor:disable-file <rules>`
 anywhere in a file suppresses those rules for every line;
-`# rigor:disable-file all` silences the file.
+`# rigor:disable-file all` silences the file. Convention is to
+put it near the top — typically on a generated file, a fixture,
+or a vendored snippet — but every comment in the file is
+scanned, so any placement works.
+
+The three layers **compose**: a file-scope marker does not
+cancel a line-scope one, and a project-wide `disable:` still
+applies to a file that carries neither.
 
 **Project-wide.** The `disable:` config key turns rules off
 across the whole run:

data/docs/manual/06-baseline.md

@@ -4,7 +4,11 @@ A **baseline** records the diagnostics a project already has,
 so `rigor check` can stay silent about them and surface only
 what is *new*. It is the pragmatic on-ramp for adopting Rigor
 on an existing codebase: you do not have to reach zero
-diagnostics before the check becomes useful in CI.
+diagnostics before the check becomes useful in CI. It is also
+what the [`rigor-project-init` skill](08-skills.md) snapshots
+for you at onboarding
+([ADR-22](../adr/22-baseline-and-project-onboarding.md) is the
+design).
 
 ## The baseline file
 
@@ -89,6 +93,36 @@ unless you specifically need per-message discrimination, and
 expect to `regenerate` a `message`-mode baseline after upgrading
 Rigor.
 
+## The ad-hoc form — `rigor diff`
+
+A managed baseline is not the only way to fail CI on *new*
+diagnostics only. The lightweight alternative keeps a plain JSON
+snapshot in the repository and compares against it explicitly:
+
+```sh
+# Once: capture the current diagnostic surface.
+rigor check --format=json > rigor.baseline.json
+git add rigor.baseline.json
+
+# Per PR: compare against the committed snapshot.
+rigor diff rigor.baseline.json
+```
+
+[`rigor diff`](02-cli-reference.md#rigor-diff) prints a `+ NEW`
+row for every diagnostic absent from the snapshot and a
+`- FIXED` row for every one resolved since, and exits `1` when
+anything is new — so a PR that adds a violation fails while the
+recorded legacy ones stay quiet. `--format=json` is available
+for editor and dashboard integrations. Regenerate the snapshot
+with the same `rigor check --format=json` redirection whenever
+you fix a row, and the project tightens monotonically.
+
+The difference from a managed baseline is where the knowledge
+lives: `rigor diff` is a separate step your CI script has to
+run, while a `baseline:` file makes `rigor check` itself exit
+clean on recorded diagnostics. Prefer the managed form unless
+you specifically want the raw JSON snapshot.
+
 ## Working a baseline down
 
 `rigor triage` summarises a diagnostic stream — rule

data/docs/manual/08-skills.md

@@ -106,6 +106,7 @@ source checkout. The `rigor skill` command surfaces them:
 
 ```sh
 rigor skill describe        # probe the project + recommend the next skill (alias: rigor describe)
+rigor skill describe --deep # same, but run `rigor check` first and route on its result
 rigor skill --list          # name + absolute path for each bundled skill
 rigor skill <name>          # print the SKILL.md body (with a references/ header)
 rigor skill --full <name>   # the body + every references/*.md inline (complete procedure)
@@ -113,7 +114,11 @@ rigor skill --path <name>   # one-line absolute SKILL.md path, for a file-readin
 ```
 
 `rigor skill describe` is the recommendation engine driven by
-`rigor-next-steps`; `rigor skill rigor-project-init` is the
+`rigor-next-steps`. It is a presence-only probe by default — cheap and
+side-effect-free; add `--deep` when you want the recommendation to come
+from a real analysis instead
+([CLI reference](02-cli-reference.md#describe---deep)).
+`rigor skill rigor-project-init` is the
 canonical way to hand an agent the onboarding workflow without pointing
 it at the repository. The `list` / `print` / `path` verb spellings are
 deprecated (removed in v0.3.0). See [CLI reference](02-cli-reference.md#rigor-skill).

data/docs/manual/09-editor-integration.md

@@ -18,6 +18,7 @@ design + capability matrix lives in
 
 | LSP method | Behaviour |
 |---|---|
+| `textDocument/didOpen` / `didChange` / `didClose` | Incremental sync (`TextDocumentSyncKind::Incremental`): a `didChange` carries range edits, which are spliced into the buffer the server already holds instead of re-sending and re-parsing the whole document on every keystroke. Positions are read as UTF-16 code-unit offsets (`positionEncoding: "utf-16"`), so an emoji or other non-BMP character counts as two. The full-text change form stays supported. |
 | `textDocument/publishDiagnostics` | Pushed on every `didChange`, 200ms debounced. Severity / rule / source map directly to Rigor's diagnostic taxonomy. |
 | `textDocument/hover` | Type-aware markdown. Per-node-class dispatch surfaces receiver type + RBS signature for method calls, FQN + singleton type + defined-in path for constants, narrowed type + bound-at for locals, canonical refinement names (`non-empty-string`, …) for `Refined` / `Difference` carriers. |
 | `textDocument/completion` | Method completion after `.` (driven by inferred receiver type), constant-path completion after `::`. Composite receivers (Union → intersection of methods, Tuple / HashShape → ancestor nominal, Refined → underlying nominal) handled. Parse-recovery sentinel makes mid-edit `obj.` / `Foo::` buffers work. |
@@ -234,8 +235,8 @@ Cold start is dominated by RBS environment build; warm starts
 
 LSP v1 + v2 landed in v0.1.6 and ship in the `0.1.x` line. Queued
 follow-ups (`textDocument/signatureHelp`, hash-key completion,
-`textDocument/definition`, incremental `didChange` sync, Ractor
-pool dispatch, codeAction / rename / semanticTokens / inlayHint)
+`textDocument/definition`, Ractor pool dispatch,
+codeAction / rename / semanticTokens / inlayHint)
 are demand-driven; the current queue is the open
 [`area:editor` issues](https://github.com/rigortype/rigor/issues?q=is%3Aissue+is%3Aopen+label%3Aarea%3Aeditor).
 

data/docs/manual/plugins/rigor-actioncable.md

@@ -44,6 +44,30 @@ or `stream_for record`) — the absence of a literal match doesn't prove
 the stream is invalid. Non-`Channel` receivers and non-literal stream
 arguments pass through silently.
 
+## `#receive(data)` parameter typing
+
+The plugin also carries an [ADR-28](../../adr/28-path-scoped-protocol-contracts.md)
+path-scoped protocol contract: inside any `#receive(data)` defined
+under `channel_search_paths`, `data` types as `Hash` instead of
+`Dynamic[Top]`. `#receive` is ActionCable's framework-dispatched
+catch-all action — invoked with the decoded JSON payload when an
+incoming message carries no `"action"` key — so the parameter shape is
+uniform across every channel.
+
+```ruby
+# app/channels/chat_channel.rb
+class ChatChannel < ApplicationCable::Channel
+  def receive(data)
+    data["body"]           # data: Hash
+    data.no_such_method    # error: call.undefined-method
+  end
+end
+```
+
+Custom action methods (`def speak(data)`) are not covered — their
+names are project-chosen, and a protocol contract names a single fixed
+method. Only `#receive` is a reserved, uniformly-shaped hook.
+
 ## Configuration
 
 ```yaml
@@ -54,6 +78,11 @@ plugins:
       channel_base_classes: ["ApplicationCable::Channel", "ActionCable::Channel::Base"] # default
 ```
 
+`channel_search_paths` also retargets the `#receive` protocol
+contract's glob — including for multiple configured roots — so a
+custom channel directory gets the same `data: Hash` typing as the
+default.
+
 ## Limitations
 
 - **Direct-superclass match only.** An indirect chain (`AdminChannel <
@@ -68,6 +97,9 @@ plugins:
   than directly in the channel body) is out of scope.
 - **Bare `broadcast(...)`** without an explicit `ActionCable.server`
   receiver is skipped to avoid false positives on unrelated methods.
+- **The `#receive` contract is path-scoped, not class-scoped** (ADR-28):
+  any `def receive(data)` defined anywhere under `channel_search_paths`
+  is typed, even on a class that isn't an ActionCable channel.
 
 ## Plugin internals
 

data/docs/manual/plugins/rigor-devise.md

@@ -64,7 +64,9 @@ The macro manifest (the trait registry mapping each strategy to its
 module), the concern re-targeting walk, the demo, and the
 contract surfaces this plugin exercises are in the
 [plugin's README](../../../plugins/rigor-devise/README.md);
-[handbook chapter 9](../../handbook/09-plugins.md) covers the Tier B
-macro substrate generally. To write a plugin, see
+[`docs/internal-spec/macro-substrate.md`](../../internal-spec/macro-substrate.md)
+specifies the Tier B trait registry generally, and
+[handbook chapter 9](../../handbook/09-plugins.md) is the
+orientation. To write a plugin, see
 [`examples/`](../../../examples/README.md) and the
 [`rigor-plugin-author`](../08-skills.md) skill.

data/lib/rigor/analysis/check_rules/void_value_use_collector.rb

@@ -36,6 +36,12 @@ module Rigor
           Prism::ConstantWriteNode, Prism::ConstantPathWriteNode
         ].freeze
 
+        # ADR-53 Track B — the node classes the shared {RuleWalk} dispatches to this collector: the consumer
+        # nodes whose slots are value positions. Prism node classes are leaves, so class-equality dispatch
+        # matches the legacy walk's `case`. No context gate — a value-context void use is a use wherever the
+        # DFS reaches it, loops and blocks included.
+        NODE_CLASSES = [Prism::CallNode, *WRITE_NODE_CLASSES].freeze
+
         Result = Data.define(:void_node, :origin)
 
         def initialize(scope_index)
@@ -43,14 +49,27 @@ module Rigor
           @results = []
         end
 
-        # Walk the whole subtree once, checking each consumer node's value slots. Returns one {Result} per
-        # value-context use of a recovered-`void` call.
+        # Legacy single-collector walk — kept as the oracle the ADR-53 Track B equivalence harness compares
+        # {RuleWalk} against. Walks the whole subtree once, checking each consumer node's value slots.
+        # Returns one {Result} per value-context use of a recovered-`void` call.
         # @return [Array<Result>]
         def collect(root)
           walk(root)
           @results.freeze
         end
 
+        # {RuleWalk} entry point: the legacy walk's per-node slot inspection, invoked at every consumer node
+        # under the shared traversal contract. The `context` is unused — every consumer node is inspected.
+        def visit(node, _context = nil)
+          inspect_consumer(node)
+        end
+
+        # The accumulated result, frozen the same way `#collect` returns it — used by {RuleWalk}-driven
+        # callers after the walk completes.
+        def results
+          @results.freeze
+        end
+
         private
 
         def walk(node)

data/lib/rigor/analysis/check_rules.rb

@@ -97,7 +97,6 @@ module Rigor
         collectors = node_collectors || run_node_collectors(path, root, scope_index)
         diagnostics = collectors[:main_pass].results.dup
         diagnostics.concat(self_undefined_method_diagnostics(path, self_call_misses, root, scope_index))
-        diagnostics.concat(void_value_use_diagnostics(path, root, scope_index))
         COLLECTOR_DIAGNOSTIC_BUILDERS.each do |role, builder|
           diagnostics.concat(send(builder, path, collectors[role].results))
         end
@@ -109,10 +108,13 @@ module Rigor
       end
 
       # The per-collector diagnostic builders {.diagnose} folds over, in the historical emission order
-      # (always-truthy → unreachable-clause → shadowed-rescue → ivar-write → dead-assignment →
-      # duplicate-hash-key → return-in-ensure). Keys match {.build_node_collectors}' roles; each value is a
-      # `(path, results)` module_function on this module.
+      # (value-use-void → always-truthy → unreachable-clause → shadowed-rescue → ivar-write →
+      # dead-assignment → duplicate-hash-key → return-in-ensure). Keys match {.build_node_collectors}'
+      # roles; each value is a `(path, results)` module_function on this module. `void_value_use` leads
+      # because its standalone walk used to run before this fold, and the emission order is byte-identical
+      # output, not an implementation detail.
       COLLECTOR_DIAGNOSTIC_BUILDERS = {
+        void_value_use: :void_value_use_diagnostics,
         always_truthy: :always_truthy_condition_diagnostics,
         unreachable_clauses: :unreachable_clause_diagnostics,
         shadowed_rescues: :shadowed_rescue_diagnostics,
@@ -155,6 +157,7 @@ module Rigor
       def build_node_collectors(path, scope_index)
         {
           main_pass: MainPassCollector.new(->(node) { main_pass_node_diagnostics(path, node, scope_index) }),
+          void_value_use: VoidValueUseCollector.new(scope_index),
           always_truthy: AlwaysTruthyConditionCollector.new(scope_index),
           unreachable_clauses: UnreachableClauseCollector.new(scope_index),
           shadowed_rescues: ShadowedRescueCollector.new(scope_index),
@@ -354,12 +357,11 @@ module Rigor
         end
       end
 
-      # ADR-100 WD2 — `static.value-use.void`. Runs a standalone walk (like `self_undefined_method_diagnostics`)
-      # over `root`, so its value-context slot inspection stays independent of the shared per-node
-      # {RuleWalk}. Each result is a value-context use of a call whose author-declared `-> void` return the
-      # engine recovered to `top`.
-      def void_value_use_diagnostics(path, root, scope_index)
-        VoidValueUseCollector.new(scope_index).collect(root).map do |result|
+      # ADR-100 WD2 — `static.value-use.void`. Its value-context slot inspection rides the shared per-node
+      # {RuleWalk} like the other collectors, so the file is not re-traversed for it. Each result is a
+      # value-context use of a call whose author-declared `-> void` return the engine recovered to `top`.
+      def void_value_use_diagnostics(path, results)
+        results.map do |result|
           build_void_value_use_diagnostic(path, result)
         end
       end
@@ -2117,7 +2119,7 @@ module Rigor
           arguments = call_node.arguments&.arguments || []
           arguments.each_with_index do |arg, index|
             arg_type = scope.type_of(arg)
-            params = overload_positional_params(functions, index)
+            params = overload_positional_params(method_types, index)
             next if params.nil? # arity divergence — some overload lacks a param here
 
             mismatch =
@@ -2152,11 +2154,30 @@ module Rigor
         # The matching positional RBS param across every overload, or nil when
         # any overload has no param at `index` (arity divergence — the
         # wrong-arity rule's concern, not this one's).
-        def overload_positional_params(functions, index)
-          params = functions.map { |function| (function.required_positionals + function.optional_positionals)[index] }
+        def overload_positional_params(method_types, index)
+          params = method_types.map do |method_type|
+            function = method_type.type
+            param = (function.required_positionals + function.optional_positionals)[index]
+            param && resolve_param_bounds(param, method_type)
+          end
           params.any?(&:nil?) ? nil : params
         end
 
+        # Substitutes each bounded method-level type parameter for its bound, so
+        # `[I < _ToInt] (I index) -> …` is walked as `(_ToInt index) -> …`. A bare
+        # `Variable` is undecidable to the acceptance walk and admits everything,
+        # which silently disables both channels for the whole overload; the bound
+        # constrains the argument exactly as an ordinary param of that type would.
+        # Load-bearing since rbs 4.1 rewrote core signatures into this form
+        # (`Array#fetch`'s block overload is `[I < _ToInt, T] (I index) { … }`).
+        def resolve_param_bounds(param, method_type)
+          bounded = method_type.type_params.select(&:upper_bound)
+          return param if bounded.empty?
+
+          substitution = RBS::Substitution.build(bounded.map(&:name), bounded.map(&:upper_bound))
+          param.map_type { |type| type.sub(substitution) }
+        end
+
         # The class names whose instances `nil` IS — `NilClass` and every
         # ancestor. A parameter typed as any other class instance rejects nil.
         NIL_COMPATIBLE_CLASS_NAMES = %w[NilClass Object BasicObject Kernel].to_set.freeze

data/lib/rigor/analysis/run_cache_key.rb

@@ -36,6 +36,16 @@ module Rigor
 
       RUN_DIAGNOSTICS_PRODUCER_ID = "analysis.run-diagnostics"
 
+      # The run-result producer's declared compaction budget (`Cache::Store#evict!` pass 2). Whole-project,
+      # but unlike the `rbs.*` producers several generations can be live at once: the `paths` key slot means
+      # one entry per analyzed-path SET, so `rigor check` over the whole project, over `lib`, and over a
+      # single file are three separate live generations. 16 is a judgement call sized for that churn; it is
+      # a cap on GENERATIONS, not on correctness — over-evicting here costs a recompute, never a wrong
+      # answer. Measured 2026-07-25 against a real project's `.rigor/cache`: the cap does bind (60 distinct
+      # path-set generations observed, differing in the `paths` slot alone), with no evidence yet on how
+      # often an evicted generation is asked for again — see issue #151.
+      GENERATION_CAP = 16
+
       # @param rbs_config_entries [Array<Cache::Descriptor::ConfigEntry>] the RBS-derived config slots
       #   (`rbs.libraries` [+ `rbs.virtual_rbs`]). nil on any failure so a malformed key disables the cache.
       def descriptor(configuration:, files:, explain:, rbs_config_entries:)

data/lib/rigor/analysis/runner.rb

@@ -454,7 +454,8 @@ module Rigor
 
         computed = false
         diagnostics = @cache_store.fetch_or_validate(
-          producer_id: RunCacheKey::RUN_DIAGNOSTICS_PRODUCER_ID, key_descriptor: key_descriptor
+          producer_id: RunCacheKey::RUN_DIAGNOSTICS_PRODUCER_ID, key_descriptor: key_descriptor,
+          generation_cap: RunCacheKey::GENERATION_CAP
         ) do
           computed = true
           diags = assemble_run_diagnostics(expansion, environment: environment)

data/lib/rigor/cache/rbs_cache_producer.rb

@@ -15,12 +15,22 @@ module Rigor
     # `self::PRODUCER_ID` resolves the constant on the concrete subclass, and `compute(loader)` dispatches to
     # its private class method. See the `_CacheProducer` RBS interface for the structural contract.
     class RbsCacheProducer
+      # Every RBS producer is whole-project and content-keyed: one entry is live and any older generation is
+      # unreachable, so `Cache::Store#evict!` keeps a small number of them (one spare for the still-warm
+      # previous signature state — the RBS environment blob alone runs to ~1.8 MB, ADR-54 WD3). Declared on
+      # the base, so a producer added by subclassing inherits a cap instead of being silently uncapped; a
+      # subclass with different economics overrides this method.
+      def self.generation_cap
+        2
+      end
+
       def self.fetch(loader:, store:)
         # ADR-54 WD4 — the descriptor is identical for every producer consulting the same loader (same sig
         # files, same libraries), so the loader memoises one build per process instead of re-digesting every
         # .rbs file once per producer.
         descriptor = loader.rbs_cache_descriptor
-        store.fetch_or_compute(producer_id: self::PRODUCER_ID, params: {}, descriptor: descriptor) do
+        store.fetch_or_compute(producer_id: self::PRODUCER_ID, params: {}, descriptor: descriptor,
+                               generation_cap: generation_cap) do
           compute(loader)
         end
       end

data/lib/rigor/cache/rbs_environment_marshal_patch.rb

@@ -17,6 +17,20 @@ require "rbs"
 #
 # Idempotent: the guard checks `method_defined?(:_dump)` so requiring this file twice (or against an upstream
 # rbs that adds Marshal hooks itself) is a no-op.
+#
+# `RBS::TypeName` / `RBS::Namespace` carry a second, subtler Marshal hazard, introduced by rbs 4.1's
+# flyweight interning (ruby/rbs#2957): both memoise their `#hash` into an `@hash` ivar, and that value is
+# derived from `Array#hash` / `Symbol#hash`, which Ruby seeds PER PROCESS. Marshal round-trips the ivar
+# verbatim, so a cached `TypeName` loaded in a later process answers `hash` with the *writing* process's
+# value while a freshly parsed `TypeName.parse("::String")` answers with this process's. The two are still
+# `eql?`, so nothing raises — every Hash keyed by a TypeName simply misses. `RBS::Environment#class_decls`
+# is exactly such a Hash, so a warm cache silently reported every core class as unknown.
+#
+# `_dump` / `_load` on both classes fixes it at the representation: the name is dumped as its source string
+# and reconstructed through `.parse`, which routes back through the flyweight interner. That drops the stale
+# `@hash` (it is re-memoised on demand, under this process's seed), and restores the flyweight identity the
+# interner exists to provide — a cached env now shares one object per distinct name rather than one per
+# reference. Both classes are value objects fully described by `to_s`, so the round-trip is lossless.
 module RBS
   class Location
     unless method_defined?(:_dump)
@@ -29,4 +43,28 @@ module RBS
       end
     end
   end
+
+  class Namespace
+    unless method_defined?(:_dump)
+      def _dump(_)
+        to_s
+      end
+
+      def self._load(string)
+        parse(string)
+      end
+    end
+  end
+
+  class TypeName
+    unless method_defined?(:_dump)
+      def _dump(_)
+        to_s
+      end
+
+      def self._load(string)
+        parse(string)
+      end
+    end
+  end
 end