rigortype 0.3.9 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 857b76366640c2aa188649c7fe6af483d599bc05e5f185c4d8285b093c092fdd
-  data.tar.gz: 8e281f8668221704dd74c0b8d942830f6e58b252135db54142a70543bcfdf839
+  metadata.gz: 96e337b134c8bcb33bf20707e88ffbe16ff98b94513d483043e18432d9bf6328
+  data.tar.gz: e46a5af02a699ef2d0ad41e7b8b94e2d5eac02d1085d30fc03831df208ef930e
 SHA512:
-  metadata.gz: aaea4bc6f1073c80307375365f111ba58c198cef0852a63abe5476c1ffa937754b0e45a506b69a052e685724d24fa44689f4f8bfb375f902b7e53521eea7ae4d
-  data.tar.gz: 846d488914e0046afce19772fa8295ab99b068acf8e94a04d57590f9feb7718ebca29858ca78f47435a1542e7c1c8cbf000ca983619b3ebdb684650f8c8fc7aa
+  metadata.gz: cc7a7cadf53373e66de5ff268b2a44452d42972cbd9c1683825e2809480573bf195d9c26252d0522ddac2ae3f39f9dc665768d61cbb7c6e63ee6d60eaa17b87a
+  data.tar.gz: 05b82b8662a6e5b0283a04eca851d0bb6aa1031f55fd1e99525c5b884e433a30b89d519486f6fceebca95e47a306f721766adecc13d4c68134c833e9e525304a

data/README.md

@@ -231,8 +231,8 @@ rigor docs --list                 # list every bundled page
 
 ## Status
 
-Current release: **`v0.3.9`** (2026-09-12) — on the
-`0.3.x` line, continuing the evaluation era opened by `v0.2.0`, the first
+Current release: **`v0.4.0`** (2026-09-27) — opening the
+`0.4.x` line, continuing the evaluation era opened by `v0.2.0`, the first
 publicly-announced (general / evaluation) release. The line publishes
 an enumerated [compatibility surface](docs/compatibility.md) as a
 minor-non-break trial, rehearsing the contract that hard-freezes at

data/data/core_overlay/enumerable.rbs

@@ -0,0 +1,51 @@
+# Rigor core overlay — supplemental core signatures.
+#
+# --- Enumerable#detect with an ifnone argument ---
+#
+# CRuby binds `detect` and `find` to one C function (`enum.c`:
+# `rb_define_method(rb_mEnumerable, "detect", enum_find, -1)`), so
+# `detect(ifnone)` answers `ifnone.call` when no element matches, exactly as
+# `find(ifnone)` does. Upstream `ruby/rbs` declares the two apart, and only
+# `find` carries the fallback arm:
+#
+#   def find: () { (Elem) -> boolish } -> Elem?
+#           | () -> ::Enumerator[Elem, Elem?]
+#           | [T] (_NotFound[T] ifnone) { (Elem) -> boolish } -> (Elem | T)
+#           | [T] (_NotFound[T] ifnone) -> ::Enumerator[Elem, Elem | T]
+#   def detect: (?Proc ifnone) { (Elem) -> boolish } -> Elem?
+#             | (?Proc ifnone) -> ::Enumerator[Elem, Elem?]
+#
+# so `r = { a: 1 }.detect(-> { 0 }) { |k, v| v > 5 }` typed `[:a, 1]?`
+# although it is `0` at runtime, and `r + 1` reported
+# `call.possible-nil-receiver` on correct code. No core or stdlib class
+# declares a `detect` of its own except `Array`, which rbs 4.1 and later
+# alias to `Array#find`; `Hash`, `Range`, `Set`, `Struct`, `Enumerator`,
+# `Enumerator::Lazy` (whose lazy method table leaves `detect` eager), `IO`,
+# `Dir`, `ENV` and every other includer inherit this one, as does `Array`
+# before rbs 4.1.
+#
+# Upstream's `?Proc` parameter also rejected a valid fallback that is not a
+# `Proc` — `nil` (no fallback) or any object answering `call` — with
+# `call.argument-type-mismatch`. Such an argument reaches the `_NotFound[T]`
+# arms below, so `detect` checks its argument as `find` does.
+#
+# The overloads below are prepended to upstream's through `| ...` (rbs
+# unshifts a continuation's overloads, so they are tried first). The last two
+# are `find`'s ifnone arms. The first two restate them for a `Proc` argument:
+# `OverloadSelector`'s strict pass skips an interface-typed parameter such as
+# `_NotFound[T]`, so without them upstream's strictly typed `(?Proc ifnone)`
+# arm would win a lambda and answer `Elem?` again. A block-only
+# `detect { ... }` passes no argument, skips all four on arity, and keeps
+# upstream's `Elem?`.
+#
+# The continuation's base is in rbs core on every supported release, so the
+# file loads unconditionally. Once an upstream release aligns `detect` with
+# `find`, gate this file off that release through
+# `RbsLoader::RBS_LINE_CORE_OVERLAYS`, as `hash_rbs3.rbs` is.
+module Enumerable[unchecked out Elem]
+  def detect: [T] (^() -> T ifnone) { (Elem) -> boolish } -> (Elem | T)
+            | [T] (^() -> T ifnone) -> ::Enumerator[Elem, Elem | T]
+            | [T] (_NotFound[T] ifnone) { (Elem) -> boolish } -> (Elem | T)
+            | [T] (_NotFound[T] ifnone) -> ::Enumerator[Elem, Elem | T]
+            | ...
+end

