rigortype 0.3.8 → 0.4.0

data/lib/rigor/analysis/runner.rb

@@ -9,6 +9,7 @@ require_relative "../scope"
 require_relative "../cache/store"
 require_relative "../cache/rbs_descriptor"
 require_relative "../cache/file_digest"
+require_relative "../cache/incremental_snapshot"
 require_relative "run_cache_key"
 require_relative "path_expansion"
 require_relative "../plugin"
@@ -47,6 +48,7 @@ require_relative "runner/run_snapshots"
 require_relative "runner/project_pre_passes"
 require_relative "runner/pool_coordinator"
 require_relative "runner/diagnostic_aggregator"
+require_relative "template_units"
 require_relative "runner/effect_envelope_pass"
 require_relative "runner/effect_annotation_residual_pass"
 require_relative "runner/buffer_pool_dispatcher"
@@ -74,6 +76,18 @@ module Rigor
                   # file-positioned ones (`effect.annotations-unchecked`, `source-rbs-*`).
                   :per_file_diagnostics
 
+      # Issues #796 / #794 — the two run-level rows a NARROWED run cannot re-derive from the files it
+      # analyses: the `definition-build-failed` set (whose producer is the analysis's own demand, and #696
+      # forbids Rigor demanding in its place) and the HKT-scan outcome (whose producer is an environment a
+      # nothing-changed recheck otherwise has no reason to build). {IncrementalSession} persists what a full
+      # run answers here and hands it back to the next narrowed run.
+      def run_level_rows
+        Cache::IncrementalSnapshot::RunLevelRows.new(
+          definition_build_failures: @snapshots.definition_build_failures,
+          hkt_scan_failure: @snapshots.hkt_scan_failure
+        )
+      end
+
       # ADR-46 — the per-file cross-file read records this run captured (empty unless
       # `record_dependencies: true`). Sequential analysis records into `@file_dependencies` via
       # {#analyze_file}; the fork pool records per-worker and marshals the records into the coordinator, so a
@@ -94,6 +108,32 @@ module Rigor
         @effect_table || Effects::EffectTable.empty
       end
 
+      # ADR-103 WD9 (#391) — the envelope index this run resolved, for `rigor sig-gen`'s annotation
+      # emission to consult. Public for the same reason {#effect_table} is: a consumer outside the
+      # diagnostic stream needs what the run already computed, and rebuilding it from configuration
+      # alone would read a narrower set of strata — the accepted signatures and the rbs-inline virtual
+      # RBS both come from the built environment.
+      #
+      # Built on demand when the run never analysed a file. A WARM whole-run cache hit serves the
+      # propagated table from cache, so {#analyze_with_effects} — the only caller of
+      # {#effect_envelope_index} — never runs and the ivar stays nil. Returning an empty index there
+      # would silently drop sig-gen's "the author already declared a bound" gate on exactly the runs a
+      # user makes most often: the same `sig-gen` invocation would withhold on its first run and emit on
+      # its second. `@run_environment` is resolved before the cache is consulted, so the warm build reads
+      # the same strata the cold one does.
+      #
+      # `@run_environment` is nil only when the run resolved no environment at all — a run over zero
+      # project files, or one that never reached {#compute_run_diagnostics}. The build then falls back to
+      # the configuration-only strata (`sig/` annotations, class-level ones and `effects.envelopes:`,
+      # without the accepted signatures or the rbs-inline virtual RBS), which is the narrower answer but
+      # not a wrong one: a run with no environment analysed no file, so there is no candidate for the
+      # missing strata to have bounded.
+      def effect_envelopes
+        return @effect_envelope_index if @effect_envelope_index
+
+        effect_envelope_index(@run_environment)
+      end
+
       # ADR-103 WD2 / WD6 / WD10 / #387 — the loaded plugins' effect contributions, compiled once per
       # process. Memoised on first use rather than built in the constructor for two reasons: the plugin
       # registry is adopted after construction (`apply_prebuilt` / the plugin-load pre-pass), and the
@@ -214,41 +254,40 @@ module Rigor
         end
       end
 
-      # @param configuration [Rigor::Configuration]
-      # @param explain [Boolean] surface fail-soft fallback events as `:info` diagnostics.
-      # @param cache_store [Rigor::Cache::Store, nil] the persistent cache the runner exposes to producers
+      # @param explain — surface fail-soft fallback events as `:info` diagnostics.
+      # @param cache_store — the persistent cache the runner exposes to producers
       #   (`RbsConstantTable` and successors). Pass `nil` to disable caching for this run; the CLI's
       #   `--no-cache` flag wires `nil` through. v0.0.9 group A slice 1 introduces the surface; later
       #   slices route real producers through it.
-      # @param workers [Integer] ADR-15 Phase 4b — when greater than zero, per-file analysis dispatches
+      # @param workers — ADR-15 Phase 4b — when greater than zero, per-file analysis dispatches
       #   across a pool of N workers. Default `0` keeps the sequential code path bit-for-bit unchanged.
       #   Controlled via the `RIGOR_RACTOR_WORKERS` env var or `.rigor.yml` `parallel.workers:` (Phase 4c,
       #   fully wired).
-      # @param collect_stats [Boolean] when true (default), `#run` builds a {RunStats} summary exposed via
+      # @param collect_stats — when true (default), `#run` builds a {RunStats} summary exposed via
       #   `result.stats` — this forces the RBS env build at end-of-run so the `class_decl_paths` snapshot
       #   has real source attribution. Set to false to skip the stats summary entirely; the CLI's
       #   `--no-stats` threads `false` through to keep trivial-fixture runs from warming `.rigor/cache`.
-      # @param prebuilt [Rigor::Analysis::ProjectScan, nil] when supplied, the runner adopts the pre-built
+      # @param prebuilt — when supplied, the runner adopts the pre-built
       #   plugin registry / dependency-source index / scanner outputs from the snapshot and skips the
       #   per-call pre-passes that produce them. Used by long-lived integrations
       #   (`Rigor::LanguageServer::ProjectContext`) to keep per-buffer requests fast — scanners walk the
       #   project once per generation rather than once per request, and plugin `#prepare` runs once per
       #   generation rather than once per request. Watched-file invalidation is the owner's responsibility;
       #   the runner trusts the snapshot it was given.
