rigortype 0.4.6 → 0.4.8

data/lib/rigor/analysis/self_call_resolution_recorder.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../typing_state"
+
 module Rigor
   module Analysis
     # ADR-24 slice 4a — records every *implicit-self* method call the inference engine could not resolve to any
@@ -18,15 +20,32 @@ module Rigor
     # recompute" lesson applied to self-calls.
     #
     # ADR-24 slice 4 (`call.self-undefined-method`) consumes the recorded misses behind a confidently-closed-class
-    # gate (see `CheckRules` L775). The rule ships `:off` by default — {active?} is false on a normal run, so
+    # gate (see `CheckRules`). The rule ships `:off` by default — {active?} is false on a normal run, so
     # the instrumented choke-point pays a single integer read and records nothing. Recording is purely
     # observational; it never changes a diagnostic.
     #
     # Modelled on {DependencyRecorder}: process-thread-local accumulator, a cheap disabled fast path, and a
     # frozen snapshot for consumers.
     module SelfCallResolutionRecorder
-      KEY = :__rigor_self_call_resolution_recorder__
-      private_constant :KEY
+      # ADR-129 WD1 — the installed accumulator is a Frame; its contents are the bound Table {CALLS}. The activation
+      # count below is a process switch, outside the typing state (WD5).
+      RECORDER = TypingState.frame(
+        :self_call_resolution_recorder,
+        contents: :table, reason: "the accumulator a recording installs; each unresolved call records into it",
+        # G1′ witness: the memo journals and replays the records, so it is not a shut switch (unlike the tracers).
+        witness: "spec/fixtures/typing_state_witnesses/self_call_resolution_recorder.rb"
+      )
+      private_constant :RECORDER
+
+      # ADR-129 WD1 — the recorded misses are a bound Table: each installed accumulator is one of its stores, keyed by
+      # the call tuple (deduplicated, so the first record of a tuple is its only write), journaled while a capture is
+      # open so a later `type_of` memo can validate the reads and replay the writes in order.
+      CALLS = TypingState.table(
+        :self_call_misses,
+        bound: true,
+        reason: "UnresolvedSelfCall => true per consumer accumulator, appended in first-record order"
+      )
+      private_constant :CALLS
 
       # One unresolved implicit-self call. `class_name` is the receiver's statically known class (the
       # enclosing `self` type); `method_name` the called name; `node` the Prism `CallNode` (held in-memory so
@@ -45,10 +64,28 @@ module Rigor
           @seen = Set.new
         end
 
-        def add(call)
-          return unless @seen.add?(call)
+        def add?(call)
+          return false unless @seen.add?(call)
 
           @calls << call
+          true
+        end
+
+        # Whether `call` is already recorded.
+        def recorded?(call) = @seen.include?(call)
+
+        # The bound Table's store protocol ({CALLS}): `true` for a recorded call, else `default`.
+        def fetch(call, default) = @seen.include?(call) || default
+
+        # The bound Table's store protocol: an undone write (G1's stage-4 form) forgets `call`.
+        def delete(call)
+          @calls.delete(call) if @seen.delete?(call)
+        end
+
+        # The bound Table's store protocol: a replayed write records `call` as {#add?} does, so the replay order of a
+        # write slice is the order of {#calls}.
+        def []=(call, _value)
+          add?(call)
         end
 
         def snapshot
@@ -69,15 +106,16 @@ module Rigor
       # Activates recording for `consumer` (the path being analyzed) for the duration of the block and returns
       # the frozen {Record}. Nests safely; restores the previous recorder on exit.
       def record_for(consumer)
-        previous = Thread.current[KEY]
         accumulator = Accumulator.new(consumer.to_s)
-        Thread.current[KEY] = accumulator
-        @mutex.synchronize { @active_count += 1 }
-        yield
-        accumulator.snapshot
-      ensure
-        Thread.current[KEY] = previous
-        @mutex.synchronize { @active_count -= 1 }
+        TypingState.current.with(RECORDER, accumulator) do
+          @mutex.synchronize { @active_count += 1 }
+          begin
+            yield
+            accumulator.snapshot
+          ensure
+            @mutex.synchronize { @active_count -= 1 }
+          end
+        end
       end
 
       # Plain integer read (GVL-atomic) — no `Thread.current` lookup on the disabled fast path.
