rigortype 0.2.7 → 0.2.8

data/lib/rigor/scope.rb

@@ -10,11 +10,9 @@ require_relative "inference/flow_tracer"
 require_relative "inference/statement_evaluator"
 
 module Rigor
-  # Immutable analyzer scope: holds local-variable bindings and a reference
-  # to the surrounding Environment. State changes return new scopes through
-  # explicit transition methods (#with_local). The central query is
-  # #type_of(node), the Rigor counterpart of PHPStan's
-  # $scope->getType($node).
+  # Immutable analyzer scope: holds local-variable bindings and a reference to the surrounding Environment. State
+  # changes return new scopes through explicit transition methods (#with_local). The central query is
+  # #type_of(node), the Rigor counterpart of PHPStan's $scope->getType($node).
   #
   # See docs/internal-spec/inference-engine.md for the binding contract.
   # rubocop:disable Metrics/ClassLength,Metrics/ParameterLists
@@ -24,19 +22,15 @@ module Rigor
                 :indexed_narrowings, :method_chain_narrowings,
                 :declaration_sourced,
                 :source_path, :discovery, :struct_fold_safe_locals,
-                :dynamic_origins
+                :dynamic_origins, :local_origins, :ivar_origins
 
-    # ADR-53 Track A — the seed-time discovery tables live on the
-    # {DiscoveryIndex} the scope carries by a single reference; the
-    # per-table readers stay on Scope so engine call sites and plugins
-    # are unaffected by the extraction. The whole index is swapped in
-    # one transition through {#with_discovery}.
+    # ADR-53 Track A — the seed-time discovery tables live on the {DiscoveryIndex} the scope carries by a single
+    # reference; the per-table readers stay on Scope so engine call sites and plugins are unaffected by the
+    # extraction. The whole index is swapped in one transition through {#with_discovery}.
     #
-    # `declared_types` carries the identity-comparing
-    # `Prism::Node => Rigor::Type` declaration overrides
-    # `ExpressionTyper#type_of(node)` MUST consult before any other
-    # dispatch (a `module Foo` / `class Bar` header types as
-    # `Singleton[<qualified path>]` rather than `Dynamic[Top]`).
+    # `declared_types` carries the identity-comparing `Prism::Node => Rigor::Type` declaration overrides
+    # `ExpressionTyper#type_of(node)` MUST consult before any other dispatch (a `module Foo` / `class Bar` header
+    # types as `Singleton[<qualified path>]` rather than `Dynamic[Top]`).
     def declared_types = @discovery.declared_types
     def class_ivars = @discovery.class_ivars
     def class_cvars = @discovery.class_cvars
@@ -53,68 +47,63 @@ module Rigor
     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.
+    # 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
-    # value of the map at this key is the narrowed type the next
-    # read at the same address MUST observe.
+    # Narrowing key for an indexed read `receiver[key]` where both the receiver and the key are stable enough to
+    # address. The value of the map at this key is the narrowed type the next read at the same address MUST
+    # observe.
     #
-    # - `receiver_kind` ∈ `{:local, :ivar}` — the analyzer only
-    #   tracks reads against a local or instance variable today.
+    # - `receiver_kind` ∈ `{:local, :ivar}` — the analyzer only tracks reads against a local or instance variable
+    #   today.
     # - `receiver_name` is the variable's Symbol.
-    # - `key` is the Ruby value of the literal index (Symbol /
-    #   String / Integer). Non-literal keys (`params[field]`) are
-    #   not recorded; they have no stable address.
+    # - `key` is the Ruby value of the literal index (Symbol / String / Integer). Non-literal keys
+    #   (`params[field]`) are not recorded; they have no stable address.
     IndexedKey = Data.define(:receiver_kind, :receiver_name, :key)
 
-    # Narrowing key for a no-arg / no-block method-call chain
-    # `receiver.method_name` (a "single-hop" chain per A1 from the
-    # ROADMAP § Future cycles slice). The value of the map at this
-    # key is the narrowed type the next read of the same chain
-    # MUST observe — typically the post-`is_a?(C)` narrowing
-    # established on a predicate edge.
+    # Narrowing key for a no-arg / no-block method-call chain `receiver.method_name` (a "single-hop" chain per A1
+    # from the ROADMAP § Future cycles slice). The value of the map at this key is the narrowed type the next read
+    # of the same chain MUST observe — typically the post-`is_a?(C)` narrowing established on a predicate edge.
     #
-    # - `receiver_kind` ∈ `{:local, :ivar}` — the analyzer only
-    #   tracks chains rooted at a local or instance variable
-    #   today (Law-of-Demeter-style single-hop).
+    # - `receiver_kind` ∈ `{:local, :ivar}` — the analyzer only tracks chains rooted at a local or instance
+    #   variable today (Law-of-Demeter-style single-hop).
     # - `receiver_name` is the root variable's Symbol.
     # - `method_name` is the no-arg method invoked on the root.
     #
-    # Chains with arguments (`x.first(3)`), with a block
-    # (`x.detect { ... }`), or with intermediate links
-    # (`x.foo.bar`) are NOT recorded; each loses stability for
-    # different reasons (args / block alter the call's return;
-    # multi-hop loses the LoD guarantee).
+    # Chains with arguments (`x.first(3)`), with a block (`x.detect { ... }`), or with intermediate links
+    # (`x.foo.bar`) are NOT recorded; each loses stability for different reasons (args / block alter the call's
+    # return; multi-hop loses the LoD guarantee).
     ChainKey = Data.define(:receiver_kind, :receiver_name, :method_name)
 
     EMPTY_VAR_BINDINGS = {}.freeze
     EMPTY_INDEXED_NARROWINGS = {}.freeze
     EMPTY_CHAIN_NARROWINGS = {}.freeze
