rigortype 0.3.4 → 0.3.6

data/lib/rigor/analysis/runner.rb

@@ -108,7 +108,9 @@ module Rigor
         return @effect_plugin_facts if @effect_plugin_facts && @effect_plugin_facts_ancestry.equal?(table)
 
         @effect_plugin_facts_ancestry = table
-        @effect_plugin_facts = Effects::PluginFacts.build(@plugin_registry, superclasses: table)
+        @effect_plugin_facts = Effects::PluginFacts.build(
+          @plugin_registry, superclasses: table, includes: @project_discovered_includes
+        )
       end
 
       # The merged per-file collections behind {#effect_table} — the *direct* summaries, before the graph
@@ -118,23 +120,65 @@ module Rigor
         Effects::FileCollection.merge_all(effect_collections)
       end
 
+      # The run's as-written superclass table — what `effect.liskov-widened` reads. Served straight from
+      # the summary entry on a warm hit (#482), where merging every collection to recover one of its
+      # tables would be the whole cost the split removes.
+      def effect_ancestry
+        @cached_effect_ancestry || effect_collection.superclasses
+      end
+
       # Issue #382 — the same collections keyed by the path that produced each, which is the form the two
       # caches persist: `{ "lib/a.rb" => FileCollection, … }`. The merged {#effect_collection} cannot be
       # persisted per file (merging is where the path is deliberately dropped), and per file is what an
       # ADR-46 recheck needs — it re-collects the changed closure and serves the rest from the snapshot.
       def effect_collections_by_path
         pooled = @pool_coordinator.collected_effects
-        pooled.empty? ? @file_effects.dup : @file_effects.merge(pooled)
+        base = forced_file_effects
+        pooled.empty? ? base.dup : base.merge(pooled)
+      end
+
+      # #482 — the per-file collections of a run served from the summary entry, loaded on the first
+      # question that genuinely needs them. A served run adopts the table, the sources and the ancestry
+      # from the small entry and never touches the collections blob; this is the escape hatch that makes
+      # that split safe, because a consumer the split did not anticipate loads the blob here instead of
+      # silently reading an empty table. Nil loader (an analyzing run) is the identity.
+      def forced_file_effects
+        loader = @cached_collections_loader
+        return @file_effects if loader.nil?
+
+        @cached_collections_loader = nil
+        loaded = loader.call
+        @file_effects = loaded if loaded.is_a?(Hash)
+        @file_effects
+      end
+
+      # Issue #382 — adopt persisted collections as this run's own. The warm-hit half of the whole-run
+      # effects slot: the analysis did not run, so `#assemble_run_diagnostics` never reached
+      # {#close_effect_graph}. The slot stores the propagated table BESIDE the collections — the whole-run
+      # entry is already invalidated by every analyzed file (the same post-run dependency descriptor as
+      # the diagnostics slot) and by every meaning input (the effects identity), which is exactly the
+      # invalidation a stored closure needs — so a warm hit adopts both and re-runs nothing. An entry
+      # from before the table rode along reads as a miss (`#peek_effect_collections`' shape guard), and
+      # the ADR-46 incremental snapshot still persists per-file collections only: a recheck re-collects a
+      # partial closure, which is the case a stored table genuinely cannot serve.
+      def adopt_effect_collections(collections, table: nil)
+        @file_effects = collections
+        if table
+          @effect_table = table
+        else
+          close_effect_graph
+        end
       end
 
