rigortype 0.3.4 → 0.3.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ffcad04b990dc4220690a6906bb96306056a02792017fcf41200b8865c040846
-  data.tar.gz: b62aa8767389da9ddd808df2a74d09447aee4d5a9c0deb0d7d4292da5ff7669b
+  metadata.gz: cc7f03a32a104c1c3ed00374974fc9af408c84e1c4d19dbb9ad8dc863f0ea0c4
+  data.tar.gz: 6c7f1fd0b81526c436731ac6c4710c0937bd00043570b6db5e9d59d6973f7872
 SHA512:
-  metadata.gz: f55c7fb8b035ba5364d97163f6ae66e1212d544d5fa2821110a230818be1f64bd2d803ff88739af394d57c39a3bb6ed77737451a68f1cfb047276e23c6ede98a
-  data.tar.gz: 85aafda9ac9c46b73757c5690484d97d77b1dea26cc499252d39a24aefbd9f58fcf0dfda759a11e7dea553b4d8fac3ae83db9a165e1e926ff62a8fdecad78967
+  metadata.gz: 492d3d04d9bce6672ad46885d2eda1234d4f4a30f41b3168244f794754f37fa1a3d0edfc88e425fc2b0582dd09b5f45afee312189c2099c8101140db798eec0a
+  data.tar.gz: 8fd06bd7e9af340ba29019c84bd913934c77b094987e5c52be131351bc60c52e1a8a28d777d4a417ac96480a42cf110236346a1a4f62aa5d54f4a5f50d0c8e5b

data/README.md

@@ -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.5`** (2026-08-25) — 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/docs/manual/02-cli-reference.md

@@ -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
 
@@ -1069,7 +1108,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"
+```

data/docs/manual/03-configuration.md

@@ -176,12 +176,15 @@ explicitly with `bundler.bundle_path:`, or supply signatures another way:
 
 ### Effect labels
 
+The key reference is below; the workflow these keys serve — the vocabulary, the report, the committed
+snapshot, the CI gate — is [Effect labels](19-effect-labels.md).
+
 | 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.reach` | Array | `[]` | Entry points whose **transitive** footprint the snapshot records under `reach:`. The default is empty **deliberately**: Rigor could infer `[rails]` from your plugin list, but a snapshot is a record you agree to and review the diff of, and one whose contents moved because your plugin list moved would be the worse artefact. `rigor effects update` names the presets your plugins registered and leaves the same hint in the written file. 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); the error lists the presets your plugins did register, so it names the fix. |
 | `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. |
