rigortype 0.3.7 → 0.3.9

data/lib/rigor/cache/store.rb

@@ -38,7 +38,14 @@ module Rigor
       # `PAYLOAD_ABI_VERSION` already rebuilds across a RELEASE, so the exposure is a same-version tree; this
       # closes that window too, because "the same project reports differently depending on how you ran it" is
       # the defect the diagnostic exists to end and a stale blob reintroduces it.
-      FORMAT_VERSION = 3
+      #
+      # v4 (issue #799): `RBS::AST::Annotation` now carries its own `marshal_dump` / `marshal_load`, which
+      # keep the annotation's POSITION as well as its file, so `rbs_extended.unsatisfied-conformance` points
+      # at the `%a{rigor:v1:conforms-to …}` line warm as well as cold. A pre-change blob loads perfectly well
+      # — Marshal encodes an ivar dump and a `marshal_dump` payload differently, and only the latter reaches
+      # `marshal_load` — which is exactly the problem: without a bump it would keep reporting the row at
+      # `1:1` forever, and `--verify-incremental` would keep failing on that project.
+      FORMAT_VERSION = 4
 
       # Payload ABI version. Store values are mostly Marshal blobs of Rigor/RBS objects, so a Rigor release
       # upgrade is an ABI boundary even when the byte layout and descriptor schema are unchanged. Folding the
@@ -58,8 +65,8 @@ module Rigor
 
       VALID_PRODUCER_ID = /\A[a-z][a-z0-9._-]*\z/
 
-      # @param root [String] cache root directory.
-      # @param read_only [Boolean] when true, every disk-side side-effect is suppressed: `fetch_or_compute`
+      # @param root — cache root directory.
+      # @param read_only — when true, every disk-side side-effect is suppressed: `fetch_or_compute`
       #   still reads existing entries (hits, gated on a current `schema_version.txt` marker — see
       #   {#ensure_schema_version!}) and still runs the producer block on miss, but it does NOT write the
       #   produced value to disk, does NOT update the marker, and does NOT touch the on-disk root directory.
@@ -100,7 +107,7 @@ module Rigor
 
       attr_reader :root
 
-      # @return [Boolean] whether this Store suppresses disk writes (`schema_version.txt`, entry creation).
+      # @return whether this Store suppresses disk writes (`schema_version.txt`, entry creation).
       #   Reads are unaffected.
       def read_only?
         @read_only
@@ -111,7 +118,7 @@ module Rigor
       # specific instance rather than the on-disk cache state. Disk-level state is reported separately by
       # {.disk_inventory}.
       #
-      # @return [Hash] `{ hits:, misses:, writes:, by_producer: { id => { hits:, misses:, writes: } } }`
+      # @return `{ hits:, misses:, writes:, by_producer: { id => { hits:, misses:, writes: } } }`
       def stats
         @monitor.synchronize do
           per_producer = @by_producer.transform_values { |counts| counts.dup.freeze }.freeze
@@ -123,7 +130,7 @@ module Rigor
       # `rigor check --cache-stats` to surface cache size and per-producer entry counts without depending on
       # in-process counters (which only reflect the current run).
       #
-      # @return [Hash] `{ root:, schema_version:, total_entries:, total_bytes:, producers: [{ id:, entries:,
+      # @return `{ root:, schema_version:, total_entries:, total_bytes:, producers: [{ id:, entries:,
       #   bytes: }, ...] }`. When the root does not exist or has no schema-version marker, `schema_version` is
       #   nil and the producer list is empty.
       #
@@ -169,21 +176,21 @@ module Rigor
       end
       private_class_method :collect_producers
 