-      # @param environment [Rigor::Environment, nil] opt-in Environment override. When supplied, sequential
+      # @param environment — opt-in Environment override. When supplied, sequential
       #   mode uses the provided env instance in `#analyze_files` instead of building a fresh one via
       #   `Environment.for_project`, and attaches the runner's per-run reporter pair onto the env's mutable
       #   `Reporters` slot via `Environment#attach_reporters!`. Long-lived consumers (LSP `ProjectContext`)
       #   pass a shared env so per-publish work doesn't repeat the `Environment.for_project` build (bundler
       #   / lockfile / collection discovery, RbsLoader construction). Pool mode ignores the override — each
       #   worker continues to build its own Environment.
-      # @param discovery_seed [Hash, nil] issue #260 — opt-in cross-file discovery tables, keyed by
+      # @param discovery_seed — issue #260 — opt-in cross-file discovery tables, keyed by
       #   {Scope::DiscoveryIndex} slot name, seeded onto every per-file scope through
       #   `project_scope_seed_tables`. The ONE deliberate exception to "a `prebuilt:` runner carries no
       #   discovery tables": {Protection::DiagnosticOracle} threads the table set Tier 2's site filter already
       #   judges anchors against, so a site admitted because a sibling-file class resolved is also a site the
       #   oracle can kill at. nil (the default) leaves the prebuilt/LSP contract byte-identical.
-      # @param no_tolerated_effects [Boolean] ADR-103 WD1 / #385 — `rigor check --no-tolerated-effects`.
+      # @param no_tolerated_effects — ADR-103 WD1 / #385 — `rigor check --no-tolerated-effects`.
       #   Judges effect envelopes as if `effects.tolerated:` were empty. A judgment-time switch only: the
       #   run, its collection and its cache identity are unchanged.
       def initialize(configuration:, explain: false, # rubocop:disable Metrics/ParameterLists,Metrics/AbcSize,Metrics/MethodLength
@@ -257,8 +296,12 @@ module Rigor
                      buffer: nil, prebuilt: nil, environment: nil,
                      record_dependencies: false, record_self_calls: false, analyze_only: nil,
                      seed_bundles: nil, collect_seed_bundles: false, param_inferred_types: nil,
-                     discovery_seed: nil, no_tolerated_effects: false)
+                     discovery_seed: nil, no_tolerated_effects: false,
+                     restored_run_level_rows: nil)
         @configuration = configuration
+        # Issues #796 / #794 — the previous full run's run-level rows, supplied only by
+        # {IncrementalSession} on a narrowed run; see {PoolCoordinator#replay_restored_run_level_rows}.
+        @restored_run_level_rows = restored_run_level_rows
         @explain = explain
         @cache_store = enforce_read_only_cache(cache_store, buffer)
         @plugin_requirer = plugin_requirer
@@ -298,6 +341,10 @@ module Rigor
         # check reads.
         @no_tolerated_effects = no_tolerated_effects
         @file_effects = {}
+        # #392 — the run's template units, synthesised once per run after the plugins load (see
+        # {#template_units}). nil until then; a project whose plugins declare no `template_globs:` resolves
+        # to the shared empty index and pays one `Array#empty?` for the whole run.
+        @template_units = nil
         @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
@@ -362,6 +409,16 @@ module Rigor
         # Issue #682 — the `Module.nesting` each class / module declaration HEADER is written in.
         @project_discovered_header_nestings = {}.freeze
         @project_discovered_includes = {}.freeze
+        # Issue #1123 — the instance-side prepend table (`prepend M`, and `Recv.prepend(M)`), in
+        # instance-ancestor SEARCH order.
+        @project_discovered_prepends = {}.freeze
+        # Issue #898 — the singleton-side twin of the include table (`extend M` / `extend self`).
+        @project_discovered_extends = {}.freeze
+        @project_discovered_deferred_ranges = {}.freeze
+        # Issue #1120 — `{refined class => {method => [refining modules]}}`, every `refine X do … end` body.
+        @project_discovered_refinements = {}.freeze
+        # Issue #1367 — the project's `Inference::GlobalWriteCensus`, which the `global.*` write rules read.
+        @project_discovered_global_write_census = Set.new.freeze
         @project_discovered_class_sources = {}.freeze
         # Issue #644 — the cross-file VALUE-constant publication table (`{qualified name => Type::Constant}`,
         # literal writes only) and its per-name write attribution. The first seeds `in_source_constants` on
@@ -372,8 +429,12 @@ module Rigor
         # ...and the raw per-(name, path) publication census the incremental producer diffs.
         @project_constant_writes = {}.freeze
         @published_constant_name_set = nil
+        @constant_writer_index = nil
+        @constant_shadower_index = nil
         @project_discovered_method_visibilities = {}.freeze
         @project_discovered_methods = {}.freeze
+        # Issue #992 — the cross-file parameter-envelope table `call.wrong-arity` reads for an undeclared `def`.
+        @project_discovered_parameter_envelopes = {}.freeze
         @project_data_member_layouts = {}.freeze
         @project_struct_member_layouts = {}.freeze
         # Issue #684 — set per run by {#project_discovery_expansion}; nil on every path that does not widen.
@@ -388,6 +449,9 @@ module Rigor
         # (sequential + fork-worker) through `project_scope_seed_tables`. Empty unless the project lists
         # `pre_eval:` files that declare publishable constants, so a project without one is byte-identical.
         @project_pre_eval_constants = {}.freeze
+        # Issue #663 — the listed set {#publishable_pre_eval_constants} asks "is this writer one of ours?"
+        # against; a function of the configuration alone, so it outlives every discovery rebuild.
+        @pre_eval_path_set = nil
         # ADR-84 WD2 — per-run identity token for the user-method return memo's bucket (see
         # Scope::DiscoveryIndex#run_generation). Minted fresh in `run_analysis` so the memo never serves an
         # entry across a run boundary (LSP re-check, ADR-62 warm loop); nil until the first run so
