rigortype 0.3.8 → 0.3.9

data/lib/rigor/builtins/imported_refinements.rb

@@ -31,11 +31,12 @@ module Rigor
     # - **No-argument refinement names** (`non-empty-string`, `non-zero-int`,
     #   `lowercase-string`, …) live in `REGISTRY` and resolve through `lookup(name)`.
     # - **Parameterised refinement payloads** (`non-empty-array[Integer]`,
-    #   `non-empty-hash[Symbol, Integer]`, `int<5, 10>`) are accepted by `parse(payload)`. The
-    #   full grammar is documented on `Parser`. The two surfaces share `REGISTRY` for the
-    #   no-arg head names; the parameterised head names live in `PARAMETERISED_TYPE_BUILDERS`
-    #   (square-bracket form, type args) and `PARAMETERISED_INT_BUILDERS` (angle-bracket form,
-    #   integer bounds).
+    #   `non-empty-hash[Symbol, Integer]`, `Integer[5..10]`, and the deprecated `int<5, 10>`)
+    #   are accepted by `parse(payload)`. The full grammar is documented on `Parser`. The two
+    #   surfaces share `REGISTRY` for the no-arg head names; the parameterised head names live
+    #   in `PARAMETERISED_TYPE_BUILDERS` (square-bracket form, type args), `RANGE_HEAD_BUILDERS`
+    #   (a numeric class over a range literal) and `PARAMETERISED_INT_BUILDERS` (the deprecated
+    #   angle-bracket form, integer bounds).
     module ImportedRefinements
       REGISTRY = {
         "non-empty-string" => -> { Type::Combinator.non_empty_string },
@@ -58,7 +59,10 @@ module Rigor
         "non-empty-lowercase-string" => -> { Type::Combinator.non_empty_lowercase_string },
         "non-empty-uppercase-string" => -> { Type::Combinator.non_empty_uppercase_string },
         "literal-string" => -> { Type::Combinator.literal_string },
-        "non-empty-literal-string" => -> { Type::Combinator.non_empty_literal_string }
+        "non-empty-literal-string" => -> { Type::Combinator.non_empty_literal_string },
+        # ADR-109 WD4 — names for the two Float ranges people mean most; each is an alias of a range.
+        "non-nan-float" => -> { Type::Combinator.non_nan_float },
+        "finite-float" => -> { Type::Combinator.finite_float }
       }.freeze
       private_constant :REGISTRY
 
@@ -139,13 +143,52 @@ module Rigor
       }.freeze
       private_constant :PARAMETERISED_TYPE_BUILDERS
 
-      # `name<min, max>` — integer-bound parameterised refinements. Each builder takes an
+      # `Class[range]` — a numeric class head bounded by a Ruby range literal (ADR-109). The
+      # builder receives the `Range` value and returns the carrier, or `nil` when the range is
+      # empty or its endpoints are not literals of the head class; `nil` surfaces as the ordinary
+      # unresolved-payload diagnostic. `Float` joins this table with the `FloatRange` carrier.
+      RANGE_HEAD_BUILDERS = {
+        "Integer" => lambda { |range|
+          lo = range.begin
+          hi = range.end
+          return nil unless (lo.nil? || lo.is_a?(Integer)) && (hi.nil? || hi.is_a?(Integer))
+
+          # `1...10` is the set `1..9`: Integer ranges canonicalise to the closed form.
+          hi -= 1 if range.exclude_end? && hi.is_a?(Integer)
+          return nil if lo.is_a?(Integer) && hi.is_a?(Integer) && lo > hi
+
+          Type::Combinator.integer_range(lo || Type::IntegerRange::NEG_INFINITY, hi || Type::IntegerRange::POS_INFINITY)
+        },
+        # ADR-109 WD4 — `Float[R]` is the set of Floats `R.cover?` accepts. A missing or `nil` endpoint
+        # is the infinity on that side, except that `nil..nil` covers NaN in Ruby and so is `Float`
+        # itself; an Integer endpoint coerces (`(0..1).cover?(0.5)` is true); an exclusive end is kept
+        # (the carrier canonicalises it for equality), and an empty range declines.
+        "Float" => lambda { |range|
+          return Type::Combinator.nominal_of("Float") if range.begin.nil? && range.end.nil?
+
+          lo = ImportedRefinements.float_range_endpoint(range.begin, -Float::INFINITY)
+          hi = ImportedRefinements.float_range_endpoint(range.end, Float::INFINITY)
+          return nil if lo.nil? || hi.nil?
+
+          exclusive = range.exclude_end? && !range.end.nil?
+          return nil if lo > (exclusive ? hi.prev_float : hi)
+
+          Type::Combinator.float_range(lo, hi, exclude_end: exclusive)
+        }
+      }.freeze
+      private_constant :RANGE_HEAD_BUILDERS
+
+      # `name<min, max>` — the PHPStan-style integer-bound form ADR-109 deprecates: still parsed so
+      # signatures written against v0.1–v0.3 keep resolving, never displayed. Each builder takes an
       # `Array<Integer>` and returns a `Rigor::Type` (or `nil`). Bounds are signed integer
