rigortype 0.1.19 → 0.2.1

data/lib/rigor/protection/mutator.rb

@@ -0,0 +1,267 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "../scope"
+require_relative "../inference/scope_indexer"
+
+module Rigor
+  # ADR-63 Tier 2 — the productized subset of the dev-only mutation-testing
+  # harness (`tool/mutation/`, ADR-62). Only the *per-file effectiveness
+  # measurement* lives here — the type-visible {Mutator} and the warm-loop
+  # {MutationScanner} kill-rate measurement. The dev sweep / fuzz / survivor
+  # clustering stay off the frozen surface in `tool/mutation/mutate.rb`
+  # (which now reuses this {Mutator} so there is one source of truth).
+  module Protection
+    # One concrete edit: replace source bytes [start, stop) with `replacement`.
+    # `anchor` is the Prism node whose inferred type decides type-relevance —
+    # the call receiver whose contract the mutation could violate, or nil when
+    # there is no concrete receiver (implicit-self call, literal outside a call).
+    # `anchor_type` (the rendered receiver type) and `method_name` are filled in
+    # for reporting a surviving site; both may stay nil.
+    Mutation = Struct.new(
+      :operator, :expected_rule, :start, :stop, :replacement, :line, :label, :anchor,
+      :anchor_type, :method_name,
+      keyword_init: true
+    ) do
+      def apply(source)
+        prefix = source.byteslice(0, start)
+        suffix = source.byteslice(stop, source.bytesize - stop) || ""
+        "#{prefix}#{replacement}#{suffix}"
+      end
+    end
+
+    # Generates type-visible mutations of a Ruby source string by walking the
+    # Prism AST and recording byte-range splices (no unparser needed — Prism
+    # hands us exact offsets, and the analyzer re-parses the spliced source).
+    #
+    # A mutation is "type-visible" when it should trip a diagnostic rule *if*
+    # Rigor holds a type at the site: a call-argument literal dropped to `nil`
+    # or type-swapped (→ `call.argument-type-mismatch`), or a call site renamed
+    # to a missing method (→ `call.undefined-method`). Only call sites and
+    # bodies are mutated, never `def` signatures, so a reused project scan stays
+    # valid.
+    class Mutator
+      IDENT = /\A[a-z_][A-Za-z0-9_]*\z/
+      QUOTES = ['"', "'"].freeze
+      # Mutating an argument to a universal-equality method is always an
+      # equivalent mutant: Ruby's `==` / `<=>` family returns false / nil on a
+      # type mismatch rather than raising, so the engine exempts them
+      # (`UNIVERSAL_EQUALITY_METHODS`). Skip them to keep survivors meaningful.
+      UNIVERSAL_EQUALITY = %w[== != eql? equal? <=>].freeze
+
+      # Every operator the mutator knows. Each maps to the diagnostic rule
+      # family it is *engineered* to trip when the mutated value/call sits in a
+      # context where Rigor has type knowledge.
+      ALL_OPERATORS = %i[nil_inject type_swap undefined_method arity_extra].freeze
+
+      # The default set. `arity_extra` is excluded: most Ruby methods accept an
+      # extra argument (splat / optional), so appending one is usually an
+      # equivalent mutant — it contributes almost only noise. Re-enable it
+      # explicitly via `operators:` to measure arity teeth. (A signature-arity
+      # guard would make it default-worthy — a follow-up.)
+      OPERATORS = %i[nil_inject type_swap undefined_method].freeze
+
+      def initialize(source, operators: OPERATORS)
+        @source = source
+        @operators = operators
+        @parse = Prism.parse(source)
+        @anchor_for = {} # literal node -> its enclosing call's receiver node (or nil)
+      end
+
+      def mutations
+        return [] unless @parse.success?
+
+        index_literal_anchors(@parse.value)
+        out = []
+        walk(@parse.value) { |node| collect(node, out) }
+        out
+      end
+
+      # Phase 1.5 — keep only mutations whose anchor types to a concrete,
+      # non-Dynamic type, i.e. a site where Rigor actually holds a contract the
+      # mutation could violate. Drops implicit-self calls and literals outside a
+      # typed call (no contract → guaranteed survival → noise). FP-safe
+      # direction: an unresolved/probe-failed type KEEPS the mutation, so the
+      # filter never hides a kill it is unsure about — it only removes
+      # provably-Dynamic sites. Returns [kept, dropped_count]. Builds the scope
+      # index from THIS mutator's parse so anchor node identity matches the keys.
+      def filter_by_type(mutations, environment:, path:)
+        base = Rigor::Scope.empty(environment: environment, source_path: path)
+        index = Rigor::Inference::ScopeIndexer.index(@parse.value, default_scope: base)
+        cache = {}
+        kept = mutations.select do |mut|
+          keep, type = anchor_decision(mut.anchor, index, cache)
+          mut.anchor_type = type if keep
+          keep
+        end
+        [kept, mutations.size - kept.size]
+      end
+
+      # ADR-69 Seam 2 (AllSites) — keep every *dispatch-site* mutation (a method
+      # call or a call-argument literal), Dynamic receiver included, annotating
+      # the anchor type where Rigor holds one. Drops only non-dispatch literals
+      # (a literal outside any call — no receiver contract to violate). The
+      # biteable {#filter_by_type} hides exactly the Dynamic sites a test-suite
+      # consumer most wants to probe: where Rigor cannot bite, a test is the only
+      # protection. Use only with a {TestSuiteOracle} — at a Dynamic site the
+      # type pass can never kill, so without the test axis these are all noise.
+      def dispatch_site_mutations(mutations, environment:, path:)
+        base = Rigor::Scope.empty(environment: environment, source_path: path)
+        index = Rigor::Inference::ScopeIndexer.index(@parse.value, default_scope: base)
+        cache = {}
+        mutations.select do |mut|
+          next false if mut.method_name.nil?
+
+          _keep, type = anchor_decision(mut.anchor, index, cache)
+          mut.anchor_type = type
+          true
+        end
+      end
+
+      private
+
+      def walk(node, &blk)
+        return if node.nil?
+
+        blk.call(node)
+        node.compact_child_nodes.each { |child| walk(child, &blk) }
+      end
+
+      def collect(node, out)
+        case node
+        when Prism::IntegerNode, Prism::FloatNode
+          literal_mutations(node, out, numeric: true)
+        when Prism::StringNode
+          literal_mutations(node, out, numeric: false)
+        when Prism::CallNode
+          call_mutations(node, out)
+        end
+      end
+
+      # Record, for each literal that is a direct call argument, the receiver of
+      # the enclosing call — the anchor whose param contract a literal mutation
+      # could violate. Literals elsewhere get a nil anchor (filtered out under
+      # the type filter).
+      def index_literal_anchors(node)
+        return if node.nil?
+
+        if node.is_a?(Prism::CallNode) && node.arguments
+          node.arguments.arguments.each do |arg|
+            @anchor_for[arg] = [node.receiver, node.name.to_s] if literal?(arg)
+          end
+        end
+        node.compact_child_nodes.each { |child| index_literal_anchors(child) }
+      end
+
+      def literal?(node)
+        node.is_a?(Prism::IntegerNode) || node.is_a?(Prism::FloatNode) || node.is_a?(Prism::StringNode)
+      end
+
+      # Returns [keep?, rendered_type]. Keep when `anchor` is a site where Rigor
+      # holds a concrete (non-Dynamic/Top) type. FP-safe: an unresolved or
+      # probe-failed type keeps the mutation (with a nil rendered type).
+      def anchor_decision(anchor, index, cache)
+        return [false, nil] if anchor.nil?
+        return cache[anchor] if cache.key?(anchor)
+
+        cache[anchor] = compute_anchor_decision(anchor, index)
+      end
+
+      def compute_anchor_decision(anchor, index)
+        scope = index[anchor]
+        return [true, nil] if scope.nil? # unresolved scope → keep (FP-safe)
+
+        type = scope.type_of(anchor)
+        return [true, nil] if type.nil?
+
+        concrete = !non_concrete_type?(type)
+        [concrete, concrete ? render_type(type) : nil]
+      rescue StandardError
+        [true, nil] # never let a probe failure hide a candidate
+      end
+
+      # A receiver type Rigor cannot bite on, so a mutation anchored to it would
+      # survive as noise: `Dynamic` / `Top` / `bot`, or a union with any such arm
+      # (gradually valid — `Array | Dynamic[top]`.whatever never fires). A union
+      # of fully-concrete arms (`String | Symbol`) stays concrete — it now has
+      # undefined-method teeth.
+      def non_concrete_type?(type)
+        return true if type.is_a?(Rigor::Type::Dynamic) || type.is_a?(Rigor::Type::Top) ||
+                       type.is_a?(Rigor::Type::Bot)
+        return type.members.any? { |member| non_concrete_type?(member) } if type.is_a?(Rigor::Type::Union)
+
+        false
+      end
+
+      def render_type(type)
+        type.respond_to?(:describe) ? type.describe(:short) : type.to_s
+      rescue StandardError
+        type.class.name
+      end
+
+      # Mutate a literal: drop it to nil (possible-nil channel) and swap its
+      # type (type-mismatch channel). String literals are only touched when the
+      # node is a real quoted string, so we never corrupt `%w[...]` words.
+      def literal_mutations(node, out, numeric:)
+        return if !numeric && !QUOTES.include?(node.opening_loc&.slice)
+
+        anchor, method = @anchor_for[node]
+        return if UNIVERSAL_EQUALITY.include?(method)
+
+        loc = node.location
+        add(out, :nil_inject, "call.argument-type-mismatch", loc.start_offset, loc.end_offset,
+            "nil", loc.start_line, "literal → nil  (#{snippet(loc)})", anchor, method)
+        swap = numeric ? '"rigor_mutant"' : "0"
+        add(out, :type_swap, "call.argument-type-mismatch", loc.start_offset, loc.end_offset,
+            swap, loc.start_line, "literal type swap  (#{snippet(loc)} → #{swap})", anchor, method)
+      end
+
+      def call_mutations(node, out)
+        rename_call(node, out)
+        extend_arity(node, out)
+      end
+
+      # Rename the *call site* (not the def) to a method that cannot exist, so a
+      # typed receiver trips call.undefined-method. We leave `def` signatures
+      # untouched on purpose: the prebuilt ProjectScan still carries the file's
+      # original declarations, so mutating only bodies/call-sites keeps it valid.
+      # Anchor is the explicit receiver (nil ⇒ implicit self ⇒ filtered out, as
+      # call.self-undefined-method ships `:off`).
+      def rename_call(node, out)
+        name = node.name.to_s
+        mloc = node.message_loc
+        return unless mloc && IDENT.match?(name)
+
+        add(out, :undefined_method, "call.undefined-method", mloc.start_offset, mloc.end_offset,
+            "#{name}__rigor_absent", mloc.start_line, "call ##{name} → missing method", node.receiver, name)
+      end
+
+      # Append a trailing argument inside explicit `(...)` parens to trip an
+      # arity diagnostic against a known fixed-arity signature.
+      def extend_arity(node, out)
+        open = node.opening_loc
+        close = node.closing_loc
+        return unless close && open&.slice == "("
+
+        args = node.arguments&.arguments
+        insertion = args && !args.empty? ? ", nil" : "nil"
+        add(out, :arity_extra, "call.wrong-arity", close.start_offset, close.start_offset,
+            insertion, node.location.start_line, "call ##{node.name} +1 arg", node.receiver, node.name.to_s)
+      end
+
+      def add(out, operator, rule, start, stop, replacement, line, label, anchor, method_name) # rubocop:disable Metrics/ParameterLists
+        return unless @operators.include?(operator)
+
+        out << Mutation.new(operator: operator, expected_rule: rule, start: start, stop: stop,
+                            replacement: replacement, line: line, label: label, anchor: anchor,
+                            method_name: method_name)
+      end
+
+      def snippet(loc)
+        text = loc.slice.gsub(/\s+/, " ")
+        text.length > 30 ? "#{text[0, 27]}..." : text
+      end
+    end
+  end
+end