data/data/core_overlay/enumerator.rbs

@@ -0,0 +1,84 @@
+# Rigor core overlay — supplemental core signatures.
+#
+# --- Enumerator::Lazy's redefined enumerable methods ---
+#
+# Issue #1121. `Enumerator::Lazy` is not merely an `Enumerator`: CRuby
+# redefines most of `Enumerable` on it so that the call CHAINS another lazy
+# enumerator instead of forcing the source (`enumerator.c`'s lazy method
+# table: `collect` / `map`, `find_all` / `select` / `filter`, `reject`,
+# `grep`, `grep_v`, `flat_map` / `collect_concat`, `take`, `take_while`,
+# `drop`, `drop_while`, `uniq`, `zip`, `filter_map`). Upstream `ruby/rbs`
+# declares none of them on `Enumerator::Lazy` — its whole body is `force`
+# plus `compact` and `eager` — so dispatch walks up to `Enumerable` and
+# adopts THAT class's eager return type:
+#
+#   [1, 2, 3].lazy.map { |x| x * 2 }   # Enumerable#map -> Array[U], not Lazy
+#
+# The receiver class is lost, and with it every terminal method only a lazy
+# enumerator answers: `…map { … }.force` / `.eager` report
+# `call.undefined-method` on correct code, on 124 `.lazy` sites in one
+# survey corpus (gitlab services and graphql, rails actiontext, sidekiq,
+# rubocop).
+#
+# The entries below mirror each upstream `Enumerable` declaration the lazy
+# method replaces, with the return rewritten to `Enumerator::Lazy`. Two
+# deliberate exclusions:
+#
+# * The single type argument spelling (`Enumerator::Lazy[U]`, not
+#   `[U, Return]`) mirrors upstream's own `Enumerable#lazy:
+#   () -> Enumerator::Lazy[Elem]` — the trailing `Return` parameter is
+#   defaulted (`void`), and Rigor binds the supplied prefix (see
+#   `docs/internal-spec/inference-engine.md` § generic dispatch).
+# * The no-block arms of the block-taking methods are NOT carried over.
+#   CRuby RAISES for a blockless `lazy.map` / `select` / `reject` /
+#   `find_all` / `take_while` ("tried to call lazy map without a block"), so
+#   the inherited `Enumerable` arm is a wrong answer for a lazy receiver
+#   rather than a harmless fallback.
+#
+# `zip` is left to `Enumerable` for now: its lazy form yields
+# `[elem, other_elem]` pairs through `_Each`, and the pair shape upstream
+# declares for the eager form is not what the lazy chain hands downstream.
+# `compact`, `eager` and `force` are upstream already and MUST NOT be
+# duplicated here — a second declaration of a method `rbs` core already
+# declares in this class is a `DuplicatedMethodDefinitionError`, which
+# degrades the whole class to `Dynamic[top]`. (`eager` in particular is
+# declared by rbs 4.x only; a `| ...` overload continuation that would
+# declare it on the 3.10 line as well raises `InvalidOverloadMethodError`
+# there, for the same whole-class cost, so `.eager` stays the 3.10 line's
+# own gap.)
+class Enumerator::Lazy[out E, out R = void]
+  def collect: [U] () { (E) -> U } -> Enumerator::Lazy[U]
+
+  def map: [U] () { (E) -> U } -> Enumerator::Lazy[U]
+
+  def find_all: () { (E) -> boolish } -> Enumerator::Lazy[E]
+
+  def select: () { (E) -> boolish } -> Enumerator::Lazy[E]
+
+  def filter: () { (E) -> boolish } -> Enumerator::Lazy[E]
+
+  def reject: () { (E) -> boolish } -> Enumerator::Lazy[E]
+
+  def filter_map: [U] () { (E) -> (nil | false | U) } -> Enumerator::Lazy[U]
+
+  def flat_map: [U] () { (E) -> (Array[U] | U) } -> Enumerator::Lazy[U]
+
+  def collect_concat: [U] () { (E) -> (Array[U] | U) } -> Enumerator::Lazy[U]
+
+  def take: (Integer n) -> Enumerator::Lazy[E]
+
+  def take_while: () { (E) -> boolish } -> Enumerator::Lazy[E]
+
+  def drop: (Integer n) -> Enumerator::Lazy[E]
+
+  def drop_while: () { (E) -> boolish } -> Enumerator::Lazy[E]
+
+  def uniq: () -> Enumerator::Lazy[E]
+          | () { (E item) -> untyped } -> Enumerator::Lazy[E]
+
+  def grep: (untyped pattern) -> Enumerator::Lazy[E]
+          | [U] (untyped pattern) { (E) -> U } -> Enumerator::Lazy[U]
+
+  def grep_v: (untyped pattern) -> Enumerator::Lazy[E]
+            | [U] (untyped pattern) { (E) -> U } -> Enumerator::Lazy[U]
+end