-      # Issue #382 — adopt persisted collections as this run's own and close the graph over them. The
-      # warm-hit half of the whole-run effects slot: the analysis did not run, so `#assemble_run_diagnostics`
-      # never reached {#close_effect_graph} and the fixpoint is run here instead. The fixpoint is ALWAYS
-      # re-run rather than persisted — it is the cheap half, and a stored table would have to be invalidated
-      # by every input a summary has.
-      def adopt_effect_collections(collections)
-        @file_effects = collections
-        close_effect_graph
+      # #482 — the warm-hit half after the split: everything a served run reads, with the collections left
+      # behind a loader ({#forced_file_effects}). `sources` and `ancestry` are the two derived tables a
+      # served run would otherwise have to merge the whole collection set to recover.
+      def adopt_effect_summary(table:, sources:, ancestry:, collections_loader:)
+        @effect_table = table
+        @cached_effect_sources = sources
+        @cached_effect_ancestry = ancestry
+        @cached_collections_loader = collections_loader
+        @file_effects = {}
       end
 
       # Issue #382 — whether this run's effect collections came from the whole-run effects slot rather than
@@ -152,6 +196,8 @@ module Rigor
       # its entry points are named by *file* globs (`effects.snapshot.reach:`, the `unused --entry-point`
       # syntax), so the key has to be traced back to the file it was written in.
       def effect_sources
+        return @cached_effect_sources if @cached_effect_sources
+
         effect_collections.each_with_object({}) do |collection, out|
           path = collection.path
           next if path.nil?
@@ -246,6 +292,11 @@ module Rigor
         @file_effects = {}
         @effect_table = nil
         @effects_served_from_cache = false
+        # #482 — set only by a run served from the summary entry: the two derived tables it carries, and
+        # the loader that fetches the collections blob if anything still asks for per-file form.
+        @cached_effect_sources = nil
+        @cached_effect_ancestry = nil
+        @cached_collections_loader = nil
         @run_dependency_descriptor = nil
         # Memoised activation decision for the `call.self-undefined-method` rule (nil = not yet computed).
         # See `self_undefined_rule_active?`.
@@ -672,9 +723,7 @@ module Rigor
         return nil unless @record_effects
 
         descriptor = effects_key_descriptor(key_descriptor)
-        cached = descriptor && peek_effect_collections(descriptor)
-        if cached
-          adopt_effect_collections(cached)
+        if descriptor && served_from_effect_entries?(descriptor)
           @effects_served_from_cache = true
           return nil
         end
@@ -684,6 +733,32 @@ module Rigor
         analysis
       end
 
+      # The two warm lanes, in cost order (#482).
+      #
+      # The summary entry is what a warm run wants: the table and the two derived tables, and no
+      # collections blob. Its absence is not a miss on its own — a run whose propagation fail-softed
+      # deliberately stores no table (see {#storable_effect_table}), and an entry written before the
+      # split has only the collections — so the second lane adopts the collections and re-runs the
+      # fixpoint over them, which is the pre-split behaviour and the retry the fail-soft posture wants.
+      # Only when neither entry answers does the run re-analyse.
+      #
+      # @return [Boolean] whether this run was served.
+      def served_from_effect_entries?(descriptor)
+        summary = peek_effect_summary(descriptor)
+        if summary
+          table, sources, ancestry = summary
+          adopt_effect_summary(table: table, sources: sources, ancestry: ancestry,
+                               collections_loader: -> { peek_effect_collections(descriptor) || {} })
+          return true
+        end
+
+        collections = peek_effect_collections(descriptor)
+        return false if collections.nil?
+
+        adopt_effect_collections(collections)
+        true
+      end
+
       def effects_key_descriptor(key_descriptor)
         Effects::Identity.descriptor(base: key_descriptor, configuration: @configuration,
                                      plugin_facts: effect_plugin_facts)
@@ -691,42 +766,92 @@ module Rigor
         nil
       end
 
