rigortype 0.1.11 → 0.1.12

data/lib/rigor/inference/narrowing.rb

@@ -1371,16 +1371,12 @@ module Rigor
         # can resolve to a qualified class name. Anything else falls
         # through to "no narrowing".
         def analyse_class_predicate(node, scope, exact:)
-          return nil unless node.receiver.is_a?(Prism::LocalVariableReadNode)
           return nil if node.arguments.nil?
           return nil unless node.arguments.arguments.size == 1
 
           bare_name = static_class_name(node.arguments.arguments.first)
           return nil if bare_name.nil?
 
-          current = scope.local(node.receiver.name)
-          return nil if current.nil?
-
           # Resolve `bare_name` through the lexical-scope chain
           # so a name shadowed by the current class / enclosing
           # module wins over the top-level constant. Mirrors
@@ -1392,9 +1388,81 @@ module Rigor
           # surface as a spurious `undefined-method` on
           # subsequent `other.class_name` calls).
           class_name = resolve_class_name_lexically(bare_name, scope)
+
+          case node.receiver
+          when Prism::LocalVariableReadNode
+            analyse_class_predicate_on_local(node, scope, class_name, exact)
+          when Prism::CallNode
+            analyse_class_predicate_on_chain(node, scope, class_name, exact)
+          end
+        end
+
+        def analyse_class_predicate_on_local(node, scope, class_name, exact)
+          current = scope.local(node.receiver.name)
+          return nil if current.nil?
+
           class_predicate_scopes(scope, node.receiver.name, current, class_name, exact: exact)
         end
 
+        # Stable single-hop method-chain narrowing (ROADMAP §
+        # Future cycles — "Method-call receiver narrowing across
+        # stable receivers"). When the predicate's receiver is
+        # `<local/ivar>.<method>` with no args and no block,
+        # record the truthy / falsey narrowing in
+        # `Scope#method_chain_narrowings` keyed on the chain
+        # address. The dominated body's identical chain reads
+        # then observe the narrowed type through
+        # `ExpressionTyper#call_type_for`'s lookup.
+        #
+        # Heuristic-by-design (ROADMAP § "Soundness gap"): a
+        # second call to `x.last` could in principle return a
+        # different value than the first. The chain is dropped
+        # on (1) receiver variable rebind (handled inside
+        # `Scope#with_local` / `#with_ivar`), and (2) any
+        # intervening call against the same root receiver
+        # (handled by `StatementEvaluator#eval_call`'s
+        # invalidation step). The Law of Demeter justifies the
+        # single-hop restriction: a single-hop chain is the
+        # idiomatic Ruby shape where re-evaluation soundness is
+        # the strongest.
+        def analyse_class_predicate_on_chain(node, scope, class_name, exact)
+          address = stable_chain_address(node.receiver)
+          return nil if address.nil?
+
+          current = scope.type_of(node.receiver)
+          return nil if current.nil?
+
+          truthy_type = narrow_class(current, class_name, exact: exact, environment: scope.environment)
+          falsey_type = narrow_not_class(current, class_name, exact: exact, environment: scope.environment)
+
+          [
+            scope.with_method_chain_narrowing(*address, truthy_type),
+            scope.with_method_chain_narrowing(*address, falsey_type)
+          ]
+        end
+
+        # Returns `[receiver_kind, receiver_name, method_name]`
+        # iff `chain_call` is a stable single-hop chain whose
+        # root is a local / ivar read and whose own call shape
+        # has no positional arguments and no block. Other shapes
+        # (multi-hop, args, block, method-defined-on-arbitrary-
+        # receiver) lose stability for one of the reasons
+        # enumerated in the slice's design notes.
+        def stable_chain_address(chain_call)
+          return nil unless chain_call.is_a?(Prism::CallNode)
+          return nil unless chain_call.block.nil?
+
+          args = chain_call.arguments
+          return nil unless args.nil? || args.arguments.empty?
+
+          case chain_call.receiver
+          when Prism::LocalVariableReadNode
+            [:local, chain_call.receiver.name, chain_call.name]
+          when Prism::InstanceVariableReadNode
+            [:ivar, chain_call.receiver.name, chain_call.name]
+          end
+        end
+
         # Walks the lexical-nesting chain derived from
         # `scope.self_type` and returns the first
         # `<prefix>::<bare_name>` (or bare `<bare_name>` at the