@@ -432,6 +496,12 @@ module Rigor
         @snapshots.reset_for_run
         # Per-run reset of the deferred-discovery memo (see `#ensure_project_discovery`).
         @project_discovery_done = false
+        # #392 — re-derive the template units each run: their source files can change between two runs of
+        # one long-lived Runner (the LSP's), and a unit is never served from a cache of its own. Since
+        # #1038 "re-derive" is not "recompile": a `prebuilt:` runner carries the snapshot's warm index into
+        # {#template_units}, which still re-expands every claim and revalidates every template against the
+        # filesystem, and only compiles what actually moved.
+        @template_units = nil
         # Per-run reset of the environment the cacheable path resolves, reused by the envelope pass so a
         # run never builds two.
         @run_environment = nil
@@ -479,9 +549,8 @@ module Rigor
       # so the result matches a one-file disk run; only the cross-file project pre-pass is empty (there is
       # one file, and the per-file indexer self-discovers its own classes / defs).
       #
-      # @param source [String] Ruby source to analyze.
-      # @param path [String] logical path for diagnostic locations.
-      # @return [Result]
+      # @param source — Ruby source to analyze.
+      # @param path — logical path for diagnostic locations.
       def run_source(source:, path: "(source).rb")
         @in_memory_sources = { path => source }
         run([path])
@@ -607,7 +676,7 @@ module Rigor
       # arg-flooring surface). Only meaningful right after a run populated the memo (baseline / recheck),
       # before the bucket rolls. Keys are held live here; the session Marshals them for the snapshot.
       #
-      # @return [Hash] `{ [path, "Class#method" | "Class.method"] => { keys:, returns:, effects: } }`.
+      # @return `{ [path, "Class#method" | "Class.method"] => { keys:, returns:, effects: } }`.
       def return_summaries
         memo = Inference::ExpressionTyper.harvest_return_memo
         return {} if memo.empty?
@@ -665,9 +734,9 @@ module Rigor
       # store) exactly as a real run's setup does, then re-drives each spec's def through the ADR-84 return
       # memo. Off any hot path — invoked only when declaration-stable changed pairs carry a persisted summary.
       #
-      # @param paths [Array<String>, nil] analysis roots (nil → the configuration's `paths:`).
-      # @param specs [Array<Hash>] each `{ class_name:, method_name:, singleton:, keys: [[receiver, args], …] }`.
-      # @return [Hash] `{ [class_name, method_name, singleton] => [return_descriptor_or_nil, …] }`.
+      # @param paths — analysis roots (nil → the configuration's `paths:`).
+      # @param specs — each `{ class_name:, method_name:, singleton:, keys: [[receiver, args], …] }`.
+      # @return `{ [class_name, method_name, singleton] => [return_descriptor_or_nil, …] }`.
       def evaluate_return_types(paths, specs)
         return {} if specs.empty?
 
@@ -726,7 +795,10 @@ module Rigor
         @run_served_from_cache = false
         return assemble_run_diagnostics(expansion) unless run_result_cacheable?
 
-        environment = @pool_coordinator.resolve_sequential_environment(source_files: target_files(expansion))
+        # #392 — `source_files:` is what a plugin's `source_rbs_synthesizer` is offered at env-build time,
+        # and a template unit is not Ruby the synthesiser can read (rbs-inline would be handed `.rbx`
+        # bytes). The `.rb` expansion is the right set here; the units join the ANALYSED set only.
+        environment = @pool_coordinator.resolve_sequential_environment(source_files: expansion.fetch(:files))
         # Lazy-files descriptor: the cache KEY reads only `gems` + `configs`; the RBS signature-tree `files`
         # are digested solely by `run_dependency_descriptor` on a MISS, so a warm HIT never walks the tree.
         rbs_descriptor = if environment&.rbs_loader
@@ -795,7 +867,7 @@ module Rigor
       # 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.
+      # @return whether this run was served.
       def served_from_effect_entries?(descriptor)
         summary = peek_effect_summary(descriptor)
         if summary
@@ -978,7 +1050,14 @@ module Rigor
       def close_effect_graph
         return unless @record_effects
 
-        @effect_table = Effects::Propagator.propagate(effect_collection, discharge: effect_discharge)
+        # `declined_unit_keys:` — #1065. The templates a plugin claimed and produced no unit for; a render
+        # edge's format fallback must not resolve past one of them, because the file exists and the
+        # framework runs it, so the other format's effects are not what that render produces.
+        @effect_table = Effects::Propagator.propagate(
+          effect_collection,
+          discharge: effect_discharge,
+          declined_unit_keys: template_units.declined_unit_keys
+        )
       rescue StandardError
         @effect_table = Effects::EffectTable.empty
       end
@@ -1009,6 +1088,11 @@ module Rigor
         # untouched so its lazy build timing is unchanged.
         environment = seed_pre_eval_constants(expansion, environment)
         diagnostics = @diagnostic_aggregator.pre_file_diagnostics(expansion)
+        # #392 — a template transform that raised, a template that could not be read, or a unit naming a
+        # file it was not offered. Reported through the same `:plugin_loader` `runtime-error` envelope a
+        # raise from `#diagnostics_for_file` uses (ADR-2 § "Plugin Trust and I/O Policy"), rather than
+        # dropped in silence: a plugin author whose view stopped being analysed has nothing else to read.
+        diagnostics += template_unit_failure_diagnostics
         # ADR-46 — record which project files this run actually analyzed (the `analyze_only` subset, or
         # all of them). The incremental orchestrator serves every analyzed-but-not-affected file from the
         # per-file cache, so it needs the full analyzed set to subtract the affected closure from.
@@ -1025,12 +1109,39 @@ module Rigor
         # override re-stamps it; and a pool backend folds `.rigor.yml`-positioned prepare / pool-degraded rows
         # into the same return, which the slice drops. The run's own stream is stamped once, at the end.
         diagnostics += analyze_targets(targets, environment: environment, project_files: expansion.fetch(:files))
