rigortype 0.2.7 → 0.2.8

data/lib/rigor/builtins/regex_refinement.rb

@@ -4,24 +4,20 @@ require_relative "../type"
 
 module Rigor
   module Builtins
-    # Maps a curated table of canonical regex sub-patterns onto the
-    # imported refinement carriers Rigor already ships
-    # (`decimal-int-string`, `hex-int-string`, `octal-int-string`,
-    # `lowercase-string`, `uppercase-string`, `numeric-string`).
-    # See `docs/type-specification/imported-built-in-types.md` for
-    # the registry the refinements come from and `docs/ROADMAP.md`
-    # § "v0.1.1 — Planned" Track 1 slice 1 for the binding scope of
-    # this recogniser.
+    # Maps a curated table of canonical regex sub-patterns onto the imported refinement
+    # carriers Rigor already ships (`decimal-int-string`, `hex-int-string`,
+    # `octal-int-string`, `lowercase-string`, `uppercase-string`, `numeric-string`). See
+    # `docs/type-specification/imported-built-in-types.md` for the registry the refinements
+    # come from and `docs/ROADMAP.md` § "v0.1.1 — Planned" Track 1 slice 1 for the binding
+    # scope of this recogniser.
     #
-    # The intended consumer is `Inference::Narrowing.analyse_match_write`:
-    # given `if /(?<year>\d+)/ =~ str; year; end`, the v0.1.0
-    # baseline narrows `year` to plain `String`; v0.1.1 introspects
-    # the regex source and narrows further to
-    # `decimal-int-string` whenever the named-capture body matches
-    # one of the rows in {RULES}.
+    # The intended consumer is `Inference::Narrowing.analyse_match_write`: given `if
+    # /(?<year>\d+)/ =~ str; year; end`, the v0.1.0 baseline narrows `year` to plain `String`;
+    # v0.1.1 introspects the regex source and narrows further to `decimal-int-string`
+    # whenever the named-capture body matches one of the rows in {RULES}.
     #
-    # Recognised body shapes (each row admits the `+` quantifier
-    # and the bounded `{n}` / `{n,m}` forms with `n >= 1`):
+    # Recognised body shapes (each row admits the `+` quantifier and the bounded `{n}` /
+    # `{n,m}` forms with `n >= 1`):
     #
     #   - `\d`                     -> decimal-int-string
     #   - `\h`                     -> hex-int-string
@@ -32,25 +28,20 @@ module Rigor
     #   - `[A-Z]`                  -> uppercase-string
     #   - `[[:digit:]]`            -> numeric-string
     #
-    # Anything outside the table returns `nil` so the calling
-    # narrowing site falls back to its previous behaviour
-    # (plain `String`). Arbitrary regex semantic equivalence is
-    # undecidable, so the table is intentionally a small audited
-    # set of canonical shapes rather than a general equivalence
-    # checker.
+    # Anything outside the table returns `nil` so the calling narrowing site falls back to
+    # its previous behaviour (plain `String`). Arbitrary regex semantic equivalence is
+    # undecidable, so the table is intentionally a small audited set of canonical shapes
+    # rather than a general equivalence checker.
     module RegexRefinement
-      # `+` (one-or-more) or `{n}` / `{n,m}` (n >= 1, m >= n).
-      # The bound check is enforced separately by
-      # {valid_bounds?} after the structural match succeeds, so
-      # forms like `\d{0,5}` or `\d{5,3}` reject even though they
-      # parse syntactically.
+      # `+` (one-or-more) or `{n}` / `{n,m}` (n >= 1, m >= n). The bound check is enforced
+      # separately by {valid_bounds?} after the structural match succeeds, so forms like
+      # `\d{0,5}` or `\d{5,3}` reject even though they parse syntactically.
       QUANTIFIER_SOURCE = '(?:\+|\{\d+(?:,\d+)?\})'
       private_constant :QUANTIFIER_SOURCE
 