-      # @param producer_id [String] stable cache namespace; only `[a-z][a-z0-9._-]*` is accepted.
-      # @param generation_cap [Integer, Symbol] how many generations of this producer survive a compaction
+      # @param producer_id — stable cache namespace; only `[a-z][a-z0-9._-]*` is accepted.
+      # @param generation_cap — how many generations of this producer survive a compaction
       #   pass — a positive `Integer` for a whole-project producer (one live entry, older ones unreachable),
       #   or {UNBOUNDED_GENERATIONS} for a producer with many simultaneously-live entries. REQUIRED, and
       #   sourced from the producer's own declaration (`RbsCacheProducer.generation_cap`,
       #   `RunCacheKey::GENERATION_CAP`, `Plugin::Base.producer generation_cap:`) rather than invented at the
       #   call site. See {#evict!}.
-      # @param params [Hash] producer inputs; mixed into the cache key via {Descriptor#cache_key_for}.
-      # @param descriptor [Rigor::Cache::Descriptor] the invalidation descriptor for the value being cached.
-      # @param serialize [#call, nil] optional callable that turns the producer's return value into a binary
+      # @param params — producer inputs; mixed into the cache key via {Descriptor#cache_key_for}.
+      # @param descriptor — the invalidation descriptor for the value being cached.
+      # @param serialize — optional callable that turns the producer's return value into a binary
       #   `String`. Defaults to `Marshal.dump(value).b`. Producers whose return values are not
       #   `Marshal`-clean (RBS-native objects with `RBS::Location` members, raw `IO`, …) MUST provide a
       #   serialiser. The pair `(serialize, deserialize)` MUST round-trip — a producer that reads with one
       #   strategy and writes with another corrupts its own cache slice.
-      # @param deserialize [#call, nil] optional callable that turns bytes back into the producer's value.
+      # @param deserialize — optional callable that turns bytes back into the producer's value.
       #   Defaults to `Marshal.load`. Any exception (`StandardError`) raised by the deserialiser is treated as
       #   a cache miss — the entry is considered corrupt, the producer block reruns, and the next write
       #   overwrites it. This is consistent with the fault-tolerance contract for the default `Marshal.load`
@@ -387,10 +394,22 @@ module Rigor
 
       # Reads and validates one entry file. Any failure (missing, short, bad magic, bad version, bad
       # checksum, unmarshal-able) returns nil so the caller treats it as a cache miss.
+      #
+      # The `ENOENT` rescue covers the gap between the existence check and the open: a concurrent process
+      # compacting or clearing the root can unlink the file in between, and a file that is gone reads as the
+      # same miss the existence check above already reports for one that was never there (issue #807). It is
+      # deliberately narrow — every other `SystemCallError` (a permission error, an I/O error) still raises,
+      # so a genuinely broken filesystem stays visible instead of degrading into an endless recompute. A
+      # present-but-corrupt file is not touched by this either: it still goes through the envelope and
+      # payload checks below.
       def read_entry(path, deserialize: nil)
         return nil unless File.file?(path)
 
-        bytes = File.binread(path)
+        begin
+          bytes = File.binread(path)
+        rescue Errno::ENOENT
+          return nil
+        end
         return nil unless envelope_valid?(bytes)
 
         body = bytes.byteslice(HEADER.bytesize, bytes.bytesize - HEADER.bytesize - 32)
@@ -479,22 +498,34 @@ module Rigor
       def atomically_replace(path, body)
         File.open(path, File::RDWR | File::CREAT, 0o644) do |lock_fd|
           lock_fd.flock(File::LOCK_EX)
-          tmp = "#{path}.tmp.#{Process.pid}.#{SecureRandom.hex(4)}"
-          begin
-            File.open(tmp, "wb") do |f|
-              f.write(body)
-              f.fsync
-            end
-            File.rename(tmp, path)
-          ensure
-            # A failed write/rename must not leak its temp file — rely on the 1-hour `cleanup_stale_temp_files`
-            # sweep only as a backstop for crashes that skip this ensure entirely.
-            unlink_entry(tmp) if File.exist?(tmp)
-          end
+          publish_by_rename(path, body)
           fsync_directory(File.dirname(path))
         end
       end
 