+        # Issue #1060 — the positioned batches plugins registered through `Plugin::Base#emit_once`, read once
+        # every worker payload has been merged. Kept beside the per-file stream (their rows name files and
+        # lines) but outside `#per_file_diagnostics`, which `analyze_targets` has already sliced, so no one
+        # file's incremental cache entry carries a project-wide batch.
+        diagnostics += @diagnostic_aggregator.plugin_run_emission_diagnostics
         # ADR-103 WD12 — the effect fixpoint, in the post-pool aggregation slot beside the conformance
         # results. Graph-only over a finite lattice, so it is a plain worklist to a true fixpoint; it
         # contributes NO diagnostics and its result leaves through `#effect_table`, never through the
         # stream. Skipped entirely when collection did not run.
         close_effect_graph
-        diagnostics += @diagnostic_aggregator.rbs_quarantined_signature_diagnostics
+        diagnostics + post_analysis_diagnostic_streams
+      end
+
+      def template_unit_failure_diagnostics
+        template_units.failures.map do |failure|
+          Diagnostic.new(
+            path: failure.path, line: 1, column: 1,
+            message: "plugin #{failure.plugin_id.inspect} produced no template unit for " \
+                     "#{failure.path}: #{failure.message}",
+            severity: :error, rule: "runtime-error", source_family: :plugin_loader
+          )
+        end
+      end
+      private :template_unit_failure_diagnostics
+
+      # The rbs-coverage build-failure ladder plus every remaining post-analysis stream
+      # `#assemble_run_diagnostics` appends, in their fixed contract order (see the comments at each call
+      # below and at the streams' own definitions). Split out of `#assemble_run_diagnostics` so that
+      # method's `Metrics/AbcSize` stays under budget — every stream here is a plain `DiagnosticAggregator`
+      # reader with no branching of its own, so the split changes nothing about WHEN or in WHAT order they
+      # run.
+      def post_analysis_diagnostic_streams
+        diagnostics = @diagnostic_aggregator.rbs_quarantined_signature_diagnostics
         diagnostics += @diagnostic_aggregator.rbs_environment_build_failed_diagnostics
         # Issue #696 — after its env-wide twin and before the synthesized-namespace notice: the four
         # `rbs.coverage.*` build conditions surface widest-consequence first, and their relative order is
@@ -1040,12 +1151,25 @@ module Rigor
         # `type` alias would have contributed, never a class's own declared method surface, so it is the
         # narrowest-consequence rung on the same ladder.
         diagnostics += @diagnostic_aggregator.rbs_hkt_scan_failed_diagnostics
-        diagnostics += @diagnostic_aggregator.rbs_synthesized_namespace_diagnostics
+        # The synthesized-namespace notice, then (#610) the plugin-signature stand-down: the outcome that
+        # AVOIDED a definition-build failure, so the quietest row on that ladder.
+        diagnostics += @diagnostic_aggregator.rbs_coverage_notice_diagnostics
         diagnostics += @diagnostic_aggregator.conforms_to_diagnostics
         diagnostics += @diagnostic_aggregator.rbs_extended_reporter_diagnostics
         diagnostics += @diagnostic_aggregator.boundary_cross_diagnostics
-        diagnostics + @diagnostic_aggregator.source_rbs_synthesis_diagnostics
-      end
+        diagnostics += @diagnostic_aggregator.source_rbs_synthesis_diagnostics
+        # Issue #1051 — read after `analyze_targets` for the same reason the refusal stream below is: a
+        # plugin may register a disclosure from `#prepare` (the usual case) or while analysing a file, and
+        # both have to be in before the table is harvested. Ordered before the refusals so the run-level
+        # plugin rows read plugin-authored notice first, engine-authored envelope second.
+        diagnostics += @diagnostic_aggregator.plugin_run_disclosure_diagnostics
+        # Issue #959 — read LAST (after `analyze_targets`, which already ran before this method is called),
+        # so every per-file plugin call has had its chance to record a refusal on its (per-plugin-instance
+        # memoised) `IoBoundary`, alongside the prepare-time refusals the same boundary instance may
+        # already carry.
+        diagnostics + @diagnostic_aggregator.plugin_trust_refusal_diagnostics
+      end
+      private :post_analysis_diagnostic_streams
 
       # #788 round 7 — runs per-file analysis over `targets` and exposes what it produced as
       # `#per_file_diagnostics`: the `analyze_files` return, stamped with the same severity profile the run's
@@ -1053,7 +1177,9 @@ module Rigor
       # re-stamps), sliced to the rows positioned at the targets. Returns the RAW return for the run's stream,
       # which is stamped once, at the end of `#run_analysis`.
       def analyze_targets(targets, environment:, project_files:)
-        raw = @pool_coordinator.analyze_files(targets, environment: environment, project_files: project_files)
+        raw = template_units.remap(
+          @pool_coordinator.analyze_files(targets, environment: environment, project_files: project_files)
+        )
         analysed = targets.to_set
         @per_file_diagnostics = @diagnostic_aggregator.apply_severity_profile(raw)
                                                       .select { |diagnostic| analysed.include?(diagnostic.path) }
@@ -1161,7 +1287,8 @@ module Rigor
         # reconstructs `rbs.libraries` from config) can never drift out of key agreement.
         RunCacheKey.descriptor(
           configuration: @configuration, files: expansion.fetch(:files),
-          explain: @explain, rbs_config_entries: rbs_descriptor.configs
+          explain: @explain, rbs_config_entries: rbs_descriptor.configs,
+          template_units_digest: template_units.digest
         )
       end
 
@@ -1178,14 +1305,23 @@ module Rigor
 
       def build_run_dependency_descriptor(expansion, rbs_descriptor)
         entries = analyzed_file_entries(expansion) + discovery_file_entries(expansion) +