-      # ADR-15 Phase 4b.x — `Ractor.make_shareable` (not `.freeze`)
-      # because the outer Array contains two-element `[Regexp, Symbol]`
-      # rows whose inner Arrays are not frozen by the outer freeze.
-      # A worker Ractor iterating `RULES.find { ... }` would trip
+      # ADR-15 Phase 4b.x — `Ractor.make_shareable` (not `.freeze`) because the outer Array
+      # contains two-element `[Regexp, Symbol]` rows whose inner Arrays are not frozen by the
+      # outer freeze. A worker Ractor iterating `RULES.find { ... }` would trip
       # `Ractor::IsolationError` on the first row access.
       RULES = Ractor.make_shareable([
                                       [/\A\\d#{QUANTIFIER_SOURCE}\z/, :decimal_int_string],
@@ -70,13 +61,12 @@ module Rigor
 
       module_function
 
-      # @param body [String, nil] 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 `body` is not a recognised shape.
+      # @param body [String, nil] 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
+      #   `body` is not a recognised shape.
       def for_capture_body(body)
         return nil if body.nil? || body.empty?
 
@@ -87,11 +77,10 @@ module Rigor
         Type::Combinator.public_send(rule.last)
       end
 
-      # Filters the bounded-quantifier forms to ones whose lower
-      # bound is at least 1 and whose upper bound (if any) is at
-      # least the lower bound. Without this, `\d{0,5}` would be
-      # accepted even though it admits the empty string, which is
-      # not a valid `decimal-int-string`.
+      # Filters the bounded-quantifier forms to ones whose lower bound is at least 1 and
+      # whose upper bound (if any) is at least the lower bound. Without this, `\d{0,5}` would
+      # be accepted even though it admits the empty string, which is not a valid
+      # `decimal-int-string`.
       def valid_bounds?(body)
         m = BOUND_RE.match(body)
         return true if m.nil?

data/lib/rigor/builtins/static_return_refinements.rb

@@ -4,46 +4,35 @@ require_relative "../type"
 
 module Rigor
   module Builtins
-    # Static return-type refinements for stdlib (or other built-in)
-    # methods whose upstream RBS signature is broader than the
-    # method's documented behaviour and where adding a
-    # `%a{rigor:v1:return: ...}` annotation upstream is impractical
-    # (the RBS lives in the vendored `ruby/rbs` submodule).
+    # Static return-type refinements for stdlib (or other built-in) methods whose upstream
+    # RBS signature is broader than the method's documented behaviour and where adding a
+    # `%a{rigor:v1:return: ...}` annotation upstream is impractical (the RBS lives in the
+    # vendored `ruby/rbs` submodule).
     #
-    # This tier sits in `MethodDispatcher.dispatch` between the
-    # HKT-builtin tier (which handles parametric / shape-bearing
-    # returns like `JSON.parse`'s `json::value`) and the RBS
-    # dispatch tier (the canonical lookup). It is consulted only
-    # when the method name and arg shape match an entry in the
-    # table below, so the standard RBS path stays in charge of
-    # every other call.
+    # This tier sits in `MethodDispatcher.dispatch` between the HKT-builtin tier (which
+    # handles parametric / shape-bearing returns like `JSON.parse`'s `json::value`) and the
+    # RBS dispatch tier (the canonical lookup). It is consulted only when the method name and
+    # arg shape match an entry in the table below, so the standard RBS path stays in charge
+    # of every other call.
     #
     # Match policy:
     #
-    # - Entries are keyed by `(owner_class_name, method_name,
-    #   kind)`. `owner_class_name` is the class that *defines*
-    #   the method (e.g., `"Kernel"`), not necessarily the
-    #   receiver's static class — Kernel methods are mixed into
-    #   every non-BasicObject class, so a `__dir__` call on any
-    #   receiver routes here.
-    # - `kind: :both` matches both the singleton-receiver
-    #   shape (`Kernel.__dir__`, `Singleton[Kernel]` receiver)
-    #   AND the instance-receiver shape (an implicit-self call
-    #   like `__dir__` inside any class body, or `obj.__dir__`
-    #   on an instance).
-    # - `kind: :singleton` / `kind: :instance` restrict the
-    #   match to one of the two shapes.
-    # - The handler is called with `(arg_types)` so future
-    #   entries can refine based on argument types (e.g. a
-    #   `File.expand_path(string)` entry that returns
+    # - Entries are keyed by `(owner_class_name, method_name, kind)`. `owner_class_name` is
+    #   the class that *defines* the method (e.g., `"Kernel"`), not necessarily the
+    #   receiver's static class — Kernel methods are mixed into every non-BasicObject class,
+    #   so a `__dir__` call on any receiver routes here.
+    # - `kind: :both` matches both the singleton-receiver shape (`Kernel.__dir__`,
+    #   `Singleton[Kernel]` receiver) AND the instance-receiver shape (an implicit-self call
+    #   like `__dir__` inside any class body, or `obj.__dir__` on an instance).
+    # - `kind: :singleton` / `kind: :instance` restrict the match to one of the two shapes.
+    # - The handler is called with `(arg_types)` so future entries can refine based on
+    #   argument types (e.g. a `File.expand_path(string)` entry that returns
     #   `non-empty-string` regardless of the upstream return).
     #
-    # The override fires ABOVE RBS dispatch — if RBS would have
-    # returned a wider type (`String?` for `Kernel#__dir__`), the
-    # override returns the refined union (`non-empty-string | nil`)
-    # instead. RBS erasure of the refined return goes back to the
-    # original upstream shape, so downstream RBS-shaped observers
-    # see no difference.
+    # The override fires ABOVE RBS dispatch — if RBS would have returned a wider type
+    # (`String?` for `Kernel#__dir__`), the override returns the refined union
+    # (`non-empty-string | nil`) instead. RBS erasure of the refined return goes back to the
+    # original upstream shape, so downstream RBS-shaped observers see no difference.
     module StaticReturnRefinements
       # Pre-built carrier reused across calls so structural
       # equality matches across analyzer invocations.
@@ -56,35 +45,29 @@ module Rigor
       NON_EMPTY_STRING = Type::Combinator.non_empty_string.freeze
       private_constant :NON_EMPTY_STRING
 
-      # `Kernel#__dir__` returns the canonical directory of the
-      # source file the call appears in, or `nil` when the file
-      # is invalid / not available (typically `-e` and similar
-      # one-liner contexts). When non-nil the value is always a
-      # filesystem-canonical path — never the empty string — so
-      # `non-empty-string` is exact.
+      # `Kernel#__dir__` returns the canonical directory of the source file the call appears
+      # in, or `nil` when the file is invalid / not available (typically `-e` and similar
+      # one-liner contexts). When non-nil the value is always a filesystem-canonical path —
+      # never the empty string — so `non-empty-string` is exact.
       KERNEL_DIR = ->(_arg_types) { NON_EMPTY_STRING_OR_NIL }
       private_constant :KERNEL_DIR
 
-      # `File.expand_path(path, ?dir_string)` always returns an
-      # absolute path string. Even `File.expand_path("")` expands
-      # to the current working directory's absolute path. The
-      # upstream RBS row is `(path file_name, ?path dir_string) ->
-      # String`; the refinement tightens to `non-empty-string`.
-      #
-      # `File.dirname(path, ?level)` always returns at least `"."`
-      # (or `"/"` for absolute roots), so the return is never the
-      # empty string. Upstream RBS returns `String`; the refinement
+      # `File.expand_path(path, ?dir_string)` always returns an absolute path string. Even
+      # `File.expand_path("")` expands to the current working directory's absolute path. The
+      # upstream RBS row is `(path file_name, ?path dir_string) -> String`; the refinement
       # tightens to `non-empty-string`.
       #
-      # `File.basename` is intentionally NOT refined: it returns
-      # `""` for `File.basename("")`, so `non-empty-string` would
-      # be unsound.
+      # `File.dirname(path, ?level)` always returns at least `"."` (or `"/"` for absolute
+      # roots), so the return is never the empty string. Upstream RBS returns `String`; the
+      # refinement tightens to `non-empty-string`.
+      #
+      # `File.basename` is intentionally NOT refined: it returns `""` for
+      # `File.basename("")`, so `non-empty-string` would be unsound.
       FILE_NON_EMPTY = ->(_arg_types) { NON_EMPTY_STRING }
       private_constant :FILE_NON_EMPTY
 
-      # Frozen ((owner_class_name, method_name, kind) => handler)
-      # table. The kind tag is `:both`, `:singleton`, or
-      # `:instance`. New entries SHOULD prefer `:both` unless the
+      # Frozen ((owner_class_name, method_name, kind) => handler) table. The kind tag is
+      # `:both`, `:singleton`, or `:instance`. New entries SHOULD prefer `:both` unless the
       # singleton- and instance-side shapes genuinely differ.
       OVERRIDES = {
         ["Kernel", :__dir__, :both] => KERNEL_DIR,
@@ -95,21 +78,17 @@ 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 (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 owner_class_name [String, nil] 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 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 handler so future entries can
-      #   discriminate on argument shape.
-      # @return [Rigor::Type, nil] the refined return type, or
-      #   `nil` when no override matches.
+      # @param kind [Symbol] 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
+      #   handler so future entries can discriminate on argument shape.
+      # @return [Rigor::Type, nil] 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?
 
@@ -119,27 +98,24 @@ module Rigor
         handler&.call(arg_types)
       end
 
-      # Indexed view by `(method_name, kind)` — used by the
-      # dispatcher when the receiver's owner is not yet resolved
-      # but the method name alone uniquely identifies a stdlib
-      # override (today: `__dir__` → Kernel). The table is small
-      # and the index rebuild cost trivial, but precomputing keeps
-      # `dispatch`'s hot path free of an O(n) scan.
+      # Indexed view by `(method_name, kind)` — used by the dispatcher when the receiver's
+      # owner is not yet resolved but the method name alone uniquely identifies a stdlib
+      # override (today: `__dir__` → Kernel). The table is small and the index rebuild cost
+      # trivial, but precomputing keeps `dispatch`'s hot path free of an O(n) scan.
       OWNERS_BY_METHOD = OVERRIDES.each_with_object({}) do |((owner, mname, _kind), _h), acc|
         acc[mname] ||= []
         acc[mname] << owner unless acc[mname].include?(owner)
       end.freeze
       private_constant :OWNERS_BY_METHOD
 
-      # @return [Array<String>] the candidate owner class names
-      #   for a bare method-name lookup. Empty when no override
-      #   names this method.
+      # @return [Array<String>] 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
 
-      # Consulted on every dispatch (`try_static_refinement`); the miss
-      # case is overwhelmingly common, so share one frozen empty array
-      # instead of allocating a fresh `[]` per non-refined method.
+      # Consulted on every dispatch (`try_static_refinement`); the miss case is overwhelmingly
+      # common, so share one frozen empty array instead of allocating a fresh `[]` per
+      # non-refined method.
       def self.owners_for(method_name)
         OWNERS_BY_METHOD[method_name.to_sym] || NO_OWNERS
       end

data/lib/rigor/cache/descriptor.rb

@@ -8,40 +8,28 @@ module Rigor
   module Cache
     # Cache invalidation descriptor — the typed-slot schema fixed by
     # [`docs/design/20260505-cache-slice-taxonomy.md`](../../../docs/design/20260505-cache-slice-taxonomy.md).
-    # Pure value object: no I/O, no global state, fully immutable
-    # after construction. The storage layer
-    # ([`Rigor::Cache::Store`](store.rb), v0.0.8 slice 2) consumes
-    # descriptors but does not extend them.
+    # Pure value object: no I/O, no global state, fully immutable after construction. The storage layer
+    # ([`Rigor::Cache::Store`](store.rb), v0.0.8 slice 2) consumes descriptors but does not extend them.
     #
-    # The descriptor has six slots (`files`, `gems`, `plugins`,
-    # `configs`, `dependencies`, `globs`); every slot is an array of typed entries; an empty
-    # array means "no dependency in this slot". Composition unions
-    # by key per slot; conflicts on the comparison fields raise
-    # {Conflict}.
+    # The descriptor has six slots (`files`, `gems`, `plugins`, `configs`, `dependencies`, `globs`); every slot is
+    # an array of typed entries; an empty array means "no dependency in this slot". Composition unions by key per
+    # slot; conflicts on the comparison fields raise {Conflict}.
     #
-    # See ADR-2 § "Registration, Configuration, and Caching" for
-    # the design rationale and ADR-6 for the storage backend
-    # decisions that consume this schema.
+    # See ADR-2 § "Registration, Configuration, and Caching" for the design rationale and ADR-6 for the storage
+    # backend decisions that consume this schema.
     class Descriptor
-      # Bumped on incompatible schema changes. The storage layer
-      # mixes this into the cache key, so a bump implicitly
-      # invalidates every cached value. v2 added the
-      # `dependencies` slot for ADR-10 per-gem-version cache slice
-      # invalidation. v3: `RbsLoader.build_env_for` now synthesizes
-      # `module`s for namespaces a project's `signature_paths:` RBS
-      # references but never declares, so the marshalled RBS env
-      # cached by an older Rigor (which would leave those signatures
-      # inert) MUST be rebuilt for the synthesis to take effect.
-      # v4: ADR-60 WD3 added the `globs` slot ({GlobEntry}) for the
-      # record-and-validate plugin-producer cache; the new slot
-      # changes `#to_canonical_hash` (and is Marshal-dumped inside
-      # `fetch_or_validate` entry pairs), so entries written by an
-      # older Rigor must read as misses.
+      # Bumped on incompatible schema changes. The storage layer mixes this into the cache key, so a bump
+      # implicitly invalidates every cached value. v2 added the `dependencies` slot for ADR-10 per-gem-version
+      # cache slice invalidation. v3: `RbsLoader.build_env_for` now synthesizes `module`s for namespaces a
+      # project's `signature_paths:` RBS references but never declares, so the marshalled RBS env cached by an
+      # older Rigor (which would leave those signatures inert) MUST be rebuilt for the synthesis to take effect.
+      # v4: ADR-60 WD3 added the `globs` slot ({GlobEntry}) for the record-and-validate plugin-producer cache;
+      # the new slot changes `#to_canonical_hash` (and is Marshal-dumped inside `fetch_or_validate` entry
+      # pairs), so entries written by an older Rigor must read as misses.
       SCHEMA_VERSION = 4
 
-      # 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.
+      # 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.
 
       class FileEntry
         include Rigor::ValueSemantics
@@ -125,20 +113,14 @@ module Rigor
         end
       end
 
-      # Per-(gem, version, mode) row carrying the cache slice
-      # boundary for ADR-10 dependency-source inference. A
-      # `bundle update` that bumps a listed gem's pinned version
-      # produces a different `gem_version` here and therefore a
-      # fresh cache key — invalidating exactly that gem's slice
-      # without disturbing other gems' slices or the project's
-      # own cache.
+      # Per-(gem, version, mode) row carrying the cache slice boundary for ADR-10 dependency-source inference.
+      # A `bundle update` that bumps a listed gem's pinned version produces a different `gem_version` here and
+      # therefore a fresh cache key — invalidating exactly that gem's slice without disturbing other gems'
+      # slices or the project's own cache.
       #
-      # `mode` mirrors the
-      # [Configuration::Dependencies::VALID_MODES](../configuration/dependencies.rb)
-      # enum (`:disabled` / `:when_missing` / `:full`); a mode
-      # change for the same gem also forces invalidation because
-      # the inferred shapes depend on whether RBS overrides the
-      # walk.
+      # `mode` mirrors the [Configuration::Dependencies::VALID_MODES](../configuration/dependencies.rb) enum
+      # (`:disabled` / `:when_missing` / `:full`); a mode change for the same gem also forces invalidation
+      # because the inferred shapes depend on whether RBS overrides the walk.
       class DependencyEntry
         include Rigor::ValueSemantics
 
@@ -165,14 +147,11 @@ module Rigor
         end
       end
 
-      # ADR-60 WD3 — one glob's-worth of watched files, digested as a
-      # single value so the entry covers content change, addition,
-      # AND removal in one row: the digest is the SHA-256 over the
-      # sorted `"<path>\0<sha256-of-content>\n"` rows of every file
-      # matching `File.join(root, pattern)`. A new file adds a row, a
-      # deleted file drops one, an edit changes one — all three move
-      # the digest. {Descriptor#fresh?} re-runs the same computation
-      # and compares.
+      # ADR-60 WD3 — one glob's-worth of watched files, digested as a single value so the entry covers content
+      # change, addition, AND removal in one row: the digest is the SHA-256 over the sorted
+      # `"<path>\0<sha256-of-content>\n"` rows of every file matching `File.join(root, pattern)`. A new file
+      # adds a row, a deleted file drops one, an edit changes one — all three move the digest.
+      # {Descriptor#fresh?} re-runs the same computation and compares.
       class GlobEntry
         include Rigor::ValueSemantics
 
@@ -192,13 +171,12 @@ module Rigor
           new(root: root, pattern: pattern, value: digest_for(root: root, pattern: pattern))
         end
 
-        # The digest the entry's `value` carries. Per-file read
-        # failures (a file vanishing between the glob and the
-        # digest) are treated as the file being absent — same
-        # race posture as {Descriptor#file_entry_fresh?}.
+        # The digest the entry's `value` carries. Per-file read failures (a file vanishing between the glob and
+        # the digest) are treated as the file being absent — same race posture as
+        # {Descriptor#file_entry_fresh?}.
         def self.digest_for(root:, pattern:)
-          # Dir.glob returns sorted entries by default (sort: true),
-          # so the row order — and therefore the digest — is stable.
+          # Dir.glob returns sorted entries by default (sort: true), so the row order — and therefore the
+          # digest — is stable.
           rows = Dir.glob(File.join(root, pattern)).filter_map do |path|
             next nil unless File.file?(path)
 
@@ -209,9 +187,8 @@ module Rigor
           Digest::SHA256.hexdigest(rows.join)
         end
 
-        # Composition key — {.compose} unions per (root, pattern)
-        # slot; two contributions for the same slot must agree on
-        # the digest or {Conflict} is raised.
+        # Composition key — {.compose} unions per (root, pattern) slot; two contributions for the same slot
+        # must agree on the digest or {Conflict} is raised.
         def slot_key
           "#{root}\0#{pattern}"
         end
@@ -221,11 +198,9 @@ module Rigor
         end
       end
 
-      # Raised when {.compose} encounters incompatible entries
-      # under the same key (file digest mismatch, gem-locked
-      # disagreement, …). Callers handle the exception by
-      # invalidating the cache slice rather than choosing one
-      # contribution silently.
+      # Raised when {.compose} encounters incompatible entries under the same key (file digest mismatch,
+      # gem-locked disagreement, …). Callers handle the exception by invalidating the cache slice rather than
+      # choosing one contribution silently.
       class Conflict < StandardError; end
 
       attr_reader :files, :gems, :plugins, :configs, :dependencies, :globs
@@ -240,17 +215,13 @@ module Rigor
         freeze
       end
 
-      # ADR-45 — re-validates this descriptor's recorded {FileEntry}s
-      # against the current filesystem. Used by the record-and-validate
-      # run-result cache: a value cached alongside its dependency
-      # descriptor is fresh iff every recorded file still matches. Only
-      # `files` are checked — non-file inputs (config / gems / version)
-      # belong in the cache *key*, not the validated dependency set — so
-      # a descriptor carrying any non-file slot is never considered fresh
-      # (it was built wrong for this use). ADR-60 WD3 adds `globs`
-      # alongside `files` as a re-validatable slot: a {GlobEntry} is
-      # fresh when re-globbing + re-digesting reproduces its recorded
-      # value.
+      # ADR-45 — re-validates this descriptor's recorded {FileEntry}s against the current filesystem. Used by
+      # the record-and-validate run-result cache: a value cached alongside its dependency descriptor is fresh
+      # iff every recorded file still matches. Only `files` are checked — non-file inputs (config / gems /
+      # version) belong in the cache *key*, not the validated dependency set — so a descriptor carrying any
+      # non-file slot is never considered fresh (it was built wrong for this use). ADR-60 WD3 adds `globs`
+      # alongside `files` as a re-validatable slot: a {GlobEntry} is fresh when re-globbing + re-digesting
+      # reproduces its recorded value.
       def fresh?
         return false unless gems.empty? && plugins.empty? && configs.empty? && dependencies.empty?
 
@@ -258,18 +229,15 @@ module Rigor
           globs.all? { |entry| glob_entry_fresh?(entry) }
       end
 
-      # File-comparator strictness ordering. `:digest` is strictest
-      # (deterministic across machines); `:mtime` is cheaper but
-      # local; `:exists` is the weakest signal. When two
-      # contributors disagree on the comparator for the same
-      # `path`, the stricter one wins.
+      # File-comparator strictness ordering. `:digest` is strictest (deterministic across machines); `:mtime`
+      # is cheaper but local; `:exists` is the weakest signal. When two contributors disagree on the
+      # comparator for the same `path`, the stricter one wins.
       COMPARATOR_STRICTNESS = { digest: 2, mtime: 1, exists: 0 }.freeze
       private_constant :COMPARATOR_STRICTNESS
 
-      # Composes any number of descriptors into a single descriptor
-      # whose slots are the union of the inputs' slots. Conflicts
-      # raise {Conflict}; idempotent contributions (same key, same
-      # value) collapse to a single entry.
+      # Composes any number of descriptors into a single descriptor whose slots are the union of the inputs'
+      # slots. Conflicts raise {Conflict}; idempotent contributions (same key, same value) collapse to a
+      # single entry.
       def self.compose(*descriptors)
         return new if descriptors.empty?
 
@@ -296,9 +264,8 @@ module Rigor
         Digest::SHA256.hexdigest(JSON.generate(payload))
       end
 
-      # Canonical UTF-8 JSON serialisation. Slots appear in
-      # lexicographic order; entries are sorted by their key field
-      # so two equivalent descriptors produce identical bytes.
+      # Canonical UTF-8 JSON serialisation. Slots appear in lexicographic order; entries are sorted by their
+      # key field so two equivalent descriptors produce identical bytes.
       def to_canonical_bytes
         JSON.generate(to_canonical_hash).b
       end
@@ -325,10 +292,8 @@ module Rigor
       end
 
       class << self
-        # Recursively coerces a Ruby value into a JSON-canonical
-        # structure: hash keys are stringified and sorted; arrays
-        # preserve order; symbols stringify; everything else is
-        # JSON-renderable.
+        # Recursively coerces a Ruby value into a JSON-canonical structure: hash keys are stringified and
+        # sorted; arrays preserve order; symbols stringify; everything else is JSON-renderable.
         def canonicalize_value(value)
           case value
           when Hash
@@ -360,9 +325,8 @@ module Rigor
         false
       end
 
-      # ADR-60 WD3 — re-runs the entry's glob + digest and compares
-      # against the recorded value. Any failure reads as stale
-      # (recompute), never a crash.
+      # ADR-60 WD3 — re-runs the entry's glob + digest and compares against the recorded value. Any failure
+      # reads as stale (recompute), never a crash.
       def glob_entry_fresh?(entry)
         GlobEntry.digest_for(root: entry.root, pattern: entry.pattern) == entry.value
       rescue StandardError