data/data/core_overlay/hash_rbs3.rbs

@@ -0,0 +1,41 @@
+# Rigor core overlay — supplemental core signatures, rbs 3.x line only.
+#
+# --- Hash#transform_keys / #transform_keys! with a replacements hash ---
+#
+# Ruby 3.0 added the replacements-hash argument
+# (`h.transform_keys({ a: :z }) { |k| k.to_s }`), and rbs 4.0 declares it.
+# Every rbs 3.x release declares only the blockless `Enumerator` form and
+# the block form, both with no positional parameter:
+#
+#   def transform_keys: () -> Enumerator[K, Hash[untyped, V]]
+#                     | [A] () { (K) -> A } -> Hash[A, V]
+#   def transform_keys!: () -> Enumerator[K, self]
+#                      | () { (K) -> K } -> self
+#
+# so under rbs 3.x a correct replacements call reports `call.wrong-arity`
+# ("given 1, expected 0"), and `transform_keys!` answers `Enumerator`
+# instead of the receiver.
+#
+# The overloads below are rbs 4.2's, prepended to 3.x's own through
+# `| ...`. `RbsLoader::RBS_LINE_CORE_OVERLAYS` loads this file only on
+# the rbs 3.x line: on 4.x the continuation would add a second copy of
+# the overloads upstream already declares.
+#
+# Two spellings differ from rbs 4.2 so that every name resolves on every
+# rbs 3.x release the gemspec admits:
+#
+# * `hash[K, V]` is written out as `Hash[K, V] | _ToHash[K, V]`: the
+#   `hash` alias arrived in rbs 3.3, `_ToHash` is in 3.0.
+# * `hash[_Key, K2]`'s key is `untyped`: `Hash::_Key` arrived in rbs 3.4.
+#   It constrains only `hash` / `eql?`, which every object answers.
+#
+# The non-bang return type is answered ahead of either declaration by
+# `MethodDispatcher::HashTransformKeysFolding`.
+class Hash[unchecked out K, unchecked out V]
+  def transform_keys: [K2] (Hash[untyped, K2] | _ToHash[untyped, K2] replacements) -> Hash[K | K2, V]
+                    | [K2] (Hash[untyped, K2] | _ToHash[untyped, K2] replacements) { (K old_key) -> K2 } -> Hash[K2, V]
+                    | ...
+
+  def transform_keys!: (Hash[K, K] | _ToHash[K, K] replacements) ?{ (K key) -> K } -> self
+                     | ...
+end

data/data/core_overlay/process.rbs

