rigortype 0.3.4 → 0.3.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ffcad04b990dc4220690a6906bb96306056a02792017fcf41200b8865c040846
-  data.tar.gz: b62aa8767389da9ddd808df2a74d09447aee4d5a9c0deb0d7d4292da5ff7669b
+  metadata.gz: b2709c0d68fc616109c3300013f08fda3702484c6ca01ff67b4ccf9d0f354ad0
+  data.tar.gz: 77486c048ef9cd94a725b5ebb09ae4e161003b37f67919c769845ed36f6c60bf
 SHA512:
-  metadata.gz: f55c7fb8b035ba5364d97163f6ae66e1212d544d5fa2821110a230818be1f64bd2d803ff88739af394d57c39a3bb6ed77737451a68f1cfb047276e23c6ede98a
-  data.tar.gz: 85aafda9ac9c46b73757c5690484d97d77b1dea26cc499252d39a24aefbd9f58fcf0dfda759a11e7dea553b4d8fac3ae83db9a165e1e926ff62a8fdecad78967
+  metadata.gz: 15a406b49bcd62e9efc2c1c143903a85157dbaf165ccca5defdf4abd69949d0c0d0107afd55469e5a0b27fa667e3c59a0ec58de854af503cad0a9e3952568a6e
+  data.tar.gz: fa429f47f4ed13b53fa07c7078510524bd6d3b304f7ffa48916b3cfab0e954b42167bda011b413946448dbdaeb63e78dfeaf444ec86a68cf928cefcf3fd70813

data/README.md