-      # The read half. A miss, a stale dependency, a corrupt entry and a stored value of the wrong shape
-      # are one answer — nil, "collect it again" — because none of them can be told apart from the outside
-      # and all of them have the same remedy.
+      # The read half of the serving entry (#482). A miss, a stale dependency, a corrupt entry and a
+      # stored value of the wrong shape are one answer — nil, "collect it again" — because none of them
+      # can be told apart from the outside and all of them have the same remedy. An entry from before the
+      # split simply does not exist under this producer id, so an older cache re-collects once.
+      def peek_effect_summary(descriptor)
+        cached = @cache_store.peek_validated(
+          producer_id: RunCacheKey::RUN_EFFECTS_TABLE_PRODUCER_ID, key_descriptor: descriptor
+        )
+        return nil unless cached.is_a?(Array) && cached.length == 3
+        return nil unless cached[0].is_a?(Effects::EffectTable) && cached[1].is_a?(Hash) &&
+                          cached[2].is_a?(Hash)
+
+        cached
+      rescue StandardError
+        nil
+      end
+
+      # The read half of the collections entry — only ever asked by {#forced_file_effects}, on the paths
+      # that need per-file form. The stored shape is `[collections]`; an entry from before the split is
+      # `[collections, table]` and its first member is the same Hash, so it still reads.
       def peek_effect_collections(descriptor)
         cached = @cache_store.peek_validated(
           producer_id: RunCacheKey::RUN_EFFECTS_PRODUCER_ID, key_descriptor: descriptor
         )
-        cached.is_a?(Hash) ? cached : nil
+        return nil unless cached.is_a?(Array) && cached.first.is_a?(Hash)
+
+        cached.first
       rescue StandardError
         nil
       end
 
       # The write half, run only after a miss, so the block never recomputes anything: it hands over the
-      # collections the analysis just produced, validated against the same post-run dependency descriptor
-      # the diagnostics slot records. Fail-soft — a collection that will not Marshal (which nothing in
-      # {Effects::FileCollection} should be, and the fork pool already proves per file) costs the next run
-      # its warm start and nothing else.
+      # collections the analysis just produced — and the table the analysis already closed over them, so
+      # a warm hit re-runs neither the merge nor the fixpoint — validated against the same post-run
+      # dependency descriptor the diagnostics slot records. Fail-soft — a collection that will not
+      # Marshal (which nothing in {Effects::FileCollection} should be, and the fork pool already proves
+      # per file) costs the next run its warm start and nothing else.
+      # The write half, run only after a miss, so neither block recomputes anything. Two entries under one
+      # key descriptor and one dependency descriptor (#482): the summary a warm run serves from, and the
+      # collections the incremental and fail-soft paths read. The summary is written LAST, so a run
+      # interrupted between the two leaves a collections entry that the next run's summary miss simply
+      # re-collects — never a summary whose collections are absent.
       def store_effect_collections(descriptor, expansion, rbs_descriptor)
         return if descriptor.nil?
 
         collections = effect_collections_by_path
-        @cache_store.fetch_or_validate(
-          producer_id: RunCacheKey::RUN_EFFECTS_PRODUCER_ID, key_descriptor: descriptor,
-          generation_cap: RunCacheKey::EFFECTS_GENERATION_CAP
-        ) { [collections, run_dependency_descriptor(expansion, rbs_descriptor)] }
+        dependencies = run_dependency_descriptor(expansion, rbs_descriptor)
+        write_effect_entry(RunCacheKey::RUN_EFFECTS_PRODUCER_ID, descriptor, [collections], dependencies)
+        table = storable_effect_table(collections)
+        return nil if table.nil?
+
+        write_effect_entry(RunCacheKey::RUN_EFFECTS_TABLE_PRODUCER_ID, descriptor,
+                           [table, effect_sources, effect_collection.superclasses], dependencies)
         nil
       rescue StandardError
         nil
       end