data/lib/rigor/protection/test_suite_oracle.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Protection
+    # ADR-70 — the **test-suite** kill oracle, the dynamic sibling of
+    # {DiagnosticOracle} on the ADR-69 seam. A mutant is killed iff applying its
+    # bytes to the file under test turns the project's test suite **red**. This is
+    # the dynamic half of the fused static∪dynamic protection map: a `Dynamic`
+    # site Rigor cannot bite (a type survivor) may still be fully guarded by a
+    # test.
+    #
+    # The suite command is the **runner hook** (`--test-command`, e.g.
+    # `bundle exec rake`). The runner is injectable so the decision logic is
+    # unit-testable without shelling out; the default shells out and reads the
+    # process exit status (0 = green / passed).
+    #
+    # I/O policy: {#killed?} writes the mutant to disk, runs the suite, and
+    # **always restores** the original bytes in an `ensure` — a normal exception
+    # never leaves a mutant on disk. (A hard interrupt mid-suite is the standard
+    # mutation-testing hazard the `ensure` cannot cover; callers running this in
+    # CI accept that, as `mutant` / Stryker do.)
+    class TestSuiteOracle
+      # @param command [Array<String>] the test command (the runner hook)
+      # @param runner [#call, nil] `runner.call(command) -> true iff the suite
+      #   passed`. Defaults to shelling out via `system`.
+      def initialize(command:, runner: nil)
+        @command = command
+        @runner = runner || method(:shell_run)
+      end
+
+      # The baseline: the suite must pass on clean code, else "a mutant survived"
+      # is meaningless (every mutant would look killed, or none would). Run once
+      # before measuring.
+      def green?
+        @runner.call(@command)
+      end
+
+      # Killed iff the mutant turns the suite red. Restores `original` afterward.
+      # @param path [String] the file to (temporarily) overwrite with the mutant
+      # @param original [String] the clean bytes to restore
+      # @param mutant_source [String] the mutated bytes to test against
+      def killed?(path:, original:, mutant_source:)
+        File.write(path, mutant_source)
+        !@runner.call(@command)
+      ensure
+        File.write(path, original)
+      end
+
+      private
+
+      # Run the suite with Bundler's environment stripped, so a `bundle exec`
+      # test command resolves the **target** project's Gemfile — not whatever
+      # bundle Rigor itself was launched under. Running Rigor via `bundle exec`
+      # leaks `RUBYOPT=-rbundler/setup` + `GEM_HOME` / `BUNDLE_*` into a plain
+      # `system` subprocess, which then resolves the target's Gemfile against
+      # Rigor's gems and fails — so a green suite looks red and the run aborts.
+      # `with_unbundled_env` restores the pre-bundler env (a bare `env -u
+      # BUNDLE_GEMFILE` is not enough — the `BUNDLER_ORIG_*` preservers defeat
+      # it). Found validating ADR-70 on real projects (2026-06-17).
+      def shell_run(command)
+        run = -> { system(*command, out: File::NULL, err: File::NULL) }
+        return run.call unless defined?(Bundler) && Bundler.respond_to?(:with_unbundled_env)
+
+        Bundler.with_unbundled_env(&run)
+      end
+    end
+  end
+end

