rigortype 0.3.1 → 0.3.3

data/docs/manual/12-caching.md

@@ -28,12 +28,23 @@ on:
 - the **content** of the source and `.rbs` files that fed it,
 - the **gems** in play, by name and locked version,
 - the active **plugins**, by ID and version,
-- the relevant **configuration**.
+- the relevant **configuration**,
+- **Rigor itself**, by version.
 
 Change any of those and the dependent entries are recomputed
 automatically. A corrupt or unreadable entry is treated as a
 miss and overwritten — bad cache state cannot wedge a run.
 
+Rigor's version identifies its own code only for a released gem.
+If you run Rigor from a git checkout — a working copy you are
+patching, or `gem "rigor", github:` tracking a branch, where two
+commits share one version number — the entries that hold
+analysis results are keyed on the content of Rigor's own source
+as well, so editing the analyzer and re-running recomputes
+instead of replaying the previous answer. That costs one pass
+over Rigor's source per run (about 20 ms); an installed gem
+neither pays it nor needs it.
+
 The cache is also schema-versioned: after a Rigor upgrade that
 changes the cache format, the stale cache is purged on the
 first writable run.
@@ -157,10 +168,11 @@ affected files in parallel just as a full run does.
 
 The snapshot lives under the cache directory (`.rigor/cache`)
 and is keyed by a fingerprint of your configuration, your locked