data/lib/rigor/inference/scope_indexer.rb

@@ -4,6 +4,7 @@ require "prism"
 
 require_relative "../scope"
 require_relative "../type"
+require_relative "mutation_widening"
 require_relative "narrowing"
 require_relative "statement_evaluator"
 
@@ -126,7 +127,16 @@ module Rigor
         table = {}.compare_by_identity
         table.default = seeded_scope
 
-        on_enter = ->(node, scope) { table[node] = scope unless table.key?(node) }
+        # Last-visit-wins, not first: when `StatementEvaluator`
+        # internally re-evaluates a subtree (notably `eval_begin`'s
+        # retry-edge widening pass), the LATER visit carries the
+        # corrected entry scope (e.g. a `tries` widened to
+        # `Nominal[Integer]` after the rescue body's `tries += 1;
+        # retry` is observed). The diagnostic layer reads
+        # `table[node]` to type predicates; the second pass's
+        # entry is the one that reflects all flow-derived
+        # rebinds, so it MUST overwrite the first.
+        on_enter = ->(node, scope) { table[node] = scope }
         StatementEvaluator.new(scope: seeded_scope, on_enter: on_enter).evaluate(root)
 
         propagate(root, table, seeded_scope)
@@ -172,11 +182,135 @@ module Rigor
       # via `Type::Combinator.union`.
       def build_class_ivar_index(root, default_scope)
         accumulator = {}
-        walk_class_ivars(root, [], default_scope, accumulator)
+        mutated_ivars = {}
+        read_before_write = {}
+        init_writes = {}
+        walk_class_ivars(root, [], default_scope, accumulator, mutated_ivars,
+                         read_before_write, init_writes)
+        widen_mutated_ivar_entries!(accumulator, mutated_ivars)
+        contribute_read_before_write_nil!(accumulator, read_before_write, init_writes)
         accumulator.transform_values(&:freeze).freeze
       end
 