-    # ADR-58 WD1 — the set of variable references whose binding's `nil`
-    # constituent is *declaration-sourced*: it arrives only via the
-    # class-ivar index seed (a ctor `@x = nil` written in another method),
-    # never through a method-local write, narrowing, or parameter. Members
-    # are frozen `[kind, name]` pairs (`[:ivar, :@x]`, `[:local, :r]`).
-    # `possible-nil-receiver` consults this set and declines to fire when the
-    # receiver's optionality is purely declaration-sourced — the working
-    # program's cross-method invariant is assumed per the robustness
-    # principle. Any flow-live touch (write / narrowing) drops the mark, so
-    # the diagnostic keeps firing exactly as before on flow-observed nil.
+    # ADR-58 WD1 — the set of variable references whose binding's `nil` constituent is *declaration-sourced*: it
+    # arrives only via the class-ivar index seed (a ctor `@x = nil` written in another method), never through a
+    # method-local write, narrowing, or parameter. Members are frozen `[kind, name]` pairs (`[:ivar, :@x]`,
+    # `[:local, :r]`). `possible-nil-receiver` consults this set and declines to fire when the receiver's
+    # optionality is purely declaration-sourced — the working program's cross-method invariant is assumed per the
+    # robustness 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
+    # 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
+    # ADR-82 WD1 — provenance propagation across the receiver-node lookup. `local_origins` / `ivar_origins`
+    # map a `name` (Symbol) to the {Inference::DynamicOrigin} cause of the `Dynamic` value currently bound to
+    # it, so a downstream dispatch whose receiver is a bare `x` / `@x` read resolves to why that value is
+    # dynamic (the cause was recorded on the *assignment*'s rhs node, which the receiver-read node is not).
+    # Advisory metadata like {#dynamic_origins}: ignored by `==` / `hash` (never varies a flow decision) and
+    # threaded by reference through transitions; reset per method body (a fresh entry scope drops it), so the
+    # name keys never collide across bodies.
+    EMPTY_ORIGINS = {}.freeze
     private_constant :EMPTY_VAR_BINDINGS, :EMPTY_INDEXED_NARROWINGS,
                      :EMPTY_CHAIN_NARROWINGS, :EMPTY_DECLARATION_SOURCED,
-                     :EMPTY_FOLD_SAFE
+                     :EMPTY_FOLD_SAFE, :EMPTY_ORIGINS
 
     class << self
       def empty(environment: Environment.default, source_path: nil)
@@ -141,7 +130,9 @@ module Rigor
       declaration_sourced: EMPTY_DECLARATION_SOURCED,
       source_path: nil,
       struct_fold_safe_locals: EMPTY_FOLD_SAFE,
-      dynamic_origins: {}.compare_by_identity
+      dynamic_origins: {}.compare_by_identity,
+      local_origins: EMPTY_ORIGINS,
+      ivar_origins: EMPTY_ORIGINS
     )
       @environment = environment
       @locals = locals
@@ -157,9 +148,31 @@ module Rigor
       @source_path = source_path
       @struct_fold_safe_locals = struct_fold_safe_locals
       @dynamic_origins = dynamic_origins
+      @local_origins = local_origins
+      @ivar_origins = ivar_origins
       freeze
     end
 
+    # ADR-82 WD1 — the propagated origin of the `Dynamic` value currently bound to a local / instance
+    # variable, or `nil` when none is tracked. Consulted by `Inference::ProtectionScanner` when a dispatch's
+    # receiver is a bare `x` / `@x` read whose own node carries no origin.
+    def local_origin(name) = @local_origins[name.to_sym]
+    def ivar_origin(name) = @ivar_origins[name.to_sym]
+
+    # Records the cause of the `Dynamic` value being bound to `name`. A `nil` cause is a no-op (the common
+    # case — most bindings are concrete or have no recorded origin), so callers need not pre-check.
+    def with_local_origin(name, cause)
+      return self if cause.nil?
+
+      rebuild(local_origins: @local_origins.merge(name.to_sym => cause).freeze)
+    end
+
+    def with_ivar_origin(name, cause)
+      return self if cause.nil?
+
+      rebuild(ivar_origins: @ivar_origins.merge(name.to_sym => cause).freeze)
+    end
+
     def local(name)
       @locals[name.to_sym]
     end
@@ -169,79 +182,65 @@ module Rigor
       Inference::FlowTracer.bind(name, type) if Inference::FlowTracer.active?
       new_locals = @locals.merge(name.to_sym => type).freeze
       new_fact_store = fact_store.invalidate_target(Analysis::FactStore::Target.local(name))
-      # Rebinding `name` invalidates every "after `receiver[key]
-      # ||= default`" narrowing keyed on it — the slot at `name[*]`
-      # is reachable through the old binding only, so the
-      # next read against the new binding does not inherit the
-      # earlier non-nil guarantee. The same logic applies to
-      # method-chain narrowings: `x.last` after `x = something_new`
-      # is a call on the new binding and any prior `is_a?`-driven
-      # narrowing keyed on `(local, :x, :last)` no longer holds.
+      # Rebinding `name` invalidates every "after `receiver[key] ||= default`" narrowing keyed on it — the slot at
+      # `name[*]` is reachable through the old binding only, so the next read against the new binding does not
+      # inherit the earlier non-nil guarantee. The same logic applies to method-chain narrowings: `x.last` after
+      # `x = something_new` is a call on the new binding and any prior `is_a?`-driven narrowing keyed on
+      # `(local, :x, :last)` no longer holds.
       new_indexed_narrowings = drop_indexed_narrowings_for(:local, name)
       new_chain_narrowings = drop_chain_narrowings_for(:local, name)