-                  pre_eval_file_entries + rbs_descriptor.files
-        globs = []
+                  pre_eval_file_entries + template_unit_file_entries + rbs_descriptor.files
+        # #979 — the signature ROOTS' listings, one glob row each. `rbs_descriptor.files` covers only the
+        # `.rbs` files that existed while the run read them, so without these a signature file written after
+        # the run left the slot validating fresh and the warm run answered without it.
+        globs = rbs_descriptor.globs + template_unit_glob_entries
         @plugin_registry.plugins.each do |plugin|
           # Read the boundary WITHOUT triggering its lazy `@io_boundary ||=` initializer: plugin instances
           # are frozen after the run, and a plugin that never built a boundary read no files through it,
           # so it contributes no dependencies.
           boundary = plugin.instance_variable_get(:@io_boundary)
-          entries.concat(boundary.cache_descriptor.files) if boundary
+          if boundary
+            # #629 — a boundary carries GlobEntry listing rows too (`IoBoundary#list_directory`), and they
+            # are the only edge back to a file the run decided was ABSENT from a directory it consulted.
+            boundary_descriptor = boundary.cache_descriptor
+            entries.concat(boundary_descriptor.files)
+            globs.concat(boundary_descriptor.globs)
+          end
           plugin.class.producers.each_value do |prod|
             globs.concat(plugin.send(:watch_glob_entries, prod[:watch])) if prod[:watch]
           end
@@ -1221,6 +1357,30 @@ module Rigor
       # expansion — so without this entry, editing one would leave the run-result cache serving diagnostics
       # computed against the previous version. The common case (a `lib/core_ext/` file that is also under
       # `paths:`) contributes a duplicate entry, which the descriptor's per-path validation absorbs.
+      # #392 — the TEMPLATE files behind the run's units. The key slot carries the compiled Ruby's digest
+      # (`template_units_digest`), which is what decides whether a cached answer describes this source; these
+      # entries are the validation half, so a template edited between two runs re-globs and re-digests here
+      # exactly as an analysed `.rb` file does. Both are needed: a transform that compiles two different
+      # templates to the same Ruby must still not resurrect the wrong PATH in a diagnostic.
+      # #392 — one `:names` row per claimed `template_globs:` pattern, whether or not it matched. The file
+      # rows below cover edits to templates that EXIST; only a glob row notices one appearing or vanishing,
+      # which is what let a project's first template stay invisible to every warm run.
+      def template_unit_glob_entries
+        template_units.glob_entries
+      end
+
+      # Every template the run READ, successes and failures alike: a `plugin_loader` row produced by a
+      # template that would not compile must not outlive the edit that fixes it, and a buffer-bound path is
+      # digested at the bytes the run actually read.
+      def template_unit_file_entries
+        template_units.source_paths.filter_map do |path|
+          physical = template_units.physical_path(path, @buffer)
+          next unless File.file?(physical)
+
+          Cache::Descriptor::FileEntry.stat(path: physical, digest: Cache::FileDigest.hexdigest(physical))
+        end
+      end
+
       def pre_eval_file_entries
         @configuration.pre_eval.filter_map do |path|
           physical = @buffer ? @buffer.resolve(path) : path
@@ -1305,18 +1465,39 @@ module Rigor
         @project_discovered_singleton_def_sources = discovery.discovered_singleton_def_sources
         @project_discovered_superclasses = discovery.discovered_superclasses
         @project_discovered_header_nestings = discovery.discovered_header_nestings
-        @project_discovered_includes = discovery.discovered_includes
+        apply_discovery_mixin_tables(discovery)
+        @project_discovered_deferred_ranges = discovery.discovered_deferred_ranges
+        apply_discovery_call_surface_tables(discovery)
         @project_discovered_class_sources = discovery.discovered_class_sources
         @project_constant_values = discovery.constant_values
         @published_constant_name_set = nil
+        @constant_writer_index = nil
+        @constant_shadower_index = nil
         @project_constant_sources = discovery.constant_sources
         @project_constant_writes = discovery.constant_writes
         @project_discovered_method_visibilities = discovery.discovered_method_visibilities
         @project_discovered_methods = discovery.discovered_methods
+        @project_discovered_parameter_envelopes = discovery.discovered_parameter_envelopes
         @project_data_member_layouts = discovery.data_member_layouts
         @project_struct_member_layouts = discovery.struct_member_layouts
       end
 
+      # The tables only check rules read beyond dispatch — the issue #1120 refinements and the issue #1367
+      # global-write census. Extracted to keep {#apply_discovery_result} under its ABC budget.
+      def apply_discovery_call_surface_tables(discovery)
+        @project_discovered_refinements = discovery.discovered_refinements
+        @project_discovered_global_write_census = discovery.discovered_global_write_census
+      end
+
+      # The three mixin tables the discovery pass carries — the ADR-24 `include` map, its issue #1123
+      # `prepend` twin, and the #898 `extend` table. Extracted to keep {#apply_discovery_result} under its
+      # ABC budget.
+      def apply_discovery_mixin_tables(discovery)
+        @project_discovered_includes = discovery.discovered_includes
+        @project_discovered_prepends = discovery.discovered_prepends
+        @project_discovered_extends = discovery.discovered_extends
+      end
+
       # Internal: builds the deferred cross-file discovery tables at most once per run and adopts them.
       # Memoised on `@project_discovery_done` (reset at the start of `#run`). No-op under `@prebuilt` — the
       # LSP path deliberately seeds an empty project scope from a snapshot that carries no discovery tables,
@@ -1399,7 +1580,7 @@ module Rigor
         3.0.0 3.1.0 3.2.0 3.3.0 3.4.0 3.5.0 4.0.0 4.1.0 4.2.0
       ].freeze
 
-      # @return [String, nil] the lowest `target_ruby` this Prism build accepts, or nil if none of the
+      # @return the lowest `target_ruby` this Prism build accepts, or nil if none of the
       #   ladder parses. Memoised per process (the value is constant for a given Prism).
       def self.prism_supported_floor
         @prism_supported_floor ||= PRISM_VERSION_LADDER.find do |candidate|
@@ -1450,6 +1631,25 @@ module Rigor
       # The buffer's logical path is added to the file list even if it's not under `paths:` — per design §
       # "Failure envelope": "--instead-of=Y with Y not under any paths: directory → treated as a valid
       # logical identity for the buffer".