-      private :serve_effect_collections, :effects_key_descriptor,
-              :peek_effect_collections, :store_effect_collections
+
+      def write_effect_entry(producer_id, descriptor, payload, dependencies)
+        @cache_store.fetch_or_validate(
+          producer_id: producer_id, key_descriptor: descriptor,
+          generation_cap: RunCacheKey::EFFECTS_GENERATION_CAP
+        ) { [payload, dependencies] }
+      end
+
+      # An empty table over non-empty summaries is {#close_effect_graph}'s fail-soft answer, not a
+      # result — persisting it would freeze one run's propagation failure into every warm hit until the
+      # next invalidation. Storing nil instead makes the warm hit re-run the fixpoint, which is exactly
+      # the retry the fail-soft posture wants.
+      def storable_effect_table(collections)
+        table = @effect_table
+        return nil if table.nil?
+        return nil if table.empty? && collections.any? { |_, collection| !collection.summaries.empty? }
+
+        table
+      end
+      private :serve_effect_collections, :served_from_effect_entries?,
+              :effects_key_descriptor, :peek_effect_summary,
+              :peek_effect_collections, :store_effect_collections, :write_effect_entry,
+              :storable_effect_table, :forced_file_effects
 
       # ADR-103 WD8 / #383 — the envelope check. Nothing at all without an `effects:` block, and nothing
       # under `effects.check: false`; with both, one walk of the project's own RBS for `%a{pure}` /
       # `%a{rigor:v1:effect …}`, and only if that finds an envelope does anything else run (the discovery
-      # tables the `def` positions come from are forced from inside the pass, lazily, for that reason).
+      # tables the `def` positions come from are forced from inside the judgment, on the first finding
+      # built — a judged-clean envelope forces no discovery at all).
       #
       # The environment is the one the cacheable path already resolved when there is one, so a warm run
       # reads the envelopes off the loader it built anyway rather than building a second.
@@ -743,7 +868,7 @@ module Rigor
           # ADR-103 WD1 / #386 — the nominal relation `effect.liskov-widened` reads, from the collector's
           # own as-written superclass table, so the Liskov check and the closed-world proven lane resolve
           # the same ancestry. Lazy: only a project that declared an envelope pays the merge.
-          ancestry: -> { effect_collection.superclasses },
+          ancestry: -> { effect_ancestry },
           apply_tolerated: !@no_tolerated_effects,
           # #387 — the same compiled plugin tables the collection window scanned under, so an envelope may
           # name a label a plugin opened and the unknown-label check agrees with the scan.
@@ -751,13 +876,20 @@ module Rigor
         ).diagnostics
       end
 
-      # The residual takes the loader the run ALREADY resolved — never `envelope_rbs_loader`, which
+      # The residual takes the virtual RBS the run ALREADY resolved — never `envelope_rbs_loader`, which
       # builds one on demand. This runs on the effects-off path, where an environment build is a cost
       # the project did not ask for; the `signature_paths:` `.rbs` stratum is always read, and the
       # rbs-inline stratum rides whatever the run happened to have.
+      #
+      # #441 — two sources, because two shapes of run resolve an environment and only one of them keeps
+      # it: `@run_environment` is assigned solely by the ADR-45 result-cacheable path, while every
+      # ANALYZING run (`--no-cache`, `--workers N`, `--incremental`, an editor buffer) builds one inside
+      # {PoolCoordinator} and lets it go. The snapshot is that run's carrier, and taking it second
+      # preserves the cacheable path's byte-identical behaviour.
       def effect_annotation_residual_diagnostics
         EffectAnnotationResidualPass.new(
-          configuration: @configuration, rbs_loader: @run_environment&.rbs_loader
+          configuration: @configuration,
+          virtual_rbs: @run_environment&.rbs_loader&.virtual_rbs || @snapshots.effect_annotation_carrier
         ).diagnostics
       end
 

data/lib/rigor/analysis/worker_session.rb

@@ -187,7 +187,9 @@ module Rigor
       # the same project ancestry the parent would have walked.
       def effect_plugin_facts
         @effect_plugin_facts ||= Effects::PluginFacts.build(
-          @plugin_registry, superclasses: @project_scope_seed[:discovered_superclasses] || {}
+          @plugin_registry,
+          superclasses: @project_scope_seed[:discovered_superclasses] || {},
+          includes: @project_scope_seed[:discovered_includes] || {}
         )
       end
       private :effect_plugin_facts