@@ -0,0 +1,40 @@
+# Rigor core overlay — supplemental core signatures.
+#
+# --- Process.last_status ---
+#
+# CRuby's `process.c` defines `Process.last_status` as a singleton method
+# answering the calling thread's last child status — the object `$?` reads:
+#
+#   rb_define_singleton_method(rb_mProcess, "last_status", proc_s_last_status, 0);
+#
+# It is `nil` until the thread has waited on a child process. Upstream
+# `ruby/rbs` names `::last_status` in `Process`'s doc comment but has never
+# declared it (no commit to `core/process.rbs` through 4.2 adds a `def`), so
+#
+#   system("true")
+#   status = Process.last_status
+#
+# reported `call.undefined-method` on correct code. The return mirrors rbs
+# core's own `$?: Process::Status?`.
+#
+# Declared on a module `Process` extends, not with `def self.last_status`.
+# A second direct `def` of the method is a `DuplicatedMethodDefinitionError`
+# that takes `Process`'s whole singleton surface down to `Dynamic[top]`, and
+# this method is one a project is likely to have declared already: a
+# `sig/` written for Steep, which reads the same rbs gap, or a later rbs
+# release that fills it. A direct `def` from either source overrides a
+# method `Process` gets through `extend`, on rbs 3.x and 4.x alike, so the
+# overlay stands down instead of colliding.
+#
+# Unconditional: `Process` and `Process::Status` are rbs core on every
+# supported release. `MethodDispatcher::ProcessFolding` refines the answer
+# past a subprocess call, where `$?` is known to be set.
+module RigorCoreOverlay
+  module ProcessLastStatus
+    def last_status: () -> Process::Status?
+  end
+end
+
+module Process
+  extend RigorCoreOverlay::ProcessLastStatus
+end

data/data/core_overlay/string_io.rbs

@@ -0,0 +1,33 @@
+# Rigor core overlay — supplemental core signatures.
+#
+# --- StringIO includes Enumerable[String] ---
+#
+# CRuby's `ext/stringio/stringio.c` makes `StringIO` Enumerable:
+#
+#   rb_include_module(StringIO, rb_mEnumerable);
+#
+# and `StringIO#each` yields the stream's lines, so a `StringIO` is an
+# `Enumerable[String]` exactly as rbs core declares `IO` to be. Upstream
+# `ruby/rbs` declares `class StringIO` with no `include` on every release the
+# gemspec supports, so `StringIO.new(s).detect { ... }`, `.map`,
+# `.each_with_index` and the rest of Enumerable reported
+# `call.undefined-method` on correct code, and a block-taking `.select` fell
+# through to `Kernel#select` (the IO multiplexer) and reported
+# `call.wrong-arity`.
+#
+# The mixin sits behind the class in the ancestry, so every method StringIO
+# declares itself (`each`, `each_line`, `each_char`, `readlines`, ...) keeps
+# upstream's signature. A duplicate include, should upstream add one, builds
+# on both rbs lines.
+#
+# Unconditional — NOT in `RbsLoader::LIBRARY_SUPPLEMENT_CORE_OVERLAYS`,
+# because every environment Rigor builds already declares `StringIO`: in rbs
+# `core/string_io.rbs` before 3.7, and from 3.7 on because
+# `RBS::EnvironmentLoader#load` adds the `stringio` library itself whenever
+# it loads core ("For migrating stringio to stdlib"). Gating on `stringio`
+# would drop the mixin on rbs < 3.7, which has no such library, and from any
+# environment that does not name it. The premise is pinned in
+# `spec/rigor/environment/bundled_rbs_definition_build_spec.rb`.
+class StringIO
+  include Enumerable[String]
+end

data/data/effects/core.yml

@@ -173,7 +173,7 @@ classes:
       instance_variable_set:
         effects: []
         mutates: receiver
-        why: "writes another object's state; the label follows the receiver's ownership (mutate.self on self, mutate.instance on a parameter, taint otherwise)"
+        why: "writes another object's state; the label follows the receiver's ownership (effect-summaries.md § Ownership)"
       instance_variable_get: { effects: [], why: "reads an ivar — object state, not global state" }
       hash: { effects: [], why: "per-process SipHash salt makes it irreproducible (`NON_REPRODUCIBLE_SELECTORS`), but irreproducibility is a fold hazard, not an observable effect" }
       object_id: { effects: [], why: "per-process identity — a fold hazard (`NON_REPRODUCIBLE_SELECTORS`), not an effect" }
@@ -235,12 +235,12 @@ classes:
   Hash:
     posture: value
     mutators: hash
