rigortype 0.3.3 → 0.3.4

data/data/effects/registry.yml

@@ -0,0 +1,67 @@
+# Effect-label registry — the shared vocabulary of ADR-103 WD2, normative in
+# `docs/type-specification/effect-labels.md`.
+#
+# Hand-written, NOT generated: every row is a deliberate vocabulary decision. The generated
+# `data/builtins/ruby_core/*.yml` `purity:` facet answers fold-safety, not effects, and is never
+# read as a label source (ADR-103 WD3).
+#
+# `vocabulary` bumps only on a rename or a removal, never on a leaf addition — adding a leaf can
+# never change what a recognised bound admits, because subsumption is a segment-aware prefix test.
+# A renamed or removed spelling is recorded in `retired:` so a snapshot written by an older Rigor
+# still reads.
+vocabulary: 1
+
+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.
+  - exit
+  - ffi
+  - global.read
+  - global.write
+  - io
+  - io.db
+  - io.fs
+  - io.fs.read
+  - io.fs.write
+  - io.input
+  - io.ipc
+  - io.net
+  - io.net.http
+  - io.output
+  - io.output.buffer
+  - io.output.header
+  - io.output.stdout
+  - io.output.stderr
+  - io.process
+  - io.signal
+  - mutate
+  - mutate.local
+  - nondet
+  - nondet.random
+  - nondet.time
+
+  # Ruby leaves under `mutate` (Steins ADR-0055's names; ADR-103 WD14). `mutate.self` is self's
+  # state, `mutate.instance` a receiver that is neither self nor frame-owned, `mutate.static`
+  # class-level state. Unknown ownership taints rather than producing a bare `mutate`.
+  - mutate.self
+  - mutate.instance
+  - mutate.static
+
+  # Proposed shared core leaves, to raise with Steins: a `SELECT` is a read whichever language
+  # issued it, an `INSERT` a write, `BEGIN`/`COMMIT` neither.
+  - io.db.read
+  - 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.
+  - telemetry
+  - email.send
+  - job.enqueue
+  - cache.read
+  - cache.write
+
+# Retired spellings: `old.label: [replacement, ...]`. Empty at vocabulary 1 — nothing has been
+# renamed or removed yet.
+retired: {}

data/docs/handbook/07-rbs-and-extended.md