-      # literals; `min` MUST be ≤ `max` for the carrier to construct successfully
-      # (`Type::IntegerRange` enforces the invariant).
+      # literals. A reversed pair (`min` > `max`) is declined as `nil` like every other shape
+      # mismatch, so the caller surfaces `dynamic.rbs-extended.unresolved` at the annotation;
+      # `Type::IntegerRange` raises on it instead, and that `ArgumentError` used to escape as an
+      # `internal analyzer error` that abandoned the whole Ruby file.
       PARAMETERISED_INT_BUILDERS = {
         "int" => lambda { |bounds|
           return nil unless bounds.size == 2
+          return nil if bounds[0] > bounds[1]
 
           Type::Combinator.integer_range(bounds[0], bounds[1])
         }
@@ -154,32 +197,32 @@ module Rigor
 
       module_function
 
-      # @param name [String] kebab-case refinement name.
-      # @return [Rigor::Type, nil] the matching refinement carrier, or `nil` if the name is
+      # @param name — kebab-case refinement name.
+      # @return the matching refinement carrier, or `nil` if the name is
       #   not registered.
       def lookup(name)
         builder = REGISTRY[name.to_s]
         builder&.call
       end
 
-      # @param payload [String] the trailing payload of a `rigor:v1:return:` (or sibling)
+      # @param payload — the trailing payload of a `rigor:v1:return:` (or sibling)
       #   directive. Accepts the bare-name forms `lookup` already handles plus the
       #   parameterised forms documented on {Parser}.
-      # @param name_scope [Rigor::TypeNode::NameScope, nil]
+      # @param name_scope —
       #   ADR-13 slice 3 — when provided, the parser consults the scope's `#resolver` chain
       #   after the built-in registry and built-in parametric forms but before the RBS
       #   Nominal fallback. `nil` (default) preserves the slice-1 / slice-2 behaviour of
       #   consulting only built-ins + RBS.
-      # @param reporter [Rigor::RbsExtended::Reporter, nil]
+      # @param reporter —
       #   ADR-13 slice 3b — collector that the Resolver feeds `dynamic.shape.lossy-projection`
       #   events into when a shape-projection head (`pick_of`, `omit_of`, `partial_of`,
       #   `required_of`, `readonly_of`) is applied to a carrier that does not preserve shape
       #   information. `nil` (default) suppresses event accumulation; legacy call sites that
       #   have no reporter to thread keep the pre-slice-3b silent fall-through.
-      # @param source_location [RBS::Location, nil] location attribution for the events the
+      # @param source_location — location attribution for the events the
       #   Resolver records. Carries the annotation's filename / line / column so the runner
       #   can stamp diagnostics with the user-visible source site.
-      # @return [Rigor::Type, nil] the resolved refinement carrier, or `nil` when the payload
+      # @return the resolved refinement carrier, or `nil` when the payload
       #   is unparseable or names a refinement / class no registered source resolved.
       def parse(payload, name_scope: nil, reporter: nil, source_location: nil)
         Parser.new(
@@ -201,6 +244,20 @@ module Rigor
         PARAMETERISED_INT_BUILDERS[name]
       end
 
+      def range_head_builder(name)
+        RANGE_HEAD_BUILDERS[name]
+      end
+
+      # A Float-head range endpoint as a double: `nil` (absent) is `default`, an Integer literal
+      # coerces, a non-NaN Float stands, anything else declines with `nil`.
+      def float_range_endpoint(value, default)
+        case value
+        when nil then default
+        when Integer then value.to_f
+        when Float then value.nan? ? nil : value
+        end
+      end
+
       def known?(name)
         REGISTRY.key?(name.to_s) ||
           PARAMETERISED_TYPE_BUILDERS.key?(name.to_s) ||
@@ -219,8 +276,10 @@ module Rigor
       #   parametric  := simple_name '[' type_arg_list ']'
       #                | simple_name '<' int_bound_list '>'
       #   type_arg_list := type_arg (',' type_arg)*
-      #   type_arg    := type | class_name
+      #   type_arg    := range_literal | type | class_name
       #   class_name  := /[A-Z][A-Za-z0-9_]*(?:::[A-Z][A-Za-z0-9_]*)*/
+      #   range_literal := endpoint? ('..' | '...') endpoint?     (at least one side written)
+      #   endpoint    := signed_int | 'nil'
       #   int_bound_list := signed_int (',' signed_int)*
       #   signed_int  := /-?\d+/
       #
@@ -274,7 +333,16 @@ module Rigor
         # delimiter.
         SYMBOL_LITERAL = /:(?<value>[a-zA-Z_][a-zA-Z0-9_]*[?!=]?)/
         STRING_LITERAL = /"(?<value>[^"\\]*)"/
