rigortype 0.2.0 → 0.2.2

data/docs/handbook/12-lightweight-hkt.md

@@ -0,0 +1,333 @@
+# Lightweight HKT (JSON.parse and friends)
+
+`JSON.parse(str)` returns "some JSON value": `nil`, a bool, a
+number, a string, an array of JSON values, or a hash of JSON
+values. RBS describes that as `untyped` because there is no way
+to spell a recursive sum type without quantifying over a type
+constructor. Most type checkers shrug and let `JSON.parse(str)`
+fade into `Dynamic[top]`.
+
+Rigor models it precisely:
+
+```ruby
+parsed = JSON.parse('{"name": "Alice"}')
+assert_type(
+  "Array[json::value[String]] | Float | " \
+  "Hash[String, json::value[String]] | Integer | " \
+  "String | false | nil | true",
+  parsed)
+```
+
+The mechanism behind this — and the one that lets you wire the
+same shape for your own DSL or stdlib method — is **Lightweight
+HKT** ([ADR-20](../adr/20-lightweight-hkt.md)), Rigor's
+defunctionalised encoding of higher-kinded types in the
+[Yallop & White 2014](https://www.cl.cam.ac.uk/~jdy22/papers/lightweight-higher-kinded-polymorphism.pdf) /
+[fp-ts `URItoKind`](https://github.com/gcanti/fp-ts/blob/master/src/HKT.ts)
+style. This chapter walks through what it does, when to reach
+for it, and how to author your own overlay.
+
+This is the most advanced chapter in the handbook. Most
+readers only need the first two sections — what the carrier
+looks like and which stdlib methods are wired out of the box.
+Everything after "Authoring your own overlay" is for the rare
+case where you want to model a recursive sum type of your own.
+
+## The five-second pitch
+
+| Concept | Rigor spelling | Where you see it |
+| --- | --- | --- |
+| Type-constructor "tag" | Namespaced Symbol URI (`:json::value`, `:dry_monads::result`) | `%a{rigor:v1:hkt_register: uri=…}` directive |
+| Abstract application `F<A>` | `Type::App[uri, args]` | Carrier in dispatcher output |
+| Type-level definition | `%a{rigor:v1:hkt_define: uri=… params=… body=…}` directive | `.rbs` overlay file |
+| Reducing `App[F, A]` to a real type | `env.hkt_registry.reduce(app)` (or `app.reduce(registry)`) | Called eagerly by the dispatcher tier for known stdlib methods |
+| Hooking it to a method | `Builtins::HktBuiltins::METHOD_RETURN_OVERRIDES` table | Plugin / Rigor-bundled wiring |
+
+The next sections show each of these in action.
+
+## What's bundled today
+
+Rigor ships two HKT registrations out of the box. The main
+one is **`json::value[K]`**, the recursive JSON-value sum (the
+second, `csv::parsed[K]`, is covered at the end of this
+section). `json::value` has two parts:
+
+```rbs
+# Registration — names the tag, declares its arity, variance,
+# and erasure bound. The bound is what Rigor's RBS round-trip
+# falls back to when reduction is blocked.
+uri=json::value arity=1 variance=out bound=untyped
+
+# Definition — the actual body, parameterised on K (the hash
+# key type). Note the self-referential `App[json::value, K]`
+# arms — Rigor's reducer handles recursion with lazy "tying-
+# the-knot" semantics.
+params=K body=
+  nil | true | false | Integer | Float | String
+  | Array[App[json::value, K]]
+  | Hash[K, App[json::value, K]]
+```
+
+Nine stdlib methods route through this:
+
+- `JSON.parse` / `JSON.parse!` / `JSON.load` / `JSON.load_file` / `JSON.load_file!`
+- `YAML.safe_load` / `YAML.safe_load_file`
+- `Psych.safe_load` / `Psych.safe_load_file`
+
+The HKT-builtin dispatcher tier sits ABOVE the standard RBS
+dispatch, so even though upstream RBS declares
+`JSON.parse: (string, ?options) -> untyped`, Rigor's answer is
+the reduced Union. `YAML.load` / `YAML.unsafe_load` deliberately
+stay out — they can return any Ruby object and have no useful
+HKT envelope.
+
+The second bundled registration, **`csv::parsed[K]`**, models
+`CSV.parse` / `CSV.read` as `Array[Array[K | nil]]` — the
+no-headers shape. Calls passing `headers: true` (which return
+a `CSV::Table`) and `CSV.foreach` (which yields rather than
+returns) fall through to the upstream RBS type.
+
+## Two kinds of call-site discrimination
+
+The bundled overrides are not just `(receiver, method) → fixed
+type`. Two **discriminators** look at the call's actual
+arguments:
+
+### `symbolize_names: true` swaps K
+
+```ruby
+JSON.parse(str)
+# parsed: ... | Hash[String, json::value[String]] | ...
+
+JSON.parse(str, symbolize_names: true)
+# parsed: ... | Hash[Symbol, json::value[Symbol]] | ...
+```
+
+The `:json_symbolize_names` discriminator inspects the call's
+second-argument `HashShape` for a literal `symbolize_names: true`
+entry. Match swaps `K = String` for `K = Symbol` before the
+reducer runs. Non-literal `symbolize_names: x` (a variable, a
+non-`Constant<true>` value) stays on the default `String`
+branch.
+
+### `permitted_classes:` unions extra arms
+
+```ruby
+require "date"
+parsed = YAML.safe_load(str, permitted_classes: [Date])
+# parsed: ... | Date | ...
+```
+
+The `:yaml_permitted_classes` **post-reduce hook** runs after the
+reducer and augments the result. It walks the second-argument
+`HashShape` for a `permitted_classes:` key whose value is a
+literal `Tuple` or `Array` of Singleton classes, maps each to a
+`Nominal`, and unions them with the base `json::value` Union.
+`[Date, Symbol]` adds both arms.
+
+Non-literal `permitted_classes:` values (a variable, a `Dynamic`,
+a non-Singleton element) silently no-op so Rigor never invents
+classes it can't statically see.
+
+## Authoring your own overlay
+
+You can register your own HKT URIs in a `.rbs` file under your
+`signature_paths:`. The annotations attach to a class or module
+declaration (RBS's annotation grammar requires that):
+
+```rbs
+%a{rigor:v1:hkt_register: uri=my_app::box arity=1 variance=out bound=untyped}
+%a{rigor:v1:hkt_define: uri=my_app::box params=K body=K | nil}
+class MyAppBoxOverlay
+end
+```
+
+A few rules:
+
+- **URIs MUST be namespaced** (`<author>::<name>`). The `::`
+  separator prevents cross-plugin collisions per ADR-20 WD1.
+- **The payload format is space-separated `key=value` pairs.**
+  RBS's `%a{...}` annotation grammar rejects quotes, so JSON
+  payload won't work — the kv-form is what RBS will deliver.
+- **`body=` is special-cased to gobble everything to the end** of
+  the payload, so the body string can contain spaces, `|`, `[]`
+  etc. without escaping.
+- **`params=` is a comma-separated list** of UCName identifiers
+  (`params=K` or `params=T,E`).
+- **`bound=` accepts `untyped` (default) or a bare class name**.
+  Richer bound forms (parameterised generics, unions,
+  refinements) wait for a follow-up slice's expression parser.
+
+When `Environment.for_project` builds the env, it scans the
+loaded RBS for these annotations and merges them into
+`env.hkt_registry` on top of the bundled builtins. Last-write-
+wins on URI collisions so an overlay can override `json::value`
+if you want to.
+
+## The body grammar
+
+`body=` is parsed by `HktBodyParser` into a tree the reducer
+walks. The grammar covers ADR-20 § D3 in full:
+
+| Form | Example | Meaning |
+| --- | --- | --- |
+| Atom | `nil` / `true` / `false` / `bool` / `untyped` | Constants and the `Dynamic[top]` carrier |
+| Nominal class | `Integer` / `String` / `Foo::Bar` / `::String` | `Nominal[class_name]` |
+| Param reference | `K`, `T`, `E` (when in `params`) | Substituted at reduction time |
+| Parameterised nominal | `Array[K]`, `Hash[K, V]` | `Nominal[..., type_args: [...]]` |
+| Lightweight HKT application | `App[json::value, K]` | Another `Type::App` carrier, reduced lazily |
+| Union | `A \| B \| C` | `Type::Union` (normalised) |
+| **Conditional** | `(K <: String ? Integer : Float)` | Branches on a test verdict |
+
+Disambiguation: a UCName matching one of `params` becomes a
+`Param` node, **unless** it's followed by `::` (qualified class
+continuation) or `[` (parameterised app), in which case it's
+treated as a nominal. So `K` is a param ref, `K[X]` is the
+class `K` applied to `X`.
+
+### Conditional types (§ D3)
+
+Conditional types let the body branch on the bound type — useful
+for shape-driven discriminators inside a single registration:
+
+```rbs
+%a{rigor:v1:hkt_define: uri=my_app::result params=K body=
+  (K <: String ? Integer : Float)
+}
+```
+
+Three test operators:
+
+| Test | Example | Meaning |
+| --- | --- | --- |
+| `<:` (subtype) | `K <: String` | True when `K`'s reduced type is a subtype of `String` |
+| `==` (structural equality) | `K == :symbol` | True when `K`'s reduced type structurally equals the right side |
+| `in [...]` (membership) | `K in [String, Symbol]` | True when `K`'s reduced type structurally equals any option |
+
+The reducer's verdict policy is **trinary**:
+
+- `:yes` → reduce the `then_branch`.
+- `:no` → reduce the `else_branch`.
+- `:maybe` (undecided — e.g. `Dynamic[T]` on either side) → widen
+  to the union of both reduced branches (per ADR-20 WD7 /
+  robustness principle — Rigor stays conservative when it can't
+  prove which arm fires).
+
+Verdict policy at the current slice: structural equality → `:yes`;
+disjoint nominals (different `class_name`) or disjoint constants
+(different `value`) → `:no`; everything else → `:maybe`.
+
+Branches accept unions and nested conditionals:
+
+```rbs
+%a{rigor:v1:hkt_define: uri=my_app::numeric params=E body=
+  (E <: Integer ? Integer
+    : (E <: Float ? Float
+      : (E <: String ? Integer | Float | nil
+        : untyped)))
+}
+```
+
+Test sides themselves are single arms (no union directly on a
+test side — wrap in `App[my_union, ...]` if you need a union
+there).
+
+## Reduction semantics — lazy "tying-the-knot"
+
+The interesting part: `json::value`'s body contains
+`Array[App[json::value, K]]` — a SELF-REFERENCE. A naive
+recursive reducer would infinite-loop.
+
+Rigor's reducer carries an **in-progress stack** keyed on
+`(uri, reduced_args)`. When evaluating an `AppRef` whose
+`(uri, args)` matches something already on the stack, it
+returns the in-progress `Type::App` carrier as-is — lazily,
+without unfolding. The standard fix-point trick for recursive
+type aliases.
+
+So reducing `App[json::value, [String]]` produces:
+
+```
+Union[ nil, true, false, Integer, Float, String,
+       Array[ Type::App[json::value, [String]] ],  ← carrier left intact
+       Hash[ String, Type::App[json::value, [String]] ] ]
+```
+
+The nested `Type::App` is a normal Rigor type; downstream
+consumers (acceptance, narrowing, dispatch) handle it by
+delegating to its `bound` (default `Dynamic[top]`). If they
+need one more level of unfolding, they call
+`app.reduce(env.hkt_registry)` again — but the typical
+consumer doesn't need to.
+
+A **fuel budget** (default 64 reduction steps per call-site
+evaluation) bounds runaway expansion. Exhaustion unwinds to
+`app.bound`.
+
+## What it doesn't do (yet)
+
+Lightweight HKT is, well, lightweight. Conscious non-goals:
+
+- **Pattern-matching with binder extraction**
+  (`E <: [:if, _, A, B] ? lisp_type[A] | lisp_type[B] : ...`).
+  The conditional grammar described above tests yes/no/maybe
+  but does not bind new type variables out of the pattern.
+  `rigor-lisp-eval` needs binder extraction for full
+  AST-shape discrimination; it stays on the diagnostic-emitter
+  path until pattern bindings land.
+- **Multi-arg HKTs for non-recursive containers**
+  (`Result[T, E]` / `Maybe[T]`) — the registry supports
+  multi-arg URIs, but Rigor's existing carriers don't have
+  the sealed-union shape `Result` needs (ADR-3 amendment is
+  the gating piece).
+- **Sugar syntax**. The explicit `%a{rigor:v1:hkt_register /
+  hkt_define}` pair is the canonical form. A recursive
+  `type alias` shorthand is a future option, gated on user
+  feedback that the explicit form is too verbose.
+- **Plugin-side resolver hookup**. Plugins can't yet register
+  HKT URIs through their manifests; today only Rigor-bundled
+  registrations and user `.rbs` overlays populate the
+  registry.
+
+If you hit one of these, ADR-20's § Implementation slicing
+menu names the slice that addresses it.
+
+## Where to look in the code
+
+| Layer | Location |
+| --- | --- |
+| Carrier | [`lib/rigor/type/app.rb`](../../lib/rigor/type/app.rb) |
+| Registry value objects | [`lib/rigor/inference/hkt_registry.rb`](../../lib/rigor/inference/hkt_registry.rb) |
+| Body tree node types | [`lib/rigor/inference/hkt_body.rb`](../../lib/rigor/inference/hkt_body.rb) |
+| Reducer (lazy self-ref + fuel) | [`lib/rigor/inference/hkt_reducer.rb`](../../lib/rigor/inference/hkt_reducer.rb) |
+| Body-string grammar parser | [`lib/rigor/inference/hkt_body_parser.rb`](../../lib/rigor/inference/hkt_body_parser.rb) |
+| Directive parser (`hkt_register` / `hkt_define`) | [`lib/rigor/rbs_extended/hkt_directives.rb`](../../lib/rigor/rbs_extended/hkt_directives.rb) |
+| Bundled `json::value` + `METHOD_RETURN_OVERRIDES` | [`lib/rigor/builtins/hkt_builtins.rb`](../../lib/rigor/builtins/hkt_builtins.rb) |
+| Dispatcher tier | [`lib/rigor/inference/method_dispatcher.rb`](../../lib/rigor/inference/method_dispatcher.rb) (`try_hkt_builtin_return`) |
+| Environment integration | [`lib/rigor/environment.rb`](../../lib/rigor/environment.rb) (`#hkt_registry` + `HktRegistryHolder`) |
+| RBS scan | [`lib/rigor/environment/rbs_loader.rb`](../../lib/rigor/environment/rbs_loader.rb) (`each_class_decl_annotation`) |
+
+## What's next
+
+If you came here from a "where does JSON.parse get its type
+from?" question, the rest of the handbook covers the surrounding
+machinery:
+
+- [Chapter 2 — Everyday types](02-everyday-types.md) for the
+  carrier zoo the reducer outputs.
+- [Chapter 7 — RBS and `RBS::Extended`](07-rbs-and-extended.md)
+  for the broader annotation grammar (`%a{rigor:v1:return:}`,
+  `%a{rigor:v1:predicate-if-true}`, …) the HKT directives
+  sit alongside.
+- [Appendix — Connections to type theory](appendix-type-theory.md)
+  § "What Rigor does NOT model" for the formal-type-theory
+  context that explains why Rigor adopted the lightweight
+  encoding rather than real HKT.
+
+If you want to author your own overlay end-to-end, the
+worked example in
+[`spec/rigor/environment_spec.rb`](../../spec/rigor/environment_spec.rb)
+("ADR-20 HKT registry scan" context) is the smallest viable
+reference — a fixture `.rbs` file with the directive pair, a
+class declaration to anchor them on, and an `Environment.for_project`
+call that surfaces the registration through `env.hkt_registry`.

data/docs/handbook/README.md

@@ -0,0 +1,275 @@
+# The Rigor Handbook
+
+A walkthrough of Rigor's type model written for Ruby
+programmers — no prior static-typing background assumed. Read
+top to bottom for the first pass; come back to individual
+chapters for reference once you know what you are looking for.
+
+## Who this is for
+
+You write Ruby for a living, you have run into a `NoMethodError`
+on `nil` more than once, and you want to know:
+
+- What does `rigor check` actually look at?
+- Why did it flag this expression — or, more often, why
+  didn't it flag the one I expected it to?
+- When inference falls short, how do I push it further
+  without writing annotations all over my `.rb` files?
+
+The handbook answers those questions. It does **not** try to
+replace the [normative type
+specification](../type-specification/README.md) — that lives
+in `docs/type-specification/` and is the binding source when
+this handbook disagrees.
+
+Operational topics — installation, the CLI command reference,
+configuration keys, baselines, CI — live in the
+[User Manual](../manual/README.md). Reach for this handbook to
+understand what a type *means*; reach for the manual to look
+up the flag, key, or command that *acts* on it.
+
+## Table of contents
+
+1. [**Getting started**](01-getting-started.md) — running
+   `rigor check`, reading diagnostics, the "no annotations
+   needed" stance.
+2. [**Everyday types**](02-everyday-types.md) — the carrier
+   zoo. Constants, integer ranges, refinements, unions,
+   `Dynamic[top]`. The shortest path to "now I see what
+   Rigor sees."
+3. [**Narrowing**](03-narrowing.md) — how `if`, `case`, and
+   predicate methods sharpen a variable's type along the
+   branch.
+4. [**Tuples and hash shapes**](04-tuples-and-shapes.md) — the
+   structural carriers Ruby's `[a, b, c]` literals and
+   `{key: value}` hashes get when Rigor can prove their layout.
+   Includes the **shape-projection functions** (`pick_of` /
+   `omit_of` / `partial_of` / `required_of` / `readonly_of`)
+   that mirror TypeScript's `Pick` / `Omit` / `Partial` /
+   `Required` / `Readonly` utility types.
+5. [**Methods and blocks**](05-methods-and-blocks.md) — argument
+   typing, return-type inference, block parameters, arity.
+6. [**Classes**](06-classes.md) — instance-side vs class-side,
+   `self`, `attr_accessor`, `Data.define`.
+7. [**RBS and RBS::Extended**](07-rbs-and-extended.md) — when
+   inference cannot prove what the runtime actually returns,
+   how to nudge it through `.rbs` files and `%a{rigor:v1:…}`
+   directives.
+8. [**Understanding errors**](08-understanding-errors.md) —
+   the rule catalogue (`call.undefined-method`,
+   `call.argument-type-mismatch`, `flow.always-raises`, …),
+   severity profiles, and `# rigor:disable` suppression.
+9. [**Plugins**](09-plugins.md) — when to author one,
+   pointer to the [examples/](../../examples/README.md)
+   landing page.
+10. [**Coexisting with Sorbet**](10-sorbet.md) — for users
+    arriving from a Sorbet-using project: the
+    [`rigor-sorbet`](../../plugins/rigor-sorbet/) adapter
+    reads `sig { ... }` blocks, RBI files, and
+    `T.let` / `T.cast` / `T.must` / `T.unsafe` assertions
+    as type sources without rewriting in RBS.
+11. [**Generating RBS with rigor sig-gen**](11-sig-gen.md)
+    — emitting RBS from Rigor's inference results, the
+    `new-file` / `new-method` / `tighter-return`
+    classification model, the `--print` / `--diff` /
+    `--write` modes, the `--params` policy and ADR-5
+    trade-off, RSpec-aware observations.
+12. [**Lightweight HKT (JSON.parse and friends)**](12-lightweight-hkt.md)
+    — Rigor's defunctionalised higher-kinded type encoding
+    ([ADR-20](../adr/20-lightweight-hkt.md), Yallop & White
+    2014 / fp-ts shape). Covers the bundled `json::value`
+    registration backing `JSON.parse` / `YAML.safe_load`,
+    the `symbolize_names: true` + `permitted_classes: [...]`
+    call-site discriminators, how to author your own URI
+    overlay in `.rbs`, the body grammar, the reducer's
+    lazy "tying-the-knot" handling for recursive sums, and
+    the conscious non-goals (no conditional bodies, no
+    multi-arg containers yet, no plugin manifest hookup).
+
+### Appendix — Coming from another type checker
+
+A short cross-language reference for readers whose mental
+model of "static type checker" was set by another tool.
+Each page maps Rigor's vocabulary onto the concepts you
+already know — type carriers, narrowing primitives,
+configuration shape, severity model, suppression — and
+calls out the places where the two systems make different
+choices.
+
+- [**Coming from TypeScript**](appendix-typescript.md) —
+  the structural-vs-nominal-with-refinements split, `unknown`
+  / `any` / `never` ↔ `Top` / `Dynamic[top]` / `Bot`,
+  type guards ↔ `predicate-if-true` directives, what
+  conditional / mapped types do not have a Rigor analogue.
+- [**Coming from PHPStan**](appendix-phpstan.md) — the
+  closest peer in spirit. Identical refinement vocabulary
+  (`non-empty-string`, `int<min, max>`, `numeric-string`,
+  `literal-string`), `@phpstan-assert*` ↔ `RBS::Extended`,
+  Type-Specifying Extensions ↔ plugins, baseline diffing.
+- [**Coming from mypy / Pyright**](appendix-mypy.md) — gradual
+  typing parallels, `Literal` ↔ `Constant`, `TypeGuard` /
+  `TypeIs` ↔ `predicate-if-true` / `predicate-if-false`,
+  `Protocol` ↔ RBS `interface`, `LiteralString` ↔
+  `literal-string`.
+- [**Coming from Steep**](appendix-steep.md) — Ruby's other
+  RBS-driven static checker. Both consume the same `.rbs`
+  files; this page covers the layer each tool adds on top
+  and the coexistence pattern for projects that want to run
+  both.
+- [**Coming from TypeProf**](appendix-typeprof.md) — Ruby's
+  official type *inference* tool. Both infer without
+  annotations; this page covers the whole-program-vs-local
+  analysis trade, why `rigor sig-gen` is the direct analogue
+  to the `typeprof` CLI, and the diagnostics-vs-RBS-output
+  split.
+- [**Coming from Java or C#**](appendix-java-csharp.md) — the
+  two nominal, statically-typed languages share enough reflexes
+  (annotate-everything, generics, records, sealed
+  hierarchies, pattern-matching `switch`) to share one page.
+  Covers the inference-first vs annotate-first inversion,
+  records ↔ `Data.define`, C#'s `string?` / Java's
+  `Optional<T>` ↔ `T?`, declaration-site (C#) vs use-site
+  (Java) variance ↔ RBS, `dynamic` ↔ `Dynamic[top]`, and why
+  Rigor reports *unreachable* `case` clauses rather than
+  enforcing sealed-type exhaustiveness.
+- [**Coming from Rust**](appendix-rust.md) — the sum-type and
+  exhaustive-`match` peer. `Option<T>` ↔ `T?`, `Result<T, E>`
+  ↔ Ruby's raising model, `enum` variants ↔ a union of
+  `Data.define`, `match` ↔ `case`/`in` with the
+  enforce-totality vs report-unreachable inversion, traits
+  (nominal, coherent) ↔ RBS structural interfaces, and
+  refinements ↔ the newtype pattern. Ownership is a noted
+  non-goal.
+- [**Coming from Go**](appendix-go.md) — the structural-typing
+  cousin. Go's implicitly satisfied `interface` *is* Rigor's
+  RBS interface, so the feature Java/C# readers stumble on is
+  the one a Go reader already has by reflex. Covers
+  `interface{}` / `any` ↔ `Dynamic[top]`, type switch ↔
+  `case`/`in`, errors-as-values ↔ raising, and the unions /
+  literal types / refinements Go does not have.
+- [**Coming from Elixir**](appendix-elixir.md) — the closest
+  *philosophical* match: dynamic origin, gradual typing, and a
+  success-typing / no-false-positives stance shared with
+  Dialyzer. Covers pattern matching + guards ↔ narrowing (the
+  `flow.unreachable-clause` rule was modelled on Elixir's
+  clause-reachability work, [ADR-47](../adr/47-narrowing-driven-clause-reachability.md)),
+  set-theoretic types ↔ Rigor's unions + `~T` / `T - U`
+  operators, atoms ↔ symbols, and protocols / behaviours ↔
+  structural interfaces.
+
+### Appendix — Protocols and structural typing
+
+A standalone concept page for the question this handbook gets
+from Python and Swift readers alike: *"where is Rigor's
+`Protocol`?"* It untangles the one word that means two
+unrelated things in Rigor — the **interface** (RBS structural
+type, the Python `typing.Protocol` analogue) and the
+**protocol contract** (ADR-28's path-scoped behavioural
+contract) — so you reach for the right one.
+
+- [**Protocols, interfaces, and structural typing**](appendix-protocols-and-structural-typing.md)
+  — RBS `interface` ↔ `typing.Protocol`, inferred object
+  shapes and capability roles, and how all of that differs
+  from the plugin-declared, path-scoped protocol contracts of
+  [ADR-28](../adr/28-path-scoped-protocol-contracts.md).
+  Includes the side-by-side "interface vs protocol contract"
+  table and a "which one do I want?" guide.
+
+### Appendix — Connections to type theory
+
+A short bridge between Rigor's vocabulary and the formal
+type-theoretic concepts you may have seen in a programming-
+languages textbook or in another type checker's documentation.
+Read this if you came in from a "where does Rigor sit in the
+type-theory landscape" question; the handbook proper stays
+deliberately short on theory.
+
+- [**Connections to type theory**](appendix-type-theory.md) —
+  the type lattice, subtyping vs gradual consistency, nominal
+  vs structural, the polymorphism family (parametric / subtype
+  / ad-hoc), variance, refinement / predicate subtyping,
+  occurrence typing, gradual typing, effect systems, the
+  soundness vs completeness trade-off, and a short list of
+  features Rigor deliberately does not model (HKT,
+  higher-rank, full dependent types, …) — each with the
+  matching Rigor surface and a pointer into the spec corpus.
+- [**The Liskov Substitution Principle**](appendix-liskov.md) —
+  why LSP is a *behavioural* discipline that applies to Ruby
+  *more* than to a statically-checked language (not less — the
+  "Ruby isn't statically typed so LSP is optional" claim gets
+  the principle backwards), how Rigor's robustness principle
+  (strict returns, lenient parameters) re-derives the LSP
+  signature rule (covariant returns, contravariant parameters)
+  from Ruby-adoption ergonomics rather than substitutability
+  proofs, why that convergence means Rigor's defaults do not
+  fight duck typing or the "L" of SOLID, and which
+  behavioral-subtyping obligations (cross-hierarchy override
+  compatibility, exception rules, Design-by-Contract, the
+  history constraint) Rigor does *not* statically enforce. On
+  this page only, "LSP" means Liskov — not the Language Server.
+
+## How to read this handbook
+
+Each chapter is short on theory and long on examples. Every
+example is real Ruby that runs under MRI as written; the
+prose around it is what `rigor check` would say about that
+code.
+
+When you see an `assert_type(...)` line in a snippet, that is
+Rigor's introspection helper, not a runtime check — it pins
+the inferred type at that program point so you can compare
+the prose to the actual analyzer output. `dump_type(...)` is
+the same idea but emits a notice instead of failing on
+mismatch.
+
+Snippet conventions:
+
+```ruby
+n = 1 + 2
+assert_type("3", n)  # Rigor folds the literal sum
+```
+
+means: at the `assert_type` call, Rigor's inference for `n` is
+`3` — the folded literal value.
+
+Wording convention — **"interface"**: Ruby has no `interface`
+keyword, so most readers import the word's meaning from another
+language, and the Java / PHP *nominal* sense (a class declares
+`implements`) dominates. Rigor's RBS `interface` is the opposite —
+*structural*, like Go's `interface` or Python's `Protocol`, satisfied
+by having the methods with no declaration. To avoid the misread,
+qualify the word on first use in any chapter as **"structural
+interface"** or **"RBS interface,"** never the bare "interface." The
+[Protocols and structural typing appendix](appendix-protocols-and-structural-typing.md)
+is the canonical explainer.
+
+When a chapter references a more formal document, the link
+takes you out of the handbook into the binding spec corpus or
+ADRs:
+
+- [`docs/types.md`](../types.md) — one-page mental model.
+- [`docs/type-specification/`](../type-specification/README.md)
+  — normative spec corpus.
+- [`docs/internal-spec/`](../internal-spec/README.md) —
+  analyzer-internal contracts (engine surface, type-object
+  public API).
+- [`docs/adr/`](../adr/) — architecture decision records.
+
+## Non-goals
+
+The handbook is meant to be readable cover-to-cover in a few
+hours. To keep it short:
+
+- It does **not** introduce Ruby itself. `def`, `class`,
+  blocks, modules, `attr_*`, regex, RBS basics — all assumed.
+- It does **not** cover every edge case. Edge cases live in
+  the spec corpus.
+- It does **not** discuss internal contracts (engine surface,
+  type-object public API). Those live in
+  [`docs/internal-spec/`](../internal-spec/README.md).
+- It does **not** cover plugin **authoring** — that is the
+  job of [examples/](../../examples/README.md). Chapter 9 is
+  a one-page pointer.
+
+If a topic comes up that the handbook does not explain, the
+relevant spec document is one click away.