+      # #392 — the run's template units. Built once per run, on the parent, AFTER the plugin pre-pass has
+      # loaded the registry; a run whose plugins declare no `template_globs:` never globs and never calls a
+      # plugin.
+      #
+      # #1038 — a runner built with `prebuilt:` hands the snapshot's warm index to `collect(previous:)`, so
+      # a per-buffer publish against a long-lived {LanguageServer::ProjectContext} re-runs the transform
+      # only for a template that actually moved on disk (and for the buffer's own, always). The globs are
+      # still re-expanded and every surviving template is still revalidated, so an added, deleted or edited
+      # template is seen on the next publish without the owner invalidating anything. A runner with no
+      # `prebuilt:` — every CLI run — passes no `previous:` and builds the index exactly as before.
+      def template_units
+        @template_units ||= if @plugin_registry.nil?
+                              TemplateUnits.empty
+                            else
+                              TemplateUnits.collect(registry: @plugin_registry, buffer: @buffer,
+                                                    previous: @prebuilt&.template_units)
+                            end
+      end
+
       def target_files(expansion)
         files = expansion.fetch(:files)
         # ADR-46 slice 2 — restrict the analyzed set to the affected closure while the pre-pass (run
@@ -1460,14 +1660,41 @@ module Rigor
           # the same allowance option A makes below.
           files = files.select { |path| @analyze_only.include?(path) }
           files |= [@buffer.logical_path] if @buffer && @analyze_only.include?(@buffer.logical_path)
-          return files
+          return template_unit_targets(files)
         end
-        return files if @buffer.nil?
+        return template_unit_targets(files) if @buffer.nil?
 
-        # Editor mode option A — no closure, so the buffer's single logical path IS the analyzed set.
+        # Editor mode option A — no closure, so the buffer's single logical path IS the analyzed set. The
+        # template units deliberately do NOT join it: a per-buffer publish answers about the buffer the
+        # editor is showing, and appending every view would publish diagnostics for files the editor did
+        # not ask about (and re-parse them on every keystroke).
         [@buffer.logical_path]
       end
 
+      # #392 — the template units join the analysed set AFTER any narrowing, so an `--incremental` recheck
+      # re-analyses every unit even when its closure is one `.rb` file. Nothing in the ADR-46 dependency
+      # graph names a synthesised file, so there is no edge that could put a unit in a closure — narrowing
+      # first and appending second is what makes "always re-analysed" true rather than a comment. The cost
+      # is one parse per template on the warm path; the alternative silently drops every template
+      # diagnostic from the second run onwards.
+      #
+      # Appended rather than merged in sorted order so the `.rb` expansion's own order — and every output
+      # that follows it — is byte-identical for a project with no units.
+      def template_unit_targets(files)
+        return files if template_units.empty?
+
+        files + (template_units.paths - files)
+      end
+      private :template_unit_targets
+
+      # #392 — the unit paths this run synthesised. Read by {IncrementalSession}, which keeps them OUT of
+      # its analysed-file set: a unit is never served from the per-file cache and never counts as a file
+      # that was removed from the project, because `#target_files` re-analyses it every run.
+      def template_unit_paths
+        template_units.paths
+      end
+      public :template_unit_paths
+
       # Editor mode (`buffer:` non-nil) auto-flips the cache store to `read_only: true` so multiple
       # debounced editor invocations against the same project don't churn the on-disk cache or race on
       # schema-version writes. Cache reads continue unchanged; misses still run the producer block but the
@@ -1504,7 +1731,9 @@ module Rigor
           synthetic_method_index: -> { @synthetic_method_index },
           project_patched_methods: -> { @project_patched_methods },
           project_scope_seed: -> { project_scope_seed_tables },
-          analyze_file: ->(path, environment) { analyze_file(path, environment) }
+          template_units: -> { template_units },
+          analyze_file: ->(path, environment) { analyze_file(path, environment) },
+          restored_run_level_rows: @restored_run_level_rows
         )
         @diagnostic_aggregator = DiagnosticAggregator.new(
           configuration: @configuration,
@@ -1518,10 +1747,12 @@ module Rigor
           pre_eval_diagnostics_from_scanner: -> { @pre_eval_diagnostics_from_scanner },
           synthesized_namespaces_snapshot: -> { @snapshots.synthesized_namespaces },
           quarantined_signatures_snapshot: -> { @snapshots.quarantined_signatures },
+          signature_standdowns_snapshot: -> { @snapshots.signature_standdowns },
           env_build_failure_snapshot: -> { @snapshots.env_build_failure },
           definition_build_failures_snapshot: -> { @snapshots.definition_build_failures },
           hkt_scan_failure_snapshot: -> { @snapshots.hkt_scan_failure },
-          conformance_results_snapshot: -> { @snapshots.conformance_results }
+          conformance_results_snapshot: -> { @snapshots.conformance_results },
+          pooled_run_disclosures: -> { @pool_coordinator.collected_run_disclosures }
         )
       end
 
