rigortype 0.4.7 → 0.4.8

data/lib/rigor/analysis/worker_session.rb

@@ -169,6 +169,14 @@ module Rigor
       # 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
@@ -204,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
@@ -227,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?
@@ -237,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,
@@ -258,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.
@@ -419,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
-      rescue StandardError
-        nil
+        Plugin::TrustPolicy.for_configuration(@configuration)
       end
 
       def run_plugin_prepare
@@ -473,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

@@ -126,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,
@@ -156,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
@@ -174,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/cache/file_digest.rb

@@ -2,6 +2,8 @@
 
 require "digest"
 
+require_relative "../typing_state"
+
 module Rigor
   module Cache
     # Per-run content-digest memo AND the ADR-87 stat-then-digest freshness choke point. Within a single
@@ -20,20 +22,38 @@ module Rigor
     # zero SHA-256 bytes. The SHA-256 digest remains the sole change AUTHORITY — the stat tier only decides
     # whether the digest needs recomputing.
     #
-    # Soundness: the memo + recording-instant + strict flag are process-local (thread-locals, so Ractor-safe
-    # and never crossing a fork boundary), never persisted to disk, and scoped to exactly one run via
-    # {.with_run} (which installs a fresh table and restores the previous one on exit — a second run, or a run
+    # Soundness: the memo + recording-instant + strict flag are process-local (a per-thread {TypingState}
+    # Frame, so Ractor-safe and never crossing a fork boundary), never persisted to disk, and scoped to exactly one
+    # run via {.with_run} (which installs a fresh table and restores the previous one on exit — a second run, or a run
     # that re-reads a file the user edited between runs, gets a clean table). Within a single run the analyzer
     # already assumes the filesystem is stable — {Descriptor#fresh?} validates the whole dependency set against
     # the live tree in one pass and never re-checks mid-run — so caching a coherent per-run snapshot changes
     # nothing about what a run observes. Outside a run scope (no active table) every call digests directly,
     # identical to a bare `Digest::SHA256.file`.
     module FileDigest
-      MEMO_KEY = :rigor_cache_file_digest_memo
-      STAT_KEY = :rigor_cache_file_stat_memo
-      INSTANT_KEY = :rigor_cache_recording_instant
-      STRICT_KEY = :rigor_cache_strict_validation
-      private_constant :MEMO_KEY, :STAT_KEY, :INSTANT_KEY, :STRICT_KEY
+      # One run's state: the digest table, the stat table, the recording instant and the strict flag, installed
+      # together by {.with_run}.
+      Run = Data.define(:digests, :stats, :instant, :strict)
+      private_constant :Run
+
+      # ADR-129 WD1 — a Frame: {.with_run} installs the run and restores the previous one on the way out, and whether
+      # one is installed changes answers (outside a run every call digests or stats directly, the recording instant
+      # is the moment of the call, and validation is not strict). The installed {Run} is frozen; its two tables are
+      # extensional caches its owner fills in place without a touch (Memos by kind, whose entry is fixed once
+      # written): `digests` is keyed on the path and reads the file's bytes, `stats` is keyed on the path and reads
+      # its `File::Stat`, both under the run's premise that the filesystem is stable. The instant and the flag are
+      # read at install time.
+      RUN = TypingState.frame(
+        :file_digest_run,
+        memos: %i[digests stats],
+        reason: "installed per run by with_run; the digest and stat tables are extensional caches keyed on the path, " \
+                "filled in place, both reading the filesystem under the run's stable-filesystem premise, and the " \
+                "recording instant and strict flag are fixed at install",
+        # G1′: the run wraps the typing of every file, but the digest and stat lookups are the cache layer's, made while
+        # the RBS environment is prepared and its producers fetched, before anything types (#2883).
+        typing_never_reads: true
+      )
+      private_constant :RUN
 
       # Set in the environment to force the strict digest-always validation path for a single run, regardless
       # of the `cache.validation` config setting (the env wins). The escape hatch for a filesystem whose stat