+      # The rename-into-place half of {#atomically_replace}, without the destination lock: writes `body` to a
+      # sibling temp file, fsyncs it, and renames it over `path`. POSIX makes the rename atomic within one
+      # filesystem, so an unlocked concurrent reader sees either the previous contents in full or the new
+      # ones in full — never a truncated or half-written file.
+      #
+      # {#repair_writable_marker!} uses this half alone. It needs the atomicity (its reader is another
+      # process's constructor, which does not lock) but not the ordering a lock would buy: every writer of
+      # `schema_version.txt` writes the same value, so there is no last-writer-wins question to settle.
+      def publish_by_rename(path, body)
+        tmp = "#{path}.tmp.#{Process.pid}.#{SecureRandom.hex(4)}"
+        begin
+          File.open(tmp, "wb") do |f|
+            f.write(body)
+            f.fsync
+          end
+          File.rename(tmp, path)
+        ensure
+          # A failed write/rename must not leak its temp file — rely on the 1-hour `cleanup_stale_temp_files`
+          # sweep only as a backstop for crashes that skip this ensure entirely.
+          unlink_entry(tmp) if File.exist?(tmp)
+        end
+      end
+
       # Checks (and, for a writable store, repairs) the `schema_version.txt` marker, and reports whether the
       # disk tier is usable for the rest of this Store's lifetime. The result is memoized in `@disk_available`
       # — one check per Store is enough; a benign double-check under a thread race would just repeat
@@ -508,8 +539,6 @@ module Rigor
       # (permission, disk full, deleted root) also reports unavailable, degrading this Store instance to
       # in-memory-memo-only for the rest of its lifetime — the producer block still runs, its result still
       # lands in `@memo`, and disk reads/writes are simply skipped.
-      #
-      # @return [Boolean]
       def ensure_schema_version!
         return @disk_available unless @disk_available.nil?
 
@@ -525,25 +554,48 @@ module Rigor
         false
       end
 
+      # The marker is PUBLISHED BY RENAME rather than written in place. Its reader is another process's
+      # constructor, which takes no lock, so an `O_TRUNC`-then-write would expose a window in which the file
+      # exists and is empty; a reader landing there concludes the marker disagrees and clears the whole cache
+      # root — under, among others, a sibling that is between its own `File.file?` and `File.binread`, which
+      # is the `Errno::ENOENT` of issue #807. Two `rigor check` processes over one fresh `.rigor/cache` are
+      # enough to hit it.
+      #
+      # An EMPTY marker is treated as an ABSENT one — rewritten, never cleared on. Emptiness carries no
+      # information: it is what a torn write by an older Rigor looks like, what a crash between the create
+      # and the write leaves, and what this method's own clear-then-rewrite passes through. Answering an
+      # ambiguous signal by destroying a cache root is the wrong trade, and declining grants the entries
+      # below no trust they did not already have — a marker that is simply MISSING over existing entries is
+      # already kept and served (see the spec's writable-store rules), and `clear_cache_root!` removes the
+      # marker before rewriting it, so it produces that state itself.
       def repair_writable_marker!
         FileUtils.mkdir_p(@root)
         marker = File.join(@root, "schema_version.txt")
         current = self.class.schema_marker_value
 
-        if File.file?(marker)
-          on_disk = File.read(marker).strip
-          return true if on_disk == current
+        on_disk = read_marker(marker)
+        return true if on_disk == current
 
-          clear_cache_root!
-        end
+        clear_cache_root! unless on_disk.nil? || on_disk.empty?
 
         FileUtils.mkdir_p(@root)
-        File.write(marker, "#{current}\n")
+        publish_by_rename(marker, "#{current}\n")
+        fsync_directory(@root)
         true
       rescue StandardError
         false
       end
 