data/lib/rigor/cache/file_digest.rb

@@ -30,9 +30,10 @@ module Rigor
     # 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, :INSTANT_KEY, :STRICT_KEY
+      private_constant :MEMO_KEY, :STAT_KEY, :INSTANT_KEY, :STRICT_KEY
 
       # 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
@@ -47,14 +48,17 @@ module Rigor
       # 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
       end
@@ -102,12 +106,26 @@ module Rigor
         digest = parsed[0]
         return hexdigest(path) == digest if strict_validation?
 
-        st = File.stat(path)
+        st = validation_stat(path)
         return true if !racy?(parsed) && tuple_matches?(st, parsed)
 
         hexdigest(path) == digest
       end
 
+      # The VALIDATION-side stat, served from the per-run table when one is installed — a collecting run
+      # validates the effects entry and the diagnostics entry against the same ~thousands-of-files
+      # dependency descriptor, and the second pass is pure repetition under the run's own stable-filesystem
+      # premise (see the module doc). The RECORDING side ({.pack_stat}) deliberately keeps its direct
+      # `File.stat`: it packs the tuple a *future* run validates, after the content was read, and must
+      # 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?
+
+        memo[path] ||= File.stat(path)
+      end
+
       def self.recording_instant_ns
         Thread.current[INSTANT_KEY] || now_ns
       end

data/lib/rigor/cli/check_command.rb

@@ -11,7 +11,6 @@ require_relative "../analysis/rule_catalog"
 # The baseline filter runs on EVERY exit path — including the ADR-87 WD4 cache-HIT fast path, which skips
 # `load_check_dependencies` — so it must be a load-time require. It pulls only YAML, never the engine.
 require_relative "../analysis/baseline"
-require_relative "../runtime/jit"
 require_relative "command"
 require_relative "options"
 require_relative "diagnostic_formats"
@@ -34,12 +33,10 @@ module Rigor
     # concerns that are clearer read together than split across micro-classes.
     class CheckCommand < Command # rubocop:disable Metrics/ClassLength
       # @return [Integer] CLI exit status.
-      def run # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
-        # Arm deferred YJIT enablement before any analysis work: the deadline
-        # thread only fires once a run outlasts the amortization window, so a
-        # short check finishes before it ever pays JIT compile cost while a
-        # long run JITs its dominant tail (Runtime::Jit).
-        Runtime::Jit.enable_after(Runtime::Jit.deadline_seconds)
+      #
+      # 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
         # 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
@@ -50,7 +47,7 @@ module Rigor
         configuration = apply_bleeding_edge_override(configuration, options)
         config_warnings = warn_unresolved_config(configuration)
         cache_root = configuration.cache_path
-        handle_clear_cache(cache_root) if options.fetch(:clear_cache)
+        handle_clear_cache(cache_root, options.fetch(:format)) if options.fetch(:clear_cache)
 
         # ADR-87 WD4 — try to serve the whole run from the ADR-45 cache before booting the engine. A hit boots
         # only CLI + config + cache + digest code (no `rigor/inference`), skipping the plugin prepass + env
@@ -76,7 +73,7 @@ module Rigor
         write_run_stats(result.stats) if result.stats
         write_trace_appendices
         runner.cache_store&.evict!
-        write_cache_stats(cache_root, runner.cache_store) if options.fetch(:cache_stats)
+        write_cache_stats(cache_root, runner.cache_store, options.fetch(:format)) if options.fetch(:cache_stats)
 
         exit_code = result.success? ? 0 : 1
         exit_code = 1 if baseline_strict_violation?(raw_result.diagnostics, configuration, options)
@@ -195,7 +192,8 @@ module Rigor
         incremental = normalize_diagnostics(session.reanalyze_subset(subset))
         full = normalize_diagnostics(verify_full_diagnostics(configuration, paths))
 
