rigortype 0.2.0 → 0.2.2

data/docs/handbook/appendix-phpstan.md

@@ -0,0 +1,338 @@
+# Appendix — Coming from PHPStan
+
+PHPStan is the closest spiritual peer Rigor has in another
+language. Both tools share the same priorities: stay silent on
+code the analyzer cannot characterise, lean on inference rather
+than mandatory annotations, and surface a small catalogue of
+high-confidence diagnostics. Many of Rigor's design choices —
+config-file shape, baseline diffing, severity profiles, the
+`assert` family of directives — were directly informed by
+PHPStan.
+
+If you have used PHPStan, the mental model carries over almost
+unchanged. This appendix maps the vocabulary.
+
+## The five-second pitch
+
+| Question | PHPStan | Rigor |
+| --- | --- | --- |
+| Where do annotations live? | PHPDoc `/** ... */` blocks | `.rbs` files alongside `.rb` |
+| Default behaviour | Inference, fall back silent | Inference, fall back silent |
+| "Levels" | 0 – 10 (numeric) | `lenient` / `balanced` / `strict` (named) |
+| Per-rule control | `ignoreErrors:` regex, level demotion | `disable:`, `severity_overrides:` |
+| Baseline | `phpstan-baseline.neon` | `.rigor-baseline.yml` (managed) / `rigor.baseline.json` (ad-hoc) |
+| Stub format | PHP stub files | RBS files |
+| Custom narrowing | Type-Specifying Extensions | Plugins (Chapter 9) |
+| Custom return shape | Dynamic Return Type Extensions | Plugin `dynamic_return` |
+
+The two tools agree on most of the foundational decisions. The
+biggest differences are surface (Ruby's syntax and runtime
+shape), not philosophy.
+
+## Type vocabulary mapping
+
+PHPStan and Rigor have an overlapping refinement vocabulary; this
+is the closest match of any peer.
+
+| PHPStan PHPDoc | Rigor representation | Notes |
+| --- | --- | --- |
+| `string` | `String` | |
+| `int` | `Integer` | |
+| `float` | `Float` | |
+| `bool` | `bool` (`Constant<true> \| Constant<false>`) | |
+| `null` | `Constant<nil>` | Ruby has only `nil`. |
+| `mixed` | `Top` | The "anything" carrier. |
+| `never` | `Bot` | Empty type. |
+| `void` | `void` | Same. |
+| `array<T>` / `T[]` | `Array[T]` | |
+| `array<K, V>` | `Hash[K, V]` | Ruby splits by container kind. |
+| `array{name: string, age: int}` | `HashShape{name: String, age: Integer}` | Same per-key model. |
+| `array{0: int, 1: string}` (list shape) | `Tuple[Integer, String]` | Same per-position model. |
+| `non-empty-string` | `non-empty-string` | **Identical name and meaning.** |
+| `non-falsy-string` | `non-empty-string` | Rigor does not split out the falsy-but-nonempty case. |
+| `numeric-string` | `numeric-string` | Identical. |
+| `lowercase-string` | `lowercase-string` | Identical. |
+| `class-string` | `Singleton[T]` | Equivalent shape. |
+| `int<1, 9>` | `int<1, 9>` | **Identical syntax.** |
+| `positive-int` | `positive-int` | Identical. |
+| `negative-int` | `negative-int` | Identical. |
+| `non-zero-int` | `non-zero-int` | Identical. |
+| `non-empty-array<T>` | `non-empty-array[T]` | Identical. |
+| `non-empty-list<T>` | (no separate carrier — `non-empty-array[T]` covers it) | Ruby has no list/dict split. |
+| `T \| U` | `T \| U` | |
+| `T & U` | `Intersection[T, U]` | |
+| `literal-string` | `literal-string` | **Identical concept.** Provably built from source-code literals. |
+| `'hello'` (literal type) | `Constant<"hello">` | |
+| `42` (literal type) | `Constant<42>` | |
+
+This table is the densest in the appendix because the overlap
+is so close. If you are reading PHPStan's "PHPDoc Types" page
+in another tab, almost every advanced refinement transfers.
+
+## The `@phpstan-assert` family
+
+PHPStan's assertion-narrowing PHPDoc tags map directly onto
+Rigor's `RBS::Extended` directive grammar. Chapter 7 covers
+the table in depth; here it is again for reference:
+
+| PHPStan PHPDoc | Rigor RBS::Extended | Effect |
+| --- | --- | --- |
+| `@phpstan-assert T $x` | `%a{rigor:v1:assert x is T}` | After return, caller's `x` is `T`. |
+| `@phpstan-assert-if-true T $x` | `%a{rigor:v1:predicate-if-true x is T}` | If method returns truthy, caller's `x` is `T`. |
+| `@phpstan-assert-if-false T $x` | `%a{rigor:v1:predicate-if-false x is T}` | If method returns falsey, caller's `x` is `T`. |
+| `@phpstan-assert !T $x` | `%a{rigor:v1:assert x is ~T}` | After return, caller's `x` is **not** `T`. |
+| `@phpstan-assert =T $x` (assert-and-narrow) | (covered by `assert:`) | Same effect. |
+| `@phpstan-self-out T` | `%a{rigor:v1:assert self is T}` | `self` narrows in caller scope. |
+| `@phpstan-impure` | (no analogue) | Rigor does not yet model purity for fold-through-method-call. |
+
+Every directive Rigor's grammar ships has a PHPStan PHPDoc
+analogue. If you have a PHPStan-shaped mental model for "what
+narrows what after this method returns," it transfers
+unchanged.
+
+## Type-Specifying Extensions ↔ Plugins
+
+When the assertion is recognised by **call shape** rather than
+by signature — PHPStan's `TypeSpecifyingExtension` interface,
+where you write a class that the framework instantiates and
+asks "given this call, what narrowings does it produce?" —
+Rigor's analogue is a plugin's `type_specifier` / `dynamic_return` and
+`#diagnostics_for_file` hooks plus the engine's
+`post_return_facts` substrate.
+
+| PHPStan extension type | Rigor analogue |
+| --- | --- |
+| `MethodTypeSpecifyingExtension` | Plugin's `Fact(target_kind: :parameter)` returned from `type_specifier` |
+| `StaticMethodTypeSpecifyingExtension` | Same, with `Fact(target_kind: :receiver-class)` |
+| `FunctionTypeSpecifyingExtension` | Same, with `Fact(target_kind: :argument)` |
+| `DynamicMethodReturnTypeExtension` | Plugin's `dynamic_return(methods:) { |call_node, scope, ...| ... }` |
+| `DynamicStaticMethodReturnTypeExtension` | Same, varying by receiver-class branch in plugin code |
+| `DynamicFunctionReturnTypeExtension` | Same, for module-level methods |
+
+The plugin contract pinned at
+[`docs/internal-spec/plugin.md`](../internal-spec/plugin.md)
+gives every shape PHPStan's extension API covers, with
+analogous lifecycle (manifest declaration, per-call dispatch,
+fact emission). Chapter 9 has the high-level orientation; the
+internal spec is the binding contract.
+
+The `rigor-sorbet` adapter in Chapter 10 is itself a worked
+example of a "Type-Specifying Extension at scale" — every
+`T.must`, `T.cast`, `T.bind`, `T.assert_type!` call is
+recognised by call shape, not by sig.
+
+## Configuration
+
+PHPStan's `phpstan.neon` and Rigor's `.rigor.yml` /
+`.rigor.dist.yml` use the same shape: a single config file at
+the project root, autoloaded if present, with `paths:`,
+severity controls, and includes.
+
+| PHPStan | Rigor |
+| --- | --- |
+| `phpstan.neon` | `.rigor.yml` |
+| `phpstan.neon.dist` | `.rigor.dist.yml` |
+| `paths:` | `paths:` |
+| `level:` | `severity_profile:` |
+| `excludePaths:` | (no analogue today — paths are explicitly listed) |
+| `ignoreErrors:` (regex / pattern) | `disable:` (rule identifier or wildcard) |
+| `parameters: ignoreErrors:` per-path | `# rigor:disable-file <rule>` at the file head |
+| `includes:` | `includes:` |
+| `phpstan-baseline.neon` | `.rigor-baseline.yml` (managed) — or `rigor.baseline.json` (ad-hoc) |
+| `phpstan analyse --generate-baseline` | `rigor baseline generate` (managed) — or `rigor check --format=json > rigor.baseline.json` (ad-hoc) |
+| `phpstan analyse` | `rigor check` |
+| `phpstan analyse --baseline` | `rigor check` with `baseline: .rigor-baseline.yml` configured (managed) — or `rigor diff rigor.baseline.json` (ad-hoc) |
+| Path resolution: relative to declaring file | Path resolution: relative to declaring file (same rule). |
+
+Rigor has two baseline mechanisms: a **managed** baseline
+(`rigor baseline generate` → `.rigor-baseline.yml`, read on
+the next `rigor check` via the `baseline:` config key — the
+closest match to PHPStan's `--baseline`), and a **lightweight**
+ad-hoc snapshot (`rigor diff` over a `--format=json` dump).
+Chapter 8 has the walkthrough.
+
+The `includes:` semantics also match PHPStan's: declaration
+order, later overrides earlier, the current file's keys win
+over included files. Rigor's `.rigor.yml` does NOT auto-merge
+with `.rigor.dist.yml` — the override must list the dist file
+explicitly under `includes:`. PHPStan has the same behaviour
+when you have both `phpstan.neon` and `phpstan.neon.dist` in
+play.
+
+## Stubs ↔ RBS
+
+PHPStan reads PHP stub files (`.stub`) for libraries that ship
+no PHPDoc. Rigor reads `.rbs` files for the same purpose. The
+dispatch is similar: both tools layer "stub-declared
+contract beats inferred-from-body," and both use the stub
+files as the canonical place to attach refinements via
+PHPDoc / `RBS::Extended` annotations.
+
+| PHPStan | Rigor |
+| --- | --- |
+| `*.stub` files | `.rbs` files in `sig/` (project) and `rbs_collection.lock.yaml` (third-party) |
+| PHPDoc on stubs | `RBS::Extended` `%a{rigor:v1:...}` annotations |
+| `#[Override]` / `#[\Deprecated]` attributes | RBS `attr_*` and `def` declarations |
+| `phpstan/extension-installer` | Bundler + `Gemfile` for plugin gems |
+
+A practical pattern that works in both worlds: keep the stub /
+RBS file authoritative for the public contract, then layer
+project-specific tightenings under
+`@phpstan-*` / `RBS::Extended` directives that ship alongside
+the stub.
+
+## Severity profiles vs PHPStan levels
+
+PHPStan's levels are a numeric ladder (0 = "shapes only," 10 =
+"strictest"). Rigor's profiles are named (`lenient`,
+`balanced`, `strict`).
+
+| PHPStan level | Rigor profile (rough) | Notes |
+| --- | --- | --- |
+| 0 – 2 | `lenient` | Most rules → `:warning`; uncertain rules drop to `:info`. |
+| 3 – 6 | `balanced` (default) | Most rules → `:error`. |
+| 7 – 10 | `strict` | Everything → `:error`, including `:warning` rules in `balanced`. |
+
+The mapping is approximate (the rule sets are not 1:1), but
+the practical advice is the same: start with the default,
+tighten over time. Chapter 8's "helpful workflow" matches the
+PHPStan onboarding pattern.
+
+## "No annotations needed" — yes, but with stubs
+
+PHPStan and Rigor share the philosophy that **inference does
+the heavy lifting**. You do not annotate every variable; you
+annotate the boundary (function signatures, library stubs)
+and inference propagates inward.
+
+PHPStan's catch is that PHPDoc lives in the same file as the
+PHP source. Rigor's catch is that RBS lives in `sig/`, a
+parallel tree. The trade-offs are well-known:
+
+- **Same-file PHPDoc** keeps the docs adjacent to the code
+  they describe — easier to update, harder to forget.
+- **Parallel `.rbs`** keeps the runtime source clean for
+  developers who do not care about types — no PHPDoc clutter
+  on production methods.
+
+Rigor leans toward the parallel-file model for cultural reasons
+(Ruby's tradition of compact source), but `RBS::Inline`
+provides an in-file alternative for projects that want
+PHPDoc-style adjacency. See ADR-1 for the rationale.
+
+## What PHPStan has and Rigor does not
+
+- **Generics with bounded constraints across the stub library.**
+  PHPStan's generics ecosystem is more mature; RBS generics
+  exist but the standard library's coverage is patchier.
+- **`@phpstan-impure` and pure-by-default modelling.** Rigor
+  catalogues per-method purity inside its built-in
+  `data/builtins/ruby_core/` YAML, but does not yet expose a
+  user-facing way to declare a method pure for fold-through.
+- **Custom rules.** PHPStan's `Rule` interface lets you write a
+  rule in PHP that fires on AST patterns; Rigor's plugin
+  surface covers diagnostics emission via
+  `#diagnostics_for_file`, but the rule shape is less polished
+  than PHPStan's framework.
+- **`treatPhpDocTypesAsCertain`.** PHPStan's "trust PHPDoc"
+  knob has no Rigor equivalent — Rigor always trusts RBS
+  declarations as authoritative.
+
+## What Rigor has and PHPStan does not
+
+- **Constant folding through method calls.** PHPStan does some
+  constant propagation; Rigor folds aggressively through
+  catalogued built-ins (`Numeric`, `String`, `Symbol`, `Array`,
+  `Hash`).
+- **First-class flow-sensitive narrowing on Ruby's predicate
+  methods.** `s.empty?` / `n.zero?` / `n.positive?` etc. are
+  recognised by name and narrow accordingly. PHPStan has the
+  same idea via Type-Specifying Extensions, but Rigor ships
+  the catalogue out of the box.
+- **`literal-string` carrier.** Both tools have the concept,
+  but Rigor's carrier composes through interpolation —
+  `"#{a}#{b}"` is `literal-string` if both `a` and `b` are.
+  PHPStan has `literal-string` for "literal at this position"
+  but the propagation rules are different.
+- **Sorbet-input adapter.** If your project happens to be
+  partially-Sorbet (you migrated some files to RBS but kept
+  the rest), Rigor reads both sources concurrently. PHPStan
+  has nothing analogous — there is no parallel "Sorbet of
+  PHP."
+
+## A migration vignette
+
+You are porting a PHPStan-tightened library to Ruby. The
+original PHP:
+
+```php
+class Slug {
+    /**
+     * @phpstan-param non-empty-string $name
+     * @phpstan-return non-empty-lowercase-string
+     */
+    public function normalise(string $name): string {
+        return strtolower(preg_replace('/\s+/', '-', $name));
+    }
+
+    /**
+     * @phpstan-assert non-empty-string $value
+     */
+    public function assertNotEmpty(string $value): void {
+        if ($value === '') throw new InvalidArgumentException();
+    }
+}
+```
+
+The Rigor port — Ruby source unchanged from idiomatic, RBS at
+the boundary:
+
+```ruby
+# lib/slug.rb
+class Slug
+  def normalise(name)
+    name.downcase.gsub(/\s+/, "-")
+  end
+
+  def assert_not_empty(value)
+    raise ArgumentError if value.empty?
+  end
+end
+```
+
+```rbs
+# sig/slug.rbs
+class Slug
+  %a{rigor:v1:param: name is non-empty-string}
+  %a{rigor:v1:return: non-empty-lowercase-string}
+  def normalise: (String name) -> String
+
+  %a{rigor:v1:assert value is non-empty-string}
+  def assert_not_empty: (String value) -> void
+end
+```
+
+The directive grammar is structurally a translation: every
+PHPStan `@phpstan-*` becomes a `%a{rigor:v1:...}` annotation on
+the matching `def` line in the `.rbs` file.
+
+## What's next
+
+You probably do not need to read the rest of this appendix
+section sequentially. Three useful pointers:
+
+- [Chapter 7 — RBS and `RBS::Extended`](07-rbs-and-extended.md)
+  has the full directive grammar, including the PHPStan-mapping
+  table that this page summarises.
+- [Chapter 8 — Understanding errors](08-understanding-errors.md)
+  covers the rule catalogue, severity profiles, baseline
+  diffing — every PHPStan onboarding analogue.
+- [Chapter 9 — Plugins](09-plugins.md) for the
+  Type-Specifying / Dynamic-Return analogues.
+
+If you want to compare against another tool, the sibling
+appendix pages cover [TypeScript](appendix-typescript.md),
+[mypy](appendix-mypy.md), [Steep](appendix-steep.md),
+[TypeProf](appendix-typeprof.md),
+[Java / C#](appendix-java-csharp.md), [Rust](appendix-rust.md),
+[Go](appendix-go.md), and [Elixir](appendix-elixir.md).

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

@@ -0,0 +1,292 @@
+# Appendix — Protocols, interfaces, and structural typing
+
+If you arrived from Python, "protocol" means one specific thing:
+`typing.Protocol`, PEP 544's **structural typing** — a class
+satisfies a protocol by *having the right methods*, no inheritance
+required. It is "static duck typing," and it is one of the first
+things a Python typist reaches for.
+
+That instinct is right, but the *word* is a trap in Rigor. Rigor's
+structural-typing feature is not called "protocol" — it is the RBS
+**`interface`**. Meanwhile "protocol" *does* appear in Rigor, naming
+a **different** feature: a framework's path-scoped *behavioural
+contract* ([ADR-28](../adr/28-path-scoped-protocol-contracts.md)).
+This appendix untangles the two so you reach for the right one.
+
+> **The one-line version.** Rigor's `interface` is **structural** —
+> like Go's `interface` and Python's `Protocol`. A class fits by
+> *having the methods*; there is **no `implements`** clause (Ruby has
+> none). It is *not* the Java / PHP nominal `interface`, where a class
+> declares conformance by name. Because the bare word "interface"
+> reads as the Java / PHP kind to many Ruby developers (Ruby has no
+> `interface` keyword, so the intuition is imported), Rigor's docs
+> qualify it on first use — **"structural interface"** or **"RBS
+> interface"** — and so should you when writing about it.
+
+## Two things called "protocol"
+
+| You mean… | The Rigor word | What it is | Lives where |
+| --- | --- | --- | --- |
+| "static duck typing" — a class fits if it has the methods (Python `Protocol`) | **interface** | A structural *type* in the type lattice. | RBS `interface _Foo`, read from `sig/` |
+| "every action under `app/actions/` must define `#handle`" — a framework convention enforced by tooling | **protocol contract** | A *behavioural contract* bound to classes by file path, declared by a plugin. | A plugin's `protocol_contracts:` manifest field (ADR-28) |
+
+The two are different axes, not two flavours of one
+thing, and the rest of this page is mostly about keeping them
+apart. The one-line discriminator:
+
+- An **interface** is a *type* you name in a signature. The check
+  happens *where the interface is mentioned* (`def f: (_Closable)
+  -> void` checks `f`'s argument).
+- A **protocol contract** is *never mentioned by the conforming
+  class or any signature*. A plugin says "the classes under this
+  directory carry this contract," and the engine provisions and
+  checks them implicitly.
+
+## Structural typing: RBS interfaces
+
+This is the direct analogue of Python's `Protocol`. RBS has had
+structural `interface _Foo` since its first release; Rigor reads
+them from `sig/` and checks conformance structurally.
+
+```python
+# Python (PEP 544)
+class SupportsClose(Protocol):
+    def close(self) -> None: ...
+```
+
+```rbs
+# RBS — the same idea
+interface _SupportsClose
+  def close: () -> void
+end
+```
+
+A class that defines `close` with a compatible signature satisfies
+the interface **with no `include`, no superclass, and no runtime
+marker** — the match is structural. From the normative spec
+([`structural-interfaces-and-object-shapes.md`](../type-specification/structural-interfaces-and-object-shapes.md)):
+
+> An RBS interface type … is a *named structural contract*. A
+> nominal type or object shape is assignable to an interface when
+> Rigor can prove that it provides all required members with
+> compatible types.
+
+Where does Rigor apply structural matching? Deliberately at the
+**boundaries**, not class-to-class by default:
+
+- assigning or passing a value where an RBS interface is expected;
+- checking whether an inferred object shape satisfies an interface;
+- a direct method send against a known shape;
+- plugin-provided dynamic reflection adding members to a shape.
+
+Ordinary `Foo`/`Bar` class compatibility stays **nominal** — Ruby's
+own `is_a?` / `kind_of?` depend on the class hierarchy, and RBS uses
+class names as declarations about Ruby constants, so Rigor does
+*not* go fully TypeScript-style-structural for classes. Structural
+typing is a tool you opt into by naming an interface, exactly as in
+Python you opt in by annotating against a `Protocol`. (The
+[mypy / Pyright appendix](appendix-mypy.md#protocols--rbs-interfaces)
+covers the same mapping from the Python side.)
+
+## Object shapes and capability roles
+
+RBS interfaces are the *named* structural types. Rigor also infers
+**anonymous** structural types — *object shapes* — from what a value
+demonstrably responds to, and ships a curated catalogue of
+**capability roles** for the common IO-like contracts:
+
+- `_Reader`, `_Writer` — the read/write halves of a stream;
+- `_RewindableStream`, `_ClosableStream` — `rewind` / `close`
+  capabilities;
+- `_Callable` — responds to `call`.
+
+These keep `IO` and `StringIO` as separate *nominal* types while
+letting each satisfy the smaller structural *roles* a method
+actually needs — the structural-typing payoff (write against the
+capability, not the concrete class) without giving up nominal
+identity where Ruby's runtime relies on it.
+
+If you came looking for "Rigor's Protocol," **this section is it**:
+RBS interfaces + object shapes + capability roles are Rigor's
+structural-typing surface. None of it is spelled "protocol."
+
+## The word vs the semantics, across languages
+
+Why does Rigor spell its structural type `interface` and reserve
+`protocol` for something else? Because the *word* "protocol" and the
+*semantics* "structural typing" have drifted apart across languages,
+and Rigor picks the spelling that least surprises a Ruby reader (RBS
+already says `interface`).
+
+The term itself is old. **Smalltalk** (1970s) called the set of
+messages an object understands its *protocol* — grouped into "message
+protocols" in the class browser. It was never a static-checking
+construct; it named "what you can send this object," the direct
+ancestor of Ruby's duck typing. Every later use inherits that core
+idea — "a set of methods a conforming object provides" — and then
+adds its own rules about *how conformance is established*.
+
+Two such rules matter, and they are independent of the spelling:
+
+- **Structural / implicit** — you conform by *having the methods*. No
+  declaration. (Python `Protocol`, Go `interface`, **RBS `interface`**,
+  Smalltalk's original sense.)
+- **Nominal / explicit** — you conform by *declaring that you do*.
+  (Java / PHP `interface ... implements`, Swift / Objective-C
+  `protocol` with explicit adoption.)
+
+The spelling does **not** track the rule; the two crossed long ago:
+
+| Language | Spelling | Conformance | Same as Rigor? |
+| --- | --- | --- | --- |
+| Smalltalk | "protocol" | (dynamic; duck typing) | ancestor of the idea |
+| **Rigor / RBS** | **`interface`** | **structural / implicit** | — |
+| Python (PEP 544) | `Protocol` | structural / implicit | ✅ same model, different word |
+| Go | `interface` | structural / implicit | ✅ same model, same word |
+| Java / PHP | `interface` | nominal / explicit `implements` | ❌ same word, opposite model |
+| Swift / Objective-C | `protocol` | nominal / explicit adoption | ❌ different word *and* model |
+
+So a reader's intuition depends entirely on where they came from:
+
+- **From Swift / Objective-C:** "protocol" means a type you *declare*
+  conformance to (`struct Resource: Closable`). Rigor's `interface`
+  needs no such declaration — just define `close`. (Objective-C's
+  `respondsToSelector:` and informal protocols are the runtime
+  duck-typing escape hatch; Swift allows *retroactive* conformance via
+  extensions, but adoption is still explicit.) And the one Rigor
+  surface that reuses the *word* — the **protocol contract** below — is
+  not Swift's protocol either: it binds classes by file path, not by an
+  adoption clause.
+- **From Java / PHP:** "interface" means a contract a class must
+  `implement` by name. Rigor reuses the *word* but not the rule: a
+  Ruby class satisfies an RBS `interface` structurally, never by an
+  `implements` clause (Ruby has none).
+- **From Python or Go:** you are already home. RBS `interface` is your
+  `Protocol` / `interface` — structural, implicit, checked where it is
+  named.
+
+And the Smalltalk sense — "a named set of messages a conforming type
+must provide" — is exactly what Rigor revives under the name **protocol
+contract** in the next section. Fittingly, that is the one Rigor *does*
+spell "protocol."
+
+## Protocol contracts (ADR-28)
+
+Now the other axis. A Rack-shaped web framework expects a
+controller action to take a request and return a response; a job
+framework expects `#perform`; a serializer expects `#call`. The
+convention is real, but it lives in the framework's prose — *no
+class declaration records it*, and nothing checks it, so a
+violation is a runtime surprise.
+
+An RBS interface cannot express this. RBS (like Python) has **no
+"every class under this directory implements interface I" form** —
+an interface only bites where a signature names it, and these
+controllers name nothing. That gap is what ADR-28's **protocol
+contracts** fill.
+
+A plugin that knows the framework declares a contract in its
+manifest (`param_types` is an array of positional
+`{ index:, type_name: }` provisions):
+
+```ruby
+# inside a framework plugin's manifest — an illustrative serializer contract
+protocol_contracts: [
+  Rigor::Plugin::ProtocolContract.new(
+    path_glob:        "app/serializers/**/*.rb", # which files
+    method_name:      :call,                      # the method every class must define
+    param_types:      [{ index: 0, type_name: "ActiveRecord::Base" }],
+    return_type_name: "String",
+    severity:         :error
+  )
+]
+```
+
+The engine then does **provide-and-check**:
+
+- **Provide** (engine-side). When binding a `def call(record)` in a
+  matching file, the contract's `param_types` *replace* the usual
+  `Dynamic[top]` the un-annotated parameter would get. The body is
+  then analysed as if `record` carried its real type — so a misuse
+  inside the body (`record.no_such_column`) surfaces as an ordinary
+  `call.undefined-method`, and the inferred return type is precise.
+- **Check** (plugin-side). The plugin confirms every class in a
+  matching file defines the method (else `missing-protocol-method`)
+  and that its inferred return type conforms to `return_type_name`
+  (else `protocol-return-mismatch`).
+
+The provision half is the load-bearing one: without it, `request`
+is `Dynamic[top]`, which answers every method, so any return built
+from it is also `Dynamic[top]` and the return check is vacuous.
+
+Two things to note as an *application* developer (not a plugin
+author):
+
+- You **never write** `protocol_contracts:` — the framework's
+  plugin does. You write a plain `def handle(request)`, and it gets
+  checked for free.
+- The `missing-protocol-method` / `protocol-return-mismatch`
+  diagnostics are **plugin diagnostics**, emitted under the
+  plugin's `plugin.<id>.` provenance — not core Rigor rules. The
+  worked references are [`examples/rigor-web/`](../../examples/rigor-web/)
+  (the minimal tutorial) and [`plugins/rigor-hanami/`](../../plugins/rigor-hanami/)
+  (production Hanami 2 actions).
+
+## Interface vs protocol contract
+
+| | RBS `interface` (structural type) | ADR-28 protocol contract |
+| --- | --- | --- |
+| **What it is** | A type in the lattice | A tooling-enforced convention; *not* a type |
+| **Cross-language analogue** | Python `Protocol`, Go `interface` | the Smalltalk "required message set" sense — but bound by **file path**, a mechanism no mainstream `protocol`/`interface` has |
+| **How a class opts in** | Structurally — just have the methods | Implicitly — be defined under the path glob |
+| **Where it's referenced** | Named in a signature (`(_Closable) -> void`) | Named *nowhere*; bound by file path |
+| **Where the check fires** | At the use site that names the interface | At the contracted `def` (provide) + per class (check) |
+| **Who declares it** | Whoever writes the `.rbs` | A framework plugin's manifest |
+| **Provides parameter types?** | No (it's a type, used where named) | **Yes** — into an un-annotated `def` |
+| **Diagnostics** | Core type errors at the use site | `missing-protocol-method`, `protocol-return-mismatch` (plugin) |
+
+The naming overlap is historical (see [the cross-language
+detour](#the-word-vs-the-semantics-across-languages) above): the
+Smalltalk "set of required messages" sense survives in the *protocol
+contract*, while Python's `typing.Protocol` reused the word for the
+*structural-type* idea that Ruby/RBS spell `interface`. So in Rigor,
+"protocol" never means the structural type.
+
+## Which one do I want?
+
+- You want to **write a method that accepts anything with a
+  `#close`** → that is a structural type. Declare an RBS
+  **`interface _Closable`** and annotate against it (or rely on
+  inferred object shapes for the anonymous case). See
+  [Chapter 7 — RBS and RBS::Extended](07-rbs-and-extended.md).
+- You want to **enforce that every class in a directory implements
+  a framework method with given parameter/return types** → that is
+  a **protocol contract**, and it is a *plugin-authoring* feature.
+  See [ADR-28](../adr/28-path-scoped-protocol-contracts.md) and the
+  [`examples/`](../../examples/README.md) walkthroughs.
+- You are an **application developer** using such a framework → you
+  do neither explicitly. Write idiomatic Ruby; the framework's
+  plugin supplies the contract, and Rigor checks your actions
+  against it. When you see `missing-protocol-method`, you forgot
+  the method the framework requires; when you see
+  `protocol-return-mismatch`, your action returns the wrong shape.
+
+## What's next
+
+- [Chapter 7 — RBS and RBS::Extended](07-rbs-and-extended.md) — how
+  to write the `.rbs` an interface lives in.
+- [Chapter 9 — Plugins](09-plugins.md) and the
+  [examples/ landing page](../../examples/README.md) — where
+  protocol contracts are authored.
+- [`docs/type-specification/structural-interfaces-and-object-shapes.md`](../type-specification/structural-interfaces-and-object-shapes.md)
+  — the normative spec for interfaces, object shapes, and
+  capability roles.
+- [ADR-28](../adr/28-path-scoped-protocol-contracts.md) — the
+  protocol-contract design decision and its rejected alternatives
+  (including *why* an RBS interface bound by directory was not the
+  route).
+- Coming from another checker? The
+  [mypy / Pyright appendix](appendix-mypy.md#protocols--rbs-interfaces)
+  maps `Protocol` ↔ RBS `interface` from the Python side, and the
+  [type-theory appendix](appendix-type-theory.md) places nominal vs
+  structural typing in the broader landscape.