+      # @return the marker's content, or nil when there is none to read — including the case of a concurrent
+      #   {#clear_cache_root!} removing it between the check and the open.
+      def read_marker(path)
+        return nil unless File.file?(path)
+
+        File.read(path).strip
+      rescue Errno::ENOENT
+        nil
+      end
+
       def clear_cache_root!
         Dir.children(@root).each do |entry|
           FileUtils.rm_rf(File.join(@root, entry))

data/lib/rigor/cli/annotate_command.rb

@@ -15,7 +15,7 @@ require_relative "../inference/scope_indexer"
 require_relative "../inference/statement_evaluator"
 require_relative "prism_colorizer"
 require_relative "command"
-require_relative "probe_environment"
+require_relative "../project_environment"
 
 module Rigor
   class CLI
@@ -43,7 +43,7 @@ module Rigor
       # paging stays off because the CLI may itself sit in a pipeline.
       BAT_ARGS = %w[--language=ruby --style=plain --paging=never --color=always].freeze
 
-      # @return [Integer] CLI exit status.
+      # @return CLI exit status.
       def run
         options = parse_options
         file = @argv.shift
@@ -132,10 +132,10 @@ module Rigor
 
       # The plugin-aware environment for the annotated file, so a `#=> <type>` matches what `rigor check`
       # infers on that line — including types synthesized from the file's own inline RBS annotations (the file
-      # is threaded as the synthesizer's `source_files:`; see {ProbeEnvironment}).
+      # is threaded as the synthesizer's `source_files:`; see {ProjectEnvironment}).
       def base_scope(configuration, file)
         Scope.empty(
-          environment: ProbeEnvironment.build(configuration: configuration, source_files: [file])
+          environment: ProjectEnvironment.build(configuration: configuration, source_files: [file])
         )
       end
 
@@ -220,8 +220,7 @@ module Rigor
         @scope_index = scope_index
       end
 
-      # @param program [Prism::ProgramNode]
-      # @return [Hash{Integer => Rigor::Type}] 1-indexed line => type.
+      # @return 1-indexed line => type.
       def collect(program)
         by_line = {}
         each_statement(program) do |statement|

data/lib/rigor/cli/check_command.rb

@@ -32,14 +32,21 @@ module Rigor
     # The class-length budget is relaxed (as on `Rigor::CLI` itself) because `check` aggregates several independent
     # concerns that are clearer read together than split across micro-classes.
     class CheckCommand < Command # rubocop:disable Metrics/ClassLength
-      # @return [Integer] CLI exit status.
+      # Issue #812 — `--fail-on=SEVERITY` raises the exit-status bar above the default (`:error`-only).
+      # Orders the three severities a diagnostic can carry once it survives {SeverityStamp} (`:off` rows are
+      # dropped upstream and never reach a `Result`, so they are not a member here).
+      FAIL_ON_RANK = { info: 0, warning: 1, error: 2 }.freeze
+
+      # @return CLI exit status.
       #
       # Deferred YJIT enablement (Runtime::Jit) is armed by `CLI#dispatch` for every command, this
       # one included, before any analysis work runs.
-      def run # rubocop:disable Metrics/AbcSize
+      def run # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
         # ADR-87 WD4 — parse options + resolve config WITHOUT the inference engine, so the run-cache hit probe
         # can run first. The heavy engine (`load_check_dependencies`) loads only on a miss / non-cacheable run.
         options = parse_check_options
+        return CLI::EXIT_USAGE unless valid_fail_on_option?(options)
+
         buffer = Options.resolve_buffer_binding(options, err: @err)
         return CLI::EXIT_USAGE if buffer == :usage_error
 
@@ -68,7 +75,8 @@ module Rigor
         result = apply_baseline_filter(raw_result, configuration, options)
 
         coverage = compute_coverage(runner, configuration, options)
-        write_result(result, options.fetch(:format), coverage: coverage, config_warnings: config_warnings)
+        write_result(result, options.fetch(:format), coverage: coverage, config_warnings: config_warnings,
+                                                     fail_on: options.fetch(:fail_on))
         emit_ci_detected_output(result, options)
         write_run_stats(result.stats) if result.stats
         write_trace_appendices