-      def walk_class_ivars(node, qualified_prefix, default_scope, accumulator)
+      # B2.3 — finalize the read-before-write nil contribution.
+      # For each class, for each ivar where SOME method body
+      # observed a read-before-write AND no `initialize` write
+      # exists for that ivar, contribute `Constant[nil]` to the
+      # class-wide accumulator.
+      #
+      # The `initialize` filter is the soundness gate: Ruby
+      # semantics guarantee `initialize` runs first (via
+      # `Class.new`), so a write there reaches every other
+      # method body's read. Read-before-write in a non-init
+      # method is then NOT a nil-at-runtime case — it's just
+      # AST-order coincidence. Without this filter a normal
+      # `def initialize; @x = ... end` / `def use; @x.foo end`
+      # class would have `@x` widened with nil, producing FPs
+      # at every `@x.foo` call.
+      def contribute_read_before_write_nil!(accumulator, read_before_write, init_writes)
+        nil_t = Type::Combinator.constant_of(nil)
+        read_before_write.each do |class_name, ivar_set|
+          init_set = init_writes[class_name] || EMPTY_GUARDED_IVARS
+          per_class = accumulator[class_name]
+          next if per_class.nil?
+
+          ivar_set.each do |ivar_name|
+            # Soundness gates (in order):
+            # (1) `initialize` writes the ivar → it's set
+            #     before any other method runs, so the
+            #     read-before-write in a sibling method is
+            #     NOT a runtime nil case.
+            # (2) The accumulator has NO entry for the ivar
+            #     → some write was deliberately skipped (the
+            #     falsey-default `@x = nil unless @x` slice's
+            #     no-seed behaviour). Adding nil here would
+            #     defeat that skip and re-introduce the
+            #     `Constant[nil]` FP the skip silenced.
+            next if init_set.include?(ivar_name)
+            next unless per_class.key?(ivar_name)
+
+            existing = per_class[ivar_name]
+            per_class[ivar_name] = Type::Combinator.union(existing, nil_t)
+          end
+        end
+      end
+
+      # Walks the post-collected accumulator and widens any Tuple
+      # / HashShape entry for an ivar that observed a mutator call
+      # anywhere in the same class body. The mutation evidence
+      # comes from `gather_ivar_writes` recording every
+      # `@ivar.<method>(...)` call whose method is in
+      # `MutationWidening::ARRAY_MUTATORS` or `HASH_MUTATORS`.
+      #
+      # The widening uses `MutationWidening.widen_for_mutator` —
+      # the same primitive `Inference::StatementEvaluator#eval_call`
+      # applies for per-method-body widening on a local / ivar
+      # receiver. The class-level pass extends that primitive's
+      # reach so a `Tuple`-seeded ivar in `initialize` is observed
+      # as `Nominal[Array]` at the entry of every OTHER method
+      # body in the class — closing the cross-method gap noted in
+      # ROADMAP § Future cycles / Type-language / engine
+      # ("Tuple / HashShape widening for ivar-seeded literals
+      # after mutation"; Redmine 6.1.2
+      # `Redmine::Views::Builders::Structure` is the canonical
+      # worked site).
+      #
+      # Always-safe: the widening can only LOSE precision; the
+      # underlying nominal (`Array` / `Hash`) and the element
+      # union are preserved.
+      def widen_mutated_ivar_entries!(accumulator, mutated_ivars)
+        accumulator.each do |class_name, ivars|
+          observed = mutated_ivars[class_name]
+          next if observed.nil? || observed.empty?
+
+          ivars.each do |ivar_name, type|
+            methods = observed[ivar_name]
+            next if methods.nil? || methods.empty?
+
+            ivars[ivar_name] = widen_type_for_observed_mutators(type, methods)
+          end
+        end
+      end
+
+      # Walks a class-ivar accumulator entry (which may be a
+      # `Union` of multiple write rvalues) and widens any
+      # `Tuple` or `HashShape` member whose corresponding
+      # mutator family was observed against the ivar somewhere
+      # in the class. Class-level widening is more aggressive
+      # than the per-method-body `MutationWidening` primitive:
+      # it widens both the SHAPE carrier (Tuple → Array,
+      # HashShape → Hash) AND the element types to
+      # `Dynamic[Top]`. The justification — once any method
+      # mutates the ivar, its post-mutation contents are
+      # statically unknown across method boundaries, so
+      # preserving the seed-write's element precision would be
+      # an unsound over-claim (e.g. `@struct = [{}]; somewhere:
+      # @struct << []` makes the next read's element no longer
+      # `Constant[{}]`).
+      def widen_type_for_observed_mutators(type, observed_methods)
+        members = type.is_a?(Type::Union) ? type.members : [type]
+        widened = members.map { |m| widen_member_for_observed_mutators(m, observed_methods) }
+        Type::Combinator.union(*widened)
+      end
+
+      def widen_member_for_observed_mutators(member, observed_methods)
+        case member
+        when Type::Tuple
+          return member unless observed_methods.any? { |m| MutationWidening::ARRAY_MUTATORS.include?(m) }
+
+          Type::Combinator.nominal_of("Array", type_args: [Type::Combinator.untyped])
+        when Type::HashShape
+          return member unless observed_methods.any? { |m| MutationWidening::HASH_MUTATORS.include?(m) }
+
+          Type::Combinator.nominal_of("Hash",
+                                      type_args: [Type::Combinator.untyped, Type::Combinator.untyped])
+        else
+          member
+        end
+      end
+
+      def walk_class_ivars(node, qualified_prefix, default_scope, accumulator, mutated_ivars,
+                           read_before_write = nil, init_writes = nil)
         return unless node.is_a?(Prism::Node)
 
         case node