-        private_constant :SIMPLE_NAME, :CLASS_NAME, :SIGNED_INT, :SYMBOL_LITERAL, :STRING_LITERAL
+        # ADR-109 — a Ruby range literal at type-arg position, `1..10` / `1...10` / `1..` / `..10` /
+        # `nil..nil`, and for the Float head `0.0...1.0` / `1e-3..` / `-Float::INFINITY..Float::MAX`.
+        # Tried before the class-name and integer scans so `Float::INFINITY..` and `1..10` are not
+        # consumed as a class name or a bare integer; the operator is mandatory, so a bare integer or
+        # constant never matches. `..` with nothing on either side is not Ruby and is rejected after
+        # the match.
+        RANGE_ENDPOINT = /-?(?:\d+(?:\.\d+)?(?:[eE][+-]?\d+)?|Float::INFINITY|Float::MAX)|nil/
+        RANGE_LITERAL = /(?<lo>#{RANGE_ENDPOINT})?\s*(?<op>\.\.\.?)\s*(?<hi>#{RANGE_ENDPOINT})?/
+        private_constant :SIMPLE_NAME, :CLASS_NAME, :SIGNED_INT, :SYMBOL_LITERAL, :STRING_LITERAL,
+                         :RANGE_ENDPOINT, :RANGE_LITERAL
 
         def parse_type_ast
           if (class_name = @scanner.scan(CLASS_NAME))
@@ -382,7 +450,9 @@ module Rigor
         end
 
         def parse_single_type_arg_ast
-          if (class_name = @scanner.scan(CLASS_NAME))
+          if (range = scan_range_literal)
+            range
+          elsif (class_name = @scanner.scan(CLASS_NAME))
             parse_class_arg_tail_ast(class_name)
           elsif (literal = @scanner.scan(SIGNED_INT))
             TypeNode::IntegerLiteral.new(value: Integer(literal))
@@ -421,6 +491,36 @@ module Rigor
           Integer(literal)
         end
 
+        # Returns a {TypeNode::RangeLiteral} when the scanner sits on a Ruby range literal, `nil`
+        # (without consuming input) otherwise. `nil` and an absent endpoint both become Ruby's
+        # `nil` endpoint; the two spellings denote the same range.
+        def scan_range_literal
+          return nil unless @scanner.scan(RANGE_LITERAL)
+
+          lo = @scanner[:lo]
+          hi = @scanner[:hi]
+          return nil if lo.nil? && hi.nil?
+
+          TypeNode::RangeLiteral.new(
+            value: Range.new(range_endpoint(lo), range_endpoint(hi), @scanner[:op] == "...")
+          )
+        end
+
+        # The endpoint as the Ruby value the token denotes: an Integer literal stays an Integer (the
+        # `Integer` head needs to tell `1` from `1.0`), a Float literal or one of the four spelled
+        # constants becomes the double.
+        def range_endpoint(token)
+          case token
+          when nil, "nil" then nil
+          when "Float::INFINITY" then Float::INFINITY
+          when "-Float::INFINITY" then -Float::INFINITY
+          when "Float::MAX" then Float::MAX
+          when "-Float::MAX" then -Float::MAX
+          when /[.eE]/ then Float(token)
+          else Integer(token)
+          end
+        end
+
         def skip_ws
           @scanner.skip(/\s+/)
         end
@@ -463,7 +563,7 @@ module Rigor
         # `StringLiteral`) carries a Ruby value that lifts directly to a `Constant<value>`
         # carrier through the same helper.
         LITERAL_AST_NODES = [
-          TypeNode::IntegerLiteral, TypeNode::SymbolLiteral, TypeNode::StringLiteral
+          TypeNode::IntegerLiteral, TypeNode::SymbolLiteral, TypeNode::StringLiteral, TypeNode::RangeLiteral
         ].freeze
         private_constant :LITERAL_AST_NODES
 
@@ -519,6 +619,11 @@ module Rigor
         end
 
         def resolve_generic(node)
+          # ADR-109 — `Integer[1..10]`. A range literal under a numeric head is that head's range
+          # refinement or nothing: an empty or malformed range declines here rather than falling
+          # through to a `Nominal[Integer, [Constant<Range>]]` the RBS fallback would otherwise build.
+          return resolve_range_head(node) if range_headed?(node)
+
           builtin = try_builtin_parametric(node)
           return builtin unless builtin.nil?
 
@@ -547,6 +652,19 @@ module Rigor
           try_parametric_type_builder(node) || try_parametric_int_builder(node)
         end
 
+        def range_headed?(node)
+          !ImportedRefinements.range_head_builder(node.head).nil? &&
+            node.args.any?(TypeNode::RangeLiteral)
+        end
+
+        # Exactly one range literal under the head; `Integer[1..10, 3]` is not a range refinement.
+        # Anything else under the same head (`Integer[Foo]`) keeps its pre-ADR-109 path.
+        def resolve_range_head(node)
+          return nil unless node.args.size == 1
+
+          ImportedRefinements.range_head_builder(node.head).call(node.args.first.value)
+        end
+
         def try_parametric_type_builder(node)
           builder = ImportedRefinements.parametric_type_builder(node.head)
           return nil if builder.nil?
@@ -585,7 +703,23 @@ module Rigor
           bounds = node.args.map { |a| a.is_a?(TypeNode::IntegerLiteral) ? a.value : nil }
           return nil if bounds.any?(&:nil?)
 
-          builder.call(bounds)
+          result = builder.call(bounds)
+          record_deprecated_form(node, bounds, result) unless result.nil?
+          result
+        end
+
+        # ADR-109 WD3 — the angle-bracket form still resolves, and the run says so once per annotation with
+        # the spelling the same type now displays as. Recorded only when the payload resolved: an
+        # unresolvable one already surfaces as `dynamic.rbs-extended.unresolved`, and a second row for it
+        # would name a replacement for something that never parsed.
+        def record_deprecated_form(node, bounds, result)
+          return if @reporter.nil?
+
+          path, line, column = RbsExtended::Reporter.position_of(@source_location)
+          @reporter.record_deprecated_form(
+            payload: "#{node.head}<#{bounds.join(', ')}>", replacement: result.describe,
+            path: path, line: line, column: column
+          )
         end
 
         def resolve_args(args)

data/lib/rigor/builtins/predefined_constant_refinements.rb

@@ -117,8 +117,7 @@ module Rigor
 
       # --- private ------------------------------------------------------
 
-      # @param value [String] a non-empty string
-      # @return [Rigor::Type]
+      # @param value — a non-empty string
       def self.classify_string(value)
         if Type::Refined.ruby_numeric_literal?(value)
           NUMERIC_STRING
@@ -133,8 +132,7 @@ module Rigor
       # Called ONLY with the names in {RUNTIME_STRING_CONSTANTS} — Rigor's own source — and only
       # while this file is being loaded. It is never handed a name from the analysed program.
       #
-      # @param name [String] a qualified constant path without a leading "::"
-      # @return [String, nil]
+      # @param name — a qualified constant path without a leading "::"
       def self.runtime_string_value(name)
         mod = ::Object
         name.split("::").each do |part|
@@ -161,7 +159,7 @@ module Rigor
       end
       private_class_method :runtime_string_value
 
-      # @return [Hash{String => Rigor::Type}] frozen, built once at load time.
+      # @return frozen, built once at load time.
       def self.build_runtime_string_refinements
         RUNTIME_STRING_CONSTANTS.each_with_object({}) do |name, table|
           value = runtime_string_value(name)
@@ -175,9 +173,9 @@ module Rigor
 
       # --- public API ---------------------------------------------------
 
-      # @param name [String] unqualified constant name (e.g. `"Math::PI"`,
+      # @param name — unqualified constant name (e.g. `"Math::PI"`,
       #   `"RUBY_VERSION"`, `"Ruby::ENGINE"`)
-      # @return [Rigor::Type, nil] refined type, or nil to fall through
+      # @return refined type, or nil to fall through
       def self.lookup(name)
         FOLDED_CONSTANTS[name] || RUNTIME_STRING_REFINEMENTS[name]
       end

data/lib/rigor/builtins/regex_refinement.rb

@@ -62,11 +62,11 @@ module Rigor
 
       module_function
 
-      # @param body [String, nil] a regex sub-pattern, typically the inner body of a
+      # @param body — a regex sub-pattern, typically the inner body of a
       #   `(?<name>body)` named capture. Anchors (`\A`, `\z`, `^`, `$`) are not stripped — the
       #   recogniser table targets bodies that the regex engine treats as anchored to the
       #   capture group bounds.
-      # @return [Rigor::Type, nil] the matching imported refinement carrier, or `nil` if
+      # @return the matching imported refinement carrier, or `nil` if
       #   `body` is not a recognised shape.
       def for_capture_body(body)
         return nil if body.nil? || body.empty?
@@ -100,8 +100,8 @@ module Rigor
       # free-whitespace/`#`-comment flag from the `source` alone, so consumers bail on it before
       # calling here.
       #
-      # @param source [String, nil] the full regex source string.
-      # @return [Rigor::Type, nil] the matching imported refinement carrier, or `nil`.
+      # @param source — the full regex source string.
+      # @return the matching imported refinement carrier, or `nil`.
       def for_whole_pattern(source)
         return nil if source.nil?
         return nil unless source.start_with?('\A') && source.end_with?('\z')

data/lib/rigor/builtins/static_return_refinements.rb

@@ -97,16 +97,15 @@ module Rigor
 
       # Looks up a refined return type for the given call.
       #
-      # @param owner_class_name [String, nil] the class on which the method is defined
+      # @param owner_class_name — the class on which the method is defined
       #   (e.g., `"Kernel"`). Pass `nil` when the caller hasn't resolved a defining owner
       #   yet — the lookup will then fall back to matching by `(method_name, kind)` against
       #   entries whose owner is currently in the table.
-      # @param method_name [Symbol]
-      # @param kind [Symbol] one of `:singleton`, `:instance`. The caller passes the shape of
+      # @param kind — one of `:singleton`, `:instance`. The caller passes the shape of
       #   the actual call site; the table stores `:both` for entries that match either.
-      # @param arg_types [Array<Rigor::Type>] positional argument types. Forwarded to the
+      # @param arg_types — positional argument types. Forwarded to the
       #   handler so future entries can discriminate on argument shape.
-      # @return [Rigor::Type, nil] the refined return type, or `nil` when no override
+      # @return the refined return type, or `nil` when no override
       #   matches.
       def self.lookup(owner_class_name:, method_name:, kind:, arg_types: [])
         return nil if owner_class_name.nil?
@@ -127,7 +126,7 @@ module Rigor
       end.freeze
       private_constant :OWNERS_BY_METHOD
 
-      # @return [Array<String>] the candidate owner class names for a bare method-name
+      # @return the candidate owner class names for a bare method-name
       #   lookup. Empty when no override names this method.
       NO_OWNERS = [].freeze
       private_constant :NO_OWNERS

data/lib/rigor/cache/annotation_location.rb

@@ -41,8 +41,7 @@ module Rigor
 
       module_function
 
-      # @param location [RBS::Location, nil]
-      # @return [Array, nil] `[name, start_line, start_column, end_line, end_column]`, or nil when there is
+      # @return `[name, start_line, start_column, end_line, end_column]`, or nil when there is
       #   no location to carry. Fail-soft: a location whose buffer cannot answer is dumped as nil rather
       #   than failing the whole environment's dump.
       def dump(location)
@@ -55,8 +54,7 @@ module Rigor
         nil
       end
 
-      # @param payload [Array, nil] what {dump} produced.
-      # @return [RBS::Location, nil]
+      # @param payload — what {dump} produced.
       def load(payload)
         return nil if payload.nil?
 

data/lib/rigor/cache/descriptor.rb

@@ -48,7 +48,12 @@ module Rigor
       # added to a schema-less project) invalidates the warm entry. A pre-8 entry carries no absence rows
       # and would validate fresh across exactly that edit, so cached entries must read as misses once and
       # rebuild carrying the rows.
-      SCHEMA_VERSION = 8
+      # v9: #979 — the run-result dependency descriptor now carries a names-only {GlobEntry} directory
+      # listing per RBS signature root, so a `.rbs` file APPEARING under one (a `sig/roles.rbs` declaring the
+      # interface a `conforms-to` names) invalidates the warm entry. A pre-9 entry carries no signature-root
+      # row and would validate fresh across exactly that edit — the #577 reasoning, one slot over — so cached
+      # entries must read as misses once and rebuild carrying the rows.
+      SCHEMA_VERSION = 9
 
       # Per-slot entry value objects. Constructors validate enums / required fields and freeze the resulting
       # struct so no caller can mutate after the entry is in a Descriptor.
@@ -114,7 +119,7 @@ module Rigor
           new(path: path, comparator: :exists, value: PRESENT)
         end
 
-        # @return [Boolean] whether this row records the path as absent (see {.absent}).
+        # @return whether this row records the path as absent (see {.absent}).
         def absent?
           comparator == :exists && value == ABSENT
         end
@@ -235,31 +240,58 @@ module Rigor
         FIELD_SEPARATOR = "\0"
         private_constant :ROW_SEPARATOR, :FIELD_SEPARATOR
 
+        # `:stat` is the ADR-87 WD2 signature above — it answers "did anything under this glob change",
+        # appearance and edit alike. `:names` (#979) answers only "did the SET of matching paths change":
+        # its rows are the sorted relative names, so a file whose bytes are unchanged never moves the
+        # signature however its stat tuple moved. A row exists to catch appearance/disappearance only —
+        # edits to the files it lists are already carried by their own `:stat` {FileEntry} rows — and a
+        # names row must therefore survive what those rows survive. A `:stat` glob over a signature tree
+        # would not: ADR-87 WD1 lets a `:stat` file row fall back to its recorded content digest when the
+        # tuple moves, so a `git checkout`, a `bundle install` or a CI cache restored over a fresh checkout
+        # keeps the file rows fresh while it would move every glob signature, turning every such run into a
+        # full re-analysis. `:names` also reads no stat at all, so it costs a `Dir.glob` and nothing else.
+        VALID_MODES = %i[stat names].freeze
+
         attr_reader :root, :pattern, :value
 
-        value_fields :root, :pattern, :value
+        value_fields :root, :pattern, :mode, :value
+
+        def initialize(root:, pattern:, value:, mode: :stat)
+          raise ArgumentError, "GlobEntry mode must be one of #{VALID_MODES.inspect}, got #{mode.inspect}" \
+            unless VALID_MODES.include?(mode)
 
-        def initialize(root:, pattern:, value:)
           @root = root.to_s.dup.freeze
           @pattern = pattern.to_s.dup.freeze
+          @mode = mode
           @value = value.to_s.dup.freeze
           freeze
         end
 
+        # Defaulted rather than an `attr_reader` because an entry Marshal-loaded from a store written before
+        # the field existed carries no `@mode` ivar; every such entry was recorded under the stat signature.
+        def mode
+          @mode || :stat
+        end
+
         # Builds the entry for the glob's CURRENT filesystem state.
-        def self.compute(root:, pattern:)
-          new(root: root, pattern: pattern, value: signature_for(root: root, pattern: pattern))
+        def self.compute(root:, pattern:, mode: :stat)
+          new(root: root, pattern: pattern, mode: mode,
+              value: signature_for(root: root, pattern: pattern, mode: mode))
         end
 
         # The aggregate signature the entry's `value` carries: SHA-256 over the sorted per-file rows. In the
         # default (`:stat`) mode a row is the file's `(path, size, mtime_ns, ctime_ns, inode)` tuple — NO
         # content read; in strict mode a row is `(path, content-sha256)`, restoring the pre-ADR-87 authority.
+        # In `:names` mode a row is the path alone, stat-free, so only the matching SET moves the signature.
         # Per-file stat failures (a file vanishing between the glob and the stat) drop the row — same race
         # posture as {Descriptor#file_entry_fresh?}. `Dir.glob` returns sorted entries by default so the row
         # order — and therefore the signature — is stable.
-        def self.signature_for(root:, pattern:)
+        def self.signature_for(root:, pattern:, mode: :stat)
+          paths = Dir.glob(File.join(root, pattern))
+          return Digest::SHA256.hexdigest(paths.map { |path| "#{path}#{ROW_SEPARATOR}" }.join) if mode == :names
+
           strict = FileDigest.strict_validation?
-          rows = Dir.glob(File.join(root, pattern)).filter_map do |path|
+          rows = paths.filter_map do |path|
             st = File.stat(path)
             next nil unless st.file?
 
@@ -276,23 +308,30 @@ module Rigor
         end
 
         # ADR-87 WD2 — fresh iff re-globbing + re-stat-ing reproduces the recorded signature. Zero file-content
-        # bytes are read in the default mode. Any failure reads as stale (recompute), never a crash. A stored
-        # signature recorded under the opposite validation mode simply mismatches and recomputes.
+        # bytes are read in the default mode, and no stat at all in `:names`. Any failure reads as stale
+        # (recompute), never a crash. A stored signature recorded under the opposite validation mode simply
+        # mismatches and recomputes.
         def self.fresh?(entry)
-          signature_for(root: entry.root, pattern: entry.pattern) == entry.value
+          signature_for(root: entry.root, pattern: entry.pattern, mode: entry.mode) == entry.value
         rescue StandardError
           false
         end
 
-        # Composition key — {.compose} unions per (root, pattern) slot; two contributions for the same slot
-        # must agree on the value or {Conflict} is raised. Within one run the same glob stat-reads identically,
-        # so contributions never conflict.
+        # Composition key — {.compose} unions per (root, pattern, mode) slot; two contributions for the same
+        # slot must agree on the value or {Conflict} is raised. Within one run the same glob stat-reads
+        # identically, so contributions never conflict. The mode is part of the key because the two signatures
+        # over one (root, pattern) are different questions, not rival answers to the same one.
         def slot_key
-          "#{root}\0#{pattern}"
+          "#{root}\0#{pattern}\0#{mode}"
         end
 
         def to_h
-          { "root" => root, "pattern" => pattern, "value" => value }
+          h = { "root" => root, "pattern" => pattern, "value" => value }
+          # Omitted in the default mode so a descriptor carrying only stat globs keeps its pre-#979 canonical
+          # bytes: this FIELD moves no producer's key. (Every key still moved once with SCHEMA_VERSION 9,
+          # which the storage layer mixes in; that is the #979 migration, not the mode.)
+          h["mode"] = mode.to_s unless mode == :stat
+          h
         end
       end
 
@@ -352,9 +391,8 @@ module Rigor
             dependencies: dependencies, globs: globs)
       end
 