data/lib/rigor/rbs_extended.rb

@@ -7,43 +7,30 @@ require_relative "rbs_extended/reporter"
 require_relative "rbs_extended/hkt_directives"
 
 module Rigor
-  # Slice 7 phase 15 — first-preview reader for the
-  # `RBS::Extended` annotation surface described in
+  # Reader for the `RBS::Extended` annotation surface described in
   # `docs/type-specification/rbs-extended.md`.
   #
-  # This module reads `%a{rigor:v1:<directive> <payload>}`
-  # annotations off RBS method definitions and returns
-  # well-typed effect objects the inference engine can
-  # consume. v0.0.2 recognises:
+  # Reads `%a{rigor:v1:<directive> <payload>}` annotations off RBS
+  # method definitions and returns well-typed effect objects the
+  # inference engine can consume. Implemented directives:
   #
-  # - `rigor:v1:predicate-if-true <target> is <ClassName>`
-  # - `rigor:v1:predicate-if-false <target> is <ClassName>`
-  # - `rigor:v1:assert <target> is <ClassName>`
-  # - `rigor:v1:assert-if-true <target> is <ClassName>`
-  # - `rigor:v1:assert-if-false <target> is <ClassName>`
+  # - `rigor:v1:predicate-if-true <target> is <ClassName|refinement>`
+  # - `rigor:v1:predicate-if-false <target> is <ClassName|refinement>`
+  # - `rigor:v1:assert <target> is <ClassName|refinement>`
+  # - `rigor:v1:assert-if-true <target> is <ClassName|refinement>`
+  # - `rigor:v1:assert-if-false <target> is <ClassName|refinement>`
+  # - `rigor:v1:param <name> <type-expr>` — per-call param narrowing
+  # - `rigor:v1:return <type-expr>` — per-call return override
+  # - `rigor:v1:conforms-to <InterfaceName>` — structural conformance
   #