@@ -184,20 +318,42 @@ module Rigor
           name = qualified_name_for(node.constant_path)
           if name
             child_prefix = qualified_prefix + [name]
-            walk_class_ivars(node.body, child_prefix, default_scope, accumulator) if node.body
+            if node.body
+              # Class-body level `@x = nil` writes don't
+              # initialise instance ivars at runtime (the
+              # class's own singleton ivars and the instance's
+              # ivars are separate stores), but they signal
+              # "the author KNOWS @x could be nil" and extend
+              # the B2.3 soundness gate: an ivar with a
+              # class-body write is exempted from the
+              # read-before-write nil contribution because the
+              # seed already reflects the author's acknowledged
+              # nullability via the def-body writes' union.
+              # Without this exemption, code that explicitly
+              # `@x = nil`s at class-body level then writes
+              # `@x = SomeClass.new` inside an instance method
+              # gains an unjustified nil widening at every
+              # read.
+              collect_class_body_ivar_writes(node.body, child_prefix.join("::"), init_writes) if init_writes
+              walk_class_ivars(node.body, child_prefix, default_scope, accumulator,
+                               mutated_ivars, read_before_write, init_writes)
+            end
             return
           end
         when Prism::DefNode
-          collect_def_ivar_writes(node, qualified_prefix, default_scope, accumulator)
+          collect_def_ivar_writes(node, qualified_prefix, default_scope, accumulator,
+                                  mutated_ivars, read_before_write, init_writes)
           return
         end
 
         node.compact_child_nodes.each do |child|
-          walk_class_ivars(child, qualified_prefix, default_scope, accumulator)
+          walk_class_ivars(child, qualified_prefix, default_scope, accumulator,
+                           mutated_ivars, read_before_write, init_writes)
         end
       end
 
-      def collect_def_ivar_writes(def_node, qualified_prefix, default_scope, accumulator)
+      def collect_def_ivar_writes(def_node, qualified_prefix, default_scope, accumulator, mutated_ivars,
+                                  read_before_write = nil, init_writes = nil)
         return if def_node.body.nil? || qualified_prefix.empty?
 
         class_name = qualified_prefix.join("::")
@@ -211,32 +367,273 @@ module Rigor
           end
         body_scope = default_scope.with_self_type(self_type)
 