@@ -46,21 +66,9 @@ module Rigor
       # captured at run start — a file whose recorded mtime is not strictly older than it is treated as racy
       # (always re-hashed), catching a file edited during the analysis window. `strict:` forces the
       # digest-always path for `cache.validation: digest`.
-      def self.with_run(strict: false)
-        previous_memo = Thread.current[MEMO_KEY]
-        previous_stat = Thread.current[STAT_KEY]
-        previous_instant = Thread.current[INSTANT_KEY]
-        previous_strict = Thread.current[STRICT_KEY]
-        Thread.current[MEMO_KEY] = {}
-        Thread.current[STAT_KEY] = {}
-        Thread.current[INSTANT_KEY] = now_ns
-        Thread.current[STRICT_KEY] = strict
-        yield
-      ensure
-        Thread.current[MEMO_KEY] = previous_memo
-        Thread.current[STAT_KEY] = previous_stat
-        Thread.current[INSTANT_KEY] = previous_instant
-        Thread.current[STRICT_KEY] = previous_strict
+      def self.with_run(strict: false, &)
+        run = Run.new(digests: {}, stats: {}, instant: now_ns, strict: strict)
+        TypingState.current.with(RUN, run, &)
       end
 
       # The SHA-256 hex digest of `path`'s current content. Served from the active per-run table when one is
@@ -68,10 +76,10 @@ module Rigor
       # read failure (missing / unreadable file) propagates exactly as `Digest::SHA256.file` would and is NOT
       # memoised, so a caller's own rescue path is unchanged.
       def self.hexdigest(path)
-        memo = Thread.current[MEMO_KEY]
-        return Digest::SHA256.file(path).hexdigest if memo.nil?
+        run = TypingState.current[RUN]
+        return Digest::SHA256.file(path).hexdigest if run.nil?
 
-        memo[path] ||= Digest::SHA256.file(path).hexdigest
+        run.digests[path] ||= Digest::SHA256.file(path).hexdigest
       end
 
       # @return whether digest-always validation is forced for this run. The env var wins over the
@@ -79,7 +87,7 @@ module Rigor
       def self.strict_validation?
         return true if ENV[STRICT_ENV] == "1"
 
-        Thread.current[STRICT_KEY] == true
+        TypingState.current[RUN]&.strict == true
       end
 
       # ADR-87 WD1 — packs the `:stat` FileEntry value: `"<digest> <size> <mtime_ns> <ctime_ns> <inode>
@@ -156,14 +164,14 @@ module Rigor
       # describe that moment rather than an earlier probe's. A stat failure propagates un-memoised, exactly
       # as {.hexdigest} treats a read failure.
       def self.validation_stat(path)
-        memo = Thread.current[STAT_KEY]
-        return File.stat(path) if memo.nil?
+        run = TypingState.current[RUN]
+        return File.stat(path) if run.nil?
 
-        memo[path] ||= File.stat(path)
+        run.stats[path] ||= File.stat(path)
       end
 
       def self.recording_instant_ns
-        Thread.current[INSTANT_KEY] || now_ns
+        TypingState.current[RUN]&.instant || now_ns
       end
 
       # value layout: [digest, size, mtime_ns, ctime_ns, inode, recording_instant_ns]

data/lib/rigor/cache/incremental_snapshot.rb

@@ -202,7 +202,24 @@ module Rigor
       # 47: issues #2079 / #2170 — each seed bundle's `global_write_census` also records each instance-side ivar
       # write's coarse value (`[:own_write_type, class, name, value, path]`), which the class-ivar census joins across
       # files and along the chain; a pre-47 bundle carries none, so a warm run would keep a seed a cold run widens.