@@ -77,11 +85,34 @@ module Rigor
 
         exit_code = result.success? ? 0 : 1
         exit_code = 1 if baseline_strict_violation?(raw_result.diagnostics, configuration, options)
+        exit_code = 1 if fail_on_violation?(result.diagnostics, options)
         exit_code
       end
 
       private
 
+      # True when `diagnostics` (already baseline-filtered and severity-resolved — the same list
+      # `Result#success?` reads) carries a row at or above the `--fail-on` threshold. With the default
+      # `:error` threshold this is exactly `!diagnostics.any?(&:error?)`, i.e. a no-op over the existing exit
+      # code — `--fail-on` only ever makes a run *stricter*, never masks an `:error` the old exit code caught.
+      def fail_on_violation?(diagnostics, options)
+        threshold = FAIL_ON_RANK.fetch(options.fetch(:fail_on))
+        diagnostics.any? { |diagnostic| FAIL_ON_RANK.fetch(diagnostic.severity, FAIL_ON_RANK[:error]) >= threshold }
+      end
+
+      # True when `options[:fail_on]` (an arbitrary user-typed Symbol at this point — parsing only lower-cases
+      # and interns it, see `parse_check_options`) is one of {FAIL_ON_RANK}'s keys; writes a usage note to
+      # `@err` and returns false otherwise. Validated as a plain post-parse check rather than raised from
+      # inside the `opts.on` block: OptionParser rescues a `ParseError` raised from a switch's own block and
+      # rebuilds it as a generic `"invalid argument: --fail-on=<value>"`, discarding any custom message — this
+      # way the usage note actually names the accepted values.
+      def valid_fail_on_option?(options)
+        return true if FAIL_ON_RANK.key?(options.fetch(:fail_on))
+
+        @err.puts("rigor: invalid --fail-on value: #{options.fetch(:fail_on)} (expected error, warning, or info)")
+        false
+      end
+
       # ADR-87 WD4 — attempt the boot-slimming run-cache hit. Returns the cached {Analysis::Result} (severity
       # profile applied, no stats — matching a cache-served `Runner#run`) on a hit, or nil to fall through to
       # the full engine path. Only an ordinary sequential check whose result IS cache-served the same way is
@@ -129,11 +160,13 @@ module Rigor
       # gate reads the same diagnostics the full path would.
       def finalize_cache_hit(raw_result, configuration, options, config_warnings)
         result = apply_baseline_filter(raw_result, configuration, options)
-        write_result(result, options.fetch(:format), config_warnings: config_warnings)
+        write_result(result, options.fetch(:format), config_warnings: config_warnings,
+                                                     fail_on: options.fetch(:fail_on))
         emit_ci_detected_output(result, options)
 
         exit_code = result.success? ? 0 : 1
         exit_code = 1 if baseline_strict_violation?(raw_result.diagnostics, configuration, options)
+        exit_code = 1 if fail_on_violation?(result.diagnostics, options)
         exit_code
       end
 
@@ -233,8 +266,8 @@ module Rigor
 
         result = apply_baseline_filter(Analysis::Result.new(diagnostics: diagnostics, stats: nil), configuration,
                                        options)
-        write_result(result, options.fetch(:format))
-        result.success? ? 0 : 1
+        write_result(result, options.fetch(:format), fail_on: options.fetch(:fail_on))
+        !result.success? || fail_on_violation?(result.diagnostics, options) ? 1 : 0
       end
 
       # Editor mode option B (#146) — `--incremental` plus an editor buffer. The whole project is in scope with
@@ -260,8 +293,8 @@ module Rigor
         filtered = apply_baseline_filter(
           Analysis::Result.new(diagnostics: result.diagnostics, stats: nil), configuration, options
         )