-        report_verify_incremental(incremental, full, subset_size: subset.size, total: analyzed.size)
+        report_verify_incremental(incremental, full, subset_size: subset.size, total: analyzed.size,
+                                                     format: options.fetch(:format))
       end
 
       # ADR-46 — cross-process incremental analysis (`--incremental`). Derives the global fingerprint cheaply (no RBS
@@ -230,7 +228,8 @@ module Rigor
         @err.puts("rigor: --incremental #{warm ? 'warm — reused cached diagnostics' : 'cold — full analysis'} " \
                   "(#{session.analyzed_files.size} files)")
         emit_incremental_fact_surface_notes(session)
-        write_incremental_cache_stats(session, cache_root, store) if options.fetch(:cache_stats)
+        write_incremental_cache_stats(session, cache_root, store, options.fetch(:format)) if
+          options.fetch(:cache_stats)
 
         result = apply_baseline_filter(Analysis::Result.new(diagnostics: diagnostics, stats: nil), configuration,
                                        options)
@@ -286,8 +285,8 @@ module Rigor
       # does) plus the fact-surface status line, so an operator can see whether a full run was fact-surface
       # driven. The plain `check` cache-stats path is bypassed by the incremental short-circuit, so it is
       # emitted here.
-      def write_incremental_cache_stats(session, cache_root, store)
-        write_cache_stats(cache_root, store)
+      def write_incremental_cache_stats(session, cache_root, store, format)
+        write_cache_stats(cache_root, store, format)
         status =
           if !session.opaque_plugin_ids.empty?
             "opaque (#{session.opaque_plugin_ids.sort.join(', ')})"
@@ -296,7 +295,7 @@ module Rigor
           else
             "unchanged"
           end
-        @out.puts("  plugin fact surface: #{status}")
+        side_output(format).puts("  plugin fact surface: #{status}")
       end
 
       def verify_full_diagnostics(configuration, paths)
@@ -310,11 +309,14 @@ module Rigor
         end
       end
 
-      def report_verify_incremental(incremental, full, subset_size:, total:)
+      # The OK line follows the same rule as the other side outputs (#493) — stdout under `text`, stderr
+      # under a machine format. The FAILED branch below has always gone to stderr: it is a failure
+      # report, and a run that produced one has no valid document to protect anyway.
+      def report_verify_incremental(incremental, full, subset_size:, total:, format: "text")
         if incremental == full
-          @out.puts("rigor: --verify-incremental OK — incremental " \
-                    "(#{subset_size}/#{total} files re-analyzed, rest from cache) " \
-                    "matches full (#{full.size} diagnostics)")
+          side_output(format).puts("rigor: --verify-incremental OK — incremental " \
+                                   "(#{subset_size}/#{total} files re-analyzed, rest from cache) " \
+                                   "matches full (#{full.size} diagnostics)")
           return 0
         end
 