-      SCHEMA = 47
+      # 48: issue #1237 — a `return_summaries` key may carry a third element, `true`, for a call key a splat call
+      # observed, which the gate re-drives with no positional correspondence. A pre-48 summary holds such a call under a
+      # positional key the engine bound as one argument, so a warm run would re-drive it the old way.
+      # 49: issue #3116 — a `return_summaries` entry for a def observed under more keys than the per-def cap is
+      # `{ keys: [], returns: [], effects:, overflow: true }`. A pre-49 summary holds the first eight keys of such a
+      # def with no marker, so a warm run would skip the reader of a key it never recorded.
+      # 50: issue #3160 — a `return_summaries` entry holds every key under which a current reader observes the def,
+      # merged across the runs that observed them, and a def whose keys cannot all be listed has no entry (the
+      # `overflow` form of 49 is gone). A pre-50 summary holds only what the last run that analysed the def's file
+      # saw, so a warm run would skip a reader added, or left out of that run, since.
+      # 51: issue #3180 — a reader the ADR-89 WD2 gate skipped holds the dependency edges the gate's probe recorded
+      # for the def it passed, and the summaries hold the keys that probe observed. A pre-51 snapshot's skipped
+      # readers lack the edges and keys of whatever a gate-passed def came to reach, so a warm run would skip them.
+      # 52: issues #3186 / #3187 — a `return_summaries` entry also holds `guard_constants`, the published-constant
+      # spellings the truthiness rule's one hop reads in the def's body, and a gate-skipped reader holds the plugin
+      # reads and run-scoped registrations the gate's probe made. A pre-52 snapshot's skipped readers lack those
+      # plugin rows, so a warm run would serve them past an edit of what the plugin read.
+      SCHEMA = 52
 
       # The persisted per-file state.
       # `cache` maps an analyzed file to its diagnostics.
@@ -233,10 +250,15 @@ module Rigor
       # fingerprint cannot see.
       # ADR-89 WD2:
       # `return_summaries` maps a `[path, "Class#method" | "Class.method"]` to the callee's persisted
-      # behavioural surface `{ keys:, returns:, effects: }` — the observed `[receiver, arg_types]` call keys
-      # (Marshal-clean type tuples), their `describe(:short)` return descriptors, and the content-mutated
-      # parameter positions. A recheck re-evaluates a declaration-stable changed callee at these keys and,
-      # when every return + the effects are unchanged, skips its symbol dependents.
+      # behavioural surface `{ keys:, returns:, effects:, guard_constants: }` — the observed `[receiver, arg_types]`
+      # call keys (issue #1237: `[receiver, arg_types, true]` for a key a splat call observed)
+      # (Marshal-clean type tuples), their `describe(:short)` return descriptors, the content-mutated
+      # parameter positions, and (issue #3186) the published-constant spellings the body reads.
+      # A recheck re-evaluates a declaration-stable changed callee at these keys and,
+      # when every return, the effects and the spellings are unchanged, skips its symbol dependents.
+      # Issues #3116 / #3160 — an entry
+      # holds every key under which a current symbol dependent observes the def; a def whose keys cannot all be
+      # listed (more than the per-def cap, among others) has no entry, and the recheck never skips its dependents.
       # ADR-67 WD6c lift:
       # `param_table` is the `parameter_inference:` seed table (`[class, method, kind] => {param => Type}`)
       # the run that wrote the snapshot seeded its analysis from — `{}` when the gate is off. A recheck
@@ -333,8 +355,7 @@ module Rigor
           "sig:#{digest_signature_paths(project_sig_roots(configuration))}",
           "pre_eval:#{digest_pre_eval(configuration.pre_eval)}"
         ]
-        parts.concat(core_root_parts(configuration))
-        parts.concat(dependency_source_parts(configuration))
+        parts.concat(project_input_parts(configuration))
         identity = EngineSource.process_identity
         parts << "engine-source:#{identity}" if identity
         # Issue #1700 — the gated vendored signatures the run's source activates. A file that gains or drops a