-  # `predicate-if-*` fires when the call is used as an
-  # `if` / `unless` condition; `assert` fires unconditionally
-  # at the call's post-scope; `assert-if-true` /
-  # `assert-if-false` fire at the post-scope only when the
-  # call's return value can be observed as truthy / falsey
-  # (currently: when the call is the predicate of a
-  # subsequent `if` / `unless`). Other directives in the spec
-  # (`param`, `return`, `conforms-to`, negation `~T`,
-  # `target: self` narrowing, ...) remain on the v0.0.x
-  # roadmap. Annotations whose key is in the `rigor:v1:`
-  # namespace but whose directive is unrecognised are
-  # silently ignored at first-preview quality (a future slice
-  # MAY surface them as diagnostics-on-Rigor-itself per the
-  # spec's "unsupported metadata" guidance).
-  #
-  # The parser is minimal: it accepts a strict shape
-  # `<target> is <ClassName>` where `<target>` is a Ruby
-  # identifier (parameter name) or `self`, and `<ClassName>`
-  # is a single non-namespaced class identifier or a
-  # `::Foo::Bar` style constant path. Negative refinements
-  # (`~T`), intersections, and unions are deferred to the
-  # next iteration.
+  # `predicate-if-*` fires when the call is used as an `if` / `unless`
+  # condition; `assert` fires unconditionally at the call's post-scope;
+  # `assert-if-true` / `assert-if-false` fire at the post-scope only
+  # when the call's return value can be observed as truthy / falsey.
+  # Negation (`~T`) is supported for both class-name and refinement
+  # right-hand sides. Parameterised refinements (`non-empty-array[T]`)
+  # are also recognised. Annotations whose directive is unrecognised
+  # are silently ignored per the spec's "unsupported metadata" guidance.
   module RbsExtended # rubocop:disable Metrics/ModuleLength
     DIRECTIVE_PREFIX = "rigor:v1:"
 
