rigortype 0.3.5 → 0.3.7

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. |
@@ -114,16 +114,25 @@ missing file.
 
 ## `rigor type-of`
 
-Print the inferred type at one source position.
+Print inferred types at one or more source positions.
 
 ```sh
-rigor type-of FILE:LINE:COL
-rigor type-of FILE LINE COL
+rigor type-of [options] FILE:LINE[:COL] [FILE:LINE[:COL] ...]
+rigor type-of [options] FILE LINE COL
 ```
 
-Accepts the position as a single `file:line:col` triple or as
-three arguments. `--format=json` emits a machine-readable
-form; `--trace` records fail-soft fallbacks. The editor-mode
+The colon form is repeatable and keeps argument order while
+parsing and scope-indexing each file once. Omit `COL` to print a
+table of up to 40 expressions that start on that line, outermost
+first at each 1-based column; the table marks when further
+expressions were omitted. The legacy three-argument form accepts
+one exact position.
+
+`--format=json` keeps one result as the original flat object and
+wraps several results in a `results` array. Line queries add a
+`line_enumerations` array whose `shown` and `total` counts make
+truncation explicit. `--trace` records fail-soft fallbacks,
+after the rows of a line table in text output. The editor-mode
 `--tmp-file` / `--instead-of` pair is accepted as on `check`.
 
 ## `rigor trace`
@@ -304,8 +313,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:
@@ -314,7 +323,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"]
@@ -376,14 +385,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 —
 
 ```
@@ -556,7 +568,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
@@ -998,7 +1010,7 @@ Queued today:
 
 | Feature id | Kind | What it changes |
 | --- | --- | --- |
-| `reject-unparseable-signatures` | severity | An unparseable `.rbs` under `signature_paths:` **fails the run** (`rbs.coverage.quarantined-signature` → `error`) instead of being skipped with a warning. |
+| `reject-unparseable-signatures` | severity | A broken RBS set **fails the run** instead of degrading it silently: an unparseable `.rbs` under `signature_paths:` (`rbs.coverage.quarantined-signature` → `error`), a declaration that collides on resolve and collapses the whole environment (`rbs.coverage.environment-build-failed` → `error`), and a duplicate method definition that collapses one class's method surface (`rbs.coverage.definition-build-failed` → `error`). |
 | `use-of-void-value` | severity | Using a value recovered from an author-declared `-> void` return in value context is reported as `static.value-use.void` (`warning`). |
 | `discovery-seeded-mutation-sites` | behaviour | [`rigor coverage --protection --mutation`](15-type-protection-coverage.md) measures against the same cross-file project discovery Tier 1 already uses — both when picking the sites and when deciding whether a breakage was caught — so a call on a project class declared in a *sibling* file is measured instead of dropped, and a breakage there can actually be caught. **Adds sites to the denominator, so the reported effectiveness ratio moves** — check it against any `--threshold` you pin in CI before adopting. |
 | `dependent-closure-kill-oracle` | behaviour | [`rigor coverage --protection --mutation`](15-type-protection-coverage.md) counts a breakage as caught when the diagnostic appears anywhere in the mutated file **or the files that depend on it**, instead of in the mutated file alone — so changing what a method returns counts as caught when the error lands in its callers. Can only **add** kills, so the ratio moves up or not at all; it costs about a third more wall time per mutant, and a ratio measured under it is not comparable with one measured without it. |
@@ -1092,9 +1104,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`,

data/docs/manual/03-configuration.md

@@ -251,7 +251,7 @@ stanza it broke:
 ```
 app/presenters/user_presenter.rb:14:1: warning: Method Presenters::User#render performs io.fs.read
   (File.read), but is declared effect: [] at .rigor.yml effects.envelopes[0], so io.fs.read exceeds
-  the envelope.
+  the envelope. [effect.envelope-exceeded]
 ```
 
 When one method is a deliberate exception, write the narrower envelope on it in RBS — nearest wins,

data/docs/manual/04-diagnostics.md

@@ -19,6 +19,18 @@ Every rule has a two-segment `family.rule` identifier:
 | `assert` | `assert_type` checks. |
 | `dump` | `dump_type` notices. |
 