-        gather_ivar_writes(def_node.body, body_scope, class_name, accumulator)
+        gather_ivar_writes(def_node.body, body_scope, class_name, accumulator, EMPTY_GUARDED_IVARS, mutated_ivars)
+
+        # B2.3 — collect per-method evidence for the read-before-
+        # write nil contribution. The accumulator-level decision
+        # ("is this ivar truly read-before-write across the
+        # class lifetime?") is finalised at
+        # `contribute_read_before_write_nil!` after the whole
+        # class body has been walked, using `init_writes` as
+        # the soundness gate (an ivar written in `initialize`
+        # is initialised before any other method body runs).
+        collect_read_before_write_evidence(def_node, class_name, read_before_write, init_writes)
+      end
+
+      # Walks the method body in AST (== execution) order
+      # tracking ivar names whose first reference is a read.
+      # The set is unioned into the class-wide
+      # `read_before_write` accumulator. For `initialize` def
+      # bodies, every write target is unioned into
+      # `init_writes` instead — used by the finalisation step
+      # to suppress nil contribution for ivars the constructor
+      # guarantees are initialised.
+      def collect_read_before_write_evidence(def_node, class_name, read_before_write, init_writes)
+        return if read_before_write.nil? || init_writes.nil?
+
+        seen_writes = Set.new
+        read_first = Set.new
+        detect_read_before_write(def_node.body, seen_writes, read_first)
+
+        if def_node.name == :initialize
+          init_set = (init_writes[class_name] ||= Set.new)
+          seen_writes.each { |name| init_set << name }
+          return
+        end
+
+        return if read_first.empty?
+
+        rbw_set = (read_before_write[class_name] ||= Set.new)
+        read_first.each { |name| rbw_set << name }
+      end
+
+      IVAR_WRITE_NODES = [
+        Prism::InstanceVariableWriteNode,
+        Prism::InstanceVariableOrWriteNode,
+        Prism::InstanceVariableAndWriteNode,
+        Prism::InstanceVariableOperatorWriteNode
+      ].freeze
+      private_constant :IVAR_WRITE_NODES
+
+      # Walks class-body level statements (i.e. NOT inside any
+      # nested DefNode / ClassNode / ModuleNode) and records
+      # every `@x = …` write target as a class-body init.
+      # Consumed by `contribute_read_before_write_nil!` to
+      # exempt ivars the author already knows might be nil
+      # (the `@x = nil` at class-body level is the canonical
+      # nullability acknowledgement; the instance @x is
+      # technically a separate store, but the pragmatic intent
+      # is unambiguous).
+      def collect_class_body_ivar_writes(node, class_name, init_writes)
+        return unless node.is_a?(Prism::Node)
+        return if IVAR_BARRIER_NODES.any? { |klass| node.is_a?(klass) }
+
+        if node.is_a?(Prism::InstanceVariableWriteNode) ||
+           node.is_a?(Prism::InstanceVariableOrWriteNode) ||
+           node.is_a?(Prism::InstanceVariableAndWriteNode) ||
+           node.is_a?(Prism::InstanceVariableOperatorWriteNode)
+          (init_writes[class_name] ||= Set.new) << node.name
+        end
+
+        node.compact_child_nodes.each do |child|
+          collect_class_body_ivar_writes(child, class_name, init_writes)
+        end
+      end
+
+      def detect_read_before_write(node, seen_writes, read_first)
+        return unless node.is_a?(Prism::Node)
+        return if IVAR_BARRIER_NODES.any? { |klass| node.is_a?(klass) }
+
+        read_first << node.name if node.is_a?(Prism::InstanceVariableReadNode) && !seen_writes.include?(node.name)
+
+        # Descend BEFORE recording a write — `@x = @x + 1`'s
+        # RHS is an `InstanceVariableReadNode` that runs before
+        # the write is committed; the read is therefore
+        # read-before-write semantically. Prism's
+        # `compact_child_nodes` returns the value child before
+        # the lvalue target, matching this order.
+        node.compact_child_nodes.each do |c|
+          detect_read_before_write(c, seen_writes, read_first)
+        end
+
+        seen_writes << node.name if IVAR_WRITE_NODES.any? { |klass| node.is_a?(klass) }
       end
 
       IVAR_BARRIER_NODES = [Prism::DefNode, Prism::ClassNode, Prism::ModuleNode].freeze
       private_constant :IVAR_BARRIER_NODES
 
-      def gather_ivar_writes(node, scope, class_name, accumulator)
+      EMPTY_GUARDED_IVARS = Set.new.freeze
+      private_constant :EMPTY_GUARDED_IVARS
+
+      def gather_ivar_writes(node, scope, class_name, accumulator, guarded_ivars = EMPTY_GUARDED_IVARS,
+                             mutated_ivars = nil)
         return unless node.is_a?(Prism::Node)
 
-        record_ivar_write(node, scope, class_name, accumulator) if node.is_a?(Prism::InstanceVariableWriteNode)
+        if node.is_a?(Prism::InstanceVariableWriteNode)
+          record_ivar_write(node, scope, class_name, accumulator,
+                            guarded: guarded_ivars.include?(node.name))
+        end
+        record_ivar_mutator_call(node, class_name, mutated_ivars) if mutated_ivars && node.is_a?(Prism::CallNode)
 
         # Don't recurse into nested defs, classes, or modules; their
         # ivars belong to their own enclosing class.
         return if IVAR_BARRIER_NODES.any? { |klass| node.is_a?(klass) }
 