@@ -88,19 +126,20 @@ module Rigor
       # Records one unresolved implicit-self call. No-op when no consumer is active on this thread (another
       # thread may have flipped {active?}).
       def record(class_name:, method_name:, node:, path:, line:, column:)
-        accumulator = Thread.current[KEY]
+        state = TypingState.current
+        accumulator = state[RECORDER]
         return if accumulator.nil?
 
-        accumulator.add(
-          UnresolvedSelfCall.new(
-            class_name: class_name.to_s,
-            method_name: method_name.to_sym,
-            node: node,
-            path: path,
-            line: line,
-            column: column
-          )
+        call = UnresolvedSelfCall.new(
+          class_name: class_name.to_s,
+          method_name: method_name.to_sym,
+          node: node,
+          path: path,
+          line: line,
+          column: column
         )
+        state.log_bound_read(CALLS, accumulator, call, accumulator.fetch(call, TypingState::ABSENT)) if state.capturing?
+        state.log_bound_write(CALLS, accumulator, call, true, TypingState::ABSENT) if accumulator.add?(call)
       end
     end
   end

data/lib/rigor/analysis/template_unit_positions.rb

@@ -173,9 +173,8 @@ module Rigor
       # copies one tag body once, and the second `@author` is the same copy seen from the other end, not a
       # second reading. Only a node OUTSIDE the winning run's own compiled span counts, which is what keeps
       # the busy lines of a real view answerable while the cross-tag repeat (`<%= v %> <%= v.to_s %>`, or
-      # `<%= v %><%= "v" %>` probed at the STRING's `v`) still declines — the family a plugin-exported tag
-      # span would answer instead
-      # (see the PR), and the follow-up this rule is deliberately conservative ahead of.
+      # `<%= v %><%= "v" %>` probed at the STRING's `v`) still declines. That family is what a plugin-exported
+      # tag span would answer instead, and it is the follow-up this rule is deliberately conservative ahead of.
       #
       # `spill` is the nearest NON-BLANK compiled line above this template line's own, where a hoisted
       # leading-text literal lives. Only a string literal the run does NOT contain counts there. A code

data/lib/rigor/analysis/template_units.rb

@@ -189,6 +189,15 @@ module Rigor
         @entries.keys.sort
       end
 
+      # Issue #2233 — whether a plugin claims `path` by one of its `template_globs:`, in any spelling a caller holds it
+      # (absolute, `./`-prefixed, relative). A claimed template is analysed as a unit, never as a plain `.rb` file, so
+      # the runner keeps the buffer's logical path out of the `.rb` targets, so it is not analysed twice.
+      def claims?(path)
+        return false if @claimed_globs.empty?
+
+        TemplateUnitPaths.claims?(@claimed_globs, TemplateUnitPaths.relative(path, @root))
+      end
+
       def [](path)
         entry_for(path)
       end
@@ -293,7 +302,6 @@ module Rigor
         [entry.locals.keys.map(&:to_sym)]
       end
 
-      # The `view:<logical_name>` effect-unit key for a path, or nil.
       # The file whose bytes a unit's path was READ from: the editor's buffer when one is bound to it, the
       # project file otherwise. Read by the run's dependency descriptor, so it digests what the run read.
       def physical_path(path, buffer)

data/lib/rigor/analysis/worker_session.rb

@@ -25,6 +25,7 @@ require_relative "dependency_source_inference"
 require_relative "diagnostic"
 require_relative "erb_template_detector"
 require_relative "template_units"
+require_relative "runner/run_level_facts"
 
 module Rigor
   module Analysis
@@ -39,8 +40,8 @@ module Rigor
     # - `configuration` — Phase 2a ({Rigor::Configuration} is `Ractor.shareable?`).
     # - `cache_store` — the fork backend passes the parent runner's pre-built Store (`cache_store:
     #   @cache_store` in PoolCoordinator); workers share it rather than building their own at `cache_root`.
-    # - `plugin_blueprints` — Phase 3a (`Array<Plugin::Blueprint>` is `Ractor.shareable?`).
-    # - `explain` — Boolean.
+    # - `plugin_blueprints` — Phase 3a (a list of `Plugin::Blueprint` is `Ractor.shareable?`).
+    # - `explain` — a flag.
     # - `synthetic_method_index` / `project_patched_methods` / `project_scope_seed` — optional (default `nil`
     #   / `{}`). NOT `Ractor.shareable?` (the seed tables carry Prism def nodes), so the Ractor pool path
     #   leaves them unset; the fork backend (ADR-15 Amendment), which builds the session pre-fork on the
@@ -109,7 +110,7 @@ module Rigor
         # above: a worker and the parent agree without a flag to keep in sync.
         @effect_attribution = Effects::Attribution.build(configuration.effects_attribution)
         @file_effects = {}
-        # ADR-32 WD4 — full project file list (frozen Array<String>) for env-build-time invocation of any
+        # ADR-32 WD4 — full project file list (frozen) for env-build-time invocation of any
         # loaded plugin's `source_rbs_synthesizer` callable.
         @source_files = source_files
         # #392 — the run's template units, synthesised on the PARENT before the fork and inherited here as
@@ -162,12 +163,20 @@ module Rigor
       end
 
       # Equivalent of {Rigor::Analysis::Runner#analyze_file} + `plugin_emitted_diagnostics` +
-      # `explain_diagnostics`. Returns a flat `Array<Diagnostic>` for the file. Severity profile re-stamping
+      # `explain_diagnostics`. Returns a flat list of diagnostics for the file. Severity profile re-stamping
       # is intentionally NOT applied — that is a per-run aggregate concern handled by the caller. When
       # `record_dependencies:` was set, wraps the analysis in a {DependencyRecorder} window (ADR-46) so the
       # worker captures the file's cross-file reads for {#drain_dependencies}; the recorder's own disabled
       # fast path makes the unwrapped case free.
       def analyze(path)
+        diagnostics = analyze_attributed(path)
+        return diagnostics unless Inference::MemoAudit.enabled?
+
+        # ADR-129 WD5 (#2785) — the audit's mismatches this file raised, as `Runner#analyze_file` reports them.
+        CrashSignature.with_swallowed(path, diagnostics, Inference::MemoAudit.drain)
+      end
+
+      def analyze_attributed(path)
         return analyze_with_effects(path) unless @record_dependencies
 
         diagnostics = nil
@@ -203,6 +212,7 @@ module Rigor
         diagnostics
       end
       private :analyze_with_effects
+      private :analyze_attributed
 
       # ADR-103 WD6 / #386 — the worker-side mirror of `Runner#effect_envelope_index`. Derived from the
       # same configuration and the session's own environment, so a worker's `≤` lane is the one the
@@ -226,6 +236,20 @@ module Rigor
       end
       private :effect_envelope_index
 
+      # The scope a file's analysis starts from: the project seed, with its template units.
+      def seeded_scope(path)
+        @template_units.seed(seed_project_scope(Scope.empty(environment: @environment, source_path: path)), path)
+      end
+
+      # The main pass over `root`, which the ADR-129 stage-3 shadow ({TypeOfMemo}) counts apart from the rule walk
+      # that follows it.
+      def index_main_pass(root, scope)
+        TypeOfMemo.begin_file
+        index = Inference::ScopeIndexer.index(root, default_scope: scope, widen_clauses: true)
+        TypeOfMemo.phase!(:rule)
+        index
+      end
+
       def analyze_body(path)
         parse_result = parse_source(path)
         unless parse_result.errors.empty?
@@ -236,12 +260,10 @@ module Rigor
 
         root = parse_result.value
         Effects::Collector.record_root(root)
-        scope = @template_units.seed(
-          seed_project_scope(Scope.empty(environment: @environment, source_path: path)), path
-        )
-        index = Inference::ScopeIndexer.index(root, default_scope: scope, widen_clauses: true)
+        scope = seeded_scope(path)
+        index = index_main_pass(root, scope)
         # ADR-53 B4 — built-in collectors + plugin node rules share one walk.
-        node_collectors = CheckRules.build_node_collectors(path, index, root)
+        node_collectors = built_in_collectors(path, index, root)
         node_results = node_rule_results_by_plugin(path, root, scope, node_collectors, index)
         diagnostics = CheckRules.diagnose(
           path: path,
@@ -257,11 +279,21 @@ module Rigor
         diagnostics + explain_diagnostics(path, parse_result.value, scope)
       rescue Errno::ENOENT => e
         [analyzer_error(path, e.message)]
-      rescue StandardError => e
-        [analyzer_error(path, CrashSignature.check_rule_message(e))]
+      rescue StandardError, SystemStackError => e
+        [analyzer_error(path, CrashSignature.contained_message!(e, parse_result))]
+      ensure
+        TypeOfMemo.end_file
       end
       private :analyze_body
 
+      # The built-in collectors for one file; `plugin.api-surface`'s joins only when the rule can report.
+      def built_in_collectors(path, index, root)
+        CheckRules.build_node_collectors(
+          path, index, root, plugin_api_surface: CheckRules::PluginApiSurface.active?(@configuration)
+        )
+      end
+      private :built_in_collectors
+
       # Read-once snapshot of the per-worker reporters so the caller (or the eventual Phase 4b pool
       # aggregator) can merge into a single coordinator-side reporter. Both reporters dedupe at write time,
       # so a post-hoc concat + de-dup at the entry-key level is sound.
@@ -271,7 +303,7 @@ module Rigor
       # definition and never enters the failing build; a diagnostic wired off the parent's loader would
       # appear at `--workers=0` and vanish at `--workers=N`, which is the same "reports less depending on
       # how you ran it" defect the diagnostic exists to end. Draining it out of the workers is what makes
-      # the two paths say the same thing. The payload is `[String, String, String, Array<String>]` tuples —
+      # the two paths say the same thing. The payload is a list of plain tuples —
       # Marshal-clean for the fork backend and shareable for the Ractor one.
       #
       # Issue #784 — `hkt_scan_failure` rides the same channel for the same reason: the PARENT's own
@@ -284,33 +316,25 @@ module Rigor
       # project whose `sig/` produced a single such event killed each worker HERE — after its files were
       # analysed — and the run degraded to in-process re-analysis with a `pool-degraded` row. All three
       # streams now carry `(path, line, column)` primitives.
+      #
+      # ADR-116 WD3 (#1195) — both halves are declared rather than listed here: each reporter snapshots its
+      # own streams ({Runner::RunLevelFacts::REPORTERS}), and the `:analysis` facts come from
+      # {Runner::RunLevelFacts.drain}, the same read the coordinator makes of an environment it analysed on.
+      # The facts are read first: their HKT demand (#784, made once per worker so a worker whose share of
+      # files demanded nothing still reports the run's outcome) is what fills the hkt-directive stream (#785).
+      # On a worker that analysed a file the demand is a memoised read; the fork backend never hands a worker
+      # an empty slice, so no idle worker pays the env load.
       def drain_reporters
-        # Issue #784 — demand the registry once per worker before reading the slot, so a worker whose share
-        # of files happened to contain no `Klass.method` call still reports the run's outcome (the same
-        # reason `PoolCoordinator#hkt_scan_outcome` demands it on the sequential path). The Environment
-        # object is built in the constructor, but its RBS env is lazy: on a worker that analysed a file this
-        # is a memoised read; on one that demanded nothing it is the same cache-served env load that file
-        # would have paid. The fork backend never hands a worker an empty slice, so no idle worker pays it.
-        @environment&.hkt_registry
-        {
-          rbs_extended: {
-            unresolved_payloads: @rbs_extended_reporter.unresolved_payloads,
-            lossy_projections: @rbs_extended_reporter.lossy_projections,
-            # Issue #785 — the HKT directive stream rides the same channel for the same reason
-            # `hkt_scan_failure` does: the directives are read by the registry scan, and under the pool the
-            # PARENT never demands that scan, so a diagnostic wired off the parent's reporter would appear
-            # at `--workers=0` and vanish at `--workers=N`. The demand above is what fills this.
-            hkt_directive_errors: @rbs_extended_reporter.hkt_directive_errors,
-            # ADR-109 WD3 — the deprecated-form stream rides the same channel: the payload is read where
-            # the annotated method is dispatched, which under the pool is only ever inside a worker.
-            deprecated_forms: @rbs_extended_reporter.deprecated_forms
-          },
-          boundary_cross: @boundary_cross_reporter.entries,
-          source_rbs_synthesis: @source_rbs_synthesis_reporter.entries,
-          definition_build_failures: @environment&.rbs_loader&.definition_build_failures || [],
-          hkt_scan_failure: @environment&.hkt_scan_failure
-        }
+        facts = Runner::RunLevelFacts.drain(@environment)
+        Runner::RunLevelFacts.snapshot_reporters(reporters).merge(facts)
+      end
+
+      # The per-worker reporter accumulators, by {Runner::RunLevelFacts::REPORTERS} key.
+      def reporters
+        { rbs_extended: @rbs_extended_reporter, boundary_cross: @boundary_cross_reporter,
+          source_rbs_synthesis: @source_rbs_synthesis_reporter }
       end
+      private :reporters
 
       # ADR-46 — the per-file {DependencyRecorder::Record}s captured by this session's `#analyze` calls (empty
       # unless `record_dependencies:` was set). Marshal-clean (Data of frozen Sets / String Hashes), so the
@@ -426,40 +450,10 @@ module Rigor
         Prism.parse(File.read(physical), filepath: path, version: @configuration.target_ruby)
       end
 
-      # Mirrors {Runner#build_trust_policy}. Deriving trust inside the session keeps the substrate decoupled
-      # from the coordinator; configuration is already Ractor-shareable.
+      # {Rigor::Plugin::TrustPolicy.for_configuration} is the single derivation `rigor check`, pooled
+      # workers and `rigor unused`'s plugin roots share (#2586); configuration is already Ractor-shareable.
       def build_trust_policy
-        trusted_gems = @configuration.plugins.map { |entry| trusted_gem_name(entry) }.uniq
-        roots = [Dir.pwd]
-        Array(@configuration.signature_paths).each { |sp| roots << File.absolute_path(sp) }
-        trusted_gems.each do |gem_name|
-          path = trusted_gem_root(gem_name)
-          roots << path if path
-        end
-        @configuration.plugins_io_allowed_paths.each { |p| roots << File.absolute_path(p) }
-
-        Plugin::TrustPolicy.new(
-          trusted_gems: trusted_gems,
-          allowed_read_roots: roots,
-          network_policy: @configuration.plugins_io_network,
-          allowed_url_hosts: @configuration.plugins_io_allowed_url_hosts
-        )
-      end
-
-      def trusted_gem_name(entry)
-        case entry
-        when String then entry
-        when Hash then entry["gem"] || entry["id"]
-        end
-      end
-
-      def trusted_gem_root(gem_name)
-        return nil if gem_name.nil? || gem_name.empty?
-
-        spec = Gem.loaded_specs[gem_name]
-        spec&.full_gem_path # rigor:disable undefined-method
-      rescue StandardError
-        nil
+        Plugin::TrustPolicy.for_configuration(@configuration)
       end
 
       def run_plugin_prepare
@@ -480,7 +474,7 @@ module Rigor
       def plugin_prepare_error_diagnostic(plugin, error)
         plugin_id = safe_plugin_id(plugin)
         Diagnostic.new(
-          path: ".rigor.yml",
+          path: @configuration.config_display_path,
           line: 1,
           column: 1,
           message: "plugin #{plugin_id.inspect} raised during prepare: " \

data/lib/rigor/bleeding_edge.rb

@@ -9,11 +9,9 @@ module Rigor
   # *today's* rules are) and is versioned with the gem, NOT a user-supplied file: the
   # inspectable counterpart to PHPStan's `bleedingEdge` include.
   #
-  # The WD2 foundation slice wired the surface end-to-end (`bleeding_edge:` config, the
-  # `rigor show-bleedingedge` command, the severity-composition hook in
-  # {Configuration::SeverityProfile.resolve}), so a *severity* discipline lands as a single
-  # {FEATURES} entry with no engine plumbing — as the first one,
-  # `reject-unparseable-signatures`, does.
+  # The surface is wired end-to-end (`bleeding_edge:` config, `rigor show-bleedingedge`, the
+  # severity-composition hook in {Configuration::SeverityProfile.resolve}), so a *severity*
+  # discipline is a single {FEATURES} entry with no engine plumbing.
   #
   # A queued change whose effect is not a severity move — a measurement, an algorithm, or a
   # default that changes while every rule keeps its severity — is a `:behaviour` feature
@@ -40,7 +38,6 @@ module Rigor
     # {Configuration#bleeding_edge_active?}.
     KINDS = %i[severity behaviour].freeze
 
-    # The severity map a `:behaviour` feature carries: none.
     NO_SEVERITY_OVERRIDES = {}.freeze
 
     # One queued change.
@@ -129,6 +126,20 @@ module Rigor
           "static.value-use.void" => :warning
         }.freeze
       ),
+      # ADR-128 WD6 / ADR-130 slice 2 (#2686). Off by default because a new required diagnostic is an ADR-50
+      # Decision 3 new discipline; it graduates at the next hard break.
+      Feature.new(
+        id: "plugin-api-surface",
+        kind: :severity,
+        summary: "In plugin source (code inside a class that inherits `Rigor::Plugin::Base`), a call on a value " \
+                 "typed by a `Rigor::Plugin` interface (`_Scope`, `_Environment`, `_Services`, ...) to a member " \
+                 "the interface does not declare becomes a `:warning` (`plugin.api-surface`). The engine object " \
+                 "answers such a call today, so it is not `call.undefined-method`; it is outside the plugin API " \
+                 "Rigor promises to keep (ADR-128).",
+        severity_overrides: {
+          "plugin.api-surface" => :warning
+        }.freeze
+      ),
       Feature.new(
         id: "discovery-seeded-mutation-sites",
         kind: :behaviour,
@@ -159,7 +170,7 @@ module Rigor
                  "kills — every surviving breakage there is one the analyzer reports nowhere at all, not one " \
                  "it reports in a caller."
       ),
-      # ADR-103 WD15 — the owner-ruled preview of the v0.4.0 default. `:behaviour` because it moves no rule's
+      # ADR-103 WD15 — the owner-ruled preview of the v0.5.0 default. `:behaviour` because it moves no rule's
       # severity; safe under the header comment's cache-identity rule for a reason specific to this feature
       # rather than the generic WD13 argument, so it is spelled out here: `effects:` collection is
       # OBSERVATIONAL (ADR-103 WD13) and the `effects:` block itself is deliberately absent from the
@@ -177,9 +188,10 @@ module Rigor
                  "it had written `effects: {}` — effect collection, the `rigor effects` verbs' cache sharing, " \
                  "and `effects.check` all turn on with every sub-key at its default. Writing `effects: false` " \
                  "explicitly still opts out, and a project that writes its own `effects:` block keeps that " \
-                 "block's shape untouched either way. Graduates to default-on at v0.4.0 (owner ruling, " \
-                 "2026-08-17): ADR-50 § WD7 reads \"at a major\" as \"at v0.4.0\" for this feature on the 0.x " \
-                 "evaluation line. See ADR-103 § WD15 for the preconditions that gate the flip."
+                 "block's shape untouched either way. Graduates to default-on at v0.5.0 (owner ruling, " \
+                 "2026-10-26, moving the v0.4.0 date of 2026-08-17): ADR-50 § WD7 reads \"at a major\" as the " \
+                 "version that ruling names, for this feature on the 0.x evaluation line. See ADR-103 § WD15 " \
+                 "for the preconditions that gate the flip and § WD18 for the move."
       )
     ].freeze
 