@@ -1,7 +1,7 @@
 # Rigor
 
 [![Gem Version](https://badge.fury.io/rb/rigortype.svg?icon=si%3Arubygems)](https://badge.fury.io/rb/rigortype)
-[![GitHub License](https://img.shields.io/github/license/rigortype/rigor)](https://github.com/rigortype/rigor/blob/master/LICENSE)
+[![GitHub License](https://img.shields.io/github/license/rigortype/rigor)](LICENSE)
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/rigortype/rigor)
 
 **Type-aware bug finding for Ruby — no annotations required, and a
@@ -47,7 +47,7 @@ s.lenght
 
 ```shell-session
 $ rigor check demo.rb
-demo.rb:7:3: error: undefined method `lenght' for "hello-world"
+demo.rb:7:3: error: undefined method `lenght' for "hello-world" [call.undefined-method]
 ```
 
 Note what the error says: not ``undefined method `lenght' for String``
@@ -185,9 +185,9 @@ plugins:
 
 The full catalogue is in [`plugins/README.md`](plugins/README.md); the
 `rigor-project-init` Skill picks the right set for you. To teach Rigor
-your own DSL, the [`rigor-plugin-author`](skills/rigor-plugin-author/)
+your own DSL, the [`rigor-plugin-author`](skills/rigor-plugin-author)
 Skill authors a plugin step-by-step, and
-[`rigor-baseline-reduce`](skills/rigor-baseline-reduce/) drives the
+[`rigor-baseline-reduce`](skills/rigor-baseline-reduce) drives the
 baseline down once you are running.
 
 ## Going deeper
@@ -231,7 +231,7 @@ rigor docs --list                 # list every bundled page
 
 ## Status
 
-Current release: **`v0.3.4`** (2026-08-21) — on the
+Current release: **`v0.3.6`** (2026-08-30) — on the
 `0.3.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

data/data/effects/core.yml

@@ -531,7 +531,19 @@ classes:
   # ---------------------------------------------------------------------------------------------
   # Network.
   # ---------------------------------------------------------------------------------------------
-  Socket: { posture: net, why: "the BSD socket surface" }
+  Socket:
+    posture: net
+    why: "the BSD socket surface; the rows below read the machine's own identity and send nothing"
+    singleton_methods:
+      # `io.net` on these was a wrong label, not a conservative one, and it travelled: Redmine builds
+      # its Message-IDs from `Socket.gethostname`, so 215 of 4,234 rows — every model `save`, every
+      # `Mailer#*`, and `Redmine::IMAP.check`, whose actual IMAP connection is invisible — read as
+      # network traffic on the strength of a hostname lookup (#458). `io` is the honest bound: the
+      # call leaves the process to ask the kernel, and nothing goes over a wire.
+      gethostname: { effects: [io], why: "reads this machine's own name; no packet leaves the process" }
+      gethostbyname: { effects: [io.net], why: "resolves a name — the resolver, and possibly DNS" }
+      getifaddrs: { effects: [io], why: "reads this machine's own interfaces; local configuration, not resolution" }
+      ip_address_list: { effects: [io], why: "reads this machine's own addresses; local configuration, not resolution" }
   BasicSocket: { posture: net, why: "the shared socket surface" }
   TCPSocket: { posture: net, why: "a TCP stream" }
   TCPServer: { posture: net, why: "a listening TCP socket" }
@@ -572,6 +584,11 @@ classes:
       start: { effects: [io.net.http], why: "opens the connection; the block joins by containment" }
       new: { effects: [], why: "allocates the client; nothing is sent until start / request" }
   "Net::SMTP": { posture: net, why: "an SMTP session; `email.send` is the plugin's semantic layer, not the transport's" }
+  # rbs ships `net-http` / `net-smtp` and not these, so a project's `Net::IMAP` types as `Dynamic` and
+  # only the constant the author wrote names the class. #463 is what lets a posture answer there; before
+  # it, `Net::FTP` had a row that could never fire and these two were not worth writing.
+  "Net::IMAP": { posture: net, why: "an IMAP session" }
+  "Net::POP3": { posture: net, why: "a POP3 session" }
   "Net::FTP": { posture: net, why: "an FTP session" }
 
   URI:

data/data/effects/registry.yml

@@ -11,6 +11,25 @@
 # still reads.
 vocabulary: 1
 
+# What each root means, in one line. Read by `rigor effects --list-labels` (#429), which is the only
+# way an installed Rigor can tell a reader what to write in `effects.envelopes:`, `effects.tolerated:`,
+# `effects.attribution:` or an `%a{rigor:v1:effect …}` annotation — four surfaces that all require
+# typing a label. `docs/manual/19-effect-labels.md`'s vocabulary table is the same wording for the same
+# reason; a root without a line here simply prints without one, which is what a plugin-opened root does.
+descriptions:
+  io: talks to something outside the process — a file, a socket, a database, a terminal, a subprocess
+  mutate: changes state in place, in the frame's own objects, the receiver, another object, or the class
+  nondet: reads something that differs between two otherwise identical runs
+  global: process-wide state — ENV, $stdout, a class variable
+  exit: can end the process
+  ffi: calls out through a foreign-function interface
+  telemetry: reports on the program rather than doing its work — logs, metrics, traces
+  email: sends mail, whatever the transport underneath is
+  job: hands work to a queue for another process to run
+  cache: reads or writes a cache, whatever backs it
+  failure: registered so a policy written for Steins, the sibling PHP analyzer, parses here; Rigor never
+    produces one, so a bound naming it is satisfied vacuously
+
 labels:
   # Steins v1, verbatim (rigortype/steins `docs/type-specification/effects.md`). Shared vocabulary:
   # a policy naming these labels must read the same against a PHP service and a Rails app.
@@ -53,9 +72,18 @@ labels:
   - io.db.write
   - io.db.transaction
 
-  # Application-meaning roots, small and shared. These are the labels a policy actually names
-  # ("presenters do not enqueue jobs") and the ones `tolerated:` grips, so they must spell the same
-  # in Steins and Rigor.
+  # Steins carries these (its ADR-0042) and Rigor does not produce them: they name a failure arm's
+  # value provenance rather than an effect. Registered for the same reason `io.output.buffer` is —
+  # so a policy written against Steins parses here — and never inferred (ADR-103 WD16).
+  - failure
+  - failure.environment
+  - failure.input
+  - failure.resource
+
+  # Application-meaning roots. These are the labels a policy actually names ("presenters do not
+  # enqueue jobs") and the ones `tolerated:` grips, so a project must not need a plugin before it
+  # can write one. Rigor-owned and proposed to Steins, which holds ecosystem labels outside its
+  # builtin set and supplies them through a plugin manifest (ADR-103 WD16).
   - telemetry
   - email.send
   - job.enqueue

data/data/gem_overlay/activesupport/core_ext.rbs

@@ -65,6 +65,9 @@ class Object
   # `acts_like?(:string)` / `acts_like?(:date)` / `acts_like?(:time)`
   # is ActiveSupport's "duck-typing helper" predicate.
   def acts_like?: (Symbol | String) -> bool
+
+  # `core_ext/object/inclusion` — `x.in?([a, b])` / `x.in?(1..10)`.
+  def in?: (untyped) -> bool
 end
 
 # `nil.blank?` / `nil.present?` / `nil.try` are the most frequent
@@ -108,6 +111,9 @@ class String
   def pluralize: (?Integer count, ?Symbol locale) -> String
   def singularize: (?Symbol locale) -> String
   def humanize: (?capitalize: bool, ?keep_id_suffix: bool) -> String
+  def titlecase: () -> String
+  def dasherize: () -> String
+  def upcase_first: () -> String
 
   # `core_ext/string/filters`
   def squish: () -> String
@@ -115,6 +121,8 @@ class String
   def truncate: (Integer truncate_at, ?omission: String, ?separator: String | Regexp | nil) -> String
   def truncate_bytes: (Integer truncate_at, ?omission: String) -> String
   def truncate_words: (Integer words_count, ?omission: String, ?separator: String | Regexp | nil) -> String
+  def remove: (*Regexp | String patterns) -> String
+  def remove!: (*Regexp | String patterns) -> String
 
   # `core_ext/string/output_safety` — `html_safe` returns an
   # `ActiveSupport::SafeBuffer` (a String subclass). The closest
@@ -282,6 +290,8 @@ class Time
   # Re-declaring it raised `RBS::DuplicatedMethodDefinitionError` and took the WHOLE `Time` definition
   # down with it (every `Time` call degraded to `Dynamic[top]`). This overlay only ADDS what
   # ActiveSupport adds.
+  def advance: (untyped options) -> Time
+  def all_day: () -> Range[Time]
   def acts_like_time?: () -> true
 end
 
@@ -323,6 +333,17 @@ class Date
   def at_beginning_of_day: () -> Time
   def end_of_day: () -> Time
   def at_end_of_day: () -> Time
+  def advance: (untyped options) -> Date
+  def all_day: () -> Range[Time]
+
+  # `Date#to_time` is an OVERLOAD CONTINUATION (`| ...`), not a plain declaration: stdlib `date`
+  # already types `to_time: () -> Time`, and re-declaring it raises
+  # `RBS::DuplicatedMethodDefinitionError`, which collapses `Date` to `Dynamic[top]` for every project
+  # this overlay reaches — the failure the `Time#utc?` note above records, and the one #437 hit on the
+  # plugin. The row cannot simply be omitted either: ActiveSupport genuinely widens the arity, so
+  # without it `date.to_time(:utc)` — correct Rails code — draws an arity diagnostic (#449). `| ...`
+  # appends this overload ahead of the stdlib one, so both arities resolve.
+  def to_time: (?Symbol form) -> Time | ...
 end
 
 # ---------------------------------------------------------------
@@ -475,3 +496,15 @@ class DateTime
   def end_of_minute: () -> DateTime
   def acts_like_time?: () -> true
 end
+
+# ---------------------------------------------------------------
+# ERB::Util — ActionView extends it with `html_escape_once`
+# ---------------------------------------------------------------
+
+# `ERB` is a CLASS in Ruby / RBS (not a module), so reopen it as a class — a `module ERB` wrapper
+# collides with upstream `class ERB` once the `erb` stdlib is in scope. `ERB::Util` itself is a module.
+class ERB
+  module Util
+    def self.html_escape_once: (untyped) -> String
+  end
+end

data/docs/handbook/02-everyday-types.md

@@ -113,7 +113,7 @@ String, Symbol, Array, and Hash. The list is not in this
 handbook (it would fill several pages); see
 [`docs/types.md`](../types.md) and the per-class catalogues
 under
-[`data/builtins/ruby_core/`](../../data/builtins/ruby_core/).
+[`data/builtins/ruby_core/`](../../data/builtins/ruby_core).
 
 When folding is **not** safe (because a method has side
 effects, depends on the environment, or is not in a

data/docs/handbook/04-tuples-and-shapes.md

@@ -275,7 +275,7 @@ the underlying RBS sig advertises.
 
 If you prefer the TS spellings (`Pick<T, K>` etc.) in
 directives, opt into the
-[`rigor-typescript-utility-types`](../../plugins/rigor-typescript-utility-types/)
+[`rigor-typescript-utility-types`](../../plugins/rigor-typescript-utility-types)
 plugin. The plugin registers a `Plugin::TypeNodeResolver` that
 translates each TS name onto the canonical projection:
 

data/docs/handbook/08-understanding-errors.md

@@ -236,6 +236,6 @@ deprecations, …). Most projects will never write one; the
 chapter exists so you know the option is there.
 [Chapter 10 — Coexisting with Sorbet](10-sorbet.md) is for
 projects arriving from a Sorbet codebase: the
-[`rigor-sorbet`](../../plugins/rigor-sorbet/) adapter reads
+[`rigor-sorbet`](../../plugins/rigor-sorbet) adapter reads
 `sig { ... }` blocks, RBI files, and `T.let` / `T.cast` /
 `T.must` / `T.unsafe` assertions as type sources.

data/docs/handbook/09-plugins.md

@@ -122,7 +122,7 @@ Reach for a plugin only when:
 
 If those are true, [`examples/README.md`](../../examples/README.md)
 is your starting point. The
-[`rigor-deprecations`](../../examples/rigor-deprecations/)
+[`rigor-deprecations`](../../examples/rigor-deprecations)
 example is the smallest fully-shaped plugin — manifest +
 single per-file walk + a couple of diagnostic emissions —
 and is the recommended template for "I want to author my
@@ -146,7 +146,7 @@ From here:
   to deeper material in
   [`docs/type-specification/`](../type-specification/README.md),
   [`docs/internal-spec/`](../internal-spec/README.md), and
-  [`docs/adr/`](../adr/).
+  [`docs/adr/`](../adr).
 - The [`CHANGELOG.md`](../../CHANGELOG.md) is the per-release
   truth for what shipped when.
 

data/docs/handbook/10-sorbet.md

@@ -1,7 +1,7 @@
 # Coexisting with Sorbet
 
 If your project already uses [Sorbet](https://sorbet.org/),
-the [`rigor-sorbet`](../../plugins/rigor-sorbet/) plugin
+the [`rigor-sorbet`](../../plugins/rigor-sorbet) plugin
 lets Rigor read your existing `sig` blocks, RBI files, and
 `T.let` / `T.cast` / `T.must` / `T.unsafe` assertions as type
 sources. You do not have to rewrite anything in RBS to start

data/docs/handbook/README.md

@@ -66,7 +66,7 @@ up the flag, key, or command that *acts* on it.
    landing page.
 10. [**Coexisting with Sorbet**](10-sorbet.md) — for users
     arriving from a Sorbet-using project: the
-    [`rigor-sorbet`](../../plugins/rigor-sorbet/) adapter
+    [`rigor-sorbet`](../../plugins/rigor-sorbet) adapter
     reads `sig { ... }` blocks, RBI files, and
     `T.let` / `T.cast` / `T.must` / `T.unsafe` assertions
     as type sources without rewriting in RBS.
@@ -255,7 +255,7 @@ ADRs:
 - [`docs/internal-spec/`](../internal-spec/README.md) —
   analyzer-internal contracts (engine surface, type-object
   public API).
-- [`docs/adr/`](../adr/) — architecture decision records.
+- [`docs/adr/`](../adr) — architecture decision records.
 
 ## Non-goals
 

data/docs/handbook/appendix-go.md

@@ -105,7 +105,7 @@ type switches. Rigor has direct analogues.
 | `if x != nil` | `if x` (strips `nil`), or `unless x.nil?` |
 | `v, ok := x.(string)` (comma-ok assertion) | `x.is_a?(String)` narrowing in an `if` |
 | `switch v := x.(type) { case string: … }` | `case x; in String => v` |
-| `x.(T)` (assertion, panics on fail) | (no panicking assertion) — `is_a?` guard, or `T.cast` via [`rigor-sorbet`](../../plugins/rigor-sorbet/) |
+| `x.(T)` (assertion, panics on fail) | (no panicking assertion) — `is_a?` guard, or `T.cast` via [`rigor-sorbet`](../../plugins/rigor-sorbet) |
 | user func returning `bool` | `%a{rigor:v1:predicate-if-true x is Foo}` directive |
 
 Go's type switch is *not* exhaustive — you can omit cases and

data/docs/handbook/appendix-java-csharp.md

@@ -58,7 +58,7 @@ advisor that only speaks when it is sure.
 | `Set<T>` | `HashSet<T>` / `ISet<T>` | `Set[T]` | |
 | `record Point(int x, int y)` | `record Point(int X, int Y)` | `Point = Data.define(:x, :y)` | See [Records ↔ Data.define](#records--datadefine). |
 | `Optional<T>` | `T?` (nullable reference type) | `T?` (i.e. `T \| nil`) | Java models it as a *container*; C# as a *type modifier*. See [Nullability](#nullability). |
-| `enum Color { RED, GREEN }` | `enum Color { Red, Green }` | `Constant<:red> \| Constant<:green>` (Symbol union) | Ruby has no native enum; the [`rigor-mangrove`](../../plugins/) plugin types richer enum DSLs. |
+| `enum Color { RED, GREEN }` | `enum Color { Red, Green }` | `Constant<:red> \| Constant<:green>` (Symbol union) | Ruby has no native enum; the [`rigor-mangrove`](../../plugins) plugin types richer enum DSLs. |
 | `sealed interface Shape permits …` | `abstract` base + sealed hierarchy | union of the subtypes | See [Sealed types & exhaustiveness](#sealed-types-and-exhaustiveness). |
 | `<T>` (generic) | `<T>` (generic) | RBS `[T]` type parameter | |
 | `? extends T` (use-site) | `out T` (declaration-site) | covariant type parameter | See [Generics & variance](#generics-and-variance). |
@@ -124,7 +124,7 @@ behaviour matches.
 | `x instanceof String` | `x is string` | `x.is_a?(String)` |
 | `x instanceof String s` (binding) | `x is string s` (binding) | `case x; in String => s` |
 | `switch (x) { case Foo f -> … }` | `switch (x) { case Foo f => … }` | `case x; in Foo => f` |
-| `(Foo) x` (cast) | `(Foo)x` (cast) | (no in-source cast) — `is_a?` guard, or `T.cast` via [`rigor-sorbet`](../../plugins/rigor-sorbet/) |
+| `(Foo) x` (cast) | `(Foo)x` (cast) | (no in-source cast) — `is_a?` guard, or `T.cast` via [`rigor-sorbet`](../../plugins/rigor-sorbet) |
 | `Objects.requireNonNull(x)` | `x!` (null-forgiving) | (no in-source assertion) — `unless x.nil?`, or `T.must` via `rigor-sorbet` |
 | user method returning `boolean` | user method returning `bool` | `%a{rigor:v1:predicate-if-true x is Foo}` directive on the predicate |
 

data/docs/handbook/appendix-mypy.md

@@ -296,7 +296,7 @@ draws the distinction in full.
   Pyright's "type alias narrowing" and mypy's overload stacks
   cover some cases; Rigor's plugin contract gives you full
   Ruby code at the dispatch point. The
-  [`rigor-lisp-eval`](../../examples/rigor-lisp-eval/) example
+  [`rigor-lisp-eval`](../../examples/rigor-lisp-eval) example
   is the canonical demo — `Lisp.eval([:+, 1, 2])` returns
   `Integer`, `Lisp.eval([:<, 1, 2])` returns `bool`.
 

data/docs/handbook/appendix-protocols-and-structural-typing.md

@@ -228,8 +228,8 @@ author):
 - The `missing-protocol-method` / `protocol-return-mismatch`
   diagnostics are **plugin diagnostics**, emitted under the
   plugin's `plugin.<id>.` provenance — not core Rigor rules. The
-  worked references are [`examples/rigor-web/`](../../examples/rigor-web/)
-  (the minimal tutorial) and [`plugins/rigor-hanami/`](../../plugins/rigor-hanami/)
+  worked references are [`examples/rigor-web/`](../../examples/rigor-web)
+  (the minimal tutorial) and [`plugins/rigor-hanami/`](../../plugins/rigor-hanami)
   (production Hanami 2 actions).
 
 ## Interface vs protocol contract

data/docs/handbook/appendix-rust.md

@@ -91,7 +91,7 @@ The reflex to drop is `unwrap()`. In Rust you reach for
 `.unwrap()` / `.expect()` when you *know* it is `Some`. Rigor
 has no in-source assertion that lies to the checker; the
 equivalents are a `nil?` guard (checked, not asserted) or
-`T.must` via the [`rigor-sorbet`](../../plugins/rigor-sorbet/)
+`T.must` via the [`rigor-sorbet`](../../plugins/rigor-sorbet)
 plugin (see [Chapter 10](10-sorbet.md)).
 
 **`Result<T, E>` ↔ exceptions.** Here the models diverge. Ruby

data/docs/handbook/appendix-type-theory.md

@@ -709,7 +709,7 @@ Rigor maps onto this as:
 | Dynamic type `?` | **`Dynamic[T]`** — a carrier that *wraps* a "best-guess" type `T` while marking the value as not-statically-verified. `Dynamic[top]` is the maximally-dynamic form. |
 | Consistency `~` | The `maybe` arm of the trinary certainty — `Dynamic[T] ~ U` holds whenever `T ~ U` does. |
 | Static/dynamic boundary | Per-method, per-file, per-plugin contribution — Rigor records *why* a value became `Dynamic[T]` in its dynamic-origin algebra. |
-| Casts | No in-source cast operator. The opt-in [`rigor-sorbet`](../../plugins/rigor-sorbet/) plugin reads `T.let` / `T.cast` / `T.must` as cast forms; `RBS::Extended` `assert_type` directives serve the same role from `.rbs`. |
+| Casts | No in-source cast operator. The opt-in [`rigor-sorbet`](../../plugins/rigor-sorbet) plugin reads `T.let` / `T.cast` / `T.must` as cast forms; `RBS::Extended` `assert_type` directives serve the same role from `.rbs`. |
 
 Two Rigor-specific extensions matter:
 
@@ -794,7 +794,7 @@ against:
 ### What Rigor explicitly does NOT do
 
 - **Runtime contract insertion at the static / dynamic boundary.**
-  The opt-in [`rigor-sorbet`](../../plugins/rigor-sorbet/) plugin
+  The opt-in [`rigor-sorbet`](../../plugins/rigor-sorbet) plugin
   reads Sorbet's `T.let` / `T.cast` / `T.must` as cast forms, but
   the contract *enforcement* is `sorbet-runtime`'s job, not
   Rigor's. Rigor's static analysis uses the cast as a hint, not

data/docs/handbook/appendix-typescript.md

@@ -51,7 +51,7 @@ inference cannot see further).
 | `{ name: string; age: number }` | `HashShape{name: String, age: Integer}` | Same per-key model; Ruby uses Symbol keys idiomatically. |
 | `Array<T>` / `T[]` | `Array[T]` | Same. |
 | `Record<K, V>` | `Hash[K, V]` | Same. |
-| `Readonly<T>` | `readonly_of[T]` (via opt-in [`rigor-typescript-utility-types`](../../plugins/rigor-typescript-utility-types/) plugin) | View-level read-only marker on every entry of a `HashShape`. Does NOT prove the underlying object is frozen — ADR-13 § "Readonly". |
+| `Readonly<T>` | `readonly_of[T]` (via opt-in [`rigor-typescript-utility-types`](../../plugins/rigor-typescript-utility-types) plugin) | View-level read-only marker on every entry of a `HashShape`. Does NOT prove the underlying object is frozen — ADR-13 § "Readonly". |
 | `Partial<T>` / `Required<T>` | `partial_of[T]` / `required_of[T]` (same plugin) | Flips every entry's required-ness on a `HashShape`. `Partial` does NOT widen value types to `nil` — Rigor's `HashShape` distinguishes "key absent" from "key present with nil value" (ADR-13 WD on required-ness flips). |
 | `Pick<T, K>` / `Omit<T, K>` | `pick_of[T, K]` / `omit_of[T, K]` (same plugin) | Restrict / remove `HashShape` entries by literal-key union; Tuple receivers project by integer index. Non-shape carriers degrade conservatively and surface `dynamic.shape.lossy-projection`. |
 | Conditional types `T extends U ? A : B` | (none in core; plugin contributions) | A plugin can vary return type by argument shape. |
@@ -159,7 +159,7 @@ inferred call-site instantiation as routinely as TypeScript.
 | `Array<T>` | `Array[T]` |
 | `Map<K, V>` | `Hash[K, V]` |
 | `Promise<T>` | (no analogue — Ruby has no built-in Promise) |
-| `Pick<T, K>` / `Omit<T, K>` / `Partial<T>` / `Required<T>` / `Readonly<T>` | Opt-in [`rigor-typescript-utility-types`](../../plugins/rigor-typescript-utility-types/) plugin maps each onto `pick_of` / `omit_of` / `partial_of` / `required_of` / `readonly_of` over `HashShape` (and `pick_of` / `omit_of` over `Tuple`). |
+| `Pick<T, K>` / `Omit<T, K>` / `Partial<T>` / `Required<T>` / `Readonly<T>` | Opt-in [`rigor-typescript-utility-types`](../../plugins/rigor-typescript-utility-types) plugin maps each onto `pick_of` / `omit_of` / `partial_of` / `required_of` / `readonly_of` over `HashShape` (and `pick_of` / `omit_of` over `Tuple`). |
 | Conditional types | (no analogue — would need a plugin) |
 
 Rigor reads RBS generics through its dispatcher and instantiates
@@ -214,7 +214,7 @@ Be honest about what you give up:
   variation, not type-level expressions.
 - **Mapped types.** `Pick`, `Omit`, `Partial`, `Required`, and
   `Readonly` ship as opt-in plugin-supplied vocabulary via
-  [`rigor-typescript-utility-types`](../../plugins/rigor-typescript-utility-types/),
+  [`rigor-typescript-utility-types`](../../plugins/rigor-typescript-utility-types),
   which maps them onto the Rigor-canonical `pick_of` / `omit_of`
   / `partial_of` / `required_of` / `readonly_of` shape-projection
   type functions on `HashShape` (and `pick_of` / `omit_of` on
@@ -294,7 +294,7 @@ def pick: [K, V] (Hash[K, V] obj, Array[K] keys) -> Hash[K, V]
 
 The RBS sig stays generic. If you want `Pick<T, K>`'s exact-
 key-set tracking back, opt into the
-[`rigor-typescript-utility-types`](../../plugins/rigor-typescript-utility-types/)
+[`rigor-typescript-utility-types`](../../plugins/rigor-typescript-utility-types)
 plugin and annotate the return type with the `Pick` spelling:
 
 ```rbs

data/docs/manual/02-cli-reference.md

@@ -38,7 +38,7 @@ the `paths:` list from the configuration file.
 | `--incremental` | Re-analyse only the files changed since the last run plus the files that depend on them, serving the rest from a cross-process disk snapshot (ADR-46). Diagnostics are identical to a full run; a config / gem / version change (or a file added or removed) transparently forces a full re-analysis. See [Caching](12-caching.md). |
 | `--verify-incremental` | Acceptance gate: run the incremental analyzer against a full `--no-cache` run and assert the diagnostics are byte-identical, then exit (0 on match, 1 with the differing diagnostics on mismatch). Used in CI to guarantee `--incremental` never serves a stale result. |
 | `--clear-cache` | Delete the cache directory before running. |
-| `--cache-stats` | Print the on-disk cache inventory when finished. |
+| `--cache-stats` | Print the on-disk cache inventory when finished — on stdout under `--format text`, on stderr under every other format, so machine-readable output stays a parseable document. `--clear-cache`'s and `--verify-incremental`'s notes follow the same rule. |
 | `--[no-]stats` | Print a run summary (files, classes, memory, wall time) to stderr. Default on. |
 | `--coverage` | Add a type-precision coverage block to the output (`coverage` object under `--format json`; a one-line summary in text mode). Off by default — it is a second precision pass over the analyzed files, the same scan [`rigor coverage`](#rigor-coverage) runs, so it is opt-in. |
 | `--workers=N` | Dispatch analysis across `N` parallel worker processes (fork-based pool today; ADR-15). Default `0` (sequential). Applies to `--incremental` re-checks as well as full runs. |
@@ -169,7 +169,10 @@ Report what each method *does* — its effect labels — rather
 than what it returns, and manage the committed **effect
 snapshot** that gates drift. Opt-in and observational: nothing
 here emits a diagnostic or changes `rigor check`'s output, and
-only `rigor effects check` ever exits non-zero.
+only `rigor effects check` ever exits non-zero. The workflow
+around these verbs — the label vocabulary, how to read the
+report at scale, the review loop and the CI step — is
+[Effect labels](19-effect-labels.md).
 
 ```sh
 rigor effects [PATH...]                       # the report
@@ -183,6 +186,13 @@ configuring anything; such an ad-hoc run shares no cache with
 `rigor check`, because a run served from that cache would have
 collected nothing.
 
+Passing paths narrows the **analysis**, not just the output.
+Labels are transitive over what was analysed, so a method whose
+callees were not analysed reports fewer labels and a wider
+"possibly more" than the same method in a whole-project run —
+honest, but not a cheaper way to get the whole-project answer.
+Filter the output when you want the real footprint.
+
 Each line is one method, sorted by key:
 
 ```
@@ -199,10 +209,13 @@ lines say why. A taint is never a finding.
 
 A ` ≤ [...]` clause after the labels is the **declared** lane:
 what a source Rigor trusts but did not verify *claims* the
-method does, today the `effects.attribution:` table you wrote
-for gem methods it cannot see. It is printed apart from the
-proven labels and never folded in among them, because the two
-answer different questions. It follows call edges exactly as
+method does. Two sources feed it — the plugins you activated,
+which on a framework application contribute most of it
+(`rails.session.write` and the rest of `rails.*` are Action
+Pack's rows, not yours), and the `effects.attribution:` table
+you wrote for gem methods nothing models. It is printed apart
+from the proven labels and never folded in among them, because
+the two answer different questions. It follows call edges exactly as
 the proven labels do, so a controller two hops above an
 attributed gem call carries the claim rather than only a
 "possibly more"; a declared label the proven list already
@@ -213,10 +226,30 @@ Gateways::Client#fetch: [] ≤ [io.net.http] …?
     plugin-attribution (Acme::Http.get)
 ```
 
-A method is omitted when it is exhaustive and proves nothing
-beyond `mutate.local` — mutation of objects its own frame
-allocated and never let out, which every effect envelope
-tolerates. `--full` lists every method instead.
+Two kinds of method are omitted: one that proves nothing
+beyond `mutate.local` and claims nothing — mutation of objects
+its own frame allocated and never let out, which every effect
+envelope tolerates — and one with no label in either lane,
+which exists only to record that something below it was
+unresolved. `--full` lists both. `--pure` asks for the first
+group by name, which is the set worth annotating `%a{pure}`.
+
+`--label=LABEL` prints only the methods carrying `LABEL` or a
+label under it, in either lane. `--limit=N` caps the rows.
+`--why` expands each row's unresolved reasons and the plugin
+row behind each declared label, which are collapsed to a count
+by default. The report closes with a footer counting the two
+lanes apart, because they have different powers: a proven label
+can fail a build and a declared one cannot
+([ADR-103](../adr/103-effect-labels.md) § WD17).
+
+A `PATH` argument selects which methods are **printed**, never
+which are analysed: Rigor analyses your configured `paths:`
+either way, so a selected row carries exactly the labels the
+whole-project run gives it, and a note on stderr says how many
+of how many you are looking at. A path outside `paths:` is
+analysed as well as them, so pointing the command at a tree
+your configuration does not cover still works.
 
 `--format=text|json` selects the output format; the JSON
 payload additionally carries each method's *direct* summary
@@ -226,9 +259,15 @@ subcommands and does nothing here: the report is an
 observation, and observations are undischarged.
 
 What is collected and how it propagates is
-[the effect-summaries internal spec](../internal-spec/effect-summaries.md);
-the label vocabulary is
-[the effect-labels specification](../type-specification/effect-labels.md).
+[the effect-summaries internal spec](../internal-spec/effect-summaries.md).
+`--list-labels` prints the vocabulary this project can name —
+every shipped label with its root's meaning, plus whatever your
+plugins and your `effects.labels:` opened — and exits without
+analysing anything. The same table is in
+[Effect labels § The label vocabulary](19-effect-labels.md), and
+the grammar is specified normatively in the effect-labels
+specification, which the gem does not ship:
+<https://rigor.typedduck.fail/type-specification/effect-labels/>.
 
 ### The effect snapshot
 
@@ -265,8 +304,8 @@ supposed to fan out — the fan-out is the blast radius.
 
 ```yaml
 # .rigor-effects.yml — generated by `rigor effects update`. Commit it; review its diff.
-schema: 1
-rigor: "0.3.3"
+schema: 2
+rigor: "0.3.5"
 vocabulary: 1
 config_digest: "9ec82bfc…"
 methods:
@@ -275,7 +314,7 @@ methods:
   "Reports::Nightly#perform":
     effects: ["io.db.read"]
     exhaustive: false
-    unresolved: ["dynamic-send"]
+    unresolved: 1
 reach:
   "OrdersController#create":
     effects: ["io.db.read", "io.net.http", "job.enqueue"]
@@ -337,14 +376,17 @@ spelled out:
 Effect drift against .rigor-effects.yml:
 
 methods:
-  PaymentGateway#charge  + io.net.http
+  PaymentGateway#charge  + io.net.http  (app/services/payment_gateway.rb:18)
 
 reach:
-  OrdersController#create  + io.net.http
+  OrdersController#create  + io.net.http  (app/controllers/orders_controller.rb:7)
 
-Run `rigor effects update` and commit the result if this change is intended.
+Run `rigor effects explain` to see what caused this, and `rigor effects update` to accept it.
 ```
 
+Each row names where the method is defined, so the reviewer reads the report
+rather than searching for the method.
+
 The author runs `rigor effects explain` to see the route —
 
 ```
@@ -517,7 +559,7 @@ hand-adjudicated corpus target only **7% of the rows were genuinely
 unused**; the rest were reachable by means static analysis cannot
 see. That is why this is a separate command and never a `rigor check`
 diagnostic — see
-[ADR-102](https://github.com/rigortype/rigor/blob/master/docs/adr/102-unused-code-reachability-report.md).
+[ADR-102](../adr/102-unused-code-reachability-report.md).
 
 Reachability is computed from **roots**, not by counting references,
 so a cluster of classes that only reference each other is still
@@ -1053,9 +1095,10 @@ operational knobs read the environment instead.
 | `RIGOR_CI_DETECT=0` | Turn off CI auto-detection — the same as `--no-ci-detect`. See [Running Rigor in CI § auto-detection](11-ci.md). |
 | `RIGOR_RACTOR_WORKERS=N` | Worker count for parallel analysis. Sits between the CLI flag and the config key in precedence: `--workers=N` > `RIGOR_RACTOR_WORKERS` > `parallel.workers:` > `0` (sequential). |
 | `RIGOR_POOL_BACKEND=ractor` | Opt back into the (off-by-default) Ractor worker pool instead of the active fork-based pool ([ADR-15](../adr/15-ractor-concurrency.md)). Only relevant with a non-zero worker count; the fork pool is the supported backend. |
+| `RIGOR_LSP_POOL_MIN_BATCH=N` | Fewest buffers an [`rigor lsp`](#rigor-lsp) batch must carry before analysis is dispatched across the worker pool rather than run in-process (default `16`). Lower it if your project's per-file analysis is expensive enough that pooling pays off sooner. |
 | `RIGOR_PLUGIN_ISOLATION=none\|process\|ruby_box` | How a plugin's direct calls into its target library are isolated. Default `process`. See [Using plugins § Isolation strategy](07-plugins.md). `RIGOR_BOX` is a legacy alias for `ruby_box`. |
 | `RIGOR_STRICT_VALIDATION=1` | Force full-content cache validation for one run (the same as `cache.validation: digest`, and winning over it) — re-hash every file's content instead of trusting its stat metadata. Use it if a filesystem's timestamps or inode numbers cannot be trusted. See [Caching § How a file is checked for changes](12-caching.md#how-a-file-is-checked-for-changes). |
-| `RIGOR_DISABLE_YJIT=1` | Opt out of Rigor's deferred YJIT enablement. Rigor turns YJIT on partway through a long `check` / `coverage` run so short runs never pay the JIT warm-up; this variable leaves it off entirely. Diagnostics and allocations are identical either way — the effect is wall-time only. |
+| `RIGOR_DISABLE_YJIT=1` | Opt out of Rigor's deferred YJIT enablement. Rigor turns YJIT on partway through any long run so short runs never pay the JIT warm-up; this variable leaves it off entirely. Diagnostics and allocations are identical either way — the effect is wall-time only. |
 | `RIGOR_YJIT_DEADLINE=<seconds>` | Advanced: tune how long a run must last before deferred YJIT enables (default `5.0`). Lower it if your runs are long and you want the JIT sooner; raise it to protect short runs. Ignored when `RIGOR_DISABLE_YJIT=1` is set or YJIT is unavailable. |
 
 Three further variables (`RIGOR_BUDGET_TRACE`,
@@ -1069,7 +1112,15 @@ diagnostics about Rigor's own inference cutoffs and memory — see
 | --- | --- |
 | `0` | Success — no error-severity diagnostics. |
 | `1` | Diagnostics found, or a per-command failure (parse error, missing file, new diagnostics on `diff`, effect drift on `effects check`). |
-| `64` | Usage error — unknown command, bad flag, malformed argument. |
+| `64` | Usage error — unknown command, bad flag, malformed argument, or a value in `.rigor.yml` the loader cannot proceed on. |
 
 `rigor triage` is the exception: it is advisory and always
 exits `0`.
+
+A configuration mistake prints one `rigor:` line naming the key
+and nothing else — no backtrace, on every command:
+
+```
+$ rigor effects update
+rigor: effects.attribution key is not a method key (`Owner#method` / `Owner.method`): "Net::HTTP get"
+```