@@ -58,9 +45,10 @@ module Rigor
     # a kebab-case refinement name (`non-empty-string`,
     # `lowercase-string`, …) instead of a Capitalised class
     # name. The narrowing tier substitutes the carrier for the
-    # current local type; `class_name` is then nil and
-    # `negative` is false (refinement-form directives do not
-    # support `~T` negation in v0.0.4).
+    # current local type; `class_name` is then nil. `negative`
+    # may be true for refinement-form directives — `~T` negation
+    # is supported; the narrowing tier computes the complement
+    # decomposition (see `AssertEffect` docs below).
     class PredicateEffect < Data.define(:edge, :target_kind, :target_name, :class_name, :negative, :refinement_type)
       def truthy_only? = edge == :truthy_only
       def falsey_only? = edge == :falsey_only

data/lib/rigor/reflection.rb

@@ -17,11 +17,8 @@ module Rigor
   #    classes / modules, in-source constants, discovered method
   #    nodes, class ivar / cvar declarations).
   #
-  # This module is the **stable read shape** that v0.1.0's plugin
-  # API will be designed against. ADR-2 (`docs/adr/2-extension-api.md`)
-  # calls out a unified reflection layer as a prerequisite for the
-  # extension protocols, and `docs/design/20260505-v0.1.0-readiness.md`
-  # nominates this module as the highest-leverage cold-start slice.
+  # This module is the **stable read shape** the plugin API is
+  # designed against (ADR-2, `docs/adr/2-extension-api.md`).
   #
   # The facade is **read-only and additive**. Existing call sites
   # that read directly from `Rigor::Scope` or
@@ -52,8 +49,8 @@ module Rigor
   #   defined in the analyzed sources?
   #
   # The provenance side of the API (which source family contributed
-  # each fact) is explicitly out of scope for the v0.0.7 first
-  # pass. v0.1.0's plugin API adds it as a separate concern.
+  # each fact) is explicitly out of scope for the v0.0.7 first pass;
+  # v0.1.0's plugin API added it as a separate concern.
   module Reflection
     module_function
 

data/lib/rigor/scope/discovery_index.rb

@@ -28,7 +28,9 @@ module Rigor
       :discovered_superclasses,
       :discovered_includes,
       :discovered_class_sources,