-      # @param producer_id [String]
-      # @param params [Hash] inputs the producer was called with
-      # @return [String] hex SHA-256 cache key for the value
+      # @param params — inputs the producer was called with
+      # @return hex SHA-256 cache key for the value
       def cache_key_for(producer_id:, params: {})
         payload = {
           "schema_version" => SCHEMA_VERSION,
@@ -377,7 +415,7 @@ module Rigor
           "dependencies" => sort_entries(dependencies, "gem_name").map(&:to_h),
           "files" => sort_entries(files, "path").map(&:to_h),
           "gems" => sort_entries(gems, "name").map(&:to_h),
-          "globs" => globs.sort_by { |e| [e.root, e.pattern] }.map(&:to_h),
+          "globs" => globs.sort_by { |e| [e.root, e.pattern, e.mode.to_s] }.map(&:to_h),
           "plugins" => sort_entries(plugins, "id").map(&:to_h)
         }
       end

data/lib/rigor/cache/engine_source.rb

@@ -65,15 +65,15 @@ module Rigor
 
       module_function
 
-      # @return [String] the gem root — the directory holding `lib/`, three levels above this file.
+      # @return the gem root — the directory holding `lib/`, three levels above this file.
       def root
         @root ||= File.expand_path("../../..", __dir__)
       end
 