-    why: "a value class; mutation is ownership-classified from `MutationWidening::HASH_MUTATORS`"
+    why: "a value class; mutation is ownership-classified from `MutationClassifier::HASH_MUTATORS`, the union of the widening's `HASH_MUTATORS` and `HashLookupMutation::MUTATORS` plus `rehash`"
 
   String:
     posture: value
     mutators: string
-    why: "a value class; mutation is ownership-classified from `MutationClassifier::STRING_MUTATORS`"
+    why: "a value class; mutation is ownership-classified from `StringMutation::MUTATORS`"
 
   Symbol: { posture: value, why: "immutable value class" }
   Integer: { posture: value, why: "immutable value class" }

data/data/gem_overlay/activesupport/core_ext.rbs

@@ -68,6 +68,8 @@ class Object
 
   # `core_ext/object/inclusion` — `x.in?([a, b])` / `x.in?(1..10)`.
   def in?: (untyped) -> bool
+  # `in?(another_object) ? self : nil` — `params[:kind].presence_in(%w[a b])`.
+  def presence_in: (untyped) -> self?
 
   # Issue #673 — `core_ext/object/to_query`, `core_ext/object/duplicable` and
   # `core_ext/object/instance_variables` all hang off `Object`, so every
@@ -93,6 +95,50 @@ class Object
   # `instance_variable_names`.
   def instance_values: () -> Hash[String, untyped]
   def instance_variable_names: () -> Array[String]
+
+  # `core_ext/object/deep_dup` — `duplicable? ? dup : self`, plus `Array`
+  # (`map(&:deep_dup)`), `Hash` and `Module` overrides. `self` over-claims on
+  # an `Array` subclass, whose override answers a plain `Array`. Declared on
+  # `Object` and not only on `Hash`, where it sat alone: `[[1], [2]].deep_dup`
+  # is the common shape.
+  def deep_dup: () -> self
+
+  # `core_ext/object/with` (ActiveSupport 7.1+) — sets each keyword through
+  # its public writer, yields `self`, and restores the old values in an
+  # `ensure`; the answer is the block's. There is no blockless form: `yield` without a block raises.
+  # ActiveSupport `undef_method`s it on `NilClass`, `TrueClass`, `FalseClass`,
+  # `Integer`, `Float` and `Symbol`, which RBS cannot express, so `1.with(a: 1)`
+  # resolves here where Ruby raises — a missed error, not a false one.
+  # `Data#with` (core) is a subclass override and keeps its own `-> self`.
+  def with: [T] (**untyped attributes) { (self) -> T } -> T
+
+  # `core_ext/object/with_options` — without a block, the
+  # `ActiveSupport::OptionMerger` proxy (not declared here); with one, the
+  # block's value. A zero-arity block is `instance_eval`ed on the proxy, the
+  # `with_options dependent: :destroy do has_many … end` model-body shape.
+  def with_options: (untyped options) -> untyped
+                  | [T] (untyped options) { (?) -> T } -> T
+
+  # `core_ext/string/output_safety` — `false` on `Object`, `true` on
+  # `Numeric`, the buffer's own state on `ActiveSupport::SafeBuffer`. `bool`
+  # for the reason `duplicable?` is: `-> false` on the universal receiver makes
+  # every `if x.html_safe?` an always-falsy branch on the subclasses that answer
+  # true.
+  def html_safe?: () -> bool
+end
+
+# ---------------------------------------------------------------
+# Kernel — `core_ext/kernel/singleton_class`
+# ---------------------------------------------------------------
+
+# `singleton_class.class_eval(*args, &block)` on any object. Declared on
+# `Kernel`, where ActiveSupport defines it; a `Module` receiver still answers
+# core `Module#class_eval`, which is its own alias of `module_eval`. The two
+# overloads mirror that `module_eval`: a string, or a block given the
+# singleton class.
+module Kernel
+  def class_eval: (string code, ?string? filename, ?int lineno) -> untyped
+                | [U] () { (untyped singleton_class) -> U } -> U
 end
 
 # `nil.blank?` / `nil.present?` / `nil.try` are the most frequent
@@ -149,6 +195,10 @@ class String
   def titlecase: () -> String
   def dasherize: () -> String
   def upcase_first: () -> String
+  def downcase_first: () -> String # ActiveSupport 7.1+
+
+  # `core_ext/string/behavior` — the `acts_like?(:string)` duck-type hook.
+  def acts_like_string?: () -> true
 
   # `core_ext/string/filters`
   def squish: () -> String