-      :data_member_layouts
+      :data_member_layouts,
+      :struct_member_layouts,
+      :param_inferred_types
     )
 
     class DiscoveryIndex
@@ -53,7 +55,17 @@ module Rigor
         discovered_superclasses: EMPTY_TABLE,
         discovered_includes: EMPTY_TABLE,
         discovered_class_sources: EMPTY_TABLE,
-        data_member_layouts: EMPTY_TABLE
+        data_member_layouts: EMPTY_TABLE,
+        struct_member_layouts: EMPTY_TABLE,
+        # ADR-67 WD3 — the call-site parameter-inference table, keyed by
+        # `[class_name, method_name, kind]` (the same `(class, method, kind)`
+        # triple {Inference::ParameterInferenceCollector} records and that
+        # `build_method_entry_scope` reconstructs from the lexical class path).
+        # The value is a `{param_name(Symbol) => Rigor::Type}` map of the union
+        # of resolved call-site argument types. Empty on every normal run; only
+        # the `coverage --protection` collection pass populates it today, so a
+        # `check` run leaves it empty and seeds nothing (byte-identical).
+        param_inferred_types: EMPTY_TABLE
       )
     end
   end

data/lib/rigor/scope.rb

@@ -23,7 +23,7 @@ module Rigor
                 :ivars, :cvars, :globals,
                 :indexed_narrowings, :method_chain_narrowings,
                 :declaration_sourced,
-                :source_path, :discovery
+                :source_path, :discovery, :struct_fold_safe_locals
 
     # ADR-53 Track A — the seed-time discovery tables live on the
     # {DiscoveryIndex} the scope carries by a single reference; the
@@ -51,6 +51,13 @@ module Rigor
     def discovered_includes = @discovery.discovered_includes
     def discovered_class_sources = @discovery.discovered_class_sources
     def data_member_layouts = @discovery.data_member_layouts
+    def struct_member_layouts = @discovery.struct_member_layouts
+    # ADR-67 WD3 — call-site-inferred parameter types, keyed by
+    # `[class_name, method_name, kind]`. `build_method_entry_scope` consults
+    # this to seed an undeclared `def` parameter with the union of its
+    # resolved call-site argument types (precision-additive; an RBS-declared
+    # parameter always wins). Empty unless a collection pass seeded it.
+    def param_inferred_types = @discovery.param_inferred_types
 
     # Narrowing key for an indexed read `receiver[key]` where both
     # the receiver and the key are stable enough to address. The
@@ -99,8 +106,14 @@ module Rigor
     # principle. Any flow-live touch (write / narrowing) drops the mark, so
     # the diagnostic keeps firing exactly as before on flow-observed nil.
     EMPTY_DECLARATION_SOURCED = Set.new.freeze
+    # ADR-48 Struct slice 3 — the per-body set of local names whose struct
+    # member reads are fold-safe (provably never mutated / aliased / escaped).
+    # A static per-scope context like {#source_path}: inherited unchanged
+    # through flow transitions and ignored by `==` / `hash`.
+    EMPTY_FOLD_SAFE = Set.new.freeze
     private_constant :EMPTY_VAR_BINDINGS, :EMPTY_INDEXED_NARROWINGS,
-                     :EMPTY_CHAIN_NARROWINGS, :EMPTY_DECLARATION_SOURCED
+                     :EMPTY_CHAIN_NARROWINGS, :EMPTY_DECLARATION_SOURCED,
+                     :EMPTY_FOLD_SAFE
 
     class << self
       def empty(environment: Environment.default, source_path: nil)
@@ -120,7 +133,8 @@ module Rigor
       indexed_narrowings: EMPTY_INDEXED_NARROWINGS,
       method_chain_narrowings: EMPTY_CHAIN_NARROWINGS,
       declaration_sourced: EMPTY_DECLARATION_SOURCED,
-      source_path: nil
+      source_path: nil,
+      struct_fold_safe_locals: EMPTY_FOLD_SAFE
     )
       @environment = environment
       @locals = locals
@@ -134,6 +148,7 @@ module Rigor
       @method_chain_narrowings = method_chain_narrowings
       @declaration_sourced = declaration_sourced
       @source_path = source_path