-      # ADR-58 WD1 — rebinding a local is a flow-live touch: any prior
-      # declaration-sourced mark on `name` no longer holds (the new value
-      # may carry a method-local nil). `with_declaration_sourced_local`
-      # re-establishes the mark afterward when the RHS is a pure copy of a
-      # declaration-sourced ivar read; the default is to drop it.
+      # ADR-58 WD1 — rebinding a local is a flow-live touch: any prior declaration-sourced mark on `name` no
+      # longer holds (the new value may carry a method-local nil). `with_declaration_sourced_local` re-establishes
+      # the mark afterward when the RHS is a pure copy of a declaration-sourced ivar read; the default is to drop
+      # it.
       rebuild(locals: new_locals, fact_store: new_fact_store,
               indexed_narrowings: new_indexed_narrowings,
               method_chain_narrowings: new_chain_narrowings,
-              declaration_sourced: drop_declaration_sourced_for(:local, name))
+              declaration_sourced: drop_declaration_sourced_for(:local, name),
+              local_origins: drop_origin(@local_origins, name))
     end
 
     def with_fact(fact)
       rebuild(fact_store: fact_store.with_fact(fact))
     end
 
-    # Slice A-engine. Returns a scope with `self_type` set to `type`,
-    # preserving locals and facts. `StatementEvaluator` injects this
-    # at class-body and method-body boundaries; `ExpressionTyper`
-    # consults it when typing `Prism::SelfNode` and implicit-self
-    # `Prism::CallNode` receivers.
+    # Slice A-engine. Returns a scope with `self_type` set to `type`, preserving locals and facts.
+    # `StatementEvaluator` injects this at class-body and method-body boundaries; `ExpressionTyper` consults it
+    # when typing `Prism::SelfNode` and implicit-self `Prism::CallNode` receivers.
     def with_self_type(type)
       rebuild(self_type: type)
     end
 
-    # 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.
+    # 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.
+    # 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).
+    # 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)`.
+    # 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)`.
     def with_discovery(index)
       rebuild(discovery: index)
     end
 
-    # Slice 7 phase 1 — instance/class/global variable bindings.
-    # `ivar(name)` / `cvar(name)` / `global(name)` return the
-    # type currently bound for the named variable, or `nil` when
-    # the variable has not been written in the analyzed slice of
-    # the program. The first cut tracks bindings only within a
-    # single method body (each `def` enters with a fresh binding
-    # map), so reads in other methods of the same class fall
-    # through to `Dynamic[Top]`. Cross-method ivar/cvar inference
-    # is a follow-up slice.
+    # Slice 7 phase 1 — instance/class/global variable bindings. `ivar(name)` / `cvar(name)` / `global(name)`
+    # return the type currently bound for the named variable, or `nil` when the variable has not been written in
+    # the analyzed slice of the program. The first cut tracks bindings only within a single method body (each
+    # `def` enters with a fresh binding map), so reads in other methods of the same class fall through to
+    # `Dynamic[Top]`. Cross-method ivar/cvar inference is a follow-up slice.
     def ivar(name)
       @ivars[name.to_sym]
     end
@@ -257,44 +256,40 @@ module Rigor
     def with_ivar(name, type)
       new_indexed_narrowings = drop_indexed_narrowings_for(:ivar, name)
       new_chain_narrowings = drop_chain_narrowings_for(:ivar, name)
-      # ADR-58 WD1 — a method-local ivar write or narrowing is flow-live:
-      # drop any declaration-sourced mark so subsequent reads of `@name`
-      # observe flow-live provenance and fire as before. The seed path uses
+      # ADR-58 WD1 — a method-local ivar write or narrowing is flow-live: drop any declaration-sourced mark so
+      # subsequent reads of `@name` observe flow-live provenance and fire as before. The seed path uses
       # `seed_declaration_sourced_ivar` to (re-)establish the mark.
       rebuild(ivars: @ivars.merge(name.to_sym => type).freeze,
               indexed_narrowings: new_indexed_narrowings,
               method_chain_narrowings: new_chain_narrowings,
-              declaration_sourced: drop_declaration_sourced_for(:ivar, name))
+              declaration_sourced: drop_declaration_sourced_for(:ivar, name),
+              ivar_origins: drop_origin(@ivar_origins, name))
     end
 
-    # ADR-58 WD1 — used by the method-entry seed to mark an ivar whose only
-    # provenance is the class-ivar index. Unlike `with_ivar` this binds the
-    # type AND records the declaration-sourced mark in one transition.
+    # ADR-58 WD1 — used by the method-entry seed to mark an ivar whose only provenance is the class-ivar index.
+    # Unlike `with_ivar` this binds the type AND records the declaration-sourced mark in one transition.
     def seed_declaration_sourced_ivar(name, type)
       rebuild(ivars: @ivars.merge(name.to_sym => type).freeze,
               declaration_sourced: add_declaration_sourced(:ivar, name))
     end
 
-    # ADR-58 WD1 — a local assignment `r = @right` whose RHS is a pure read
-    # of a declaration-sourced ivar inherits the mark, so the survey's exact
-    # rotation/traversal shape (`r = @right; r.key`) does not fire. Binds the
-    # type and stamps the local's mark in one transition (the plain
-    # `with_local` would have dropped it).
+    # ADR-58 WD1 — a local assignment `r = @right` whose RHS is a pure read of a declaration-sourced ivar inherits
+    # the mark, so the survey's exact rotation/traversal shape (`r = @right; r.key`) does not fire. Binds the type
+    # and stamps the local's mark in one transition (the plain `with_local` would have dropped it).
     def with_declaration_sourced_local(name, type)
       written = with_local(name, type)
       written.with_local_declaration_mark(name)
     end
 
-    # ADR-58 WD1 — re-stamp the local mark on a scope produced by
-    # `with_local` (which always drops it). Public so the sibling
-    # `with_declaration_sourced_local` can call it across the new
-    # post-write receiver without reaching into a private method.
+    # ADR-58 WD1 — re-stamp the local mark on a scope produced by `with_local` (which always drops it). Public so
+    # the sibling `with_declaration_sourced_local` can call it across the new post-write receiver without reaching
+    # into a private method.
     def with_local_declaration_mark(name)
       rebuild(declaration_sourced: add_declaration_sourced(:local, name))
     end
 