@@ -182,6 +232,12 @@ class String
   def to_datetime: () -> DateTime
   def to_hours: () -> Float
 
+  # `core_ext/string/zones` — `Time.find_zone!(zone).parse(self)`, or
+  # `to_time` when no zone is set. `untyped` like the `Time` / `Date` rows:
+  # the parse answers an `ActiveSupport::TimeWithZone`, or `nil` on a string
+  # with no date parts.
+  def in_time_zone: (?untyped zone) -> untyped
+
   # `core_ext/string/access`
   def at: (Integer | Range[Integer] | Regexp position) -> String?
   def from: (Integer position) -> String
@@ -194,6 +250,7 @@ class String
 
   # `core_ext/string/multibyte`
   def mb_chars: () -> untyped
+  def is_utf8?: () -> bool
 
   # `core_ext/string/inquiry`
   def inquiry: () -> untyped # ActiveSupport::StringInquirer
@@ -202,6 +259,17 @@ class String
   def exclude?: (String) -> bool
 end
 
+# ---------------------------------------------------------------
+# Symbol — `core_ext/symbol/starts_ends_with`
+# ---------------------------------------------------------------
+
+# `alias_method`s of core `start_with?` / `end_with?`, declared with the core
+# parameter lists.
+class Symbol
+  def starts_with?: (*Regexp | string prefixes) -> bool
+  def ends_with?: (*string suffixes) -> bool
+end
+
 # ---------------------------------------------------------------
 # Integer — `core_ext/integer/*`
 # ---------------------------------------------------------------
@@ -762,6 +830,8 @@ class Array[unchecked out Elem]
   def fourth: () -> Elem?
   def fifth: () -> Elem?
   def forty_two: () -> Elem?
+  def second_to_last: () -> Elem?
+  def third_to_last: () -> Elem?
 
   # `core_ext/array/grouping`
   def in_groups_of: (Integer number, ?untyped fill_with) -> Array[Array[Elem]]
@@ -783,6 +853,9 @@ class Array[unchecked out Elem]
   # `core_ext/array/extract`
   def extract!: () { (Elem) -> bool } -> Array[Elem]
 
+  # `core_ext/array/extract_options`
+  def extract_options!: () -> Hash[untyped, untyped]
+
   # `core_ext/object/blank` / `core_ext/enumerable` — both
   # ActiveSupport additions, shipped on Array specifically.
   def compact_blank: () -> Array[Elem]
@@ -810,6 +883,13 @@ module Enumerable[unchecked out Elem]
   def minimum: (Symbol | String) -> untyped
   def sole: () -> Elem
   def compact_blank: () -> Array[Elem]
+  def many?: () -> bool
+           | () { (Elem) -> boolish } -> bool
+  # `key` and `series` are untyped on purpose: the default `filter: true`
+  # path is `group_by(&key).values_at(*series)`, so a Proc key or a Set /
+  # Range series is correct Rails code. `filter:` is ActiveSupport 8.x;
+  # passing it on 7.x raises, which this unversioned row does not catch.
+  def in_order_of: (untyped key, untyped series, ?filter: boolish) -> Array[Elem]
 end
 
 # ---------------------------------------------------------------
@@ -831,6 +911,9 @@ class Hash[unchecked out K, unchecked out V]
   def deep_transform_keys!: () { (K) -> K } -> self
   def deep_transform_values: () { (V) -> untyped } -> Hash[K, untyped]
   def deep_transform_values!: () { (V) -> untyped } -> self
+  # `alias_method`s of `symbolize_keys` / `symbolize_keys!`.
+  def to_options: () -> Hash[Symbol, V]
+  def to_options!: () -> self
 
   # `core_ext/hash/deep_dup`
   def deep_dup: () -> Hash[K, V]
@@ -840,6 +923,9 @@ class Hash[unchecked out K, unchecked out V]
                 | (Hash[K, V]) { (K, V, V) -> V } -> Hash[K, V]
   def deep_merge!: (Hash[K, V]) -> self
                  | (Hash[K, V]) { (K, V, V) -> V } -> self
+  # `other.is_a?(Hash)` — the hook `ActiveSupport::DeepMergeable` asks before
+  # recursing into a value. `:nodoc:`, but public.
+  def deep_merge?: (untyped other) -> bool
 
   # `core_ext/hash/except` — `Hash#except` is in core RBS as of
   # Ruby 3.0+; `except!` is ActiveSupport-only. ActiveSupport