@@ -1548,7 +1779,9 @@ module Rigor
         RunStats.new(
           wall_seconds: Process.clock_gettime(Process::CLOCK_MONOTONIC) - wall_started_at,
           peak_rss_bytes: RunStats.peak_rss_bytes,
-          target_files: expansion.fetch(:files).size,
+          # #392 — the template units count too: they are files this run parsed and typed, and a stats line
+          # that omitted them would under-report exactly the work a views-heavy project added.
+          target_files: expansion.fetch(:files).size + template_units.paths.size,
           rbs_classes_total: snapshot.size,
           rbs_classes_project_sig: project_sig,
           rbs_classes_bundled: bundled,
@@ -1705,6 +1938,12 @@ module Rigor
       # so Prism's location data carries the LOGICAL path. Non-binding paths go through the cheaper
       # `Prism.parse_file` codepath unchanged.
       def parse_source(path)
+        entry = template_units[path]
+        if entry
+          return Prism.parse(entry.source, filepath: path, version: @configuration.target_ruby,
+                                           scopes: template_units.parse_scopes(path))
+        end
+
         if @in_memory_sources&.key?(path)
           return Prism.parse(@in_memory_sources[path], filepath: path, version: @configuration.target_ruby)
         end
@@ -1752,22 +1991,58 @@ module Rigor
         unless @project_discovered_header_nestings.empty?
           tables[:discovered_header_nestings] = @project_discovered_header_nestings
         end
-        tables[:discovered_includes] = @project_discovered_includes unless @project_discovered_includes.empty?
+        seed_mixin_tables(tables)
         unless @project_discovered_method_visibilities.empty?
           tables[:discovered_method_visibilities] = @project_discovered_method_visibilities
         end
         tables[:discovered_methods] = @project_discovered_methods unless @project_discovered_methods.empty?
+        unless @project_discovered_deferred_ranges.empty?
+          tables[:discovered_deferred_ranges] = @project_discovered_deferred_ranges
+        end
+        seed_call_surface_tables(tables)
         seed_opt_in_pre_pass_tables(tables)
         seed_member_layout_tables(tables)
         seed_dependency_attribution_tables(tables)
         tables
       end
 
+      # The tables only check rules read: the issue #992 parameter envelopes (`call.wrong-arity`), the issue #1120
+      # refinements (`call.undefined-method`), and the issue #1367 global-write census (the `global.*` write
+      # rules). Split out of {#project_scope_seed_tables} to keep it under the complexity budget.
+      def seed_call_surface_tables(tables)
+        unless @project_discovered_parameter_envelopes.empty?
+          tables[:discovered_parameter_envelopes] = @project_discovered_parameter_envelopes
+        end
+        tables[:discovered_refinements] = @project_discovered_refinements unless @project_discovered_refinements.empty?
+        # Issue #1367 — read by the `global.*` write rules.
+        return if @project_discovered_global_write_census.empty?
+
+        tables[:discovered_global_write_census] = @project_discovered_global_write_census
+      end
+
+      # The three mixin tables: the ADR-24 instance-side `include` map, its issue #1123 `prepend` twin
+      # (which carries the instance-ancestor order the include table's set-shaped value cannot), and the
+      # #898 singleton-side `extend` table. Grouped here because they are read as one picture of a class's
+      # ancestry, and split out of {#project_scope_seed_tables} to keep it under the complexity budget.
+      def seed_mixin_tables(tables)
+        tables[:discovered_includes] = @project_discovered_includes unless @project_discovered_includes.empty?
+        tables[:discovered_prepends] = @project_discovered_prepends unless @project_discovered_prepends.empty?
+        tables[:discovered_extends] = @project_discovered_extends unless @project_discovered_extends.empty?
+      end
+
       # ADR-46 slice 1 / issue #644 — the two SOURCE-ATTRIBUTION tables, read only by the recording accessors
       # (`Scope#record_class_dependency` for the class-declaration map, `Scope#record_constant_dependency`
-      # for the constant-write map). A normal run carries neither. Extracted to keep
+      # for the constant-write map). A normal run carries neither of the two. Extracted to keep
       # {#project_scope_seed_tables} under the complexity budget.
+      #
+      # Issue #617 — the census's binding writes, grouped by last segment, ride every run instead: a constant
+      # compound write whose plain read resolves nothing reads its binding off them, a TYPE rather than an edge.
+      # Issue #1290's shadowing writes ride beside them for the lexical ladder, for the same reason.
       def seed_dependency_attribution_tables(tables)
+        writers = constant_writer_index
+        tables[:constant_writers] = writers unless writers.empty?
+        shadowers = constant_shadower_index
+        tables[:constant_shadowers] = shadowers unless shadowers.empty?
         return unless @record_dependencies
 
         tables[:discovered_class_sources] = @project_discovered_class_sources unless
@@ -1802,12 +2077,44 @@ module Rigor
         tables[:published_constant_names] = names unless names.empty?
       end
 
-      # Issue #644 — the seeded `in_source_constants` table, joining the two cross-file constant producers.
-      # The whole-project literal table wins over a `pre_eval:` publication of the same name: both describe
-      # the same assignment, the literal table pins the value the write actually carries while ADR-17's
-      # widener erases it to the class, and listing a file under `pre_eval:` must never LOSE precision. The
-      # per-file table still wins over both (`ScopeIndexer.index`'s merge) — same-file stays the most
-      # specific authority.
+      # Issue #617 — the censused names that bind, grouped by last segment (`Scope#bound_constant_names`). A
+      # name some write other than a memo `||=` touches always binds. A memo-only name binds once memos of its
+      # segment span two files: either may load first and set the constant the other then reads, so only a
+      # memo no other file shares keeps the idiom's reading. Files are counted expanded, because discovery can
+      # walk one file under two spellings (`lib/b.rb`, `./lib/b.rb`).
+      def constant_writer_index
+        @constant_writer_index ||= begin
+          memo_files = memo_files_by_segment
+          @project_constant_writes.each_with_object({}) do |(name, by_path), index|
+            segment = name.split("::").last
+            next if memo_only?(by_path) && memo_files.fetch(segment).size < 2
+
+            (index[segment] ||= []) << name
+          end.each_value(&:freeze).freeze
+        end
+      end
+
+      # Issue #1290 — the censused names some write other than a memo `||=` assigns, grouped by last segment
+      # (`Scope#shadowing_constant_names`): the ones that exist whether or not an outer constant of the name
+      # does, and so stop the lexical ladder above it. A memo-only name is left out however many files memoize
+      # it, unlike in {#constant_writer_index}: `X ||= v` resolves `X` through the very lookup whose lower rung
+      # the stop would replace, so wherever that rung answers, the memo finds it and never creates the name.
+      def constant_shadower_index
+        @constant_shadower_index ||= @project_constant_writes.each_with_object({}) do |(name, by_path), index|
+          (index[name.split("::").last] ||= []) << name unless memo_only?(by_path)
+        end.each_value(&:freeze).freeze
+      end
+
+      def memo_files_by_segment
+        @project_constant_writes.each_with_object({}) do |(name, by_path), files|
+          set = (files[name.split("::").last] ||= Set.new)
+          by_path.each { |path, descriptor| set << File.expand_path(path) if memo_descriptor?(descriptor) }
+        end
+      end
+
+      def memo_only?(by_path) = by_path.each_value.all? { |descriptor| memo_descriptor?(descriptor) }
+      def memo_descriptor?(descriptor) = descriptor == Inference::ScopeIndexer::CONSTANT_MEMO
+
       # Issue #644 — the LAST SEGMENTS of the published table, the run-wide half of
       # `Scope#published_constant?`. Seeded on EVERY run (unlike `constant_sources`, which only a recording
       # run needs) because {CheckRules::PublishedConstantGuard} asks the question on every `if` / `unless`.
@@ -1816,11 +2123,57 @@ module Rigor
           @project_constant_values.keys.to_set { |name| name.split("::").last }.freeze
       end
 
+      # Issue #644 — the seeded `in_source_constants` table, joining the two cross-file constant producers.
+      # The whole-project literal table wins over a `pre_eval:` publication of the same name: both describe
+      # the same assignment, the literal table pins the value the write actually carries while ADR-17's
+      # widener erases it to the class, and listing a file under `pre_eval:` must never LOSE precision. The
+      # per-file table still wins over both (`ScopeIndexer.index`'s merge) — same-file stays the most
+      # specific authority.
       def merged_seed_constants
-        return @project_constant_values if @project_pre_eval_constants.empty?
-        return @project_pre_eval_constants if @project_constant_values.empty?
+        pre_eval = publishable_pre_eval_constants
+        return @project_constant_values if pre_eval.empty?
+        return pre_eval if @project_constant_values.empty?
+
+        pre_eval.merge(@project_constant_values).freeze
+      end
 
-        @project_pre_eval_constants.merge(@project_constant_values).freeze
+      # Issue #663 — the `pre_eval:` publication with every name an UNLISTED file also assigns retracted.
+      # Without this a listed `X = :a` answered `Symbol` at every reader while a sibling `X = "str"` decided
+      # the runtime value half the time: a confident wrong type, not lost precision, and the one asymmetry
+      # #644's precedence work left standing. The retraction costs the opt-in nothing where it earns its
+      # keep — a name only listed files write is untouched, and where the literal table also publishes it
+      # already won (above).
+      #
+      # Conflict is read off #644's write attribution, which censuses every assigning form, so a name the
+      # listed file's own typed walk widened is retracted by an unlisted `X += 1` or `A, X = 1, 2` as
+      # readily as by a plain reassignment. Among LISTED files the rule is unchanged: `PreEvalConstants`
+      # widens first and drops only on disagreement, so two listed files writing `1` and `2` still publish
+      # `Integer` rather than being retracted for being two.
+      def publishable_pre_eval_constants
+        return @project_pre_eval_constants if @project_pre_eval_constants.empty?
+
+        listed = pre_eval_path_set
+        kept = @project_pre_eval_constants.reject { |name, _| unlisted_constant_writer?(name, listed) }
+        kept.size == @project_pre_eval_constants.size ? @project_pre_eval_constants : kept.freeze
+      end
+
+      # True when some file outside `listed` assigns `name`. The wildcard key is consulted alongside the
+      # name's own attribution ([#668](https://github.com/rigortype/rigor/issues/668)): a `k::X = 7` names
+      # no target, and a listed file kept out of `paths:` (ADR-17 WD5 permits it) contributes no censused
+      # name of its own for the wildcard's paths to have been folded into.
+      def unlisted_constant_writer?(name, listed)
+        segment = name.split("::").last
+        writers = @project_constant_sources[name]
+        wildcard = @project_constant_sources["#{Inference::ScopeIndexer::DYNAMIC_TARGET_PREFIX}#{segment}"]
+        [writers, wildcard].any? do |paths|
+          paths&.any? { |path| !listed.include?(File.expand_path(path)) }
+        end
+      end
+
+      # The listed `pre_eval:` files, expanded so a census path and a configured one compare as the same
+      # file whichever spelling each arrived in.
+      def pre_eval_path_set
+        @pre_eval_path_set ||= @configuration.pre_eval.to_set { |path| File.expand_path(path) }
       end
 
       # ADR-46 — seed the instance + singleton `"path:line"` def-source tables (each only when non-empty).
@@ -1865,10 +2218,11 @@ module Rigor
       def analyze_with_effects(path, environment)
         return analyze_file_body(path, environment) unless @record_effects
 
+        entry = template_units[path]
         diagnostics = nil
         collection = Effects::Collector.collect_for(
           path, attribution: @effect_attribution, envelopes: effect_envelope_index(environment),
-                plugin_facts: effect_plugin_facts
+                plugin_facts: effect_plugin_facts, unit_key: entry&.unit_key, unit_owner: entry&.self_type
         ) do
           diagnostics = analyze_file_body(path, environment)
         end
@@ -1907,7 +2261,9 @@ module Rigor
         # is a per-FILE site, so one `Thread.current` read is already nothing. The per-dispatch site in
         # `ExpressionTyper#call_type_for` is the one that pays for the integer fast path.
         Effects::Collector.record_root(parse_result.value)
-        scope = seed_project_scope(Scope.empty(environment: environment, source_path: path))
+        scope = template_units.seed(
+          seed_project_scope(Scope.empty(environment: environment, source_path: path)), path
+        )
         # ADR-24 slice 4a/4 — record unresolved implicit-self calls during the typing pass ONLY (not
         # CheckRules, whose own `type_of` queries would otherwise re-trigger the choke-point).
         # `self_call_misses` feeds the `call.self-undefined-method` collector; the recorder is inert unless
@@ -1947,7 +2303,7 @@ module Rigor
       # output and the plugin diagnostics are then built from that single walk's results.
       def rule_and_plugin_diagnostics(path, parse_result, scope, index, self_call_misses)
         root = parse_result.value
-        node_collectors = CheckRules.build_node_collectors(path, index)
+        node_collectors = CheckRules.build_node_collectors(path, index, root)
         node_results = node_rule_results_by_plugin(path, root, scope, node_collectors, index)
         diagnostics = CheckRules.diagnose(
           path: path,