-    # ADR-58 WD1 — true when `(kind, name)`'s binding optionality is purely
-    # declaration-sourced (no flow-live write/narrowing has touched it).
+    # ADR-58 WD1 — true when `(kind, name)`'s binding optionality is purely declaration-sourced (no flow-live
+    # write/narrowing has touched it).
     def declaration_sourced?(kind, name)
       @declaration_sourced.include?([kind.to_sym, name.to_sym])
     end
@@ -307,14 +302,11 @@ module Rigor
       rebuild(globals: @globals.merge(name.to_sym => type).freeze)
     end
 
-    # Regex match-data globals (`$~`, `$&`, `$1..$9`, the pre/post-match
-    # and last-paren back-references). Narrowed on a successful-`=~` /
-    # `case`-`when` match edge (see `Narrowing#regex_match_predicate_scopes`);
-    # any subsequent method call could run another match and rebind every
-    # one of them, so `eval_call` forgets the narrowed facts here. Always
-    # safe — only drops facts, so a subsequent read falls back to the
-    # default `String | nil`. Program-level `$GLOBAL = ...` seeds use other
-    # names and are untouched.
+    # Regex match-data globals (`$~`, `$&`, `$1..$9`, the pre/post-match and last-paren back-references). Narrowed
+    # on a successful-`=~` / `case`-`when` match edge (see `Narrowing#regex_match_predicate_scopes`); any
+    # subsequent method call could run another match and rebind every one of them, so `eval_call` forgets the
+    # narrowed facts here. Always safe — only drops facts, so a subsequent read falls back to the default
+    # `String | nil`. Program-level `$GLOBAL = ...` seeds use other names and are untouched.
     MATCH_DATA_GLOBALS = %i[$~ $& $` $' $+ $1 $2 $3 $4 $5 $6 $7 $8 $9].freeze
     private_constant :MATCH_DATA_GLOBALS
 
@@ -324,44 +316,33 @@ module Rigor
       rebuild(globals: @globals.except(*MATCH_DATA_GLOBALS).freeze)
     end
 
-    # Slice 7 phase 2 — class-level ivar accumulator. Keyed by
-    # the qualified class name (e.g. `"Rigor::Scope"`); the
-    # value is a `Hash[Symbol, Type::t]` of every ivar that
-    # appears as a write target inside any def body of that
-    # class. `StatementEvaluator#build_method_entry_scope`
-    # seeds the method body's `ivars` map from this table so a
-    # `def get; @x; end` reads the type written in a sibling
-    # `def init; @x = 1; end`.
+    # Slice 7 phase 2 — class-level ivar accumulator. Keyed by the qualified class name (e.g. `"Rigor::Scope"`);
+    # the value is a `Hash[Symbol, Type::t]` of every ivar that appears as a write target inside any def body of
+    # that class. `StatementEvaluator#build_method_entry_scope` seeds the method body's `ivars` map from this
+    # table so a `def get; @x; end` reads the type written in a sibling `def init; @x = 1; end`.
     #
-    # `ScopeIndexer` populates the table once at index time
-    # through a separate pre-pass over the program. The map is
-    # frozen and shared by structural reference across every
-    # derived scope.
+    # `ScopeIndexer` populates the table once at index time through a separate pre-pass over the program. The map
+    # is frozen and shared by structural reference across every derived scope.
     def class_ivars_for(class_name)
       return EMPTY_VAR_BINDINGS if class_name.nil?
 
       @discovery.class_ivars[class_name.to_s] || EMPTY_VAR_BINDINGS
     end
 
-    # Slice 7 phase 6 — class-level cvar accumulator (same shape
-    # as `class_ivars` but populated from `Prism::ClassVariableWriteNode`
-    # writes, and seeded on BOTH instance and singleton method
-    # bodies because Ruby cvars are visible from each).
+    # Slice 7 phase 6 — class-level cvar accumulator (same shape as `class_ivars` but populated from
+    # `Prism::ClassVariableWriteNode` writes, and seeded on BOTH instance and singleton method bodies because Ruby
+    # cvars are visible from each).
     def class_cvars_for(class_name)
       return EMPTY_VAR_BINDINGS if class_name.nil?
 
       @discovery.class_cvars[class_name.to_s] || EMPTY_VAR_BINDINGS
     end
 
-    # Slice 7 phase 12 — in-source method discovery. Maps a
-    # qualified class name to a `Hash[Symbol, Symbol]` of
-    # `method_name => :instance | :singleton`. Populated by
-    # `ScopeIndexer` from every `Prism::DefNode` and recognised
-    # `define_method` invocation inside class/module bodies. The
-    # `rigor check` undefined-method and wrong-arity rules
-    # consult this map to suppress diagnostics for methods the
-    # user has defined dynamically, even when no RBS sig
-    # describes them.
+    # Slice 7 phase 12 — in-source method discovery. Maps a qualified class name to a `Hash[Symbol, Symbol]` of
+    # `method_name => :instance | :singleton`. Populated by `ScopeIndexer` from every `Prism::DefNode` and
+    # recognised `define_method` invocation inside class/module bodies. The `rigor check` undefined-method and
+    # wrong-arity rules consult this map to suppress diagnostics for methods the user has defined dynamically,
+    # even when no RBS sig describes them.
     def discovered_method?(class_name, method_name, kind)
       table = @discovery.discovered_methods[class_name.to_s]
       return false unless table
@@ -369,30 +350,20 @@ module Rigor
       table[method_name.to_sym] == kind
     end
 
-    # ADR-34 § "Decision" — predicate identifying a toplevel-shaped
-    # scope (no enclosing `class` / `module` body). True at the top
-    # of a file AND inside a top-level `def` body (since toplevel
-    # defs leave `self_type` nil per the existing scope-construction
-    # contract — the same nil-`self_type` signal ADR-24's self-call
-    # return adoption historically keyed on before ADR-57 opened the
-    # gate unconditionally). Used by
-    # `CheckRules#unresolved_toplevel_diagnostic` to gate the
-    # `call.unresolved-toplevel` rule so it fires only outside
-    # class / module bodies, where Rails-DSL metaprogramming
-    # leniency (ADR-24 WD3 → WD4) does not apply.
+    # ADR-34 § "Decision" — predicate identifying a toplevel-shaped scope (no enclosing `class` / `module` body).
+    # True at the top of a file AND inside a top-level `def` body (since toplevel defs leave `self_type` nil per
+    # the existing scope-construction contract — the same nil-`self_type` signal ADR-24's self-call return
+    # adoption historically keyed on before ADR-57 opened the gate unconditionally). Used by
+    # `CheckRules#unresolved_toplevel_diagnostic` to gate the `call.unresolved-toplevel` rule so it fires only
+    # outside class / module bodies, where Rails-DSL metaprogramming leniency (ADR-24 WD3 → WD4) does not apply.
     def toplevel?
       @self_type.nil?
     end
 
-    # v0.0.2 #5 — per-class table mapping
-    # `method_name (Symbol) → Prism::DefNode`. Populated by
-    # `ScopeIndexer` alongside `discovered_methods` for
-    # instance-side defs only (singleton-side and
-    # `define_method`-introduced methods do not contribute a
-    # static body the engine can re-type). Consumed by
-    # `ExpressionTyper` to do inter-procedural return-type
-    # inference when the receiver class is user-defined and
-    # has no RBS sig.
+    # v0.0.2 #5 — per-class table mapping `method_name (Symbol) → Prism::DefNode`. Populated by `ScopeIndexer`
+    # alongside `discovered_methods` for instance-side defs only (singleton-side and `define_method`-introduced
+    # methods do not contribute a static body the engine can re-type). Consumed by `ExpressionTyper` to do
+    # inter-procedural return-type inference when the receiver class is user-defined and has no RBS sig.
     def user_def_for(class_name, method_name)
       table = @discovery.discovered_def_nodes[class_name.to_s]
       node = table && table[method_name.to_sym]
@@ -400,15 +371,12 @@ module Rigor
       node
     end
 
-    # Module-singleton call resolution (ADR-57 follow-up) — companion of
-    # {#user_def_for} for SINGLETON-side defs (`def self.x`, `def Foo.x`,
-    # `class << self` bodies, and `module_function` defs). Returns the
-    # `Prism::DefNode` for `class_name.method_name` invoked on the
-    # module/class constant itself, or nil. The `discovered_def_nodes`
-    # table is deliberately instance-side only (its ancestor walk binds
-    # `self` as `Nominal`), so singleton bodies live in a parallel table
-    # the `ScopeIndexer` populates alongside it. Records the same
-    # cross-file dependency edge as the instance path (ADR-46).
+    # Module-singleton call resolution (ADR-57 follow-up) — companion of {#user_def_for} for SINGLETON-side defs
+    # (`def self.x`, `def Foo.x`, `class << self` bodies, and `module_function` defs). Returns the
+    # `Prism::DefNode` for `class_name.method_name` invoked on the module/class constant itself, or nil. The
+    # `discovered_def_nodes` table is deliberately instance-side only (its ancestor walk binds `self` as
+    # `Nominal`), so singleton bodies live in a parallel table the `ScopeIndexer` populates alongside it. Records
+    # the same cross-file dependency edge as the instance path (ADR-46).
     def singleton_def_for(class_name, method_name)
       table = @discovery.discovered_singleton_def_nodes[class_name.to_s]
       node = table && table[method_name.to_sym]
@@ -416,15 +384,14 @@ module Rigor
       node
     end
 
-    # ADR-46 slice 1 — note the cross-file dependency this resolution
-    # creates: the file defining `class_name#method_name` (the consumer's
-    # analysis reads its body via `infer_user_method_return`), or, when
-    # unresolved, a negative edge so a later definition re-checks the
-    # consumer. Gated on the recorder being active — no-op on a normal run.
+    # ADR-46 slice 1 — note the cross-file dependency this resolution creates: the file defining
+    # `class_name#method_name` (the consumer's analysis reads its body via `infer_user_method_return`), or, when
+    # unresolved, a negative edge so a later definition re-checks the consumer. Gated on the recorder being
+    # active — no-op on a normal run.
     def record_cross_file_method(class_name, method_name, node)
       if node
-        # ADR-46 slice 4 — pass the symbol so the recorder tracks this as a
-        # method-call (symbol-granularity) edge rather than a file-level edge.
+        # ADR-46 slice 4 — pass the symbol so the recorder tracks this as a method-call (symbol-granularity) edge
+        # rather than a file-level edge.
         Analysis::DependencyRecorder.read_site(
           @discovery.discovered_def_sources.dig(class_name.to_s, method_name.to_sym),
           "#{class_name}##{method_name}"
@@ -435,12 +402,9 @@ module Rigor
     end
     private :record_cross_file_method
 
-    # v0.0.3 A — top-level def lookup for implicit-self
-    # calls. Returns the `Prism::DefNode` for a top-level
-    # (or DSL-block-nested, outside any class body) `def
-    # <method_name>` in the file, or nil. The sentinel key
-    # is owned by `Inference::ScopeIndexer::TOP_LEVEL_DEF_KEY`;
-    # consumers should treat its presence as an opaque
+    # v0.0.3 A — top-level def lookup for implicit-self calls. Returns the `Prism::DefNode` for a top-level (or
+    # DSL-block-nested, outside any class body) `def <method_name>` in the file, or nil. The sentinel key is owned
+    # by `Inference::ScopeIndexer::TOP_LEVEL_DEF_KEY`; consumers should treat its presence as an opaque
     # implementation detail and go through this accessor.
     def top_level_def_for(method_name)
       table = @discovery.discovered_def_nodes[Inference::ScopeIndexer::TOP_LEVEL_DEF_KEY]
@@ -449,14 +413,12 @@ module Rigor
       node
     end
 
-    # ADR-46 slice 3 — a top-level (`def helper` outside any class) call has
-    # NO class ancestry to walk, so unlike {#user_def_for} a miss here records
-    # no positive ancestry edge that would re-check the consumer when the
-    # method later appears. Record the cross-file edge explicitly: the file
-    # defining the top-level method (symbol-granularity, so a body / removal
-    # edit re-checks the caller), or, on a miss, a negative `toplevel:` edge
-    # so a later top-level definition re-checks this consumer (the
-    # `call.unresolved-toplevel` stale-diagnostic gap).
+    # ADR-46 slice 3 — a top-level (`def helper` outside any class) call has NO class ancestry to walk, so unlike
+    # {#user_def_for} a miss here records no positive ancestry edge that would re-check the consumer when the
+    # method later appears. Record the cross-file edge explicitly: the file defining the top-level method
+    # (symbol-granularity, so a body / removal edit re-checks the caller), or, on a miss, a negative `toplevel:`
+    # edge so a later top-level definition re-checks this consumer (the `call.unresolved-toplevel`
+    # stale-diagnostic gap).
     def record_cross_file_toplevel(method_name, node)
       key = Inference::ScopeIndexer::TOP_LEVEL_DEF_KEY
       if node
@@ -470,16 +432,12 @@ module Rigor
     end
     private :record_cross_file_toplevel
 
-    # Companion to {#user_def_for}: returns the `"path:line"` where
-    # the project defines `class_name#method_name` (instance-side),
-    # or nil. Populated only by the cross-file project pre-pass
-    # ({Inference::ScopeIndexer.discovered_def_index_for_paths}) — a
-    # `Prism::Location` hides its source file, so the site is recorded
-    # at scan time. `CheckRules#undefined_method_diagnostic` consults
-    # this to name the defining file when a project monkey-patch on a
-    # core/stdlib/gem class is called cross-file, so the diagnostic
-    # can point at `pre_eval:` (ADR-17) instead of reading as a bare
-    # unresolved call.
+    # Companion to {#user_def_for}: returns the `"path:line"` where the project defines `class_name#method_name`
+    # (instance-side), or nil. Populated only by the cross-file project pre-pass
+    # ({Inference::ScopeIndexer.discovered_def_index_for_paths}) — a `Prism::Location` hides its source file, so
+    # the site is recorded at scan time. `CheckRules#undefined_method_diagnostic` consults this to name the
+    # defining file when a project monkey-patch on a core/stdlib/gem class is called cross-file, so the diagnostic
+    # can point at `pre_eval:` (ADR-17) instead of reading as a bare unresolved call.
     def user_def_site_for(class_name, method_name)
       table = @discovery.discovered_def_sources[class_name.to_s]
       return nil unless table
@@ -487,74 +445,56 @@ module Rigor
       table[method_name.to_sym]
     end
 
-    # ADR-24 slice 2 — per-class table mapping a fully
-    # qualified user-class name to its superclass name AS
-    # WRITTEN at the `class Foo < Bar` declaration (`"Bar"`,
-    # possibly a qualified `"A::B"`). Populated by `ScopeIndexer`
-    # — per-file plus the cross-file project pre-pass — and
-    # consumed by `ExpressionTyper#try_user_method_inference`
-    # to walk the superclass chain when an implicit-self call
-    # does not resolve against the enclosing class's own defs.
-    # The as-written name is resolved to a qualified class at
-    # walk time against the call's lexical nesting.
+    # ADR-24 slice 2 — per-class table mapping a fully qualified user-class name to its superclass name AS WRITTEN
+    # at the `class Foo < Bar` declaration (`"Bar"`, possibly a qualified `"A::B"`). Populated by `ScopeIndexer` —
+    # per-file plus the cross-file project pre-pass — and consumed by
+    # `ExpressionTyper#try_user_method_inference` to walk the superclass chain when an implicit-self call does not
+    # resolve against the enclosing class's own defs. The as-written name is resolved to a qualified class at walk
+    # time against the call's lexical nesting.
     def superclass_of(class_name)
       record_class_dependency(class_name) if Analysis::DependencyRecorder.active?
       @discovery.discovered_superclasses[class_name.to_s]
     end
 
-    # ADR-48 — per-class table mapping a fully qualified class name to its
-    # ordered `Data.define` / `Struct.new` member-name list. Populated by
-    # `ScopeIndexer` for both the constant-assigned form
-    # (`Point = Data.define(:x, :y)`) and the named-subclass form
-    # (`class Point < Data.define(:x, :y)`). Consumed by
-    # {Inference::MethodDispatcher::DataFolding} so `Point.new(...)` on a
-    # `Singleton[Point]` receiver materialises a precise member instance.
-    # Returns nil when the class has no recorded layout.
+    # ADR-48 — per-class table mapping a fully qualified class name to its ordered `Data.define` / `Struct.new`
+    # member-name list. Populated by `ScopeIndexer` for both the constant-assigned form
+    # (`Point = Data.define(:x, :y)`) and the named-subclass form (`class Point < Data.define(:x, :y)`). Consumed
+    # by {Inference::MethodDispatcher::DataFolding} so `Point.new(...)` on a `Singleton[Point]` receiver
+    # materialises a precise member instance. Returns nil when the class has no recorded layout.
     def data_member_layout(class_name)
       layout = @discovery.data_member_layouts[class_name.to_s]
-      # Record the ancestry dependency only on a hit — DataFolding consults
-      # this for every `Singleton[*].new`, and a miss (the common case: an
-      # ordinary class) must not manufacture a spurious cross-file edge.
+      # Record the ancestry dependency only on a hit — DataFolding consults this for every `Singleton[*].new`,
+      # and a miss (the common case: an ordinary class) must not manufacture a spurious cross-file edge.
       record_class_dependency(class_name) if layout && Analysis::DependencyRecorder.active?
       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.
+    # 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
-    # mixin call. Populated by `ScopeIndexer` (per-file plus
-    # the cross-file pre-pass) and consumed by
-    # `ExpressionTyper#resolve_user_def_through_ancestors` so an
-    # implicit-self call resolves against an included module's
-    # `def`s, not just the superclass chain. As-written names
-    # are resolved to qualified classes at walk time.
+    # 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 mixin call. Populated by `ScopeIndexer` (per-file
+    # plus the cross-file pre-pass) and consumed by `ExpressionTyper#resolve_user_def_through_ancestors` so an
+    # implicit-self call resolves against an included module's `def`s, not just the superclass chain. As-written
+    # names are resolved to qualified classes at walk time.
     def includes_of(class_name)
       record_class_dependency(class_name) if Analysis::DependencyRecorder.active?
       @discovery.discovered_includes[class_name.to_s] || []
     end
 
-    # Records, for a resolved cross-class ancestry read, every file that
-    # declares `class_name` (its declaration / reopening / superclass /
-    # include sites). The `discovered_class_sources` table it reads is
-    # populated only by the cross-file project pre-pass
-    # ({Inference::ScopeIndexer.discovered_def_index_for_paths}) and only
-    # when dependency recording is active. No-op when the class is not a
-    # project class (core / stdlib / gem names never appear in the source
-    # map). Gated by the caller on the recorder being active.
+    # Records, for a resolved cross-class ancestry read, every file that declares `class_name` (its declaration /
+    # reopening / superclass / include sites). The `discovered_class_sources` table it reads is populated only by
+    # the cross-file project pre-pass ({Inference::ScopeIndexer.discovered_def_index_for_paths}) and only when
+    # dependency recording is active. No-op when the class is not a project class (core / stdlib / gem names
+    # never appear in the source map). Gated by the caller on the recorder being active.
     def record_class_dependency(class_name)
       sites = @discovery.discovered_class_sources[class_name.to_s]
       return if sites.nil?
@@ -563,15 +503,11 @@ module Rigor
     end
     private :record_class_dependency
 
-    # v0.1.2 — per-class table mapping `method_name (Symbol) →
-    # :public | :private | :protected`. Populated by
-    # `ScopeIndexer` for every `def` it sees inside a class
-    # body, with the visibility taken from the surrounding
-    # `private` / `protected` / `public` modifier state plus
-    # any post-hoc `private :name, ...` named-argument calls.
-    # Consumed by the `def.method-visibility-mismatch` rule
-    # so explicit-non-self calls to a private method surface
-    # a diagnostic.
+    # v0.1.2 — per-class table mapping `method_name (Symbol) → :public | :private | :protected`. Populated by
+    # `ScopeIndexer` for every `def` it sees inside a class body, with the visibility taken from the surrounding
+    # `private` / `protected` / `public` modifier state plus any post-hoc `private :name, ...` named-argument
+    # calls. Consumed by the `def.method-visibility-mismatch` rule so explicit-non-self calls to a private method
+    # surface a diagnostic.
     def discovered_method_visibility(class_name, method_name)
       table = @discovery.discovered_method_visibilities[class_name.to_s]
       return nil unless table
@@ -579,15 +515,11 @@ module Rigor
       table[method_name.to_sym]
     end
 
-    # Closes the "`params[:f] ||= []; params[:f] << x`" precision
-    # gap (ROADMAP § Type-language / engine — indexed-collection
-    # narrowing through `Hash[k] ||= default`). After
-    # `receiver[key] ||= default`, the next read at `receiver[key]`
-    # is known non-nil; recording the post-`||=` type keyed on
-    # `(receiver_kind, receiver_name, literal_key)` lets the
-    # ExpressionTyper's `[]` dispatch hand back the narrowed
-    # type. Receiver-rebind and `[]=`/mutator invalidation rules
-    # are documented at the call sites in
+    # Closes the "`params[:f] ||= []; params[:f] << x`" precision gap (ROADMAP § Type-language / engine —
+    # indexed-collection narrowing through `Hash[k] ||= default`). After `receiver[key] ||= default`, the next
+    # read at `receiver[key]` is known non-nil; recording the post-`||=` type keyed on
+    # `(receiver_kind, receiver_name, literal_key)` lets the ExpressionTyper's `[]` dispatch hand back the
+    # narrowed type. Receiver-rebind and `[]=`/mutator invalidation rules are documented at the call sites in
     # `Inference::StatementEvaluator`.
     def indexed_narrowing(receiver_kind, receiver_name, key)
       @indexed_narrowings[indexed_key(receiver_kind, receiver_name, key)]
@@ -615,16 +547,12 @@ module Rigor
       rebuild(indexed_narrowings: new_table)
     end
 
-    # Closes the "stable receiver method-chain narrowing" gap
-    # (ROADMAP § Future cycles / Type-language / engine —
-    # "Method-call receiver narrowing across stable receivers";
-    # 2026-05-28 Redmine survey). After `if x.last.is_a?(Array)`
-    # the dominated body's `x.last` reads MUST observe the
-    # truthy-narrowed type; the same chain reaching the falsey
-    # edge observes the negative narrowing.
+    # Closes the "stable receiver method-chain narrowing" gap (ROADMAP § Future cycles / Type-language / engine —
+    # "Method-call receiver narrowing across stable receivers"; 2026-05-28 Redmine survey). After
+    # `if x.last.is_a?(Array)` the dominated body's `x.last` reads MUST observe the truthy-narrowed type; the same
+    # chain reaching the falsey edge observes the negative narrowing.
     #
-    # Address shape mirrors {.indexed_narrowing}: stable root
-    # variable + no-arg single-hop method name. See
+    # Address shape mirrors {.indexed_narrowing}: stable root variable + no-arg single-hop method name. See
     # {ChainKey} for the precise contract.
     def method_chain_narrowing(receiver_kind, receiver_name, method_name)
       @method_chain_narrowings[chain_key(receiver_kind, receiver_name, method_name)]
@@ -664,23 +592,19 @@ module Rigor
       Inference::ExpressionTyper.new(scope: self, tracer: tracer).type_of(node)
     end
 
-    # Statement-level evaluation: returns the pair `[type, scope']`
-    # where `type` is what the node produces and `scope'` is the
-    # scope observable after the node has run. The receiver scope is
-    # never mutated. See {Rigor::Inference::StatementEvaluator} for
-    # the catalogue of nodes that thread scope; everything else
-    # defers to {#type_of} and returns the receiver scope unchanged.
+    # Statement-level evaluation: returns the pair `[type, scope']` where `type` is what the node produces and
+    # `scope'` is the scope observable after the node has run. The receiver scope is never mutated. See
+    # {Rigor::Inference::StatementEvaluator} for the catalogue of nodes that thread scope; everything else defers
+    # to {#type_of} and returns the receiver scope unchanged.
     def evaluate(node, tracer: nil)
       Inference::StatementEvaluator.new(scope: self, tracer: tracer).evaluate(node)
     end
 
-    # Joins this scope with another at a control-flow merge point. The
-    # joined scope is bound to every local that BOTH branches bind, with
-    # the type widened to the union of both sides. Names bound in only
-    # one branch are dropped from the joined scope; the eventual
-    # statement-level evaluator (Slice 3 phase 2) is responsible for
-    # nil-injecting half-bound names where the language semantics demand
-    # it. The two scopes MUST share the same Environment.
+    # Joins this scope with another at a control-flow merge point. The joined scope is bound to every local that
+    # BOTH branches bind, with the type widened to the union of both sides. Names bound in only one branch are
+    # dropped from the joined scope; the eventual statement-level evaluator (Slice 3 phase 2) is responsible for
+    # nil-injecting half-bound names where the language semantics demand it. The two scopes MUST share the same
+    # Environment.
     def join(other)
       raise ArgumentError, "join requires a Rigor::Scope, got #{other.class}" unless other.is_a?(Scope)
 
@@ -725,7 +649,9 @@ module Rigor
       declaration_sourced: @declaration_sourced,
       source_path: @source_path,
       struct_fold_safe_locals: @struct_fold_safe_locals,
-      dynamic_origins: @dynamic_origins
+      dynamic_origins: @dynamic_origins,
+      local_origins: @local_origins,
+      ivar_origins: @ivar_origins
     )
       self.class.new(
         environment: environment, locals: locals,
@@ -737,16 +663,16 @@ module Rigor
         declaration_sourced: declaration_sourced,
         source_path: source_path,
         struct_fold_safe_locals: struct_fold_safe_locals,
-        dynamic_origins: dynamic_origins
+        dynamic_origins: dynamic_origins,
+        local_origins: local_origins,
+        ivar_origins: ivar_origins
       )
     end
 
     def join_bindings(left, right)
-      # Keys present in both, unioned. Iterating `left` and probing
-      # `right.key?` yields the same keys in the same order as the prior
-      # `(left.keys & right.keys)` while avoiding the two key arrays and
-      # the intersection array — this is the control-flow join, run at
-      # every branch merge, and was a top allocation site (~75% of
+      # Keys present in both, unioned. Iterating `left` and probing `right.key?` yields the same keys in the same
+      # order as the prior `(left.keys & right.keys)` while avoiding the two key arrays and the intersection
+      # array — this is the control-flow join, run at every branch merge, and was a top allocation site (~75% of
       # `Hash#keys`).
       result = {}
       left.each do |name, ltype|
@@ -769,16 +695,35 @@ module Rigor
         discovery: @discovery,
         indexed_narrowings: join_bindings(@indexed_narrowings, other.indexed_narrowings),
         method_chain_narrowings: join_bindings(@method_chain_narrowings, other.method_chain_narrowings),
-        # ADR-58 WD1 — a ref is declaration-sourced after a join only when
-        # BOTH branches agree it is. If either path made the binding
-        # flow-live (a method-local nil write / failed-guard narrowing), the
-        # merge is flow-live and `possible-nil-receiver` fires as before.
+        # ADR-58 WD1 — a ref is declaration-sourced after a join only when BOTH branches agree it is. If either
+        # path made the binding flow-live (a method-local nil write / failed-guard narrowing), the merge is
+        # flow-live and `possible-nil-receiver` fires as before.
         declaration_sourced: join_declaration_sourced(other),
         source_path: source_path,
-        dynamic_origins: @dynamic_origins
+        dynamic_origins: @dynamic_origins,
+        local_origins: join_origins(@local_origins, other.local_origins),
+        ivar_origins: join_origins(@ivar_origins, other.ivar_origins)
       )
     end
 
+    # ADR-82 WD1 — merge two branches' propagated origins (self wins on a name conflict; advisory metadata, so
+    # a disagreement is harmless). Zero-alloc when either side is empty — the common case, keeping the join
+    # hot-path cost negligible.
+    def join_origins(mine, theirs)
+      return mine if mine.equal?(theirs) || theirs.empty?
+      return theirs if mine.empty?
+
+      theirs.merge(mine).freeze
+    end
+
+    # ADR-82 WD1 — rebinding drops any propagated origin for the name (the new value's provenance is set
+    # afterward by `with_local_origin` when it is a `Dynamic` with a recorded cause). Zero-alloc when the name
+    # carries no origin — the overwhelming common case, so this stays off the with_local hot-path budget.
+    def drop_origin(origins, name)
+      key = name.to_sym
+      origins.key?(key) ? origins.reject { |k, _| k == key }.freeze : origins
+    end
+
     def join_declaration_sourced(other)
       return @declaration_sourced if @declaration_sourced.equal?(other.declaration_sourced)
       return EMPTY_DECLARATION_SOURCED if @declaration_sourced.empty? || other.declaration_sourced.empty?