-        write_result(filtered, options.fetch(:format))
-        filtered.success? ? 0 : 1
+        write_result(filtered, options.fetch(:format), fail_on: options.fetch(:fail_on))
+        !filtered.success? || fail_on_violation?(filtered.diagnostics, options) ? 1 : 0
       end
 
       # ADR-88 WD1 — a one-line stderr note when the plugin fact surface (an ADR-9 fact, an ADR-60 producer
@@ -439,6 +472,10 @@ module Rigor
           baseline: :unset,
           # ADR-22 slice 5 — `--baseline-strict` CI gate: fail the run on any baseline drift, in either direction.
           baseline_strict: false,
+          # Issue #812 — `--fail-on=SEVERITY` raises the exit-status bar: the run exits non-zero when a
+          # diagnostic AT OR ABOVE this severity survives baseline filtering and severity resolution, not only
+          # on `:error` (today's default and behaviour). See `FAIL_ON_RANK`.
+          fail_on: :error,
           # ADR-32 WD10 carry-over — `--treat-all-as-inline-rbs` forces the `rigor-rbs-inline` plugin into the loaded
           # plugin set with `require_magic_comment: false` so a single ad-hoc `rigor check` invocation treats every
           # analysed file as inline-RBS without the user editing `.rigor.yml`. Intended for single-file / ad-hoc CI use;
@@ -508,6 +545,12 @@ module Rigor
                   "fail the run on any baseline drift (CI gate)") do
             options[:baseline_strict] = true
           end
+          opts.on("--fail-on=SEVERITY",
+                  "exit non-zero on a diagnostic at or above SEVERITY: error (default), warning, or info") do |value|
+            # Validated post-parse (`valid_fail_on_option?`, called from `run`) rather than here — see its
+            # comment for why an unrecognised value is not raised from inside this block.
+            options[:fail_on] = value.to_s.downcase.to_sym
+          end
           opts.on("--treat-all-as-inline-rbs",
                   "force-load rigor-rbs-inline with require_magic_comment: false") do
             options[:treat_all_as_inline_rbs] = true
@@ -661,7 +704,6 @@ module Rigor
         @err.puts("  body evals:      #{counts[bt::MEMO_BODY_EVALS]}")
         @err.puts("  non-stored:      on-stack #{counts[bt::MEMO_REFUSE_ON_STACK]}  " \
                   "unroll-in-flight #{counts[bt::MEMO_REFUSE_UNROLL]}  " \
-                  "consult-tainted #{counts[bt::MEMO_REFUSE_CONSULT_TAINTED]}  " \
                   "transient-tainted #{counts[bt::MEMO_REFUSE_TRANSIENT]}")
         write_memo_signature_table
       end
@@ -841,10 +883,15 @@ module Rigor
         format == "text" ? @out : @err
       end
 
-      def write_result(result, format, coverage: nil, config_warnings: [])
+      def write_result(result, format, coverage: nil, config_warnings: [], fail_on: :error)
         case format
         when "json"
           payload = enrich_json(result.to_h)
+          # Issue #812 — the exit code can be stricter than `payload["success"]` (which stays the `:error`-only
+          # reading `Result#success?` always gave, per the other consumers already reading it); a JSON
+          # consumer that wants to know WHY a run exited non-zero reads this alongside it rather than
+          # re-deriving `--fail-on`'s value from the invocation.
+          payload["fail_on"] = fail_on.to_s
           payload["coverage"] = coverage_payload(coverage) if coverage
           payload["config_warnings"] = config_warnings.map(&:to_h) unless config_warnings.empty?
           @out.puts(JSON.pretty_generate(payload))

data/lib/rigor/cli/check_invocation.rb

@@ -22,7 +22,7 @@ module Rigor
       # The outcome of {.attempt} — the best-effort variant. Exactly one of the two is non-nil, so a caller can never
       # read "the check could not run" as "the check ran clean": `result` is nil precisely when `error` is set.
       Outcome = Data.define(:result, :error) do