-      # @param root [String] the gem root, defaulted through {.root} so a spec can relocate the tree.
-      # @return [String, nil] a digest identifying the engine's current source, or nil when the tree is
+      # @param root — the gem root, defaulted through {.root} so a spec can relocate the tree.
+      # @return a digest identifying the engine's current source, or nil when the tree is
       #   version-pinned and the caller should add no slot at all.
-      # @raise [Unavailable] when a mutable tree's source cannot be read.
+      # @raise Unavailable — when a mutable tree's source cannot be read.
       def identity(root = self.root)
         return nil if version_pinned?(root)
 

data/lib/rigor/cache/file_digest.rb

@@ -74,7 +74,7 @@ module Rigor
         memo[path] ||= Digest::SHA256.file(path).hexdigest
       end
 
-      # @return [Boolean] whether digest-always validation is forced for this run. The env var wins over the
+      # @return whether digest-always validation is forced for this run. The env var wins over the
       #   run-scoped config flag so an operator can bypass the stat tier without editing `.rigor.yml`.
       def self.strict_validation?
         return true if ENV[STRICT_ENV] == "1"
@@ -112,6 +112,14 @@ module Rigor
         hexdigest(path) == digest
       end
 
+      # The content-digest field of a packed `:stat` entry ({.pack_stat}); nil when the entry is absent or not
+      # well-formed. Exposed for the caller that must compare the recorded digest against bytes it hashes
+      # itself rather than against the file on disk — the incremental session's editor-mode freshness check,
+      # whose authority is the editor's buffer.
+      def self.content_digest(packed)
+        parse_stat(packed)&.first
+      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