@@ -853,8 +939,10 @@ class Hash[unchecked out K, unchecked out V]
   def to_param: (?String namespace) -> String
   def to_xml: (**untyped) -> String
 
-  # `core_ext/hash/indifferent_access`
+  # `core_ext/hash/indifferent_access` — `nested_under_indifferent_access`
+  # is an `alias` of `with_indifferent_access`.
   def with_indifferent_access: () -> untyped
+  def nested_under_indifferent_access: () -> untyped
 
   # `core_ext/hash/conversions`
   def self.from_xml: (String, ?Symbol disallowed_types) -> Hash[String, untyped]
@@ -864,14 +952,49 @@ class Hash[unchecked out K, unchecked out V]
   def compact_blank: () -> Hash[K, V]
   def compact_blank!: () -> self
 
-  # `core_ext/hash/reverse_merge`
-  def reverse_merge: (Hash[K, V]) -> Hash[K, V]
+  # `core_ext/array/extract_options`
+  def extractable_options?: () -> bool
+
+  # `core_ext/hash/reverse_merge` — `other_hash.merge(self)`, so the result
+  # carries the argument's keys and values as well as the receiver's, the
+  # same shape as core `Hash#merge`. `-> Hash[K, V]` typed
+  # `opts.reverse_merge(size: 25, velocity: 10)` as `Hash[:size, 1]`.
+  def reverse_merge: [A, B] (Hash[A, B] other_hash) -> Hash[A | K, B | V]
   def reverse_merge!: (Hash[K, V]) -> self
+  # `alias_method`s: `with_defaults` of `reverse_merge`, `with_defaults!`
+  # and `reverse_update` of `reverse_merge!`.
+  def with_defaults: [A, B] (Hash[A, B] other_hash) -> Hash[A | K, B | V]
+  def with_defaults!: (Hash[K, V]) -> self
+  def reverse_update: (Hash[K, V]) -> self
 
   # `core_ext/hash/slice` — `Hash#except` is in core RBS (Ruby 3.0+);
   # `Hash#slice` is in core RBS (Ruby 2.5+); the bang variants are
-  # ActiveSupport-only.
+  # ActiveSupport-only. `extract!` deletes the named keys and answers them
+  # as a new hash; a key the receiver lacks is skipped, not `nil`-filled.
   def slice!: (*K) -> Hash[K, V]
+  def extract!: (*K) -> Hash[K, V]
+end
+
+# ---------------------------------------------------------------
+# Range — `core_ext/range/*`
+# ---------------------------------------------------------------
+
+# `[out E]` matches core `range.rbs`. A reopening whose parameters differ in
+# count or variance (`class Range`, `class Range[E]`) raises
+# `RBS::GenericParameterMismatchError` and collapses `Range`.
+class Range[out E]
+  # `core_ext/range/overlap` — an `alias` of `overlap?`, which rbs declares
+  # since Ruby 3.3 (ActiveSupport defines the method itself only on an older
+  # Ruby). `overlap?` is therefore NOT redeclared here: a second declaration
+  # is a `DuplicatedMethodDefinitionError` that collapses the whole class.
+  def overlaps?: (Range[untyped]) -> bool
+
+  # `core_ext/range/conversions` — `ActiveSupport::RangeWithFormat`, prepended
+  # onto `Range`. An unknown format falls back to `to_s`; `:db` answers `nil`
+  # for a beginless-and-endless range, which the declared `String` does not
+  # model — `(nil..nil).to_fs(:db)` is not a shape correct code writes.
+  def to_fs: (?Symbol format) -> String
+  def to_formatted_s: (?Symbol format) -> String
 end
 
 # ---------------------------------------------------------------

data/docs/handbook/03-narrowing.md