@@ -495,46 +497,46 @@ module Rigor
           end
           Options.add_editor_mode(opts, options)
           opts.on("--baseline=PATH",
-                  "ADR-22: load baseline from PATH (overrides .rigor.yml `baseline:`)") do |value|
+                  "load baseline from PATH (overrides .rigor.yml `baseline:`)") do |value|
             options[:baseline] = value
           end
           opts.on("--no-baseline",
-                  "ADR-22: ignore any configured baseline for this run") do
+                  "ignore any configured baseline for this run") do
             options[:baseline] = false
           end
           opts.on("--baseline-strict",
-                  "ADR-22: fail the run on any baseline drift (CI gate)") do
+                  "fail the run on any baseline drift (CI gate)") do
             options[:baseline_strict] = true
           end
           opts.on("--treat-all-as-inline-rbs",
-                  "ADR-32: force-load rigor-rbs-inline with require_magic_comment: false") do
+                  "force-load rigor-rbs-inline with require_magic_comment: false") do
             options[:treat_all_as_inline_rbs] = true
           end
           opts.on("--verify-incremental",
-                  "ADR-46: assert incremental analysis matches a full run, then exit") do
+                  "assert incremental analysis matches a full run, then exit") do
             options[:verify_incremental] = true
           end
           opts.on("--incremental",
-                  "ADR-46: re-analyze only files changed since the last run (cross-process cache)") do
+                  "re-analyze only files changed since the last run (cross-process cache)") do
             options[:incremental] = true
           end
           opts.on("--no-ci-detect",
-                  "ADR-51: do not auto-emit CI-native output when a CI environment is detected") do
+                  "do not auto-emit CI-native output when a CI environment is detected") do
             options[:ci_detect] = false
           end
           # ADR-50 § WD2 — `=[LIST]` (not ` [LIST]`) so a bare `--bleeding-edge` never swallows a following positional
           # path: `rigor check --bleeding-edge lib` adopts the whole overlay and checks `lib`.
           opts.on("--bleeding-edge=[LIST]",
-                  "ADR-50: adopt the bleeding-edge overlay for this run " \
+                  "adopt the bleeding-edge overlay for this run " \
                   "(all features, or a comma-separated feature-id list)") do |value|
             options[:bleeding_edge] = value.nil? || value.split(",").map(&:strip).reject(&:empty?)
           end
           opts.on("--no-bleeding-edge",
-                  "ADR-50: ignore any configured bleeding_edge: selection for this run") do
+                  "ignore any configured bleeding_edge: selection for this run") do
             options[:bleeding_edge] = false
           end
           opts.on("--no-tolerated-effects",
-                  "ADR-103: check effect envelopes as if effects.tolerated: were empty") do
+                  "check effect envelopes as if effects.tolerated: were empty") do
             options[:no_tolerated_effects] = true
           end
         end
@@ -599,12 +601,13 @@ module Rigor
         }]
       end
 
-      def handle_clear_cache(cache_root)
+      def handle_clear_cache(cache_root, format)
+        out = side_output(format)
         if File.directory?(cache_root)
           FileUtils.rm_rf(cache_root)
-          @out.puts("Cleared cache: #{cache_root}")
+          out.puts("Cleared cache: #{cache_root}")
         else
-          @out.puts("Cache already empty: #{cache_root}")
+          out.puts("Cache already empty: #{cache_root}")
         end
       end
 
@@ -772,42 +775,43 @@ module Rigor
         Kernel.format("%.1f MB", bytes / 1_048_576.0)
       end
 
-      def write_cache_stats(cache_root, runtime_store)
+      def write_cache_stats(cache_root, runtime_store, format)
         inv = Cache::Store.disk_inventory(root: cache_root)
+        out = side_output(format)
 
-        @out.puts("")
-        @out.puts("Cache (root: #{inv.fetch(:root)})")
+        out.puts("")
+        out.puts("Cache (root: #{inv.fetch(:root)})")
         schema = inv.fetch(:schema_version)
-        @out.puts("  schema_version: #{schema.nil? ? 'absent' : schema}")
-        write_disk_inventory(inv)
-        write_runtime_stats(runtime_store) if runtime_store
+        out.puts("  schema_version: #{schema.nil? ? 'absent' : schema}")
+        write_disk_inventory(inv, out)
+        write_runtime_stats(runtime_store, out) if runtime_store
       end
 
-      def write_disk_inventory(inv)
+      def write_disk_inventory(inv, out)
         if inv.fetch(:total_entries).zero?
-          @out.puts("  (empty)")
+          out.puts("  (empty)")
           return
         end
 
-        @out.puts("  #{inv.fetch(:total_entries)} entries, #{format_bytes(inv.fetch(:total_bytes))}")
+        out.puts("  #{inv.fetch(:total_entries)} entries, #{format_bytes(inv.fetch(:total_bytes))}")
         inv.fetch(:producers).each do |producer|
           bytes = format_bytes(producer.fetch(:bytes))