@@ -215,7 +218,8 @@ effects:
     reach: [rails]
 ```
 
-`rails` — registered by [`rigor-railties`](plugins/rigor-rails.md) — stands for `app/controllers/**`,
+`rails` — registered by `rigor-railties`, which is a distinct plugin from the
+[`rigor-rails`](plugins/rigor-rails.md) convenience grouping — 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
@@ -247,13 +251,26 @@ 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]
+  the envelope.
 ```
 
 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.
 
+**One stanza can land hundreds of warnings**, one per (method, label) pair — on a mid-size Rails
+application, `match: "app/helpers/**/*.rb"` with `effect: []` produced 343 across 18 files. That is
+the layer telling you what it does rather than a misconfiguration, but it is not a work list either;
+[Effect labels § Envelopes by convention](19-effect-labels.md) walks the recipe for working it down.
+
+A stanza is checked against **proven** labels only, so on a Rails application it cannot fire on
+`io.db.*`, `cache.*`, `telemetry`, `email.send`, `job.enqueue` or any `rails.*`: those come from a
+plugin modelling a framework Rigor did not read, and a claim about unread code must not be able to
+fail your build. The enforcement path for that half is the committed snapshot, whose `rigor effects
+check` marks a declared-lane addition with `≤+` — [Effect labels § What a bound can and cannot
+see](19-effect-labels.md#what-a-bound-can-and-cannot-see), and
+[ADR-103](../adr/103-effect-labels.md) § WD17 for why.
+
 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.

data/docs/manual/04-diagnostics.md

@@ -27,7 +27,8 @@ built-in rule ID; `rigor explain` with no argument lists them all.
 Each built-in rule has a stable per-rule anchor on this page
 (`#rule-<family>-<name>`, dots written as dashes) — the
 `documentation_url` field in `--format json` and `rigor explain`'s
-`Documentation:` line both point here. The `Evidence` column is
+`Documentation:` line both point here, at this chapter's published
+copy on <https://rigor.typedduck.fail/manual/04-diagnostics/>. The `Evidence` column is
 Rigor's confidence that a firing is a true positive (see
 [Evidence tier](#evidence-tier) below). The one exception is
 `rbs_extended.unsatisfied-conformance`, an `rbs_extended`-family rule
@@ -61,7 +62,7 @@ carries no `documentation_url`.
 | <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-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. Reads both annotation lanes — `sig/*.rbs` and rbs-inline comments — except on a run that analyses no file at all (a warm `--incremental` with nothing changed), where only the `.rbs` lane is visible. | — |
 | <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 |

data/docs/manual/11-ci.md

@@ -188,6 +188,43 @@ The exit code is unchanged by `--format` — `0` when there are no errors,
 `1` otherwise — so the job still gates the pipeline. `--format json`
 remains available for any other tool that wants the raw diagnostic stream.
 
+## Gating effect drift
+
+If the project uses [effect labels](19-effect-labels.md), add a second
+step beside `rigor check`. It answers a different question — "did this
+branch change what the code *does*?" — and fails for different reasons,
+so keep it as its own step and let the log say which one went red:
+
+```yaml
+      - run: gem install rigortype
+      - run: rigor check
+      - run: rigor effects check
+```
+
+`rigor effects check` exits `0` when the committed
+`.rigor-effects.yml` matches what Rigor just recomputed and `1`
+otherwise — including when the file is missing from the checkout, which
+is what catches the pull request that changed a method and forgot to
+regenerate it. The author's fix is `rigor effects update` plus a commit;
+the regenerated diff is what the reviewer reads.
+
+A bot that wants to report *what this branch changes*, regardless of how
+stale the default branch is, compares against the base instead of the
+committed file:
+
+```sh
+rigor effects diff --baseline <(git show origin/main:.rigor-effects.yml)
+```
+
+`diff` prints the identical comparison and never gates, so it is safe as
+a comment-posting step; `check` takes the same `--baseline`.
+
+With an `effects:` block configured, the snapshot verbs share their
+cached effect summaries with `rigor check`, so running both in one job
+does not re-read the project twice. Exit codes, `--strict-tolerated`, the
+`--no-tolerated-effects` audit switch and the review loop are covered in
+[Effect labels § In CI](19-effect-labels.md).
+
 ## Pinning Rigor's version
 
 The workflow above installs whatever `rigortype` is current at run

data/docs/manual/12-caching.md

@@ -49,6 +49,45 @@ The cache is also schema-versioned: after a Rigor upgrade that
 changes the cache format, the stale cache is purged on the
 first writable run.
 
+## Effect summaries
+
+[Effect labels](19-effect-labels.md) are cached alongside the rest,
+but under their **own** identity: Rigor's effect vocabulary, its
+built-in effect catalogue, and your `effects:` block. Two
+consequences worth knowing:
+
+- **Turning `effects:` on or off does not invalidate the entries
+  your `rigor check` already relies on.** The two identities are
+  separate, so adopting effect labels costs a first collection
+  pass and leaves the diagnostics cache alone. Upgrading to a
+  Rigor whose catalogue changed does the reverse — it re-reads
+  your effects without re-running your check.
+- **The `rigor effects` verbs share those summaries with `rigor
+  check`.** In a job that runs both, the second command pays for
+  the propagation rather than for a second analysis.
+
+The exception is a `rigor effects` run on a project with **no**
+`effects:` block: it collects under an implicit empty block and
+shares no cache with `rigor check`, because a run served from that
+cache would have collected nothing.
+
+**Everything the effect system produces survives a cache hit.** A
+warm `rigor check` reports exactly the `effect.envelope-exceeded`
+warnings a cold one does; there is no configuration in which the
+effect checks fire on the first build of the day and go quiet
+afterwards. The judgment itself is never stored — it is recomputed
+each run from the summaries — so editing an envelope, a
+`tolerated:` list or an `%a{pure}` annotation re-judges your code
+on the next run even though no Ruby file changed, and a warning
+can never outlive the stanza that justified it.
+
+That costs speed in exactly one case. Declaring an envelope
+anywhere opts the project out of the cache-hit fast path, because
+Rigor has to load the analyzer to re-judge: a warm run takes about
+a second on a mid-sized Rails application instead of about a
+quarter of one. A project with `effects:` on and nothing declared
+anywhere pays nothing.
+
 ## How a file is checked for changes
 
 To decide whether a cached entry is still valid, Rigor needs to

data/docs/manual/16-rbs-extended-annotations.md

@@ -162,7 +162,7 @@ Every directive above describes what a method returns. Two
 describe what it *does*: `%a{pure}` — rbs' own purity
 annotation, read as "nothing at all" — and
 `%a{rigor:v1:effect <labels>}`, a comma-separated list of bare
-[effect labels](../type-specification/effect-labels.md) the
+[effect labels](19-effect-labels.md) the
 method may not exceed. Both attach to a method or to a `class` /
 `module`, where they distribute to that class's own methods
 (nearest wins), and both tolerate mutating objects the method
@@ -210,7 +210,20 @@ on:
   at the declaration.
 - Without the block, one
   [`effect.annotations-unchecked`](04-diagnostics.md#rule-effect-annotations-unchecked)
-  `:info` per run tells you the annotations are inert.
+  `:info` per run tells you the annotations are inert — from either
+  lane, with one exception: a run that analyses **no file at all**
+  (a warm `rigor check --incremental` with nothing changed) has no
+  synthesised RBS to read, so it reports a `.rbs` annotation and not
+  an inline one. Any run that analyses something reports both.
+
+Two practical notes. Annotating one method in a `.rbs` file forces you to
+declare its whole signature — RBS has no way to annotate a method it does
+not declare — while the rbs-inline form above does not, so prefer the
+inline lane when the bound is all you want. And an envelope is checked
+against the **proven** lane only: a method whose labels all sit in the
+declared (`≤`) lane passes `%a{pure}` in silence.
+[Effect labels](19-effect-labels.md) covers both, with the vocabulary
+these annotations draw from.
 
 ## Higher-kinded type directives