@@ -77,6 +77,32 @@ unless x.is_a?(Integer)
 end
 ```
 
+A guard can also name a class the variable's type says it cannot
+be. Inside such a branch the variable reads `bot`, so no call on
+it is checked. That matters when the type is one Rigor inferred
+or read from a signature: `$stdout` is typed `IO`, and a test runs
+the same code with a `StringIO`, which is not an `IO` subclass, so
+the guarded call below is correct code and stays quiet. A guard
+on `$stdout`, `STDOUT` or another global or constant narrows the
+same way:
+
+```ruby
+require "stringio"
+
+def captured_output
+  out = STDOUT
+  if out.is_a?(StringIO)
+    assert_type("bot", out)
+    out.string
+  end
+end
+```
+
+The rest of the branch is still checked, and its `bot` variable
+never reaches the code after it. A `case` drops such a branch
+from its value (see below); keeping it is tracked in
+[#1465](https://github.com/rigortype/rigor/issues/1465).
+
 ## Equality with literal values
 
 Rigor narrows `==` and `!=` against trusted literal values:
@@ -117,17 +143,78 @@ The result type unions the per-branch results. When the input
 is a finite literal union, Rigor proves the `else` branch is
 unreachable when every member is matched.
 
-The same narrowing also works in reverse: when a `when <Class>`
-clause is disjoint from the subject's type, or an earlier
-clause already covered it, the clause is dead — Rigor emits
+The same narrowing also works in reverse: when an earlier clause
+already covered the subject, or a `when <Class>` clause is
+disjoint from the subject's type, the clause is dead — Rigor emits
 [`flow.unreachable-clause`](08-understanding-errors.md) so you
 can delete it. (It ships at `:info` under the default profile.)
 
+A disjoint `when <Class>` is reported only when the subject's
+type is what the code literally shows: a literal (`1`, `"s"`,
+`:a`), an array or hash literal, a class object, or `nil` /
+`true` / `false`. When the subject's type is one Rigor inferred
+or read from a signature, the `when` is evidence that it can hold
+something else, as in the `is_a?` example above, so the clause is
+not reported. It is still read as `bot`, and the `case` value
+drops it:
+
+```ruby
+require "stringio"
+
+io = STDOUT
+assert_type(":io", (case io when StringIO then :string_io else :io end))
+
+count = 3
+assert_type(":number", (case count when String then :text else :number end))
+
+case io
+when StringIO then puts io.string # not reported
+end
+
+case count
+when String then puts count # flow.unreachable-clause
+end
+```
+
+Both values leave the `when` branch out. Of the two `case`
+statements after them, only the second reports
+`flow.unreachable-clause`. The check reads a `case` the code runs
+as a statement or assigns to a variable; one passed straight to a
+method, like the two `assert_type` lines, is not checked.
+
 `case x; in pattern` (one-line pattern matching) narrows the
 same way for the patterns Rigor understands — class checks,
 literal equality, array / hash structural patterns. The
 clause-reachability check extends to bare-class `in` patterns
-(`in String` / `in MyClass => x`) too.
+(`in String` / `in MyClass => x`) too, under the same literal
+rule.
+
+## `respond_to?`
+
+A truthy `respond_to?(:name)` with a literal symbol removes `nil`
+from the receiver (unless `nil` itself responds to `name`) and the
+members whose class Rigor knows lacks `name`. When no member could
+respond, the receiver reads `Dynamic[top]` if its type is one
+Rigor inferred or read from a signature, so the guarded call is
+not an error. It reads `bot` if it is a literal, an array or hash
+literal, a class object, or `nil` / `true` / `false`, so the
+branch goes unchecked. For a literal value that is exact: it
+never gains the method. A class object can gain one from a gem
+Rigor has no signature for (`Time.respond_to?(:zone)` under
+ActiveSupport), and its branch is then not checked either:
+
+```ruby
+require "stringio"
+
+value = [1, "one"].sample
+assert_type('"one"', value) if value.respond_to?(:upcase)
+
+io = STDOUT
+assert_type("Dynamic[top]", io) if io.respond_to?(:string)
+
+count = 3
+assert_type("bot", count) if count.respond_to?(:upcase)
+```
 
 ## Boolean composition
 
@@ -343,12 +430,10 @@ not chase mutation).
 A few forms you might expect that Rigor does **not** narrow
 today:
 
-- `respond_to?(:method_name)` records only a non-nil
-  narrowing — a truthy check with a statically-known symbol
-  removes `nil` from the receiver (since `nil` does not
-  respond to most methods) — but it does **not** yet expose a
-  structural "this object responds to that method" capability
-  fact you could dispatch against.
+- `respond_to?(:method_name)` narrows by removing members (see
+  [`respond_to?`](#respond_to) below), but it does **not** yet
+  expose a structural "this object responds to that method"
+  capability fact you could dispatch against.
 - `frozen?` and other mutation guards — Rigor does not track
   mutability as a narrowing fact yet.
 - Open-ended class-comparison via `===` against arbitrary