@@ -360,12 +381,34 @@ module Rigor
       # Issue #2517 — a selected core is read like the project's own `sig/`, so an edit in place to one of its files
       # must drop the snapshot (and the language server's session, which keys on this fingerprint). No part for the
       # default core, so every other project's fingerprint is as it was.
+      def self.extra_signature_parts(configuration)
+        core_root_parts(configuration) + bundle_sig_parts(configuration)
+      end
+      private_class_method :extra_signature_parts
+
       def self.core_root_parts(configuration)
         core_root = configuration.core_root
         core_root.nil? ? [] : ["core:#{digest_signature_paths([core_root])}"]
       end
       private_class_method :core_root_parts
 
+      # Issue #2987 — the bundle gems' own `sig/` directories the environment loads: which gems have one and what
+      # their `.rbs` files hold. The lockfile digest above covers a gem's version, not a `sig/` appearing under an
+      # unchanged version, nor an edit in place to one. Shared with the language server's session key. No part for a
+      # project whose bundle holds none, so its fingerprint is as it was.
+      def self.bundle_sig_parts(configuration)
+        locked = Environment::LockfileResolver.locked_gems(
+          lockfile_path: configuration.bundler_lockfile, project_root: Dir.pwd,
+          auto_detect: configuration.bundler_auto_detect
+        )
+        dirs = Environment::BundleSigDiscovery.discover(
+          bundle_path: configuration.bundler_bundle_path, project_root: Dir.pwd,
+          auto_detect: configuration.bundler_auto_detect, locked_gems: locked.empty? ? nil : locked
+        ).map(&:to_s).sort
+        dirs.empty? ? [] : ["bundle-sig:#{dirs.join("\n")}:#{digest_signature_paths(dirs)}"]
+      end
+      private_class_method :bundle_sig_parts
+
       def self.required_features(configuration, roots)
         files = Analysis::PathExpansion.ruby_files(roots, configuration.exclude_patterns,
                                                    base: configuration.exclude_base)
@@ -383,6 +426,22 @@ module Rigor
       end
       private_class_method :dependency_source_parts
 
+      # The parts read off the project beside its configuration, in the order the fingerprint has always joined them:
+      # the extra signature roots, the `dependencies.source_inference` gems, and (#3030) the collection setup hint.
+      def self.project_input_parts(configuration)
+        extra_signature_parts(configuration) + dependency_source_parts(configuration) +
+          collection_setup_hint_parts(configuration)
+      end
+      private_class_method :project_input_parts
+
+      # Issue #3030 — the `rbs.coverage.collection-not-installed` hint, a run-level row read off the working directory
+      # that no other part covers. No part without a hint, so every other project's fingerprint is as it was.
+      def self.collection_setup_hint_parts(configuration)
+        hint = Analysis::RunCacheKey.collection_setup_hint(configuration)
+        hint ? ["rbs-collection-hint:#{hint}"] : []
+      end
+      private_class_method :collection_setup_hint_parts
+
       def self.digest_file_if_present(path)
         path = path&.to_s
         path && File.file?(path) ? Digest::SHA256.file(path).hexdigest : "absent"

data/lib/rigor/cache/rbs_descriptor.rb

@@ -77,7 +77,8 @@ module Rigor
       # reconstructs {.config_entries} without loading a plugin, so an entry there that it cannot rebuild
       # would turn the warm fast lane into a permanent miss on every project that enables a bundled plugin.
       def self.env_only_config_entries(loader)
-        [deferred_signature_paths_entry(loader), project_signature_paths_entry(loader), core_root_entry(loader)].compact
+        [deferred_signature_paths_entry(loader), project_signature_paths_entry(loader), core_root_entry(loader),
+         subordinate_signature_paths_entry(loader), collection_signature_paths_entry(loader)].compact
       end
 
       # Issue #2517 — which directory the env loaded core from. The selected core's files are digested by