+      @struct_fold_safe_locals = struct_fold_safe_locals
       freeze
     end
 
@@ -180,17 +195,29 @@ module Rigor
       rebuild(self_type: type)
     end
 
-    # ADR-11 per-call-site assertion gating prerequisite. The
-    # analyzer's per-file boundary stamps the current source
-    # file's path onto the seed scope; nested rebuilds carry
-    # the value through so plugin rules (`dynamic_return`'s
-    # `file_methods:` gate, sigil checks) can resolve "which
-    # file does this call site belong to?" without
+    # ADR-28 / ADR-52 slice 5a — per-file source path carried on
+    # the scope. The analyzer stamps the current file's path onto
+    # the seed scope; nested rebuilds propagate it so plugin rules
+    # (`dynamic_return`'s `file_methods:` gate, sigil checks) can
+    # resolve "which file does this call site belong to?" without
     # thread-locals.
     def with_source_path(path)
       rebuild(source_path: path)
     end
 
+    # ADR-48 Struct slice 3 — installs the per-body fold-safe-local set
+    # ({Inference::StructFoldSafety}). Set once at body entry; inherited
+    # unchanged through subsequent flow transitions.
+    def with_struct_fold_safe(locals)
+      rebuild(struct_fold_safe_locals: locals)
+    end
+
+    # True when `name`'s `Struct` member reads are fold-safe in this body
+    # (the local is provably never mutated / aliased / escaped).
+    def struct_fold_safe?(name)
+      @struct_fold_safe_locals.include?(name.to_sym)
+    end
+
     # ADR-53 Track A — swaps the whole discovery index in one transition.
     # The sole seeding path; the per-table writers it replaced are derived
     # off-`Scope` through `scope.discovery.with(table_name: table)`.
@@ -484,6 +511,20 @@ module Rigor
       layout
     end
 
+    # ADR-48 Struct follow-up — the `{ members:, keyword_init: }` layout
+    # recorded for a `Struct.new(...)`-defined class, in the constant form
+    # (`Point = Struct.new(:x, :y)`) and the named-subclass form
+    # (`class Point < Struct.new(:x, :y)`). Consumed by
+    # {Inference::MethodDispatcher::StructFolding} so `Point.new(...)` on a
+    # `Singleton[Point]` receiver materialises a member instance. Returns nil
+    # when the class has no recorded struct layout. Mirrors
+    # {#data_member_layout}'s dependency-recording contract.
+    def struct_member_layout(class_name)
+      layout = @discovery.struct_member_layouts[class_name.to_s]
+      record_class_dependency(class_name) if layout && Analysis::DependencyRecorder.active?
+      layout
+    end
+
     # ADR-24 slice 2 — per-class/module table mapping a fully
     # qualified user class or module to the list of module
     # names it `include`s / `prepend`s, AS WRITTEN at the
@@ -674,7 +715,8 @@ module Rigor
       indexed_narrowings: @indexed_narrowings,
       method_chain_narrowings: @method_chain_narrowings,
       declaration_sourced: @declaration_sourced,
-      source_path: @source_path
+      source_path: @source_path,
+      struct_fold_safe_locals: @struct_fold_safe_locals
     )
       self.class.new(
         environment: environment, locals: locals,
@@ -684,7 +726,8 @@ module Rigor
         indexed_narrowings: indexed_narrowings,
         method_chain_narrowings: method_chain_narrowings,
         declaration_sourced: declaration_sourced,
-        source_path: source_path
+        source_path: source_path,
+        struct_fold_safe_locals: struct_fold_safe_locals
       )
     end
 

data/lib/rigor/sig_gen/observed_call.rb

@@ -5,9 +5,9 @@ module Rigor
     # Per-call-site argument observation produced by
     # {ObservationCollector}. ADR-14 follow-up: the earlier
     # MVP shape (`Array[Type]` of positional types only)
-    # could not represent keyword arguments — every call like
-    # `MethodCatalog.new(path: ..., mutating_selectors: ...)`
-    # discarded the whole observation via `non_positional?`.
+    # could not represent keyword arguments — keyword calls
+    # like `MethodCatalog.new(path: ..., mutating_selectors: ...)`
+    # were silently skipped in that shape.
     # The new shape carries positional and keyword arg types
     # in parallel so the per-position / per-keyword unions
     # can each be reconstructed independently.