-        # @return [Boolean] true when an analysis actually completed.
+        # @return true when an analysis actually completed.
         def ran?
           !result.nil?
         end
@@ -42,12 +42,9 @@ module Rigor
 
       # Runs the analysis the way `rigor check` does and returns the runner + its raw result.
       #
-      # @param configuration [Rigor::Configuration]
-      # @param options [Hash] at least `:no_cache`, `:explain`, `:stats`, `:workers` (see {CheckRunnerFactory.build}).
-      # @param paths [Array<String>, nil] analysed paths; nil falls back to the configuration's `paths:`.
-      # @param buffer [Rigor::Analysis::BufferBinding, nil]
-      # @param cache_root [String, nil] nil falls back to the configuration's cache path.
-      # @return [Invocation]
+      # @param options — at least `:no_cache`, `:explain`, `:stats`, `:workers` (see {CheckRunnerFactory.build}).
+      # @param paths — analysed paths; nil falls back to the configuration's `paths:`.
+      # @param cache_root — nil falls back to the configuration's cache path.
       def run(configuration:, options:, paths: nil, buffer: nil, cache_root: nil)
         require_relative "check_runner_factory"
         runner = CheckRunnerFactory.build(
@@ -68,10 +65,8 @@ module Rigor
       # routing hint is outside the false-positive envelope, but a crash in it is not — `describe` must stay a command
       # an agent can run freely.
       #
-      # @param config_path [String, nil] path to the config file; nil uses {Configuration.discover}.
-      # @param options [Hash] runner options (defaults to {DEEP_OPTIONS}).
-      # @param paths [Array<String>, nil]
-      # @return [Outcome]
+      # @param config_path — path to the config file; nil uses {Configuration.discover}.
+      # @param options — runner options (defaults to {DEEP_OPTIONS}).
       def attempt(config_path: nil, options: DEEP_OPTIONS, paths: nil)
         require_relative "../configuration"
         configuration = Configuration.load(config_path)

data/lib/rigor/cli/check_runner_factory.rb

@@ -14,12 +14,8 @@ module Rigor
 
       # Builds a runner matching the configuration/plugin/cache resolution that `rigor check` itself uses.
       #
-      # @param configuration [Rigor::Configuration]
-      # @param options [Hash] parsed CLI options (must contain at least
+      # @param options — parsed CLI options (must contain at least
       #   `:no_cache`, `:explain`, `:stats`, `:workers`)
-      # @param buffer [Rigor::Analysis::BufferBinding, nil]
-      # @param cache_root [String]
-      # @return [Rigor::Analysis::Runner]
       def build(configuration:, options:, buffer:, cache_root:)
         cache_store = if options.fetch(:no_cache)
                         nil

data/lib/rigor/cli/coverage_command.rb

@@ -53,7 +53,7 @@ module Rigor
       # `--test-command`.
       DEFAULT_TEST_COMMAND = %w[bundle exec rake].freeze
 
-      # @return [Integer] CLI exit status.
+      # @return CLI exit status.
       #
       # Deferred YJIT enablement (Runtime::Jit) is armed by `CLI#dispatch` for every command, this
       # one included: a scan long enough to amortize JIT compile cost enables mid-flight; a short one

data/lib/rigor/cli/coverage_mutation.rb

@@ -48,8 +48,6 @@ module Rigor
       # Both measurement-integrity warnings, and the escalation rule between them, live in
       # {MeasurementIntegrityWarning}. Only the floor stays here: it is this command's policy, and
       # `coverage_command_spec` reads it off this module.
-      #
-      # @param report [MutationProtectionReport, FusedProtectionReport]
       def warn_harness_errors(report)
         MeasurementIntegrityWarning.emit(report, err: @err, floor: HARNESS_ERROR_WARN_FLOOR)
       end
@@ -113,10 +111,21 @@ module Rigor
             cache_store: context.cache_store, workers: workers
           ),
           seed_bundles: Protection::DiscoverySeed.bundles(paths: paths),