+Every diagnostic carries its identifier in brackets at the end of the
+line, so the ID you need for `# rigor:disable`, for `disable:` and for
+`severity_profile:` is the one you are already looking at:
+
+```text
+app/user.rb:11:3: error: undefined method `lenght' for "hello" [call.undefined-method]
+```
+
+A diagnostic no rule produced — a parse error, a path error, an
+internal analyzer error — has nothing to suppress and carries no
+bracket.
+
 `rigor explain <rule>` prints the full catalogue entry for any
 built-in rule ID; `rigor explain` with no argument lists them all.
 

data/docs/manual/05-inspecting-types.md

@@ -63,19 +63,31 @@ syntax-highlighted for a tty — through
 colorizer; `--no-color` (and the `NO_COLOR` environment
 variable) disable the colour.
 
-## `rigor type-of` — one position
+## `rigor type-of` — exact positions or a whole line
 
-When you only need one expression's type — typically while
-chasing down why a diagnostic did or did not fire — query a
-single position:
+When you need a few expression types — typically while chasing
+down why a diagnostic did or did not fire — query the exact
+positions together so Rigor loads the project and each source
+file once:
 
 ```sh
-rigor type-of lib/example.rb:12:8
+rigor type-of lib/example.rb:12:8 lib/example.rb:12:14
 ```
 
-`--format=json` emits a machine-readable result for tooling.
-This is the same query the editor integration answers on
-hover.
+Leave off the column to avoid counting it by hand. Rigor prints
+a table of the first 40 expressions starting on the line,
+outermost first at each 1-based column, and marks a truncated
+table:
+
+```sh
+rigor type-of lib/example.rb:12
+```
+
+`--format=json` emits a machine-readable result for tooling: one
+result stays a flat object, while several results use a `results`
+array. Line queries add `line_enumerations` metadata with the
+shown and total expression counts. An exact position is the same
+query the editor integration answers on hover.
 
 ## `rigor trace` — watch the inference happen
 

data/docs/manual/07-plugins.md

@@ -49,6 +49,10 @@ each plugin's options — but the families today are:
   `rigor-factorybot`.
 - **dry-rb** — `rigor-dry-types`, `rigor-dry-schema`,
   `rigor-dry-struct`, `rigor-dry-validation`.
+- **FFI** — `rigor-ffi` and sub-plugins (`rigor-ffi-rzmq`,
+  `rigor-rbnacl`, `rigor-sassc`, `rigor-ethon`). For plugin authors,
+  `rigor-ffi` provides the `ffi_binding_recognizer` class DSL on
+  `Rigor::Plugin::Base` to recognize custom binding definitions.
 - **Other ecosystems** — `rigor-sinatra`, `rigor-hanami`,
   `rigor-devise`, `rigor-pundit`, `rigor-sidekiq`,
   `rigor-graphql`, `rigor-statesman`, `rigor-sorbet`,

data/docs/manual/08-skills.md

@@ -2,7 +2,7 @@
 
 Rigor bundles a set of **Agent Skills** — structured workflows an AI
 coding agent (Claude Code and compatible tools) can run on your behalf.
-They live in [`skills/`](../../skills/) and are auto-discovered when an
+They live in [`skills/`](../../skills) and are auto-discovered when an
 agent works inside a project that has Rigor available.
 
 Skills are optional. Everything they do, you can do by hand with the

data/docs/manual/11-ci.md

@@ -73,7 +73,7 @@ platform reads to annotate the diff directly, instead of leaving them in
 the job log ([ADR-51](../adr/51-ci-diagnostic-output-formats.md)). These
 layer on the generic `--format json` stream; they add no new diagnostics,
 only a platform-native rendering. Ready-to-copy template files live under
-[`ci-templates/`](ci-templates/).
+[`ci-templates/`](ci-templates).
 
 ### GitHub — inline annotations (the default)
 

data/docs/manual/12-caching.md

@@ -137,7 +137,7 @@ CI detection that `auto` relies on.
 | --- | --- |
 | `rigor check --no-cache` | Run without reading or writing the persistent cache. |
 | `rigor check --clear-cache` | Delete the cache directory, then run. |
-| `rigor check --cache-stats` | Print the on-disk cache inventory when the run finishes. |
+| `rigor check --cache-stats` | Print the on-disk cache inventory when the run finishes (on stderr under every `--format` but `text`, so the document on stdout stays parseable). |
 | `rigor check --incremental` | Re-analyse only what changed; serve the rest from the incremental snapshot (see below). |
 
 There is no config key to disable caching permanently — the

data/docs/manual/15-type-protection-coverage.md

@@ -333,7 +333,7 @@ ones a type actually catches.
 > [Configuration](03-configuration.md)). A project whose gems live in
 > the active Ruby's default gem home — the common `rbenv` / `mise`
 > case with no `--path` set — is invisible to the isolated analyzer by
-> design ([ADR-27](https://github.com/rigortype/rigor/blob/master/docs/adr/27-tool-distribution-model.md)):
+> design ([ADR-27](../adr/27-tool-distribution-model.md)):
 > point Rigor at it with `bundler.bundle_path:`. Until you do, these
 > holes keep the generic `engine_gap` cause instead of `add_rbs` —
 > the label is missing, never wrong.

data/docs/manual/18-removing-dead-code.md

@@ -140,7 +140,7 @@ Four sections, needing four different decisions:
 
 | Section | What it means | What to do |
 | --- | --- | --- |
-| **Reachable only from test code** | Live test, no production caller | Work these first |
+| **Reachable only from test code** | Live test, no production caller Rigor can see or suspect | Work these first |
 | **Candidates** | Nothing reachable names it | Adjudicate — most are still live |
 | **Cannot decide** | Something can name it at runtime | Read the reason; do not delete from here |
 | **Namespace-only** | A module wrapping live code | Excluded from candidates; count only |
@@ -209,14 +209,23 @@ skip most of a list quickly:
 
 ### Cannot decide: read the reason, do not delete
 
-These were demoted out of `candidates` because something can name the
-class at runtime. Each row says what:
+These were demoted because something can name the class at runtime —
+out of `candidates`, or out of **reachable only from test code**. Each
+row says what:
 
 ```
   1  Handlers::Alpha                     lib/handlers.rb:2
        constantize on an interpolated string (lib/dispatch.rb:14)
 ```
 
+A row demoted out of the test-only section is the second kind, and it
+is the one worth knowing about: a class your specs reference and a
+data file also names — a job in `config/recurring.yml`, a class named
+from a YAML setting — is not a dead production path, because the
+configuration may well be what drives it. The test-only section makes
+a claim about production, so a row Rigor holds evidence against
+belongs here instead, with the file named.
+
 `"Foo".constantize` names `Foo` exactly, so it counts as an ordinary
 reference and never reaches this section. `"Foo::#{key}".constantize`
 can only bound the namespace, so everything under `Foo` is demoted. A
@@ -322,5 +331,5 @@ Running it as a **reporting** job is fine, and is the intended way to
 notice the drift described above: run it on a schedule, publish the
 JSON, and let a person read the trend.
 
-[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
 [issue-363]: https://github.com/rigortype/rigor/issues/363

data/docs/manual/19-effect-labels.md

@@ -313,8 +313,8 @@ digest of your `effects:` block, so an upgrade or a policy edit shows up as a
 
 ```yaml
 # .rigor-effects.yml — generated by `rigor effects update`. Commit it; review its diff.