-        node.compact_child_nodes.each { |c| gather_ivar_writes(c, scope, class_name, accumulator) }
+        if node.is_a?(Prism::IfNode) || node.is_a?(Prism::UnlessNode)
+          walk_conditional_ivar_writes(node, scope, class_name, accumulator, guarded_ivars, mutated_ivars)
+          return
+        end
+
+        node.compact_child_nodes.each do |c|
+          gather_ivar_writes(c, scope, class_name, accumulator, guarded_ivars, mutated_ivars)
+        end
+      end
+
+      # Records `@ivar.<method>(...)` calls whose method is in
+      # `MutationWidening::ARRAY_MUTATORS` or `HASH_MUTATORS`.
+      # The class-ivar pre-pass uses the resulting set to widen
+      # the post-collected accumulator entries (see
+      # {.widen_mutated_ivar_entries!}). Always-safe to over-
+      # collect: any name that the widening primitive declines
+      # is ignored at finalization.
+      def record_ivar_mutator_call(node, class_name, mutated_ivars)
+        receiver = node.receiver
+        return unless receiver.is_a?(Prism::InstanceVariableReadNode)
+        return unless MutationWidening::ARRAY_MUTATORS.include?(node.name) ||
+                      MutationWidening::HASH_MUTATORS.include?(node.name)
+
+        per_class = (mutated_ivars[class_name] ||= {})
+        per_ivar = (per_class[receiver.name] ||= Set.new)
+        per_ivar << node.name
+      end
+
+      # Walk an `IfNode` / `UnlessNode` so writes inside the THEN body
+      # that look like defensive ivar initialisation gain a `nil` union
+      # in the seeded type. Without this, `@x = v unless @x` records
+      # `Constant[v]` for `@x`, then the predicate folds to that same
+      # constant and `flow.always-truthy-condition` fires against a
+      # working program. Mirrors the existing skip for `@x ||= v`
+      # (`Prism::InstanceVariableOrWriteNode`, which the pre-pass does
+      # not seed at all).
+      #
+      # Polarity-aware on purpose: only the THEN body picks up the
+      # guard. The ELSE branch of `if @x; ...; else; @x = init; end`
+      # would otherwise be marked too — but that pattern (write @x in
+      # the else of `if @x`) is a separate idiom whose surrounding
+      # reads of `@x` would then surface a nil-receiver FP. The
+      # ELSE branch is left ungarded so those reads continue to type
+      # as they did before this fix.
+      def walk_conditional_ivar_writes(node, scope, class_name, accumulator, guarded_ivars, mutated_ivars = nil)
+        then_guards = then_body_guarded_ivars(node)
+        then_guarded = then_guards.empty? ? guarded_ivars : (guarded_ivars | then_guards)
+
+        gather_ivar_writes(node.predicate, scope, class_name, accumulator, guarded_ivars, mutated_ivars)
+        if node.statements
+          gather_ivar_writes(node.statements, scope, class_name, accumulator, then_guarded, mutated_ivars)
+        end
+        branch = node.is_a?(Prism::IfNode) ? node.subsequent : node.else_clause
+        gather_ivar_writes(branch, scope, class_name, accumulator, guarded_ivars, mutated_ivars) if branch
+      end
+
+      # Returns the set of ivar names that, in the THEN body of this
+      # conditional, are statically known to be in a nil / unset state
+      # — i.e. the body really IS the defensive-init half of the
+      # idiom. Conservative on purpose: only the shapes that
+      # idiomatically express "the ivar is missing" qualify.
+      #
+      # For `unless P; body; end`, body runs when `P` is falsey:
+      #   - `P = @x` (or `@x && other` / `@x || other`)            → @x is falsey
+      #   - `P = defined?(@x)`                                     → @x is undefined
+      #
+      # For `if P; body; ...`, body runs when `P` is truthy:
+      #   - `P = @x.nil?`                                          → @x is nil
+      #   - `P = !@x` / `not @x`                                   → @x is falsey
+      def then_body_guarded_ivars(node)
+        names = Set.new
+        if node.is_a?(Prism::UnlessNode)
+          collect_truthy_test_ivars(node.predicate, names)
+          collect_defined_test_ivars(node.predicate, names)
+        else
+          collect_nil_test_ivars(node.predicate, names)
+        end
+        names
+      end
+
+      def collect_truthy_test_ivars(node, names)
+        return unless node.is_a?(Prism::Node)
+
+        case node
+        when Prism::InstanceVariableReadNode
+          names << node.name
+        when Prism::AndNode, Prism::OrNode
+          collect_truthy_test_ivars(node.left, names)
+          collect_truthy_test_ivars(node.right, names)
+        end
+      end
+
+      def collect_defined_test_ivars(node, names)
+        return unless node.is_a?(Prism::Node)
+
+        case node
+        when Prism::DefinedNode
+          target = node.value
+          names << target.name if target.is_a?(Prism::InstanceVariableReadNode)
+        when Prism::AndNode, Prism::OrNode
+          collect_defined_test_ivars(node.left, names)
+          collect_defined_test_ivars(node.right, names)
+        end
+      end
+
+      def collect_nil_test_ivars(node, names)
+        return unless node.is_a?(Prism::Node)
+
+        case node
+        when Prism::CallNode
+          receiver = node.receiver
+          if receiver.is_a?(Prism::InstanceVariableReadNode) &&
+             %i[nil? !].include?(node.name)
+            names << receiver.name
+          end
+        when Prism::AndNode, Prism::OrNode
+          collect_nil_test_ivars(node.left, names)
+          collect_nil_test_ivars(node.right, names)
+        end
       end
 