-          discovery_seed: seed
+          discovery_seed: seed,
+          rebuild_session: -> { rebuilt_session(context) }
         )
       end
 
+      # Issue #790 — how the oracle replaces an Environment a mutant degraded. {LanguageServer::ProjectContext}
+      # already has the operation: `invalidate!` drops the cached environment AND the project scan together,
+      # which is the pair the oracle measures over, and the next reader rebuilds both. Under
+      # {MutationForkScan} this runs in a forked child against its copy-on-write context, so one file's
+      # defect never costs the parent or its siblings a rebuild.
+      def rebuilt_session(context)
+        context.invalidate!
+        [context.environment, context.project_scan]
+      end
+
       # The scope {Protection::Mutator} judges a mutation site's receiver against, derived from the same seed
       # the oracle gets. nil (the gate off, or an empty seed) keeps the bare `Scope.empty` per file.
       def mutation_base_scope(seed, environment)

data/lib/rigor/cli/coverage_scan.rb

@@ -21,9 +21,7 @@ module Rigor
     module CoverageScan
       module_function
 
-      # @param files [Array<String>] explicit `.rb` file paths to scan.
-      # @param configuration [Rigor::Configuration]
-      # @return [Rigor::CLI::CoverageReport]
+      # @param files — explicit `.rb` file paths to scan.
       #
       # Issue #513 — the environment is PLUGIN-AWARE (`LanguageServer::ProjectContext`, the same builder
       # `--protection` uses), not the bare RBS environment this path carried until 2026-09-01. Without the
@@ -57,8 +55,6 @@ module Rigor
       # the precision lens must mirror the walk it describes (`check` leaves the table empty unless
       # `parameter_inference:` is on, ADR-67 WD6a), while `--protection` seeds it unconditionally by ADR-67's own
       # wiring — it only ever reclassifies sites it already counted.
-      #
-      # @return [Rigor::Scope]
       def discovery_seeded_scope(files:, configuration:, environment:, parameter_inference:, workers: nil)
         base = Scope.empty(environment: environment)
         seed = Protection::DiscoverySeed.discovery_tables(files).dup

data/lib/rigor/cli/diff_command.rb

@@ -26,7 +26,7 @@ module Rigor
     class DiffCommand < Command
       USAGE = "Usage: rigor diff [options] <baseline.json> [paths...]"
 
-      # @return [Integer] CLI exit status.
+      # @return CLI exit status.
       def run
         options = parse_options
 

data/lib/rigor/cli/doc_links.rb

@@ -36,9 +36,9 @@ module Rigor
 
       module_function
 
-      # @param body [String] the page as it is stored.
-      # @param from [String] its absolute path, so relative targets resolve.
-      # @return [String] the page with every relative link turned into a `rigor docs` key.
+      # @param body — the page as it is stored.
+      # @param from — its absolute path, so relative targets resolve.
+      # @return the page with every relative link turned into a `rigor docs` key.
       def rewrite(body, from:)
         dir = File.dirname(from)
         body.gsub(MARKDOWN_LINK) do

data/lib/rigor/cli/docs_command.rb

@@ -52,7 +52,7 @@ module Rigor
       HANDBOOK_ROOT = File.join(DOCS_ROOT, "handbook")
       LLMS_INDEX = File.join(DOCS_ROOT, "llms.txt")
 
-      # @return [Integer] CLI exit status.
+      # @return CLI exit status.
       def run
         case @argv.first
         when nil
@@ -136,7 +136,7 @@ module Rigor
       # Resolve a query to a single doc. Exact relative-path and prefixed-basename aliases are unique; a short
       # (prefix-stripped) name is accepted only when one category owns it.
       #
-      # @return [Hash, Integer] the doc entry, or an error exit status
+      # @return the doc entry, or an error exit status
       #   after the error has been written to `@err`.
       def resolve_doc(query)
         # A key printed by a rendered page may carry the section it pointed at; resolve the page and say