-schema: 1
-rigor: "0.3.4"
+schema: 2
+rigor: "0.3.5"
 vocabulary: 1
 config_digest: "44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a"
 methods:
@@ -324,10 +324,12 @@ methods:
 
 Two notes on reading the file:
 
-- **Do not read the `unresolved:` arrays.** They are inference-quality metadata,
-  they are what makes half the file's bytes, and they churn on Rigor upgrades
-  and on unrelated edits. They exist so `check` can print
-  `exhaustive → not`. The lines a reviewer reads are `effects:` and `declared:`.
+- **`unresolved:` is a count, not a list.** It says how many calls the analyzer
+  could not follow, which is why `exhaustive:` is false. The causes themselves
+  are not recorded — they are inference-quality metadata that churns on Rigor
+  upgrades and on unrelated edits — so ask for them when you need them:
+  `rigor effects explain` names them, including for an `exhaustive → not` row.
+  The lines a reviewer reads are `effects:` and `declared:`.
 - Trivial and synthesised entries are left out, as in the report. `--full`
   records everything, and produces a much larger and much noisier file.
 
@@ -398,11 +400,11 @@ CI runs `rigor effects check` and fails, exit 1:
 Effect drift against .rigor-effects.yml:
 
 methods:
-  Change#init_path  + io.fs.write
-  Change#init_path  + nondet.time
-  Change#init_path  exhaustive → not
+  Change#init_path  + io.fs.write  (app/models/change.rb:41)
+  Change#init_path  + nondet.time  (app/models/change.rb:41)
+  Change#init_path  exhaustive → not  (app/models/change.rb:41)
 
-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.
 ```
 
 `+ label` and `- label` are the proven lane; `≤+` / `≤-` the declared one;
@@ -410,6 +412,11 @@ Run `rigor effects update` and commit the result if this change is intended.
 someone introduced a call Rigor cannot follow; `+symbol` / `-symbol` are methods
 that appeared or vanished, and a rename is one of each.
 
+The parenthetical is where the method is defined — the file, and the `def`'s own
+line when the file has one. A method defined by a reopening spans several files
+and the row names them all; a `-symbol` row carries no position, because a method
+this run no longer sees is one it cannot locate.
+
 Before regenerating, ask why:
 
 ```sh