@@ -142,6 +143,40 @@ module Rigor
 
       private_class_method :deferred_signature_paths_entry
 
+      # Issue #2978 — which of the loader's `signature_paths:` stand down member by member to the rest (a bundle gem's
+      # collection copy behind its own `sig/`) changes the env built from byte-identical files, as the deferred
+      # partition does. Absent when there is none, so every other project keeps its key.
+      def self.subordinate_signature_paths_entry(loader)
+        return nil unless loader.respond_to?(:subordinate_signature_paths)
+
+        subordinate = Array(loader.subordinate_signature_paths).map(&:to_s).sort
+        return nil if subordinate.empty?
+
+        Descriptor::ConfigEntry.new(
+          key: "rbs.subordinate_signature_paths",
+          value_hash: Digest::SHA256.hexdigest(subordinate.join("\n"))
+        )
+      end
+
+      private_class_method :subordinate_signature_paths_entry
+
+      # Issue #3030 — which of the loader's `signature_paths:` are `rbs collection` gem directories decides whether
+      # their `_`-prefixed directories load, so it changes the env built from byte-identical files. Absent when
+      # there is none, so every project without a collection lockfile keeps its key.
+      def self.collection_signature_paths_entry(loader)
+        return nil unless loader.respond_to?(:collection_signature_paths)
+
+        collection = Array(loader.collection_signature_paths).map(&:to_s).sort
+        return nil if collection.empty?
+
+        Descriptor::ConfigEntry.new(
+          key: "rbs.collection_signature_paths",
+          value_hash: Digest::SHA256.hexdigest(collection.join("\n"))
+        )
+      end
+
+      private_class_method :collection_signature_paths_entry
+
       # Public (ADR-87 WD4) so the boot-slimming run-cache probe reconstructs the identical `gems` +
       # `rbs.libraries` key slots the runner writes, from the config-derived library list, without a loader.
       def self.rbs_gem_entry
@@ -208,7 +243,7 @@ module Rigor
       end
 
       # @param library_names — the loader's merged library list (or, on the WD4 probe
-      #   path, `Environment::DEFAULT_LIBRARIES + config.libraries` reconstructed without a loader).
+      #   path, `Environment::BaseLibraries.resolve` reconstructed without a loader).
       def self.libraries_entry(library_names)
         sorted = library_names.map(&:to_s).sort
         Descriptor::ConfigEntry.new(

data/lib/rigor/cache/rbs_environment.rb

@@ -36,7 +36,11 @@ module Rigor
             loader.respond_to?(:deferred_signature_paths) ? loader.deferred_signature_paths : [],
           project_signature_paths:
             loader.respond_to?(:project_signature_paths) ? loader.project_signature_paths : [],
-          core_root: loader.respond_to?(:core_root) ? loader.core_root : nil
+          core_root: loader.respond_to?(:core_root) ? loader.core_root : nil,
+          subordinate_signature_paths:
+            loader.respond_to?(:subordinate_signature_paths) ? loader.subordinate_signature_paths : [],
+          collection_signature_paths:
+            loader.respond_to?(:collection_signature_paths) ? loader.collection_signature_paths : []
         )
       end
 

data/lib/rigor/cli/baseline_command.rb

@@ -176,7 +176,7 @@ module Rigor
 
         baseline = Analysis::Baseline.from_diagnostics(diagnostics, match_mode: options.fetch(:match_mode),
                                                                     project_root: Dir.pwd)
