rigortype 0.3.8 → 0.4.0

data/data/gem_overlay/activesupport/core_ext.rbs

@@ -68,6 +68,77 @@ 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
+  # RBS-known receiver reaches them; declaring them only on `Hash` (as
+  # `to_param` / `to_query` were) or only on `NilClass` (as `duplicable?` /
+  # `instance_values` were) left `"x".to_param`, `1.duplicable?` and friends a
+  # `call.undefined-method` on ordinary Rails code.
+  #
+  # `to_param` is `to_s`; `to_query(key)` interpolates two `CGI.escape` results.
+  # `key` is `untyped` because the body only calls `to_param` on it, and both
+  # `:name` and `"user[name]"` are ordinary call sites.
+  def to_param: () -> String
+  def to_query: (untyped key) -> String
+
+  # `bool` and not `true`: `Object#duplicable?` answers true, but the
+  # `Singleton` (and, on a Ruby where methods are not duplicable, `Method` /
+  # `UnboundMethod`) overrides answer false. `-> true` on the universal
+  # receiver would make every `if x.duplicable?` an always-truthy branch —
+  # a false positive on the only shape anybody writes.
+  def duplicable?: () -> bool
+
+  # Keys without the leading `@` for `instance_values`, with it for
+  # `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
@@ -80,16 +151,24 @@ class NilClass
   def try!: (*untyped) -> nil
   def duplicable?: () -> true
   def instance_values: () -> Hash[String, untyped]
+  # `core_ext/object/to_query` overrides `to_param` on the three singleton
+  # values to return `self` rather than `Object#to_param`'s `to_s`, so the
+  # `Object` row above would carry a wrong return here. `NilClass#to_query`
+  # is its own method (`CGI.escape(key.to_param)`), still a String.
+  def to_param: () -> nil
+  def to_query: (untyped key) -> String
 end
 
 class TrueClass
   def blank?: () -> false
   def present?: () -> true
+  def to_param: () -> true
 end
 
 class FalseClass
   def blank?: () -> true
   def present?: () -> false
+  def to_param: () -> false
 end
 
 # ---------------------------------------------------------------