data/lib/rigor/builtins/imported_refinements.rb

@@ -113,9 +113,8 @@ module Rigor
         },
         # ADR-13 § "Canonical type-function additions" — five shape-projection type functions
         # that the `rigor-typescript-utility-types` plugin (and any other plugin that ships a
-        # shape-projection vocabulary) maps onto. Phase A handles `HashShape` carriers;
-        # non-shape inputs return the input unchanged (the lossy-projection diagnostic lands
-        # in slice 5).
+        # shape-projection vocabulary) maps onto. Non-shape inputs return the input unchanged;
+        # the Resolver records `dynamic.shape.lossy-projection` for them.
         "pick_of" => lambda { |args|
           return nil unless args.size == 2
 
@@ -148,7 +147,7 @@ module Rigor
       # `Class[range]` — a numeric class head bounded by a Ruby range literal (ADR-109). The
       # builder receives the `Range` value and returns the carrier, or `nil` when the range is
       # empty or its endpoints are not literals of the head class; `nil` surfaces as the ordinary
-      # unresolved-payload diagnostic. `Float` joins this table with the `FloatRange` carrier.
+      # unresolved-payload diagnostic. `Float` builds a `FloatRange` carrier.
       RANGE_HEAD_BUILDERS = {
         "Integer" => lambda { |range|
           lo = range.begin
@@ -186,8 +185,7 @@ module Rigor
       # `Array<Integer>` and returns a `Rigor::Type` (or `nil`). Bounds are signed integer
       # literals. A reversed pair (`min` > `max`) is declined as `nil` like every other shape
       # mismatch, so the caller surfaces `dynamic.rbs-extended.unresolved` at the annotation;
-      # `Type::IntegerRange` raises on it instead, and that `ArgumentError` used to escape as an
-      # `internal analyzer error` that abandoned the whole Ruby file.
+      # `Type::IntegerRange` would raise on it instead, which must not escape the analyzer.
       PARAMETERISED_INT_BUILDERS = {
         "int" => lambda { |bounds|
           return nil unless bounds.size == 2
@@ -276,14 +274,14 @@ module Rigor
       # grammar:
       #
       #   type        := simple_name | parametric
-      #   simple_name := /[a-z][a-z0-9-]*/
+      #   simple_name := /[a-z][a-z0-9_-]*/
       #   parametric  := simple_name '[' type_arg_list ']'
       #                | simple_name '<' int_bound_list '>'
       #   type_arg_list := type_arg (',' type_arg)*
       #   type_arg    := range_literal | type | class_name
       #   class_name  := /[A-Z][A-Za-z0-9_]*(?:::[A-Z][A-Za-z0-9_]*)*/
       #   range_literal := endpoint? ('..' | '...') endpoint?     (at least one side written)
-      #   endpoint    := signed_int | 'nil'
+      #   endpoint    := signed_int | float_literal | 'nil' | 'Float::INFINITY' | 'Float::MAX'
       #   int_bound_list := signed_int (',' signed_int)*
       #   signed_int  := /-?\d+/
       #

data/lib/rigor/builtins/predefined_constant_refinements.rb

@@ -62,7 +62,7 @@ module Rigor
     # `RBS::VERSION` while Rigor checks itself, rubygems and Bundler internals while it checks
     # CRuby's `lib/` — and that is worse than no answer: identical source would type differently
     # depending on how the analyzer was installed. Removing an ad hoc `Object.const_get` from an
-    # analysis path is the same move ADR-4 § 330 already made for predicate narrowing.
+    # analysis path is the same move ADR-4 already made for predicate narrowing.
     #
     # This module is consulted by `Environment#constant_for_name` BEFORE the RBS
     # constant-type table (widest types) but AFTER in-source constant writes (the user's own

data/lib/rigor/builtins/regex_refinement.rb

@@ -8,13 +8,11 @@ module Rigor
     # carriers Rigor already ships (`decimal-int-string`, `hex-int-string`,
     # `octal-int-string`, `lowercase-string`, `uppercase-string`, `numeric-string`). See
     # `docs/type-specification/imported-built-in-types.md` for the registry the refinements
-    # come from and `docs/ROADMAP.md` § "v0.1.1 — Planned" Track 1 slice 1 for the binding
-    # scope of this recogniser.
+    # come from.
     #
-    # The intended consumer is `Inference::Narrowing.analyse_match_write`: given `if
-    # /(?<year>\d+)/ =~ str; year; end`, the v0.1.0 baseline narrows `year` to plain `String`;
-    # v0.1.1 introspects the regex source and narrows further to `decimal-int-string`
-    # whenever the named-capture body matches one of the rows in {RULES}.
+    # The consumer is `Inference::Narrowing.analyse_match_write`: given `if /(?<year>\d+)/ =~ str;
+    # year; end`, `year` narrows to `decimal-int-string` when the named-capture body matches a row
+    # in {RULES}, and stays plain `String` otherwise.
     #
     # Recognised body shapes (each row admits the `+` quantifier and the bounded `{n}` /
     # `{n,m}` forms with `n >= 1`):

data/lib/rigor/cache/descriptor.rb

@@ -10,7 +10,8 @@ module Rigor
   module Cache
     # Cache invalidation descriptor — the typed-slot schema fixed by
     # [`docs/design/20260505-cache-slice-taxonomy.md`](../../../docs/design/20260505-cache-slice-taxonomy.md).
-    # Pure value object: no I/O, no global state, fully immutable after construction. The storage layer
+    # Value object, fully immutable after construction. Filesystem reads happen only in the `FileEntry.stat`,
+    # `FileEntry.kind` and `GlobEntry.compute` builders and in {#fresh?}. The storage layer
     # ([`Rigor::Cache::Store`](store.rb), v0.0.8 slice 2) consumes descriptors but does not extend them.
     #
     # The descriptor has six slots (`files`, `gems`, `plugins`, `configs`, `dependencies`, `globs`); every slot is
@@ -462,10 +463,10 @@ module Rigor
 
       # ADR-45 — re-validates this descriptor's recorded {FileEntry}s against the current filesystem. Used by
       # the record-and-validate run-result cache: a value cached alongside its dependency descriptor is fresh
-      # iff every recorded file still matches. Only `files` are checked — non-file inputs (config / gems /
+      # iff every recorded file still matches. Only `files` and `globs` are checked — non-file inputs (config / gems /
       # version) belong in the cache *key*, not the validated dependency set — so a descriptor carrying any
       # non-file slot is never considered fresh (it was built wrong for this use). ADR-60 WD3 adds `globs`
-      # alongside `files` as a re-validatable slot: a {GlobEntry} is fresh when re-globbing + re-digesting
+      # alongside `files` as a re-validatable slot: a {GlobEntry} is fresh when re-globbing
       # reproduces its recorded value. ADR-45 WD1 (#577): an absence row ({FileEntry.absent}) is fresh
       # while its path is still missing — the negative half of the dependency set.
       def fresh?
@@ -581,8 +582,8 @@ module Rigor
         false
       end
 
-      # ADR-60 WD3 / ADR-87 WD2 — stat-validates the entry's per-file table against the live tree, re-hashing
-      # only stat-moved files. Any failure reads as stale (recompute), never a crash.
+      # ADR-60 WD3 / ADR-87 WD2 — recomputes the entry's signature over the live tree and compares it. Any
+      # failure reads as stale (recompute), never a crash.
       def glob_entry_fresh?(entry)
         GlobEntry.fresh?(entry)
       end