-        File.write(path, baseline.to_yaml)
+        return EXIT_USAGE unless write_baseline_file(path, baseline.to_yaml)
 
         covered = baseline.buckets.sum(&:count)
         @err.puts(
@@ -415,7 +415,8 @@ module Rigor
         return 0 if options.fetch(:dry_run)
 
         pruned = baseline.without(cleared.map(&:bucket))
-        File.write(options.fetch(:baseline), pruned.to_yaml)
+        return EXIT_USAGE unless write_baseline_file(options.fetch(:baseline), pruned.to_yaml)
+
         @err.puts("rigor: pruned #{cleared.size} bucket(s); baseline now has #{pruned.size} entries.")
         0
       end
@@ -439,6 +440,18 @@ module Rigor
 
       # ---- shared helpers ----------------------------------------
 
+      # #2576 — an output path that cannot be written is a usage error, the same rule `rigor init
+      # --path` follows (#2562): one `rigor baseline: cannot write PATH: REASON` line on stderr and
+      # exit 64, with no backtrace and no directory created on the way. The bare Errno backtrace read
+      # as an internal crash.
+      def write_baseline_file(path, content)
+        File.write(path, content)
+        true
+      rescue SystemCallError => e
+        @err.puts("rigor baseline: cannot write #{path}: #{e.message.sub(/ @ .*\z/m, '')}")
+        false
+      end
+
       def load_baseline_or_exit(path)
         unless File.exist?(path)
           @err.puts("rigor: baseline file not found: #{path}")

data/lib/rigor/cli/check_command.rb

@@ -866,7 +866,8 @@ module Rigor
         return Configuration.load(options.fetch(:config)) unless options.fetch(:treat_all_as_inline_rbs)
 
         path = options.fetch(:config) || Configuration.discover
-        data = path && File.exist?(path) ? Configuration.load_with_includes(path) : {}
+        config_file = path && File.exist?(path) ? path : nil
+        data = config_file ? Configuration.load_with_includes(config_file) : {}
         # ADR-103 WD15 — captured before `DEFAULTS.merge` below folds "no `effects:` key" and "`effects:
         # false`" into the same value; see `Configuration.load`'s identical capture.
         effects_key_present = data.key?("effects")
@@ -874,7 +875,8 @@ module Rigor
         data = data.dup
         data["plugins"] = inject_treat_all_as_inline_rbs(Array(data["plugins"]))
         Configuration.new(Configuration::DEFAULTS.merge(data), effects_key_present, target_ruby_key_present)
-                     .with_exclude_base(path && File.exist?(path) ? File.dirname(path) : nil)
+                     .with_exclude_base(config_file && File.dirname(config_file))
+                     .with_config_path(config_file)
       end
 
       # ADR-50 § WD2 — applies the `--bleeding-edge[=ids]` / `--no-bleeding-edge` CLI selection over the configured

data/lib/rigor/cli/effects_snapshot_command.rb

@@ -91,7 +91,14 @@ module Rigor
       # exists" hazard: it records observations, so overwriting it is the whole point of running it.
       def write(configuration, snapshot)
         path = configuration.effects_snapshot_path
-        File.write(path, snapshot.to_yaml)
+        begin
+          File.write(path, snapshot.to_yaml)
+        rescue SystemCallError => e
+          # #2576 — an `effects.snapshot.path:` that cannot be written is a usage error, the same rule
+          # `rigor init --path` follows (#2562): one line on stderr and exit 64, no backtrace.
+          @err.puts("rigor effects: cannot write #{path}: #{e.message.sub(/ @ .*\z/m, '')}")
+          return CLI::EXIT_USAGE
+        end
         @err.puts("rigor: wrote #{path} (#{snapshot.methods.size} method(s), #{snapshot.reach.size} reach entr" \
                   "#{snapshot.reach.size == 1 ? 'y' : 'ies'})")
         # #436 — the note names what to write, not only what is missing: the same per-project preset

data/lib/rigor/cli/lens_command.rb

@@ -8,13 +8,14 @@ require_relative "options"
 require_relative "check_runner_factory"
 require_relative "../configuration"
 require_relative "../lens"
+require_relative "../lens/claims"
 
 module Rigor
   class CLI
     # `rigor lens FILE...` — a declaration map of the files with type provenance, computed as `rigor check`
     # computes them (ADR-113; output contract docs/internal-spec/lens.md). Experimental until `lens/v1`.
     class LensCommand < Command
-      USAGE = "Usage: rigor lens [--format=text|json] [--config=PATH] [--workers=N] FILE..."
+      USAGE = "Usage: rigor lens [--format=text|json] [--claims=REQUEST] [--config=PATH] [--workers=N] FILE..."
 
       def run
         options = parse_options
@@ -25,13 +26,19 @@ module Rigor
         config_path = options.fetch(:config) || Configuration.discover
         # The working directory: Rigor auto-detects sig/ and the lockfiles there (lens.md § Serialization).
         root = Dir.pwd
+        request = options[:claims] && Lens::Claims::Request.read(options[:claims], root: root, arguments: @argv)
         workers = CheckRunnerFactory.resolve_workers(options, configuration)
-        outcome = Lens::Run.new(configuration: configuration, root: root, arguments: @argv, workers: workers).call
+        run = Lens::Run.new(configuration: configuration, root: root, arguments: @argv, workers: workers)
+        outcome = run.call
         document = Lens::Document.new(outcome: outcome, configuration: configuration, root: root,
                                       config_path: config_path).to_h
+        attach_claims(document, request, outcome, run)
         @err.puts("rigor lens: #{outcome.warm ? 'warm' : 'cold'} — #{@argv.size} target(s)")
         render(document, options.fetch(:format))
         outcome.targets.any? { |target| target.status == "ok" } ? 0 : 1
+      rescue Lens::Claims::IntegrityError => e
+        usage_error(e.message)
+        CLI::EXIT_USAGE
       end
 
       # The parser this command parses with, built without parsing anything: the catalogue reads the
@@ -42,15 +49,23 @@ module Rigor
           Options.add_format(opts, options, "Output format: text (default) or json")
           opts.on("--workers=N", Integer, "Worker processes for a cold run") { |value| options[:workers] = value }
           Options.add_config(opts, options)
+          opts.on("--claims=REQUEST", "Check documentation claims (requires --format=json)") do |value|
+            options[:claims] = value
+          end
         end
       end
 
       private
 
+      def attach_claims(document, request, outcome, run)
+        document["claims"] = Lens::Claims.new(request: request, outcome: outcome, run: run).call if request
+      end
+
       def parse_options
         options = { format: "text", config: nil, workers: nil }
         option_parser(options).parse!(@argv)
         return usage_error("no FILE given") if @argv.empty?
+        return usage_error("--claims requires --format=json") if options[:claims] && options[:format] != "json"
 
         options
       rescue OptionParser::ParseError => e

data/lib/rigor/cli/sig_gen_command.rb

@@ -308,6 +308,14 @@ module Rigor
         # user asked for a write and did not get one, so the command must not report success — a green
         # `sig-gen --write` in CI would otherwise mean nothing.
         results.any? { |result| TARGET_REFUSALS.include?(result.action) } || !refused.empty? ? 1 : 0
+      rescue SigGen::Writer::WriteError => e
+        # #2576 — a target that cannot be written at all (permission denial, a directory where the
+        # `.rbs` belongs, a parent path that is a regular file) is a usage error, the same rule
+        # `rigor init --path` follows (#2562):
+        # one line on stderr and exit 64. The run stops at the first failure; targets already written
+        # stay written.
+        @err.puts("rigor sig-gen: #{e.message}")
+        CLI::EXIT_USAGE
       end
 
       # ADR-112 WD4 — the methods whose inline and `sig/` declarations disagree, refused because the run did not

data/lib/rigor/cli/skill_describe.rb

@@ -130,6 +130,7 @@ module Rigor
         rigor-editor-setup
         rigor-mcp-setup
         rigor-protection-uplift
+        rigor-rbs-contract
         rigor-plugin-tune
         rigor-plugin-author
         rigor-upgrade