@@ -518,7 +525,7 @@ A method that exceeds its bound gets one diagnostic per (method, label) pair, at
 its `def`, naming the route:
 
 ```
-app/helpers/application_helper.rb:59:1: warning: Method ApplicationHelper#link_to_principal performs io.fs.read (Dir.glob via IconsHelper#principal_icon → IconsHelper#sprite_icon → IconsHelper#sprite_source → Redmine::Themes::Helper#current_theme → Redmine::Themes.theme → Redmine::Themes.themes → Redmine::Themes.scan_themes), but is declared effect: [] at .rigor.yml effects.envelopes[0], so io.fs.read exceeds the envelope.
+app/helpers/application_helper.rb:59:1: warning: Method ApplicationHelper#link_to_principal performs io.fs.read (Dir.glob via IconsHelper#principal_icon → IconsHelper#sprite_icon → IconsHelper#sprite_source → Redmine::Themes::Helper#current_theme → Redmine::Themes.theme → Redmine::Themes.themes → Redmine::Themes.scan_themes), but is declared effect: [] at .rigor.yml effects.envelopes[0], so io.fs.read exceeds the envelope. [effect.envelope-exceeded]
 ```
 
 **Budget for a big first number.** That one stanza, on Redmine, is **343
@@ -608,7 +615,7 @@ app/serializers/rest/v1/instance_serializer.rb:89:1: warning: Method
   REST::V1::InstanceSerializer#invites_enabled performs mutate.self
   (receiver-mutation via UserRole.everyone → UserRole.create! → UserRole#set_position),
   but is declared effect: [] at .rigor.yml effects.envelopes[0], so mutate.self
-  exceeds the envelope.
+  exceeds the envelope. [effect.envelope-exceeded]
 ```
 
 Rigor walked *through* the database write and reported the ivar assignment beyond

data/docs/manual/README.md

@@ -80,7 +80,7 @@ flag, key, or command that *acts* on it.
     Cline, …) via `rigor mcp`.
 11. [Running Rigor in CI](11-ci.md) — a clean CI job, inline
     PR/MR diagnostics (SARIF / GitHub Actions / GitLab Code
-    Quality), copy-paste [templates](ci-templates/), and
+    Quality), copy-paste [templates](ci-templates), and
     version pinning.
 12. [Caching](12-caching.md) — where the cache lives, what
     invalidates it, and how to clear it.
@@ -94,4 +94,4 @@ flag, key, or command that *acts* on it.
 - [`docs/types.md`](../types.md) — one-page type-system guide.
 - [`docs/type-specification/`](../type-specification/README.md)
   — the normative spec corpus.
-- [`docs/adr/`](../adr/) — architecture decision records.
+- [`docs/adr/`](../adr) — architecture decision records.

data/docs/manual/plugins/rigor-actionmailer.md

@@ -17,10 +17,10 @@ plugins:
 ## What it checks
 
 ```text
-demo.rb:7:1:  info:  `UserMailer.welcome` matches mailer action (arity 1..2)
-errors_demo.rb:7:1:  error: `UserMailer.welcome` expects 1..2 argument(s), got 0
-errors_demo.rb:15:1: error: `UserMailer.does_not_exist` is not a defined mailer action (known actions: digest, reset_password, welcome)
-app/mailers/user_mailer.rb:14:7: warning: `UserMailer#digest` has no view template under `app/views/user_mailer/`
+demo.rb:7:1: info: `UserMailer.welcome` matches mailer action (arity 1..2) [plugin.actionmailer.mailer-call]
+errors_demo.rb:10:1: error: `UserMailer.welcome` expects 1..2 argument(s), got 0 [plugin.actionmailer.wrong-arity]
+errors_demo.rb:18:1: error: `UserMailer.does_not_exist` is not a defined mailer action (known actions: digest, reset_password, welcome) [plugin.actionmailer.unknown-action]
+app/mailers/user_mailer.rb:26:7: warning: `UserMailer#digest` has no view template under `app/views/user_mailer/` [plugin.actionmailer.missing-view]
 ```
 
 1. **Action existence** — `Mailer.unknown_action(...)` →

data/docs/manual/plugins/rigor-actionpack.md

@@ -56,6 +56,43 @@ plugins:
       view_search_paths: ["app/views"]               # default
 ```
 
+## What it types
+
+Inside a controller, `params`, `request`, `session`, `flash` and
+`cookies` type as their Action Pack classes, and so do the chains
+built on them:
+
+```ruby
+request.post?          # bool — and so do get? / put? / patch? / delete? /
+                       # head? / options? / trace? / link? / unlink? /
+                       # xhr? / xml_http_request? / ssl? / local? / form_data?
+flash.now              # ActionDispatch::Flash::FlashNow
+flash.keep             # ActionDispatch::Flash::FlashHash
+flash[:notice] = "hi"  # "hi" — an assignment is its right-hand side
+```
+
+Rigor ships **no signature** for these Action Pack classes, on
+purpose: the receiver becomes concrete (so `rigor coverage
+--protection` counts the site) while the method surface stays
+lenient, so `request.headers`, `flash.now[:alert] = x` and anything
+else the framework adds resolve without a diagnostic. A partial
+signature would be worse than none — every member it omitted would
+become a false `call.undefined-method`.
+
+The predicates are typed `bool` — the union of `true` and `false` —
+which is both the real contract (every one of them is an `==`,
+`match?` or `include?` in Rails or Rack) and the reason they are safe
+to type at all: a condition that folds needs to prove *one* constant,
+and a union of both never does. `return unless request.post?` and
+`mode = request.get? ? :a : :b` read exactly as they did before.
+
+`request.format` is **not** typed. That inertness argument is
+narrower than it looks — it holds for a union of the two boolean
+constants, not for a union of ordinary classes, which is nil-free and
+so *can* fold a condition — and `Mime::NullType`, the value `format`
+returns when there is no format, answers `nil?` with `true` while
+being a real object. Typing it needs a nil-aware answer.
+
 ## Limitations
 
 - **Implicit-self helpers only.** `*_path` / `*_url` calls with an
@@ -69,6 +106,30 @@ plugins:
   knows what `rigor-rails-routes` published, and `permit`
   validation only what `rigor-activerecord` published — enabling
   those producers widens what this plugin can check.
+- **`params[:key]` stays untyped.** Inside a controller, `params`
+  types as `ActionController::Parameters`, and so does the result
+  of every builder method that always returns one — `require`,
+  `permit`, `permit!`, `expect`, `slice`, `slice!`, `except`,
+  `without`, `extract!`, `merge`, `merge!`, `reverse_merge`,
+  `reverse_merge!`, `with_defaults`, `with_defaults!`, `compact`,
+  `compact_blank`, `deep_dup` — so a chain built from them keeps a
+  concrete receiver throughout. A subscript read is deliberately
+  left untyped: `params[:missing]` is `nil` at runtime, and a type
+  that says otherwise would let the flow rules fold live
+  conditions (`if params[:q]`, `url.nil?`) to a constant and report
+  working code. Methods whose result depends on the call — `dig`,
+  `fetch`, `compact!`, and the block-less `select` / `reject` /
+  `transform_keys` / `transform_values` — are untyped for the same
+  reason.
+- **`flash[:key]` and `session[:key]` stay untyped too**, for that
+  same reason and measured the same way. Both are leaf reads that
+  return whatever was stored — or `nil` for a key that is not set.
+  A non-nil type folds `mode = flash[:notice] ? … : …` to one arm and
+  reports the live guard after it; a nullable one puts
+  `call.possible-nil-receiver` on `note = flash[:notice];
+  note.upcase`. Writing through them is unaffected: `flash[:k] = v`
+  is `v` because that is what an assignment expression means in Ruby,
+  with no rule needed.
 
 ## Plugin internals
 

data/docs/manual/plugins/rigor-activejob.md

@@ -18,9 +18,9 @@ Given a job whose `#perform` takes one required and one optional
 argument (arity `1..2`):
 
 ```text
-demo.rb:6:1:  info:  `WelcomeEmailJob.perform_later` matches `#perform` (arity 1..2)
-demo.rb:9:1:  error: `WelcomeEmailJob.perform_later` expects 1..2 argument(s), got 0
-demo.rb:12:1: error: `WelcomeEmailJob.perform_later` expects 1..2 argument(s), got 3
+demo.rb:8:1: info: `WelcomeEmailJob.perform_later` matches `#perform` (arity 1..2) [plugin.activejob.job-call]
+errors_demo.rb:10:1: error: `WelcomeEmailJob.perform_later` expects 1..2 argument(s), got 0 [plugin.activejob.wrong-arity]
+errors_demo.rb:14:1: error: `WelcomeEmailJob.perform_later` expects 1..2 argument(s), got 3 [plugin.activejob.wrong-arity]
 ```
 
 A `*rest` parameter yields an unbounded upper bound (`arity 0+`).