@@ -165,6 +165,79 @@ so because you added it. The stacking and diagnostic semantics
 are in
 [manual — `conforms-to`](../manual/16-rbs-extended-annotations.md#conforms-to--a-checked-structural-contract).
 
+## Bounding what a method *does* — effect envelopes
+
+Every directive so far describes what a method returns. One
+describes what it *does*:
+
+```rbs
+class UserRepository
+  %a{rigor:v1:effect io.db}
+  def find: (Integer) -> User
+
+  %a{pure}
+  def slug: (String) -> String
+end
+```
+
+`%a{rigor:v1:effect io.db}` says "this method may touch the
+database, and nothing else the vocabulary names". `%a{pure}`
+says "nothing at all" — it is rbs' own purity annotation, the
+one Steep already reads, so Rigor honours the spelling that
+exists rather than inventing a synonym. Both tolerate mutating
+objects the method itself allocated and never let out, so a
+`%a{pure}` method may still build and fill a local array.
+
+The payload is a comma-separated list of bare labels
+(`%a{rigor:v1:effect io.db, nondet.time}`), from the vocabulary
+in
+[effect-labels.md](../type-specification/effect-labels.md).
+Write the annotation on a `class` or `module` declaration
+instead and it applies to every method of that class —
+reopenings and `attr_writer`-generated methods included, but
+never to subclasses. A method that carries its own envelope
+keeps it; nearest wins.
+
+The bound covers the method's whole *code*, including what it
+calls. A `find` declared `io.db` that reaches an HTTP request
+through a helper exceeds its envelope, and Rigor says so — on
+the Ruby `def`, naming the route it took:
+
+```text
+lib/user_repository.rb:12: warning: Method UserRepository#find
+performs io.net.http (Net::HTTP.get via PaymentGateway#charge),
+but is declared %a{rigor:v1:effect io.db} at sig/repo.rbs:3,
+so io.net.http exceeds the envelope.
+```
+
+Two things it will not do. It never reports an effect it only
+*suspects*: a call Rigor could not resolve makes the summary
+read "and possibly more", and possibly is not a finding. And
+none of this happens unless you asked for it — the check needs
+an `effects:` block in `.rigor.yml`, so an `%a{pure}` already
+sitting in your signatures for Steep's benefit stays inert
+until you opt in. Set `effects.check: false` to keep the
+`rigor effects` report and its snapshot while silencing the
+diagnostic. Inert is not the same as unmentioned: annotations
+with no `effects:` block earn one
+[`effect.annotations-unchecked`](../manual/04-diagnostics.md#rule-effect-annotations-unchecked)
+`:info` per run, so a bound nobody checks never goes unnoticed.
+
+Misspell a label and the annotation does not narrow to the part
+Rigor recognised — the **whole** tag reads as unbounded, so a
+typo can never turn into findings on correct code. That would
+be a silent loss of a contract you thought you had, so where
+the spelling is evidently meant to be a label Rigor says so:
+[`effect.unknown-label`](../manual/04-diagnostics.md#rule-effect-unknown-label),
+at the line you wrote it on, naming the nearest real label.
+A word that resembles nothing in the vocabulary stays silent —
+you may be opening a root of your own.
+
+The whole feature — the label vocabulary, the committed effect
+snapshot, and `rigor effects` itself — is
+[ADR-103](../adr/103-effect-labels.md); start with
+[`rigor effects`](../manual/02-cli-reference.md#rigor-effects).
+
 ## Worked example: an assertion gate
 
 ```rbs
@@ -299,11 +372,39 @@ class Slug
 end
 ```
 
-You **cannot** put these `%a{rigor:v1:…}` directives inside a
-`.rb` file. The directives only fire when read from RBS —
-that is a design choice (see
-ADR-5, the robustness principle: strict on returns, lenient
-on parameters).
+You can also write them **in a `.rb` file**, as rbs-inline
+`# @rbs %a{…}` comments:
+
+```rb
+# rbs_inline: enabled
+
+class Slug
+  # @rbs %a{rigor:v1:return: non-empty-string}
+  # @rbs id: String
+  # @rbs return: String
+  def normalise(id) = id.strip
+end
+```
+
+`%a{}` is *rbs-inline's own* grammar, not a Rigor dialect, and
+the annotation reaches Rigor through the ordinary path: the
+rbs-inline writer copies it verbatim onto the signature it
+generates, and that signature joins the same RBS environment
+your `sig/` tree lands in. So this is not a per-directive
+feature — every `RBS::Extended` directive is read from the same
+annotation object whichever buffer it arrived in — the effect
+envelopes above (`%a{pure}`, `%a{rigor:v1:effect …}`) included.
+Reading them requires the rbs-inline library, which Rigor
+ingests by default when it is installed
+([ADR-93](../adr/93-default-rbs-inline-ingestion.md)).
+
+What Rigor does **not** offer is a Rigor-only comment dialect —
+there is no `# rigor:effect` directive and no file pragma. The
+`# rigor:` comment family stays suppression-only (`disable`,
+`disable-file`). Application code never has to carry
+Rigor-specific syntax ([ADR-0](../adr/0-concept.md)); an
+upstream annotation form you may use if you want one is a
+different thing from a requirement.
 
 ## Inline RBS in Ruby source — the `rigor-rbs-inline` plugin
 

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

@@ -48,6 +48,7 @@ the `paths:` list from the configuration file.
 | `--treat-all-as-inline-rbs` | Force-load `rigor-rbs-inline` with `require_magic_comment: false`, so every analysed file is treated as inline-RBS without the `# rbs_inline: enabled` comment (ADR-32). |
 | `--bleeding-edge[=ids]` | Adopt the bleeding-edge overlay for this run, overriding the configured [`bleeding_edge:`](03-configuration.md) selection (ADR-50 § WD2). Bare adopts every queued feature; `--bleeding-edge=a,b` adopts only the named feature ids. Inspect it with [`rigor show-bleedingedge`](#rigor-show-bleedingedge). |
 | `--no-bleeding-edge` | Ignore any configured `bleeding_edge:` selection for this run (adopt none). |
+| `--no-tolerated-effects` | Check effect envelopes as if [`effects.tolerated:`](03-configuration.md) were empty — the audit switch for your discharge policy (ADR-103). Judgment only: the run, what it collects and its cache entry are identical either way, so this never costs a re-analysis. |
 | `--tmp-file=PATH --instead-of=PATH` | Editor mode: analyse `PATH` using the buffer in `--tmp-file`. Both required together. Alone, only the buffer's own file produces diagnostics; add `--incremental` for whole-project scope (see below). |
 
 Exit `0` when no error-severity diagnostics remain, `1` when
@@ -162,6 +163,208 @@ rigor type-scan PATH...
 unrecognized-node ratio exceeds `RATIO`, and `--format=text|json`
 selects the output format.
 
+## `rigor effects`
+
+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.
+
+```sh
+rigor effects [PATH...]                       # the report
+rigor effects {update,check,diff,explain}     # the snapshot
+```
+
+With no paths the report analyses the configured `paths:`. It
+runs with effect collection enabled even when your `.rigor.yml`
+carries no `effects:` block, so you can try it before
+configuring anything; such an ad-hoc run shares no cache with
+`rigor check`, because a run served from that cache would have
+collected nothing.
+
+Each line is one method, sorted by key:
+
+```
+Tracer::Reporter#report: [io.output.stdout, nondet.time]
+Tracer::Gateway#fetch: [] …?
+    dynamic-receiver (external_gem_without_rbs)
+```
+
+The labels are the **transitive** footprint — the method's own
+plus every project method it reaches. A ` …?` suffix means the
+list is not exhaustive: some call could not be resolved, so the
+reading is "these effects, and possibly more". The indented
+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
+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
+covers is not printed twice.
+
+```
+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.
+
+`--format=text|json` selects the output format; the JSON
+payload additionally carries each method's *direct* summary
+broken down per origin. `--config=PATH` picks a config file.
+`--no-tolerated-effects` is accepted for symmetry with the
+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 snapshot
+
+Four subcommands manage a committed record of the effects
+Rigor observed — `.rigor-effects.yml`, the effect equivalent
+of `db/schema.rb`:
+
+```sh
+rigor effects update    # write the snapshot; commit it
+rigor effects check     # 0 fresh, 1 drift — the CI gate
+rigor effects diff      # the same comparison, never gating
+rigor effects explain   # why an entry point reaches a label
+```
+
+Unlike the report, the subcommands take no paths: a snapshot
+records the whole project, and one written over a subset would
+read as a project where every other method vanished. They all
+accept `--config=PATH`, `--format=text|json` and `--full`;
+`check`, `diff` and `explain` additionally accept
+`--baseline=PATH` (compare against a file other than the
+configured one — `--baseline <(git show
+origin/main:.rigor-effects.yml)` in a bot),
+`--strict-tolerated` and `--no-tolerated-effects`.
+
+The file records two tables. `methods:` holds each method's
+**direct** summary — what its own body does, block literals
+and catalogued callees included, but not what the project
+methods it calls do. That is deliberate: an entry moves only
+when its own lines changed, so the diff stays attributable to
+the pull request that caused it. `reach:` holds the
+**transitive** footprint at the entry points
+`effects.snapshot.reach:` names, where a leaf change is
+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"
+vocabulary: 1
+config_digest: "9ec82bfc…"
+methods:
+  "PaymentGateway#charge":
+    effects: ["io.net.http", "telemetry"]
+  "Reports::Nightly#perform":
+    effects: ["io.db.read"]
+    exhaustive: false
+    unresolved: ["dynamic-send"]
+reach:
+  "OrdersController#create":
+    effects: ["io.db.read", "io.net.http", "job.enqueue"]
+```
+
+A method is left out when it is exhaustive and proves nothing
+beyond `mutate.local`, when its summary is a synthesised
+accessor's, and when it carries no label in either lane — a
+row that would say only "not exhaustive, and here is why" is
+something `rigor effects` and `rigor effects explain` answer
+better than a committed record. `--full` records everything.
+The header carries
+the Rigor and vocabulary versions and a digest of your
+`effects:` block, so an upgrade or a policy edit shows up as a
+*regeneration event* rather than as silent reinterpretation.
+
+Under `methods:` the declared lane is what that method's own
+body claims; under `reach:` it is the transitive claim, like
+the proven labels beside it.
+
+`check` prints one line per difference: `+ label` / `- label`
+for the proven lane, `≤+` / `≤-` for the declared one,
+`materialised` when a declared label became proven,
+`exhaustive → not` when someone introduced a call Rigor cannot
+follow, and `+symbol` / `-symbol` for methods that appeared or
+vanished (a rename is one of each, counted in the footer). A
+removal read off a summary that is no longer exhaustive is
+printed hedged — "possibly more" cannot prove an absence.
+
+`effects.snapshot.gate:` decides what fails. `symmetric` (the
+default) fails on any drift: a job that stopped enqueueing is
+news too. `additions` is the ratchet — only growth fails.
+`effects.tolerated:` is applied at judgment time, never while
+writing: a difference confined to tolerated labels is printed
+under a `tolerated:` heading and does not fail the gate unless
+you pass `--strict-tolerated`. `--no-tolerated-effects` judges
+as if the list were empty; on `update` it changes nothing,
+because the record itself is undischarged.
+
+Discharge works **per origin**, not per label. `Logger#info`
+carries `io` and `telemetry` together, so `tolerated:
+[telemetry]` frees the `io` that came with the logging — and
+leaves an `io.fs.read` from a `File.read` two lines down
+exactly where it was. An added label is discharged only when
+every origin that introduces it is discharged.
+
+### Reviewing effect drift
+
+Day one, run `rigor effects update` and commit the result. The
+diff you are committing is the team's first map: which
+controllers reach the network, which jobs write, which
+presenters query.
+
+Add `rigor effects check` to CI. From then on a pull request
+that changes what the code *does* fails it with the reason
+spelled out:
+
+```
+Effect drift against .rigor-effects.yml:
+
+methods:
+  PaymentGateway#charge  + io.net.http
+
+reach:
+  OrdersController#create  + io.net.http
+
+Run `rigor effects update` and commit the result if this change is intended.
+```
+
+The author runs `rigor effects explain` to see the route —
+
+```
+reach:
+  OrdersController#create → OrderService#place → PaymentGateway#charge → Net::HTTP.get [io.net.http]
+```
+
+— then runs `rigor effects update` and commits the regenerated
+file. **Intent is expressed by committing the regenerated
+snapshot**, not by annotating the code; the reviewer reads the
+two-line diff alongside the code change and either nods or
+pushes back. A bundle update that moves effects with no code
+diff of its own works the same way, and is exactly the case
+worth seeing.
+
+None of this is a diagnostic. `rigor check`'s output and exit
+code are identical whether or not you use the snapshot, and
+drift is never a finding: whether it *matters* is the
+reviewer's judgment, which is what makes it a review artefact.
+
 ## `rigor explain`
 
 Print the catalogue entry for a diagnostic rule, or list every
@@ -300,6 +503,112 @@ rigor triage --format json | jq '[.selectors[] | select(.receiver == "String")]'
 The same `receiver_type` / `method_name` fields ride on each
 diagnostic of `rigor check --format json`, for per-site (rather than
 aggregated) grouping.
+## `rigor unused`
+
+Report project constants that nothing reachable references — a
+starting point for dead-code removal.
+
+```sh
+rigor unused [paths] --entry-point='lib/cli.rb'
+```
+
+**Read the output as a review queue, not a defect list.** On a
+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).
+
+Reachability is computed from **roots**, not by counting references,
+so a cluster of classes that only reference each other is still
+reported. Roots are the declarations in files matching
+`--entry-point=GLOB` (repeatable), anything referenced at file level
+by non-test code, and anything the project's **plugins** contribute.
+
+Plugin-supplied roots are where framework knowledge enters. A Rails
+controller is reached by name at request time, so nothing in the
+project references it and a reference index cannot tell a live
+controller from a dead one. `rigor-rails-routes` closes that by
+reading `config/routes.rb` statically and naming every controller it
+dispatches to — no Rails boot, and a route written under a
+conditional (`get "/beta", to: "beta#index" if ENV["BETA"]`) is
+visible where a booted app's route table would not show it. On two
+Rails corpus targets this removed 56 % and 84 % of the candidate list.
+
+`rigor unused` loads the same `plugins:` your `rigor check` run uses,
+and prints how many roots came from them:
+
+```
+  roots:                    404 (288 from plugins, 0 matched no declaration)
+```
+
+`matched no declaration` is the number a plugin claimed that this
+project does not declare — normally framework classes such as
+`Rails::HealthController`. A number climbing away from zero means a
+root source has drifted out of step with the code, which matters
+because an over-claiming root source silently *hides* dead code. A
+framework Rigor has no plugin for supplies no roots, so its
+controllers still read as candidates.
+
+`rigor-pundit` supplies the second kind of root: a policy class is
+reached as `PostPolicy` from `authorize @post`, a name that appears
+nowhere in the source. It publishes the policies your authorization
+calls actually name — not every class under `app/policies`, because a
+file's location is not evidence that anything authorizes against it.
+
+`rigor-sidekiq` shows how narrow a root source has to be to be worth
+having. A worker named as `class: "NightlyReportWorker"` in a cron
+schedule is enqueued from YAML, so its name appears nowhere in the
+code and it reads as dead — that name becomes a root. The queue list
+in the same `sidekiq.yml` does not: a queue name is not a class name,
+and inflecting one into a worker name would root a class on a naming
+coincidence.
+
+A plugin can also contribute a **reference** rather than a root, and
+`rigor-factorybot` is why the distinction exists. `factory :user,
+class: "Admin::User"` names a class as a string the scan cannot see,
+so it is real evidence of use — but a factory lives in the test tree.
+Supplied as a reference carrying the `test` role, the class leaves
+the candidate list and appears under *Reachable only from test code*;
+supplied as a root it would have been promoted to
+production-reachable, and the more interesting finding would have
+disappeared.
+
+Most bundled plugins deliberately contribute nothing.
+`MyJob.perform_later`, `MyMailer.welcome`, `MyWorker.perform_async`
+and `RSpec.describe User` all write the class name as an ordinary
+constant, which the report already records — and for the spec case,
+records with the `test` role that makes the section above possible.
+Each plugin's page says which choice it made and why.
+
+Three things the report separates rather than merges:
+
+- **Reachable only from test code** gets its own section — a class
+  used solely by its own spec is dead production code with a live
+  test, which is a more actionable finding than either bucket alone.
+- **Constants something can name at runtime** are demoted to a
+  `cannot decide` section with the reason, never claimed as unused.
+  `"Foo".constantize` names `Foo` exactly, so it counts as an ordinary
+  reference; `"Foo::#{key}".constantize` instead marks everything
+  under `Foo` undecidable. A class name appearing as a string in a
+  `.yml`, `.json`, or template file demotes it the same way — that is
+  weaker evidence than a constant reference, so it is neither proof of
+  use nor grounds to call it dead.
+- **Namespace modules** wrapping live code are excluded and counted,
+  because nothing references an intermediate namespace by itself. A
+  namespace whose contents are *all* unreachable is still reported.
+
+Only class and module constants are reported at all; value constants
+are omitted because they do not resolve across files.
+
+References are harvested from a wider file set than the analysed
+paths — `.rake` tasks, `config/`, specs and the project's own `sig/`
+all count as references — because a constant used only from a Rake
+task is not dead.
+
+`--format json` emits the same data; `--limit=N` truncates the
+printed lists. `--incremental` is refused: reachability is only sound
+over a whole-project run.
 
 ## `rigor coverage`
 
@@ -654,6 +963,7 @@ Queued today:
 | `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. |
+| `effects-on-by-default` | behaviour | A project whose `.rigor.yml` carries no [`effects:`](03-configuration.md#effect-labels) key at all is treated as if it had written `effects: {}` — [effect collection](03-configuration.md#effect-labels), the `rigor effects` verbs' cache sharing, and `effects.check` all turn on with every sub-key at its default. Writing `effects: false` explicitly still opts out. **Scheduled to graduate at v0.4.0** ([ADR-103](../adr/103-effect-labels.md) § WD15) rather than at the next major — an owner ruling specific to this feature, ahead of the general v1.0.0 majors-only cadence below. |
 
 Once a feature **graduates** — it becomes the default at a major
 ([ADR-50](../adr/50-release-engineering-and-stability-strategy.md) § WD7)
@@ -758,7 +1068,7 @@ diagnostics about Rigor's own inference cutoffs and memory — see
 | Code | Meaning |
 | --- | --- |
 | `0` | Success — no error-severity diagnostics. |
-| `1` | Diagnostics found, or a per-command failure (parse error, missing file, new diagnostics on `diff`). |
+| `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. |
 
 `rigor triage` is the exception: it is advisory and always

data/docs/manual/03-configuration.md

@@ -70,7 +70,7 @@ cache:
 | --- | --- | --- | --- |
 | `libraries` | Array | `[]` | Standard-library / gem names whose bundled RBS to load. |
 | `signature_paths` | Array | `nil` | Extra directories of `.rbs` files. Relative entries resolve against the config file's directory. |
-| `pre_eval` | Array | `[]` | Files (or globs) walked before per-file analysis, to register project monkey-patches. |
+| `pre_eval` | Array | `[]` | Files (or globs) walked before per-file analysis, to register project monkey-patches and publish their top-level constants project-wide. |
 | `plugins` | Array | `[]` | Plugins to activate — see [Using plugins](07-plugins.md). |
 
 ### Config validation warnings
@@ -174,6 +174,89 @@ explicitly with `bundler.bundle_path:`, or supply signatures another way:
 | `plugins_io.allowed_paths` | Array | `[]` | Filesystem paths plugins may read. |
 | `plugins_io.allowed_url_hosts` | Array | `[]` | URL hosts plugins may fetch from when `network: allowlist`. |
 
+### Effect labels
+
+| Key | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `effects` | Hash | absent | **Opt-in to effect labels ([ADR-103](../adr/103-effect-labels.md)).** The *presence* of this block is the switch — `effects: {}` enables collection with every sub-key at its default, and leaving it out keeps `rigor check` byte-identical and free. Nothing else turns collection on: an `%a{pure}` or `%a{rigor:v1:effect …}` annotation in your RBS does not, because an annotation must not silently make every run more expensive — such a project gets one `effect.annotations-unchecked` `:info` per run instead, saying the annotations are inert. `rigor effects` runs under an implicit empty block when the key is absent, so you can try the report before configuring anything. Effect summaries are cached under their own identity (Rigor's effect vocabulary, its built-in catalogue and this block), so `rigor effects` after `rigor check` in the same job is a cache hit plus the propagation, and turning this block on or off does not invalidate your diagnostics cache. The sub-keys are below. `views` is declared in the schema and reserved: accepted and **not yet read**. See [`rigor effects`](02-cli-reference.md#rigor-effects). |
+| `effects.check` | Boolean | `true` | Whether the envelopes you declared — `%a{pure}` and `%a{rigor:v1:effect …}` in RBS, and the `effects.envelopes:` stanzas below — are checked against what Rigor proved, surfacing `effect.envelope-exceeded` and, for a label the vocabulary does not recognise, `effect.unknown-label`. Set it to `false` to keep the report and the snapshot while silencing both. Never on without an `effects:` block. |
+| `effects.snapshot.path` | String | `.rigor-effects.yml` | Where `rigor effects update` writes the committed record. |
+| `effects.snapshot.reach` | Array | `[]` | Entry points whose **transitive** footprint the snapshot records under `reach:`. Each entry is a project-relative file glob (the `unused --entry-point` semantics — `**` is the only way across a directory boundary) or the name of an entry-point **preset** a plugin registered. On a Rails app, `reach: [rails]` is the one you want — see below. A name nothing registered is an error when the snapshot is built (not when the configuration loads, because the plugins that name presets load *from* that configuration). |
+| `effects.snapshot.gate` | String | `symmetric` | What `rigor effects check` treats as drift. `symmetric` fails on any difference — a job that *stopped* enqueueing is news too; `additions` is the growth-only ratchet. |
+| `effects.labels` | Array | `[]` | Effect labels **your project** registers, layered over Rigor's shipped vocabulary. A project may open any root (`acme.cache`) — listing the label here is the vouching act. Once registered, a label is usable in every other key below and stops being reported as unknown. Malformed spellings are a load error. |
+| `effects.attribution` | Hash | `{}` | What a call into code Rigor cannot see *does*, keyed by method: `{"Net::HTTP.get": [io.net.http], "Logger#info": [telemetry]}`. Keys are method keys — `Owner#instance_method` or `Owner.singleton_method` — and anything else is a load error. The labels land in the caller's **declared** lane and never in the proven one, so an attribution can never make a diagnostic fire; the call still counts as unresolved, because you told Rigor what that code does and Rigor did not read it. Use it for gems nobody has written a plugin for. |
+| `effects.envelopes` | Array | `[]` | Effect envelopes by **convention**, so a whole architectural layer is bounded by one stanza instead of a per-method annotation. Each entry names exactly one of `match:` (a project-relative path glob over the files a class is defined in) or `namespace:` (a constant glob: `*` is one segment, `**` is one or more), plus `effect:` — the labels the selected classes may perform, or `[]` for pure. Nearest wins: a per-method annotation beats a class-level one, which beats a stanza; among stanzas the **first** match wins. See the example below. |
+| `effects.tolerated` | Array | `[]` | Labels your project has decided not to act on. Applied when a bound or a difference is **judged**, never when a record is written, and **per origin**: `Logger#info` carries `io` and `telemetry` together, so `tolerated: [telemetry]` frees the `io` that came with the logging and leaves an `io.fs.read` from a `File.read` in the same method exactly where it was. `rigor check --no-tolerated-effects` (and the same flag on `rigor effects check`) re-judges as if the list were empty — the audit switch for the policy. |
+
+Want the block on without writing it? The
+[`effects-on-by-default`](02-cli-reference.md#rigor-show-bleedingedge)
+bleeding-edge feature (`bleeding_edge: [effects-on-by-default]`) makes a
+config with no `effects:` key at all behave as `effects: {}` — collection,
+`effects.check`, and everything else on this page all turn on at their
+defaults. It only fills an *absence*: write `effects: false` and you stay
+opted out regardless, and any `effects:` block you do write is left exactly
+as written. It previews what becomes the default at **v0.4.0**
+([ADR-103](../adr/103-effect-labels.md) § WD15).
+
+#### Entry-point presets
+
+`reach:` asks "whose footprint should the record cover", and on a framework the honest answer is a fact
+about the framework rather than about your code. So the plugin that models it names the set, and you
+adopt it:
+
+```yaml
+plugins:
+  - rigor-railties
+  - rigor-activerecord
+  - rigor-actionpack
+
+effects:
+  snapshot:
+    reach: [rails]
+```
+
+`rails` — registered by [`rigor-railties`](plugins/rigor-rails.md) — stands for `app/controllers/**`,
+`app/jobs/**`, `app/mailers/**` and `app/channels/**`: every way the outside world enters the
+application. The component plugins also register the narrower `rails-controllers`, `rails-jobs`,
+`rails-mailers` and `rails-channels` if you want one layer's footprint rather than all four. A preset is
+just a name for globs; mixing the two in one list is fine.
+
+Listing the plugin is what registers its preset, so `reach: [rails]` without `rigor-railties` in
+`plugins:` is an error saying so.
+
+#### Envelopes by convention
+
+The `envelopes:` list is the surface that pays on day one, before you have written any RBS:
+
+```yaml
+effects:
+  envelopes:
+    - match: "app/presenters/**/*.rb"   # presenters render; they do not query
+      effect: []
+    - namespace: "Policies::*"          # Policies::Edit, not Policies::Admin::Edit
+      effect: [mutate.local]
+    - match: "app/jobs/**/*.rb"
+      effect: [io]
+  tolerated: [telemetry]
+```
+
+A stanza attaches its bound to every method of every class it selects, exactly as an annotation on the
+class would. A method that exceeds it gets one `effect.envelope-exceeded` at its `def`, naming the
+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. [effect.envelope-exceeded]
+```
+
+When one method is a deliberate exception, write the narrower envelope on it in RBS — nearest wins,
+and no `except:` key is needed. When a whole *kind* of effect is acceptable everywhere, name it in
+`tolerated:` instead of loosening every stanza.
+
+If a layer is not ready for a bound yet, leave `envelopes:` out and start with the committed snapshot
+([`rigor effects update`](02-cli-reference.md#the-effect-snapshot)) — it needs no declaration at all,
+and stanzas are the second step, written once the record has told you what the layer actually does.
 ### Reserved for other implementations
 
 | Key | Type | Default | Meaning |

data/docs/manual/04-diagnostics.md

@@ -58,6 +58,10 @@ carries no `documentation_url`.
 | <a id="rule-def-override-return-widened"></a>`def.override-return-widened` | An override's declared return type widens the inherited return (covariance). | high |
 | <a id="rule-def-override-param-narrowed"></a>`def.override-param-narrowed` | An override narrows an inherited parameter type (contravariance). | high |
 | <a id="rule-static-value-use-void"></a>`static.value-use.void` | A value recovered from an author-declared `-> void` return is used in value context (an assignment right-hand side, a call receiver, or a call argument). Off by default; reaches a run only through the `use-of-void-value` bleeding-edge feature (ADR-100). A bare-statement `void` call and a legitimate `top` value both stay silent. | high |
+| <a id="rule-effect-envelope-exceeded"></a>`effect.envelope-exceeded` | A method performs an effect its declared envelope does not admit — its proven effect labels (its own body plus everything it calls) are not covered by the `%a{pure}` or `%a{rigor:v1:effect …}` bound written on it or on its class. Opt-in twice over: it needs an `effects:` block in `.rigor.yml` and an envelope you wrote. Positioned at the Ruby `def`. Unproven ("and possibly more") effects never fire, and `mutate.local` is tolerated by every envelope. | high |
+| <a id="rule-effect-liskov-widened"></a>`effect.liskov-widened` | An override escapes the envelope written on the method it overrides. A `PgRepo` is usable wherever a `Repo` is, so a `%a{rigor:v1:effect io.db}` on `Repo#find` binds `PgRepo#find` too: an implementation may be purer than the bound it inherits, never less pure. Either what the override *does* exceeds the inherited bound, or the envelope the override *declares for itself* is wider than it. Both sides must be authored — nothing fires unless someone wrote an envelope on the ancestor — and only subclassing counts, not `include`. Positioned at the override's `def`. Needs an `effects:` block. | high |
+| <a id="rule-effect-unknown-label"></a>`effect.unknown-label` | An effect declaration names a label the registry does not know — a typo in an envelope (`%a{rigor:v1:effect io.bd}`), or a member of `effects.tolerated:`. The whole tag then reads as unbounded, so the declaration quietly stops doing anything; this says so. Positioned at the declaration: the `.rbs` line, the `.rb` line for an rbs-inline annotation, or `.rigor.yml` for a config value. `# rigor:disable` comments are not read out of `.rbs` or `.rigor.yml`, so use `disable:` or the baseline there. Only fires where the spelling is evidently meant to be a label (close to a known one, next to a known one, dotted, or retired) — a word nothing resembles stays silent, because you may be opening your own vocabulary. Needs an `effects:` block. | high |
+| <a id="rule-effect-annotations-unchecked"></a>`effect.annotations-unchecked` | Your signatures carry `%a{pure}` / `%a{rigor:v1:effect …}` but `.rigor.yml` has no `effects:` block, so nothing checks them. One `:info` per run, positioned at the first annotation. An annotation never turns effect collection on by itself — that would make one line in one file more expensive for every run — so this is how it tells you instead. Add `effects: {}` to opt in, or `disable:` it to keep the annotations documentary. | — |
 | <a id="rule-suppression-unknown-rule"></a>`suppression.unknown-rule` | A `# rigor:disable[-file]` comment names a rule that does not exist (typically a typo), so the suppression silently does nothing. `plugin.`-prefixed tokens are never flagged. | high |
 | <a id="rule-suppression-empty"></a>`suppression.empty` | A `# rigor:disable[-file]` comment lists no rules, so it suppresses nothing. | high |
 | <a id="rule-suppression-unknown-marker"></a>`suppression.unknown-marker` | A comment uses a suppression marker Rigor does not recognise — typically the RuboCop reflex `# rigor:disable-next-line <rule>` or `# rigor:enable <rule>`. Rigor's only markers are `# rigor:disable <rules>` (suppresses on its own line) and `# rigor:disable-file <rules>`, so the comment suppresses nothing. | high |
@@ -104,8 +108,8 @@ are:
 
 | Severity | Rules |
 | --- | --- |
-| `warning` | `call.unresolved-toplevel`, `def.ivar-write-mismatch`, `def.return-type-mismatch`, `def.override-visibility-reduced`, `def.override-return-widened`, `def.override-param-narrowed`, `flow.unreachable-branch`, `flow.always-truthy-condition`, `flow.dead-assignment`, `flow.duplicate-hash-key`, `flow.return-in-ensure`, `flow.shadowed-rescue-clause`, `suppression.unknown-rule`, `suppression.empty`, `suppression.unknown-marker` |
-| `info` | `flow.unreachable-clause`, `dump.type` |
+| `warning` | `call.unresolved-toplevel`, `def.ivar-write-mismatch`, `def.return-type-mismatch`, `def.override-visibility-reduced`, `def.override-return-widened`, `def.override-param-narrowed`, `flow.unreachable-branch`, `flow.always-truthy-condition`, `flow.dead-assignment`, `flow.duplicate-hash-key`, `flow.return-in-ensure`, `flow.shadowed-rescue-clause`, `suppression.unknown-rule`, `suppression.empty`, `suppression.unknown-marker`, `effect.envelope-exceeded`, `effect.liskov-widened` |
+| `info` | `flow.unreachable-clause`, `dump.type`, `effect.unknown-label`, `effect.annotations-unchecked` |
 | `off` | `call.self-undefined-method`, `static.value-use.void` |
 
 Everything else emits as `error`. For one rule under all three