@@ -116,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
@@ -149,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
@@ -161,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
@@ -169,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/*`
 # ---------------------------------------------------------------
@@ -263,6 +364,16 @@ end
 # `spec/rigor/environment/activesupport_overlay_parity_spec.rb`); every method not listed here stays
 # undeclared and silently `Dynamic` rather than guessed.
 module ActiveSupport
+  # Issue #534 item 7 — the `ActiveSupport::Concern` twin of the plugin's declaration. The plugin file
+  # carries the reasoning; the short version is that naming the module makes `extend ActiveSupport::Concern`
+  # resolve, and the three members have to come with it so that `included do … end` does not become a false
+  # `call.undefined-method` on a now-RBS-known module.
+  module Concern
+    def included: (?untyped base) ?{ (?) -> untyped } -> untyped
+    def prepended: (?untyped base) ?{ (?) -> untyped } -> untyped
+    def class_methods: () { (?) -> untyped } -> untyped
+  end
+
   class Duration
     # The `ago` family (issue #659). `since(time = ::Time.current)` and `ago(time = ::Time.current)` are
     # the only two real methods; `from_now` / `after` alias the first and `until` / `before` the second,
@@ -272,23 +383,25 @@ module ActiveSupport
     # `GEM_OVERLAY_OPEN_RECEIVERS` cannot suppress since it protects a Duration receiver, not a `Time`
     # one. #658 declared that surface and #670 the `Date` / `DateTime` twins, so the chains resolve now.
     #
-    # `Time` is the right class rather than a compromise: under a zone these answer an
-    # `ActiveSupport::TimeWithZone`, and Rails overrides `TimeWithZone#is_a?` to answer true for
-    # `::Time`. A `Time | ActiveSupport::TimeWithZone` union was measured and rejected — it types every
-    # downstream call `Dynamic[top]`. The with-an-argument form stays `untyped` because the runtime
-    # return depends on the argument's class AND on whether the duration carries a date-scale part
-    # (`(1.month).ago(Date.today)` answers a `Date`; `(30.minutes).ago(Date.today)` a `TimeWithZone`).
-    def ago: () -> Time
+    # Since #673 the no-argument form answers `ActiveSupport::TimeWithZone`, the class these really
+    # build off `::Time.current` under a zone, declared below as a `::Time` SUBCLASS. That keeps every
+    # `Time`-typed chain and parameter working while `1.hour.ago.time_zone` stops being a false
+    # `call.undefined-method`. A `Time | ActiveSupport::TimeWithZone` union was measured and rejected —
+    # it types every downstream call `Dynamic[top]`. The with-an-argument form stays `untyped` because
+    # the runtime return depends on the argument's class AND on whether the duration carries a
+    # date-scale part (`(1.month).ago(Date.today)` answers a `Date`; `(30.minutes).ago(Date.today)` a
+    # `TimeWithZone`).
+    def ago: () -> TimeWithZone
            | (untyped time) -> untyped
-    def until: () -> Time
+    def until: () -> TimeWithZone
              | (untyped time) -> untyped
-    def before: () -> Time
+    def before: () -> TimeWithZone
               | (untyped time) -> untyped
-    def since: () -> Time
+    def since: () -> TimeWithZone
              | (untyped time) -> untyped
-    def from_now: () -> Time
+    def from_now: () -> TimeWithZone
                 | (untyped time) -> untyped
-    def after: () -> Time
+    def after: () -> TimeWithZone
              | (untyped time) -> untyped
 
     # `to_i` / its `in_seconds` alias return `@value.to_i` — always Integer.
@@ -315,6 +428,54 @@ module ActiveSupport
     # Float` is what stays honest without costing the common `parts[:days] * 2` chain anything.
     def parts: () -> Hash[Symbol, Integer | Float]
   end
+
+  # ---------------------------------------------------------------
+  # ActiveSupport::TimeWithZone — issue #673
+  # ---------------------------------------------------------------
+  #
+  # `Time.current` and the `Duration#ago` family really answer a `TimeWithZone`
+  # under a zone, and this class was not modelled at all, so the four readers a
+  # TWZ has and a `Time` does not — `time_zone`, `time`, `period`,
+  # `comparable_time` — were `call.undefined-method` on every `Time.current`
+  # receiver. Declaring them on `Time` would have been wrong: a plain `Time`
+  # genuinely lacks them.
+  #
+  # `< ::Time` rather than a `Time | TimeWithZone` union at the producers. The
+  # union was measured during #632 and rejected — it types every downstream
+  # call `Dynamic[top]`. Inheritance is the cheaper shape AND the honest one
+  # here: Rails overrides `TimeWithZone#is_a?` to answer true for `::Time`, so
+  # `Time` is the class Rails itself tells callers a TWZ is, and TWZ's
+  # `method_missing` forwards every name it does not define to the wrapped
+  # `::Time` — which is exactly what inheriting `Time`'s surface models. A TWZ
+  # therefore also satisfies every `Time`-typed parameter, and a chain through
+  # `Time.current` keeps resolving instead of collapsing.
+  #
+  # The cost, taken deliberately: `Time.current` answers a plain `Time` when
+  # `Time.zone` is nil, so `Time.current.time_zone` in a zone-less
+  # activesupport-only project is a real `NoMethodError` this now types. Rails
+  # sets `config.time_zone` ("UTC") by default, so the shape is rare, and the
+  # false positive it replaces fired on correct Rails code — which AGENTS.md
+  # ranks above the worst-case static reading.
+  class TimeWithZone < ::Time
+    # `Time`'s own `initialize` takes the `(year, month, …)` parts; inheriting
+    # it would make `TimeWithZone.new(utc, zone)` — how Rails constructs one —
+    # a `call.argument-type-mismatch`. `untyped` because the zone and period
+    # carriers (`ActiveSupport::TimeZone`, `TZInfo::TimezonePeriod`) are not
+    # declared anywhere in this overlay.
+    def initialize: (untyped utc_time, untyped time_zone, ?untyped local_time, ?untyped period) -> void
+
+    # The `attr_reader`; an `ActiveSupport::TimeZone`, undeclared here.
+    def time_zone: () -> untyped
+
+    # The wall-clock `::Time` in the zone. `utc` / `getutc` / `getgm` /
+    # `gmtime` are `Time`'s own names and stay inherited; `comparable_time` is
+    # the alias of `utc` that `Time` does not carry.
+    def time: () -> ::Time
+    def comparable_time: () -> ::Time
+
+    # A `TZInfo::TimezonePeriod`, undeclared here.
+    def period: () -> untyped
+  end
 end
 
 # ---------------------------------------------------------------
@@ -322,7 +483,10 @@ end
 # ---------------------------------------------------------------
 
 class Time
-  def self.current: () -> Time
+  # `Time.zone ? Time.zone.now : Time.now` — an `ActiveSupport::TimeWithZone` under a zone, which
+  # since #673 is declared as a `::Time` subclass so the four TWZ-only readers resolve without the
+  # rest of the chain losing its `Time` typing. See the class's own note for the zone-less cost.
+  def self.current: () -> ActiveSupport::TimeWithZone
   def self.zone: () -> untyped # ActiveSupport::TimeZone | nil
   def self.zone=: (String | Symbol | untyped) -> untyped
 
@@ -666,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]]
@@ -687,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]
@@ -714,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
 
 # ---------------------------------------------------------------
@@ -735,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]
@@ -744,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
@@ -757,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]
@@ -768,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/02-everyday-types.md

@@ -25,7 +25,7 @@ n = ARGV.size
 ```
 
 A vanilla checker says: `n: Integer`. Rigor says:
-`n: int<0, max>` (a non-negative integer — `Array#size` cannot
+`n: Integer[0..]` (a non-negative integer — `Array#size` cannot
 return a negative count).
 
 The reason this matters: most diagnostics Rigor wants to fire
@@ -40,7 +40,7 @@ or narrow (`Constant<3>`, `non-empty-string`). The rest of
 this chapter is the carrier zoo.
 
 One note on notation before the zoo: angle brackets hold a
-concrete value or bound — `Constant<3>`, `int<0, max>` —
+concrete value or bound — `Constant<3>`, `Integer[0..]` —
 while square brackets hold type parameters, exactly as in RBS
 — `Nominal[String]`, `Hash[K, V]`, `Dynamic[top]`. A type
 parameter names the type of a *part*: `Hash[K, V]` is a Hash
@@ -124,27 +124,30 @@ nominal carrier or `Dynamic[top]`.
 
 Some integer-valued expressions produce a known range without
 producing a single literal value. Rigor describes those with
-`Type::IntegerRange`, displayed as `int<min, max>`:
+`Type::IntegerRange`, displayed as `Integer[…]` around the Ruby
+range literal that covers the values, `Integer[1..10]`:
 
 ```ruby
-n = ARGV.size               #=> dump_type: int<0, max>
-m = n + 1                   #=> dump_type: int<1, max>
-double = n * 2              #=> dump_type: int<0, max>
+n = ARGV.size               #=> dump_type: Integer[0..]
+m = n + 1                   #=> dump_type: Integer[1..]
+double = n * 2              #=> dump_type: Integer[0..]
 ```
 
-`max` here means "positive infinity" — the upper bound is
-unbounded; `min`, which appears in the table below, is its
-mirror, "negative infinity." Multiplication preserves the
-floor, so `n * 2` stays `int<0, max>`.
+The literal means what it means in Ruby: `Integer[0..]` is
+every integer `(0..).cover?` accepts, an endless range is
+unbounded above, a beginless one (`Integer[..-1]`) is unbounded
+below, and `Integer[1...10]` is written back as `Integer[1..9]`
+because for integers the two are the same set. Multiplication
+preserves the floor, so `n * 2` stays `Integer[0..]`.
 
 A handful of common ranges have shorter names:
 
 | Spelling | Meaning |
 | --- | --- |
-| `positive-int` | `int<1, max>` |
-| `non-negative-int` | `int<0, max>` |
-| `negative-int` | `int<min, -1>` |
-| `non-positive-int` | `int<min, 0>` |
+| `positive-int` | `Integer[1..]` |
+| `non-negative-int` | `Integer[0..]` |
+| `negative-int` | `Integer[..-1]` |
+| `non-positive-int` | `Integer[..0]` |
 
 `Array#size`, `Array#length`, `Hash#size`, `String#size`, …
 all carry `non-negative-int`. `Array#count` does too. Adding

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:
@@ -107,7 +133,7 @@ matched member:
 ```ruby
 case n
 when 0      then :zero        # Constant<0>
-when 1..9   then :small       # int<1, 9>
+when 1..9   then :small       # Integer[1..9]
 when 10     then :ten         # Constant<10>
 else             :large       # everything else
 end
@@ -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
 
@@ -153,7 +240,7 @@ end
 ```
 
 The `is_a?` narrowed `x` to `Integer`, then the integer
-comparison narrowed it further to `int<1, max>`.
+comparison narrowed it further to `Integer[1..]`.
 
 ## Integer comparisons
 
@@ -165,7 +252,7 @@ integer ranges:
 def safe_index(arr, n)
   return :empty if arr.empty?
   return :out_of_range if n < 0 || n >= arr.size
-  # n: int<0, arr.size - 1>  (in practice: int<0, max>
+  # n: Integer[0..arr.size - 1]  (in practice: Integer[0..]
   # tightened against `n >= arr.size`)
   arr.fetch(n)
 end
@@ -176,10 +263,43 @@ Range comparisons compose with literals:
 ```ruby
 n = some_input
 if n.between?(1, 9)
-  # n: int<1, 9>
+  # n: Integer[1..9]
 end
 ```
 
+## Float comparisons
+
+A `Float` narrows on the *true* edge only. `x > 0.0` is false for
+`NaN`, so the values that pass are a range, `Float[0.0..]`, but the
+values that fail are everything else *plus* `NaN`, which no range
+spells, so the else branch keeps `Float`:
+
+```ruby
+x = Float(input)
+if x > 0.0
+  # x: Float[0.0..]
+else
+  # x: Float
+end
+if x < 1.0
+  # x: Float[...1.0]   (Ruby's exclusive end)
+end
+if x.between?(0.0, 1.0)
+  # x: Float[0.0..1.0]
+end
+```
+
+`x.nan?` narrows its *false* edge to `non-nan-float`, and
+`x.finite?` its *true* edge to `finite-float`. The range is the
+one Ruby's `Range#cover?` would accept, so `Float[0.0..]` contains
+`Float::INFINITY` and never `Float::NAN`.
+
+Some calls produce a bounded Float on their own: `rand(0.0...1.0)`
+and `Random.rand(1.0..2.0)` are the range they name, `Math.sqrt(n)` of a `non-negative-int` is
+`Float[0.0..]`, and `x.clamp(0.0, 1.0)` or `x.clamp(0.0..1.0)` on a
+bounded `x` is the bracket. A bounded Float knows it is not `NaN`,
+so `u.nan?` folds to `false` and `u.round` to an integer range.
+
 ## Predicate methods on refinements
 
 Rigor recognises a small set of "type-carrier predicate
@@ -310,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