-          @out.puts("    #{producer.fetch(:id)}: #{producer.fetch(:entries)} entries, #{bytes}")
+          out.puts("    #{producer.fetch(:id)}: #{producer.fetch(:entries)} entries, #{bytes}")
         end
       end
 
-      def write_runtime_stats(store)
+      def write_runtime_stats(store, out)
         stats = store.stats
         hits = stats.fetch(:hits)
         misses = stats.fetch(:misses)
         writes = stats.fetch(:writes)
-        @out.puts("  this run: #{hits} #{plural(hits, 'hit')}, " \
-                  "#{misses} #{plural(misses, 'miss', 'misses')}, " \
-                  "#{writes} #{plural(writes, 'write')}")
+        out.puts("  this run: #{hits} #{plural(hits, 'hit')}, " \
+                 "#{misses} #{plural(misses, 'miss', 'misses')}, " \
+                 "#{writes} #{plural(writes, 'write')}")
         stats.fetch(:by_producer).each do |id, counts|
-          @out.puts("    #{id}: #{counts.fetch(:hits)} #{plural(counts.fetch(:hits), 'hit')}, " \
-                    "#{counts.fetch(:misses)} #{plural(counts.fetch(:misses), 'miss', 'misses')}, " \
-                    "#{counts.fetch(:writes)} #{plural(counts.fetch(:writes), 'write')}")
+          out.puts("    #{id}: #{counts.fetch(:hits)} #{plural(counts.fetch(:hits), 'hit')}, " \
+                   "#{counts.fetch(:misses)} #{plural(counts.fetch(:misses), 'miss', 'misses')}, " \
+                   "#{counts.fetch(:writes)} #{plural(counts.fetch(:writes), 'write')}")
         end
       end
 
@@ -822,6 +826,21 @@ module Rigor
         format("%.1f MiB", bytes / (1024.0 * 1024.0))
       end
 
+      # Where a human-readable side output goes (#493).
+      #
+      # `--format text` is prose already, so an extra block after the diagnostics is just more prose. Every
+      # other format is a machine contract — a SARIF document a code-scanning upload parses, a Checkstyle
+      # or JUnit XML tree, a GitLab Code Quality array — and appending `Cache (root: …)` to it produces a
+      # document the consumer rejects. Measured: all seven non-text formats were corrupted by
+      # `--cache-stats`, and JSON / SARIF / GitLab failed to parse at all.
+      #
+      # The information is not dropped, because it is what the user asked for by passing the flag; it moves
+      # to stderr, which is where this command already routes everything it says about a run rather than
+      # about the code.
+      def side_output(format)
+        format == "text" ? @out : @err
+      end
+
       def write_result(result, format, coverage: nil, config_warnings: [])
         case format
         when "json"

data/lib/rigor/cli/coverage_command.rb

@@ -14,7 +14,6 @@ require_relative "../inference/parameter_inference_collector"
 require_relative "../protection/mutation_scanner"
 require_relative "../protection/test_suite_oracle"
 require_relative "../language_server/project_context"
-require_relative "../runtime/jit"
 require_relative "../scope"
 require_relative "coverage_report"
 require_relative "coverage_renderer"
@@ -55,11 +54,11 @@ module Rigor
       DEFAULT_TEST_COMMAND = %w[bundle exec rake].freeze
 
       # @return [Integer] CLI exit status.
-      def run # rubocop:disable Metrics/AbcSize
-        # Arm deferred YJIT enablement (Runtime::Jit): a scan long enough to
-        # amortize JIT compile cost enables mid-flight; a short one finishes
-        # first and never pays it. Same seam as `rigor check`.
-        Runtime::Jit.enable_after(Runtime::Jit.deadline_seconds)
+      #
+      # 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
+      # finishes first and never pays it.
+      def run
         options = parse_options
         return mutation_misuse_error if options[:mutation] && !options[:protection]
         return with_tests_misuse_error if options[:with_tests] && !options[:mutation]