-gems, your project's own `sig/` RBS, and the Rigor version.
-Change any of those and the snapshot is dropped and the next run
-is a full one, so an incremental run can never serve a stale
-result. (The fingerprint keys on the analysis *roots* — e.g.
+gems, your project's own `sig/` RBS, the Rigor version, and — if
+you run Rigor from a checkout — the content of Rigor's own
+source. Change any of those and the snapshot is dropped and the
+next run is a full one, so an incremental run can never serve a
+stale result. (The fingerprint keys on the analysis *roots* — e.g.
 `["lib"]` — not the expanded file list, so adding or removing a
 file *under* those roots does **not** drop the snapshot: the
 incremental session re-analyzes the added files and the

data/docs/manual/15-type-protection-coverage.md

@@ -48,6 +48,17 @@ power. `--threshold=RATIO` turns it into a CI gate (exit `1`
 below the ratio) and `--format=json` carries the structured
 fields.
 
+Some `protected` sites are typed only through call-site
+[parameter inference](03-configuration.md) (`parameter_inference:`
+— an undeclared parameter seeded from what its callers pass)
+rather than a declaration — a lower bound that can only widen, so
+none of Rigor's negative rules fire against it yet
+([ADR-67](../adr/67-parameter-type-inference.md) WD6b). The text
+report calls these out as "lower-bound-typed" when there are any,
+and the JSON form always carries the count as `lower_bound_typed`.
+It is a sub-count *within* `protected`, never subtracted from it —
+the protected ratio itself is unaffected.
+
 On a large project, `--workers=N` fork-parallelizes the scan
 (both the parameter-inference pre-pass and the per-file scan),
 with output byte-identical to a sequential run. The worker count
@@ -74,11 +85,117 @@ real "add a type here" site, surfaced with no guesswork.
 
 It runs many analyses, so it defaults to the **git-changed** `.rb`
 files (pass explicit paths to widen — whole-project is minutes) and
-is an opt-in CI deep-dive, not an interactive check. The framing is
+is an opt-in CI deep-dive, not an interactive check. `--workers=N`
+applies here too, and it is the main lever on a wide run: the
+whole-project pre-pass is paid once, then the per-file measurement —
+which is nearly all of the wall time — is fork-mapped across
+workers, byte-identically to a sequential run.
+
+The framing is
 always *effectiveness / where to add a type*, never "your code is
 broken": a surviving breakage at a `Dynamic` site is a place
 the type net does not reach.
 
+### Re-running it is cheap
+
+Each file's measurement is cached and served back while nothing
+that could change it has moved — the file itself, any file it was
+recorded as reading from, the resolved configuration, your `sig/`,
+the gem set, the engine version, `--limit` / `--seed`, and which
+bleeding-edge features you have adopted. Edit one file and that
+file plus the files recorded as reading from it are re-measured;
+the rest are served. A one-line stderr report says what happened,
+so `--format=json` stdout stays clean:
+
+```
+coverage: mutation cache — re-measured 2 file(s), 350 served from cache.
+```
+
+The cache reads the cross-file dependency edges that a
+`rigor check --incremental` run records, so warm one once per
+project:
+
+```sh
+rigor check --incremental                    # records the edges
+rigor coverage --protection --mutation lib   # measures, then caches
+```
+
+Without that snapshot — or under `--no-cache`, or with
+`dependent-closure-kill-oracle` adopted, whose verdicts depend on
+*other* files' diagnostics and so cannot be validated per file —
+every file is re-measured and the stderr line names the reason. A
+file the snapshot does not know about is re-measured rather than
+served: the cache never guesses.
+
+### Which sites Tier 2 measures
+
+Tier 2 only mutates a site where Rigor holds a *concrete* receiver
+type — at a `Dynamic` receiver the breakage would survive by
+construction, which measures nothing. Today it decides that from
+the file alone, so a call on a project class declared in a
+**sibling** file (`Post.where`, `Account.find`) reads `Dynamic` and
+the site is left out of the denominator entirely, even though Tier
+1 counts it.
+
+The [`discovery-seeded-mutation-sites`](02-cli-reference.md#rigor-show-bleedingedge)
+bleeding-edge feature closes that gap, giving Tier 2 the same
+cross-file view Tier 1 has — on *both* halves of the measurement,
+site selection and the re-analysis that decides whether a mutation
+was caught, so an admitted site is one a breakage can really trip:
+
+```yaml
+# .rigor.yml
+bleeding_edge:
+  - discovery-seeded-mutation-sites
+```
+
+It is **off by default and opt-in on purpose**. Those sites are
+mostly ones the type net does not yet catch, so admitting them
+*lowers* the reported effectiveness ratio on unchanged code — and
+`--threshold=RATIO` exits 1 below a ratio you pin in CI. Adopt it
+when you are ready to re-baseline that number; it is the intended
+default at a future major.
+
+### Where a catch is allowed to land
+
+Deciding whether a breakage was caught is a separate question from
+which sites are measured, and it has the same blind spot in the
+opposite direction. Tier 2 re-analyses the mutated file and looks
+at *that file's* diagnostics — so the most valuable catch Rigor
+delivers is scored as a miss. Change what a method returns and the
+error appears in its **callers**, which is exactly the cross-file
+reach the analyzer exists for.
+
+The [`dependent-closure-kill-oracle`](02-cli-reference.md#rigor-show-bleedingedge)
+bleeding-edge feature re-analyses the mutated file **and the files
+that depend on it**, and counts the breakage as caught when a new
+diagnostic appears anywhere in that set:
+
+```yaml
+# .rigor.yml
+bleeding_edge:
+  - dependent-closure-kill-oracle
+```
+
+It composes with the site seed above — one decides what is
+measured, the other where a catch may land — and either can be
+adopted alone. The mutated file's verdict is unchanged, so this can
+only **add** kills: the ratio moves up or not at all, and it cannot
+turn a `--threshold` build red. A number recorded under it is still
+not comparable with one recorded without it.
+
+It costs more: each surviving breakage is re-analysed once per
+dependent file (the caught ones stop at the mutated file), and the
+dependency graph itself is one extra whole-project pass per run —
+about a third more wall time on Rigor's own `lib`.
+
+Worth knowing before you pay that: on the two codebases measured so
+far (Rigor's own `lib`, redmine's `app/models`) it added **no**
+kills. A breakage that survives there is one the analyzer reports
+*nowhere* — not one it reports in a caller — which is a statement
+about where the type net has teeth, and exactly what the
+unprotected-site list is telling you.
+
 What *does* reach it is your tests.
 
 ## The fused view — types **and** tests (`--with-tests`)
@@ -236,6 +353,10 @@ them as a deep-dive, not a per-keystroke check:
   (suite runtime)`. A fast, well-scoped test command is the biggest
   lever.
 - **Cap with `--limit`** on `--include-dynamic` or large files.
+- **Spread with `--workers=N`** on `--mutation` (and Tier 1). The
+  fused `--with-tests` tier stays sequential — the suite hook shells
+  out, and concurrent runs would race — so widen it with scope and
+  `--limit` instead.
 
 ## In CI
 

data/docs/manual/plugins/rigor-rbs-inline.md

@@ -45,6 +45,28 @@ plugin id/version + config), so an unchanged second run skips the parse.
 | Rule | Severity | Fires when |
 | --- | --- | --- |
 | `plugin.rbs-inline.source-rbs-synthesis-failed` | info | rbs-inline could not parse a file; analysis falls back to no inline-RBS contribution and the diagnostic carries the upstream error |
+| `plugin.rbs-inline.source-rbs-annotation-not-honoured` | info | an annotation parsed successfully but contributed nothing — the file's other annotations still apply. Today this means the `# @rbs module-self: Foo` spelling; see below |
+
+## Which inline-RBS dialect Rigor reads
+
+There are two implementations of inline RBS: the
+[`rbs-inline` gem](https://github.com/soutaro/rbs-inline), which this plugin
+runs, and the `RBS::InlineParser` built into `rbs` 4.x. **Rigor reads the
+gem's dialect** ([ADR-32](../../adr/32-rbs-inline-comment-ingestion.md) WD11).
+They overlap almost entirely — `#:`, `@rbs` method types, `def self.`,
+instance-variable annotations, `@rbs skip` all behave identically — but they
+are not the same grammar, and one difference bites in practice:
+
+| you write | Rigor honours it |
+| --- | --- |
+| `# @rbs module-self Comparable` | yes |
+| `# @rbs module-self: Comparable` | **no** — this is the spelling in rbs's own `docs/inline.md` |
+
+Rigor reports the second form as
+`plugin.rbs-inline.source-rbs-annotation-not-honoured` rather than dropping it
+in silence. Constructs the gem supports and the built-in parser does not —
+`@rbs generic T`, `@rbs!` embedded RBS blocks, `@rbs inherits`, method
+visibility — all work here.
 
 ## Configuration
 

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

@@ -3,6 +3,7 @@
 require "prism"
 
 require_relative "../../source/node_children"
+require_relative "../../inference/optimistic_origin"
 require_relative "inferred_param_guard"
 
 module Rigor
@@ -108,6 +109,13 @@ module Rigor
           # the precision-additive contract.
           return if InferredParamGuard.rooted?(predicate, scope)
 
+          # Issue #313 — a predicate whose constancy rests on an optimistically nil-free carrier is a bet, not
+          # proof: `MAP[key]` omits `nil` because pessimising the defaulted-Hash idiom costs more false
+          # positives than the miss it would model, so `MAP[key].nil?` folding to `false` says nothing about
+          # whether the key was there. The spec forbids this rule concluding from such a value; the derivation
+          # is what carries the mark across `.nil?`, `!` and `&&` / `||` to the predicate the rule reads.
+          return unless Inference::OptimisticOrigin.resolve(predicate, scope).nil?
+
           predicate_type = scope.type_of(predicate)
           return unless predicate_type.is_a?(Type::Constant)
 

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Rigor
+  module Analysis
+    module CheckRules
+      # ADR-58 WD1 — the shared "is this value's optionality declaration-sourced?" predicate.
+      #
+      # A `nil` whose only provenance is a declaration (the class-ivar index seed of a ctor `@x = nil`, a
+      # non-definitely-assigned ivar read) is real type information but not diagnostic fuel: the working
+      # program's cross-method invariant is assumed per the robustness principle ([ADR-5]). Every negative rule
+      # that would fire *because of* such a nil must therefore consult the same provenance question, and get the
+      # same answer.
+      #
+      # Before issue #324 each rule spelled the lookup itself, and they drifted: `call.possible-nil-receiver`
+      # read the `:local` mark (so `r = @right; r.key` was excused — ADR-58's own motivating shape), while both
+      # `call.argument-type-mismatch` gates opened by requiring a literal `Prism::InstanceVariableReadNode`, so
+      # `c = @count; sink.take_int(c)` fired on the same value with the same provenance. This module is that one
+      # question, asked in one place.
+      #
+      # **The mark is deliberately NOT transitive.** `Scope#with_declaration_sourced_local`
+      # ({Inference::StatementEvaluator#eval_local_write}) stamps `:local` only when the RHS is a *pure read of a
+      # currently declaration-sourced ivar*, so a second hop (`c = @count; d = c`) and an `||=` rewrite land on
+      # the plain `with_local` path and carry no mark.
+      #
+      # A branch join is NOT one of those cases, contrary to what this comment claimed when it landed: both
+      # arms of `if c then r = @count else r = @count end` stamp `(:local, :r)`, and `join_declaration_sourced`
+      # INTERSECTS, so the mark survives. Only an *asymmetric* join drops it, and by that intersection rather
+      # than by reaching `with_local`. The normative statement — establishment, drop, join and the full list of
+      # unmarked shapes, each verified against the implementation — is
+      # `docs/internal-spec/inference-engine.md` § "Declaration-sourced provenance mark (ADR-58)"; keep this
+      # comment subordinate to it.
+      #
+      # So `marked?` matches exactly the two node shapes the scope actually models and invents no propagation
+      # of its own; anything flow-live keeps firing.
+      module DeclarationSourcedGuard
+        module_function
+
+        # True when `node` is a direct read of a binding whose optionality is purely declaration-sourced. Any
+        # flow-live touch (a method-local `@x = nil` write, a failed-guard narrowing, a rebinding local write)
+        # drops the mark upstream, so this returns false there and the caller fires exactly as before.
+        def marked?(node, scope)
+          case node
+          when Prism::InstanceVariableReadNode then scope.declaration_sourced?(:ivar, node.name)
+          when Prism::LocalVariableReadNode then scope.declaration_sourced?(:local, node.name)
+          else false
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -119,6 +119,7 @@ module Rigor
       # the runner grows a new bare id.
       NON_CHECK_DIAGNOSTIC_IDS = %w[
         configuration-error load-error pool-degraded runtime-error source-rbs-synthesis-failed
+        source-rbs-annotation-not-honoured
       ].freeze
     end
   end

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

@@ -145,6 +145,13 @@ module Rigor
             return unless node.is_a?(Prism::Node)
 
             dispatch(node, hooks, context)
+            # Issue #318 — `defined?`'s operand is never evaluated (the runtime inspects it statically), so
+            # nothing under a `DefinedNode` is reachable, evaluated code. Dispatching the DefinedNode itself
+            # is fine (a collector may care that it exists); descending into `#value` would feed collectors
+            # source that can never execute, e.g. `undefined_method_diagnostic` flagging a call inside
+            # `defined? @x && @x.method_call`.
+            return if node.is_a?(Prism::DefinedNode)
+
             child_context = descend(node, context)
             node.rigor_each_child { |child| walk(child, hooks, child_context) }
           end

data/lib/rigor/analysis/check_rules.rb

@@ -5,11 +5,13 @@ require "prism"
 require_relative "../reflection"
 require_relative "../source/node_walker"
 require_relative "../source/constant_path"
+require_relative "../inference/singleton_object_constant"
 require_relative "../type"
 require_relative "diagnostic"
 require_relative "dependency_recorder"
 require_relative "check_rules/rule_ids"
 require_relative "check_rules/inferred_param_guard"
+require_relative "check_rules/declaration_sourced_guard"
 require_relative "check_rules/rule_walk"
 require_relative "check_rules/always_truthy_condition_collector"
 require_relative "check_rules/unreachable_clause_collector"
@@ -424,6 +426,12 @@ module Rigor
       #   only. `# rigor:disable all` on a line suppresses
       #   every rule on that line.
       #
+      # Both in-source forms are recognised only when the
+      # marker is the FIRST thing in the comment, so a
+      # directive quoted inside ordinary prose — as the bullets
+      # above quote it — is not a directive. See the pattern
+      # constants below.
+      #
       # Diagnostics with `rule == nil` (parse errors, path
       # errors, internal analyzer errors) are NEVER
       # suppressed — they represent failures the user cannot
@@ -443,17 +451,26 @@ module Rigor
         end
       end
 
-      LINE_SUPPRESSION_PATTERN = /#\s*rigor:disable(?!-file)\s+(?<rules>[\w.,\s-]+)/
+      # Every suppression-recognition pattern below is anchored with `\A` against the COMMENT SLICE —
+      # Prism hands us a slice that starts at the `#`, so `\A#` means "the marker is the first thing in
+      # the comment". A real directive always has that shape, in both the whole-line form and the
+      # trailing `code # rigor:disable <rule>` form; prose that merely quotes a directive
+      # (`... like `# rigor:disable-file all` ...`) has text before the inner `#` and no longer
+      # activates anything. Two consequences worth naming: a doc-tool `##` comment never activates (the
+      # second `#` is neither whitespace nor the marker word), and an `=begin`/`=end` block comment
+      # never activates either (its slice starts at `=begin`). Unanchored, these patterns silently
+      # file-suppressed this very file — see issue #306.
+      LINE_SUPPRESSION_PATTERN = /\A#\s*rigor:disable(?!-file)\s+(?<rules>[\w.,\s-]+)/
       private_constant :LINE_SUPPRESSION_PATTERN
 
-      FILE_SUPPRESSION_PATTERN = /#\s*rigor:disable-file\s+(?<rules>[\w.,\s-]+)/
+      FILE_SUPPRESSION_PATTERN = /\A#\s*rigor:disable-file\s+(?<rules>[\w.,\s-]+)/
       private_constant :FILE_SUPPRESSION_PATTERN
 
       # A `rigor:disable[-file]` marker word regardless of whether any rule tokens follow. Used only by the
       # `suppression.empty` detection — the two suppression patterns above require at least one token
       # character, so a bare `# rigor:disable` never reaches them. The lookahead keeps
       # `rigor:disable-something-else` from counting as a marker.
-      BARE_SUPPRESSION_MARKER = /#\s*rigor:disable(?<file>-file)?(?![\w-])(?<rest>.*)/
+      BARE_SUPPRESSION_MARKER = /\A#\s*rigor:disable(?<file>-file)?(?![\w-])(?<rest>.*)/
       private_constant :BARE_SUPPRESSION_MARKER
 
       # A `rigor:` marker word that is NOT part of Rigor's suppression grammar but reads like an attempted
@@ -463,7 +480,7 @@ module Rigor
       # surveillance they silently suppress nothing. Matches `disable-<suffix>` for any suffix other than
       # `file`, and `enable` with or without a suffix.
       UNKNOWN_SUPPRESSION_MARKER =
-        /#\s*rigor:(?<marker>disable-(?!file(?![\w-]))[\w-]+|enable(?:-[\w-]+)?)(?![\w-])(?<rest>.*)/
+        /\A#\s*rigor:(?<marker>disable-(?!file(?![\w-]))[\w-]+|enable(?:-[\w-]+)?)(?![\w-])(?<rest>.*)/
       private_constant :UNKNOWN_SUPPRESSION_MARKER
 
       # @return [Array<(Hash{Integer => Set}, Set)>] pair of
@@ -527,9 +544,10 @@ module Rigor
       end
 
       # A comment carrying the marker word but not the token-bearing suppression grammar. A remainder of
-      # nothing but whitespace / commas is a genuinely empty marker (`# rigor:disable`); anything else
-      # (documentation prose like "`# rigor:disable <rule>` comments") is left alone as an ordinary
-      # comment, matching the parse path, which never treats it as a suppression either.
+      # nothing but whitespace / commas is a genuinely empty marker (`# rigor:disable`); anything else is
+      # left alone as an ordinary comment, matching the parse path, which never treats it as a
+      # suppression either. Prose that merely quotes a marker is already excluded a step earlier by the
+      # `\A` anchor, since the quotation is not at the start of the comment.
       def diagnose_bare_suppression_marker(path, comment, source, diagnostics)
         bare = BARE_SUPPRESSION_MARKER.match(source)
         if bare
@@ -545,8 +563,9 @@ module Rigor
 
       # `# rigor:disable-next-line <rule>` / `# rigor:enable <rule>` — a marker word Rigor's grammar does
       # not recognise but that reads as an attempted suppression (the RuboCop reflex). Fires only when the
-      # remainder is empty or looks like a rule list, so prose mentioning the spelling in backticks stays
-      # an ordinary comment — the same escape the empty-marker detection observes.
+      # marker opens the comment and the remainder is empty or looks like a rule list, so prose mentioning
+      # the spelling in backticks stays an ordinary comment — the same escape the empty-marker detection
+      # observes.
       def diagnose_unknown_suppression_marker(path, comment, source, diagnostics)
         unknown = UNKNOWN_SUPPRESSION_MARKER.match(source)
         return if unknown.nil?
@@ -656,6 +675,13 @@ module Rigor
           # non-nil constituent (which, for a cross-file project def, would
           # be a working-code false positive).
           receiver_type = safe_navigation_receiver(call_node, scope)
+
+          # #320 — the private-singleton-object idiom (`class << Merger = Object.new`). The body's methods
+          # are recorded on the constant's own name, but the receiver reads back as `Object`, so the
+          # class-keyed probes below cannot see them. Recover the name from the receiver syntax. Scoped to
+          # the recorded name only: `Merger.nope` still fires.
+          return nil if Inference::SingletonObjectConstant.recorded?(call_node, receiver_type, call_node.name, scope)
+
           class_name = concrete_class_name(receiver_type)
           # A union receiver has no single concrete class. The scalar path
           # below cannot reason about it, but the call is still definitely
@@ -1255,8 +1281,12 @@ module Rigor
           # principle. The nil stays in the displayed type; only its use as
           # diagnostic fuel is withheld. Any flow-live touch (method-local
           # nil write, failed-guard narrowing) drops the mark upstream, so
-          # flow-observed nil keeps firing exactly as before.
-          return nil if scope.declaration_sourced?(:local, call_node.receiver.name)
+          # flow-observed nil keeps firing exactly as before. The receiver
+          # is already narrowed to a local read above, so this asks
+          # {DeclarationSourcedGuard} exactly what it asked before — but it
+          # now asks it through the predicate the argument-type gates share
+          # (issue #324), which is what keeps the two rules from drifting.
+          return nil if DeclarationSourcedGuard.marked?(call_node.receiver, scope)
 
           # ADR-67 WD6b — an inferred-parameter receiver's type (incl. any nil constituent unioned in from a
           # nil call site) is an open-call-site lower bound; a possible-nil firing against it is an FP by
@@ -1271,13 +1301,23 @@ module Rigor
           # presence checks below cannot rule out a sound call.
           return nil unless Rigor::Reflection.rbs_class_known?("NilClass", scope: scope)
 
-          return nil unless union_contains_nil?(receiver_type)
-          return nil unless union_method_present_on_non_nil?(receiver_type, call_node.name, scope)
-          return nil if nil_class_has_method?(call_node.name, scope)
+          return nil unless nil_bearing_union_witnesses?(receiver_type, call_node.name, scope)
 
           build_nil_receiver_diagnostic(path, call_node)
         end
 
+        # The receiver-type half of the rule, factored out of the node-shape
+        # guards above: the union must carry nil, must carry a non-nil arm the
+        # presence question can be asked of, must support the method on every
+        # non-nil arm (so the call is only wrong on the nil path), and the
+        # method must be absent from `NilClass` (so the nil path really raises).
+        def nil_bearing_union_witnesses?(receiver_type, method_name, scope)
+          union_contains_nil?(receiver_type) &&
+            union_has_nameable_non_nil_arm?(receiver_type) &&
+            union_method_present_on_non_nil?(receiver_type, method_name, scope) &&
+            !nil_class_has_method?(method_name, scope)
+        end
+
         def union_contains_nil?(union)
           union.members.any? { |member| nil_member?(member) }
         end
@@ -1302,6 +1342,23 @@ module Rigor
             (member.is_a?(Type::Nominal) && member.class_name == "NilClass")
         end
 
+        # Possible-nil may witness only where the presence question below is
+        # ANSWERABLE. `method_present_anywhere?` reports "present" for a
+        # nameless arm (Dynamic / Top / Bot) — the permissive polarity the
+        # union-undefined-method rule's FP safety rests on — so a union whose
+        # non-nil arms are ALL nameless satisfied that gate vacuously and fired
+        # on every method name, including names defined on no class anywhere.
+        # That inverted the intent: the gate suppressed exactly where knowledge
+        # exists (`String | nil` calling a nonexistent method stays silent) and
+        # permitted exactly where none does. Requiring one nameable concrete
+        # arm restores the polarity without touching the shared helper:
+        # `String | nil` keeps firing, and so does `Dynamic | String | nil` —
+        # the nameless arm stays permissive inside the all-arms check, which is
+        # only about the arms' method surface.
+        def union_has_nameable_non_nil_arm?(union)
+          union.members.any? { |m| !nil_member?(m) && !concrete_class_name(m).nil? }
+        end
+
         # The non-nil members must collectively support the
         # method (i.e. for every non-nil member, the method
         # exists on its class via RBS or in-source discovery).
@@ -2075,13 +2132,25 @@ module Rigor
           param_overrides = Rigor::RbsExtended.param_type_override_map(method_def, environment: scope.environment)
           mismatch = argument_mismatch(method_def.method_types, call_node, scope, param_overrides)
           return nil if mismatch.nil?
-          # ADR-67 WD6b — the mismatching argument is an inferred-parameter local, whose type is an
-          # open-call-site lower bound; firing argument-type-mismatch against it is an FP by construction.
-          return nil if inferred_param_argument?(mismatch[:node], scope)
+          return nil if inferred_param_mismatch_verdict?(call_node, mismatch, scope)
 
           build_argument_type_diagnostic(path, call_node, class_name, mismatch)
         end
 
+        # ADR-67 WD6b — an argument-type-mismatch verdict resting on an open-call-site lower bound, on
+        # either side of the call. The ARGUMENT side: the mismatching argument is an inferred-parameter
+        # local, so firing against it is an FP by construction. The RECEIVER side: when the receiver roots
+        # at an inferred parameter, the method whose parameter contract the argument was checked against
+        # was itself resolved through a lower-bound type, so the whole verdict is speculative. The 2026-07-30
+        # self-check surfaced the receiver half as a guard hole: seeding `env : RBS::Environment` activated
+        # this rule on `env.unload(culprits)` and flagged a correct Array argument against `unload`'s
+        # declared `Set[Pathname]` — an upstream signature stricter than its implementation, exactly the FP
+        # class WD6b exists to suppress. The other guarded rules already declined on a param-rooted
+        # receiver; this brings argument-type-mismatch in line.
+        def inferred_param_mismatch_verdict?(call_node, mismatch, scope)
+          inferred_param_argument?(mismatch[:node], scope) || inferred_param_receiver?(call_node, scope)
+        end
+
         # Single overload → the exact per-argument acceptance (unchanged).
         # Multiple overloads → the nil channel (a pure-`nil` argument every
         # overload rejects) plus, on non-coerce methods, the non-nil channel
@@ -2344,13 +2413,16 @@ module Rigor
           params.map { |param| param.type.to_s.delete_prefix("::") }.uniq.join(" | ")
         end
 
-        # ADR-58 parity for the nil channel: a declaration-sourced ivar read
-        # that types as nil is the same not-diagnostic-fuel case the union
-        # path gates in {#declaration_sourced_nil_only_mismatch?}; suppress it
-        # here too so a ctor-seeded `@x = nil` read passed as an argument does
-        # not fire on a working program's cross-method invariant.
+        # ADR-58 parity for the nil channel: a declaration-sourced read that
+        # types as nil is the same not-diagnostic-fuel case the union path
+        # gates in {#declaration_sourced_nil_only_mismatch?}; suppress it here
+        # too so a ctor-seeded `@x = nil` read passed as an argument does not
+        # fire on a working program's cross-method invariant. Issue #324 —
+        # delegates to {DeclarationSourcedGuard}, so a local copy of the ivar
+        # (`c = @count`) is excused on the same terms `possible-nil-receiver`
+        # already excused it.
         def declaration_sourced_nil_argument?(arg, scope)
-          arg.is_a?(Prism::InstanceVariableReadNode) && scope.declaration_sourced?(:ivar, arg.name)
+          DeclarationSourcedGuard.marked?(arg, scope)
         end
 
         def first_argument_mismatch(method_type, call_node, scope, param_overrides)
@@ -2413,14 +2485,15 @@ module Rigor
           !declaration_sourced_nil_only_mismatch?(arg, arg_type, param_type, scope)
         end
 
-        # True when `arg` is a declaration-sourced ivar read whose rejection is
+        # True when `arg` is a declaration-sourced read whose rejection is
         # caused solely by its nil constituent: stripping nil from the argument
         # type yields a type the parameter accepts (gradual mode). Mirrors the
-        # `possible-nil-receiver` WD1 gate, keyed on the ivar provenance mark
-        # rather than a local copy.
+        # `possible-nil-receiver` WD1 gate — since issue #324 through the very
+        # same {DeclarationSourcedGuard} predicate, so the ivar read and its
+        # local copy (`c = @count`) are one case rather than two spellings that
+        # can drift apart again.
         def declaration_sourced_nil_only_mismatch?(arg, arg_type, param_type, scope)
-          return false unless arg.is_a?(Prism::InstanceVariableReadNode)
-          return false unless scope.declaration_sourced?(:ivar, arg.name)
+          return false unless DeclarationSourcedGuard.marked?(arg, scope)
           return false unless arg_type.is_a?(Type::Union)
           return false unless union_contains_nil?(arg_type)
 
@@ -2681,6 +2754,12 @@ module Rigor
 
         # Returns true when `override_visibility` is strictly more restrictive than `parent_visibility`
         # under the public > protected > private ordering.
+        #
+        # The nil guard below is defence, not dead code. `VISIBILITY_RANK` is a closed literal hash read
+        # with a dynamic key, so a symbol outside the table reads as nil at runtime. The engine folds that
+        # read to the nil-free value union `0 | 1 | 2`, which `internal-spec/inference-engine.md` declares
+        # OPTIMISTIC rather than proof — and since issue #313 that mark survives the `.nil?` fold and the
+        # `||` composition, so no suppression directive is needed here.
         def visibility_reduced?(parent_visibility, override_visibility)
           parent_rank = VISIBILITY_RANK[parent_visibility]
           override_rank = VISIBILITY_RANK[override_visibility]