-      def record_ivar_write(node, scope, class_name, accumulator)
+      def record_ivar_write(node, scope, class_name, accumulator, guarded: false)
         rvalue_type = scope.type_of(node.value)
+
+        # `@x = nil unless @x` / `@y = false unless @y` —
+        # follow-up to the polarity-aware defensive-init guard
+        # fix (ROADMAP § Future cycles — "Defensive ivar-init
+        # with nil / false rvalue"). When the rvalue is itself a
+        # falsey Constant, `union(rvalue, Constant[nil])`
+        # collapses (for `nil`) or doesn't widen the type's
+        # truthiness profile (for `false`) — the predicate
+        # `unless @x` then folds to a single `Constant[nil]` /
+        # `Constant[false]` and the
+        # `flow.always-truthy-condition` / `-always-falsey-`
+        # rule false-fires on the no-op-but-documented-default
+        # idiom. Skip the seed contribution for this write
+        # (matches the existing skip for `@x ||= v`, which the
+        # pre-pass also does not seed). Other writes to the
+        # same ivar still contribute; the falsey-default write
+        # carries no useful precision the predicate hasn't
+        # already given us. See tdiary-core HEAD `ee40c2b`
+        # `lib/tdiary/configuration.rb:157` for the worked site.
+        return if guarded && falsey_constant?(rvalue_type)
+
+        rvalue_type = Type::Combinator.union(rvalue_type, Type::Combinator.constant_of(nil)) if guarded
         accumulator[class_name] ||= {}
         existing = accumulator[class_name][node.name]
         accumulator[class_name][node.name] =
           existing ? Type::Combinator.union(existing, rvalue_type) : rvalue_type
       end
 
+      def falsey_constant?(type)
+        type.is_a?(Type::Constant) && (type.value.nil? || type.value == false)
+      end
+
       # Slice 7 phase 6 — class-cvar pre-pass. Same shape as the
       # ivar pre-pass but collects `Prism::ClassVariableWriteNode`
       # writes inside ANY def body (instance or singleton) of the