plumb 0.0.17 → 0.2.0.beta.1

data/README.md

@@ -139,7 +139,7 @@ More about [Types::Hash](#typeshash) and [Types::Array](#typesarray). There's al
 
 ### Type composition
 
-At the core, Plumb types are little [Railway-oriented pipelines](https://ismaelcelis.com/posts/composable-pipelines-in-ruby/) that can be composed together with _AND_, _OR_ and _NOT_ semantics. Everything else builds on top of these two ideas.
+At the core, Plumb types are little [Railway-oriented pipelines](https://ismaelcelis.com/posts/composable-pipelines-in-ruby/) that can be composed together with _AND_ (`#>>`), _OR_ (`#|`) and _NOT_ (`#not`) semantics, plus set-style _intersection_ (`#&`). Everything else builds on top of these ideas.
 
 #### Composing types with `#>>` ("And")
 
@@ -155,6 +155,43 @@ Similar to Ruby's built-in [function composition](https://thoughtbot.com/blog/pr
 
 In other words, `A >> B` means "if A succeeds, pass its result to B. Otherwise return A's failed result."
 
+`#>>` also **type-checks the composition** at build time: if the left side could never produce a value the right side accepts, the chain is a dead end and it raises `Plumb::TypeError` before any data flows through. See [Composition type-checks](#composition-type-checks).
+
+#### A plain callable between two types
+
+A proc declares no types, so on its own it's an opaque step. Written *between* two types, those types move into its boundaries and the chain becomes a single typed function:
+
+```ruby
+Doubled = Types::Integer >> ->(result) { result.valid(result.value * 2) } >> Types::Integer
+
+Doubled.inspect             # => "(Types::Integer -> Types::Integer)"
+Doubled.input_type          # => Types::Integer
+Doubled.output_type         # => Types::Integer
+Doubled.parse(3)            # => 6
+Doubled.resolve('3').errors # => "Must be a Integer"
+```
+
+The checks are the ones you wrote — the input validated before the callable runs, the output after — but they run as one node's boundaries instead of a three-step chain, and the result reports what it accepts and produces, so it keeps composing (and type-checking) downstream. Either half works on its own: `Types::Integer >> a_proc` is `(Types::Integer -> Plumb::Types::Any)`, typed on the side you declared.
+
+Nothing is dropped to do this: a type only moves into a boundary the step left undeclared, so it runs exactly where the no-op ran. That includes a type that *builds* a value, so a struct pipeline collapses the same way:
+
+```ruby
+Person  = Types::Data[name: Types::String]
+Renamer = Person >> ->(r) { r.valid(r.value.with(name: r.value.name.upcase)) } >> Person
+
+Renamer.inspect                 # => "(Person -> Person)"
+Renamer.parse(name: 'ada').name # => "ADA"
+Renamer.resolve(name: 42).errors # => {name: "Must be a String"}
+```
+
+What keeps its own node is a step that declares what it accepts, or one carrying its own callable — two of those meeting is transform fusion's business rather than absorption's:
+
+```ruby
+# The transform declares String as its input, so the leading gate stays a step.
+(Types::String >> Types::String.transform(::Integer, &:to_i)).inspect
+# => "(Types::String >> (Types::String -> Integer))"
+```
+
 #### Disjunction with `#|` ("Or")
 
 `A | B` means "if A returns a valid result, return that. Otherwise try B with the original input."
@@ -214,6 +251,58 @@ FlexibleUSD.parse(Money.new(1000, 'GBP')) # Money(USD 15.00)
 
 You can see more use cases in [the examples directory](https://github.com/ismasan/plumb/tree/main/examples)
 
+#### Intersection with `#&` and the `Never` type
+
+`A & B` is the **intersection** (the greatest lower bound) of two types: it describes values that satisfy **both**. Unlike `#>>`, it is symmetric (order-independent) and never raises — where the two types can't overlap it produces `Types::Never` (see below).
+
+Where it can, `#&` narrows to the exact overlap:
+
+```ruby
+Types::Integer[2..] & Types::Integer[0..100]   # => Integer[2..100]  (ranges intersected)
+Types::Integer[1, 2, 3] & Types::Integer[2, 3, 4] # => Integer[Set[2, 3]]
+Types::Integer & Types::Numeric                # => Integer          (keeps the narrower)
+```
+
+It distributes over unions and intersects covariant containers element-wise:
+
+```ruby
+Types::Array[Types::Integer | Types::Float] & Types::Array[Types::Float] # => Array[Float]
+Types::Integer | (Types::String & Types::Integer)                        # => Integer
+```
+
+When the intersection is provably empty, the result is `Types::Never`:
+
+```ruby
+Types::String & Types::Integer                 # => Types::Never  (no value is both)
+Types::Integer[2..10] & Types::Integer[11..100] # => Types::Never  (disjoint ranges)
+```
+
+Chaining refinements with `#[]` (or `#where`) is the same intersection, so a provably-empty chain reduces to `Types::Never` too:
+
+```ruby
+Types::Integer[0..5][10..]                       # => Types::Never  (== Integer[0..5] & Integer[10..])
+Types::String.where(size: 0..5).where(size: 10..) # => Types::Never  (unsatisfiable clause)
+```
+
+When it can neither narrow nor prove emptiness, `#&` falls back to a runtime intersection that validates the value through both sides.
+
+`Types::Hash#&` ([Hash intersections](#hash-intersections)) and `Types::Interface#&` ([Intersecting interfaces](#intersecting-interfaces)) are the record- and interface-specific cases of the same operator.
+
+##### `Types::Never`
+
+`Types::Never` is the **bottom type** — the dual of the `Types::Any` top. No value inhabits it, so it always fails validation, and it collapses out of compositions:
+
+```ruby
+Types::Any     & Types::Integer   # => Integer  (Any is the identity of &)
+Types::Integer & Types::Never     # => Types::Never  (Never absorbs &)
+Types::Integer | Types::Never     # => Integer       (Never is dropped from |)
+
+Types::Never.resolve(42).valid?   # => false  (nothing is a Never)
+Types::Never.to_json_schema       # => { "not" => {} }
+```
+
+You rarely write `Types::Never` by hand — it's what an impossible intersection reduces to, which lets the composition algebra prove and discard dead branches (as in `Integer | (String & Integer)` above). It's also useful as a Hash catch-all to forbid undeclared keys — see [`_: Types::Never`](#undeclared-keys-and-the-_-catch-all).
+
 ### Built-in types
 
 * `Types::Value`
@@ -232,6 +321,7 @@ You can see more use cases in [the examples directory](https://github.com/ismasa
 * `Types::Numeric`
 * `Types::String`
 * `Types::Hash`
+* `Types::Range`
 * `Types::SymbolizedHash`
 * `Types::UUID::V4`
 * `Types::Email`
@@ -243,15 +333,8 @@ You can see more use cases in [the examples directory](https://github.com/ismasa
 * `Types::Lax::Integer`
 * `Types::Lax::String`
 * `Types::Lax::Symbol`
-* `Types::Forms::Boolean`
-* `Types::Forms::Nil`
-* `Types::Forms::True`
-* `Types::Forms::False`
-* `Types::Forms::Date`
-* `Types::Forms::Time`
-* `Types::Forms::URI::Generic`
-* `Types::Forms::URI::HTTP`
-* `Types::Forms::URI::File`
+
+For parsing stringy formats (HTML forms, query strings) into these types — what the `Types::Forms` namespace used to do, one way — see `Plumb::Codec::Forms` under [Encoders and Codecs](#encoders-and-codecs).
 
 TODO: datetime, others.
 
@@ -351,6 +434,14 @@ The helper accepts multiple attribute/value pairs
 JoeBloggs = Types::Any[User].where(first_name: 'Joe', last_name: 'Bloggs')
 ```
 
+Attribute constraints take part in [composition type-checks](#composition-type-checks): a constrained type is a subtype of its base, and a constraint on the same attribute is a subtype when its value is contained in the other's (compared like ranges/literals).
+
+```ruby
+Types::Array.where(size: 10) >> Types::Array                     # ok: constrained Array is still an Array
+Types::Array.where(size: 10) >> Types::Array.where(size: 8..100) # ok: 10 is within 8..100
+Types::Array.where(size: 10..15) >> Types::Array.where(size: 11..14) # raises: 10..15 isn't within 11..14
+```
+
 #### `#transform`
 
 Transform value. Requires specifying the resulting type of the value after transformation.
@@ -363,9 +454,27 @@ StringToInt = Types::String.transform(Integer, &:to_i)
 StringToInteger.parse('10') # => 10
 ```
 
+As a shorthand, `#transform` also accepts a single Ruby conversion symbol — `:to_s`, `:to_sym`, `:to_i`, `:to_f`, `:to_r`, `:to_c`, `:to_a`, `:to_h`, `:to_proc` — and infers the output type from it:
+
+```ruby
+Types::String.transform(:to_i)  # transform to Integer, via #to_i
+Types::Integer.transform(:to_s) # transform to String
+# equivalent to
+Types::String.transform(Integer, &:to_i)
+```
+
+When the input's base Ruby type is known, it validates that the type actually responds to the method, so mistakes fail at build time:
+
+```ruby
+Types::Integer.transform(:to_sym) # raises Plumb::TypeError (Integer has no #to_sym)
+Types::Any.transform(:to_i)       # ok — unknown input type, no check
+```
+
+`#transform` builds a [`Plumb::Function`](#plumbfunctioninput--output) — the underlying typed-conversion node — with a block that takes and returns a plain value. To build one standalone from a callable, or to work at the `Result` level, use `Plumb::Function[]` directly.
+
 #### `#invoke`
 
-`#invoke` builds a Step that will invoke one or more methods on the value.
+`#invoke` builds a step that will invoke one or more methods on the value.
 
 ```ruby
 StringToInt = Types::String.invoke(:to_i)
@@ -389,7 +498,7 @@ UpcaseToSym = Types::String.invoke(%i[downcase to_sym])
 UpcaseToSym.parse('FOO_BAR') # :foo_bar
 ```
 
-Note, as opposed to `#transform`, this helper does not register a type in `#metadata[:type]`, which can be valuable for introspection or documentation (ex. JSON Schema).
+Note, as opposed to `#transform`, this helper does not declare a resulting output type (`#output_type`), which can be valuable for introspection or documentation (ex. JSON Schema).
 
 Also, there's no definition-time checks that the method names are actually supported by the input values.
 
@@ -504,7 +613,6 @@ ten.parse(10) # => 10
 ten.parse(100) # => 10
 ten.parse('hello') # => 10
 ten.parse() # => 10
-ten.metadata[:type] # => Integer
 ```
 
 Useful for data structures where some fields shouldn't change. Example:
@@ -517,12 +625,6 @@ CreateUserEvent = Types::Hash[
 ]
 ```
 
-Note that the value must be of the same type as the starting step's target type.
-
-```ruby
-Types::Integer.static('nope') # raises ArgumentError
-```
-
 This usage is similar as using `Types::Static['hello']`directly.
 
 This helper is shorthand for the following composition:
@@ -531,11 +633,11 @@ This helper is shorthand for the following composition:
 Types::Static[value] >> step
 ```
 
-This means that validations and coercions in the original step are still applied to the static value.
+Because the static value flows through the original step's type, an inconsistent value is caught at build time by the [composition check](#composition-type-checks):
 
 ```ruby
-ten = Types::Integer[100..].static(10)
-ten.parse # => Plumb::ParseError "Must be within 100..."
+Types::Integer[100..].static(10) # raises Plumb::TypeError (10 is not within 100..)
+type = Types::Integer[100..].static(150) # ok
 ```
 
 So, normally you'd only use this attached to primitive types without further processing (but your use case may vary).
@@ -573,21 +675,109 @@ type.metadata[:description] # 'A long text'
 `#metadata` combines keys from type compositions.
 
 ```ruby
-type = Types::String.metadata(description: 'A long text') >> Types::String.match(/@/).metadata(note: 'An email address')
+type = Types::String[/@/].metadata(note: 'An email address') >> Types::String.metadata(description: 'A long text')
 type.metadata[:description] # 'A long text'
 type.metadata[:note] # 'An email address'
 ```
 
-`#metadata` also computes the target type.
+`#metadata` only carries user-provided annotations. The Ruby type(s) a composition accepts and produces are described by `#input_type` and `#output_type` instead (see below).
+
+TODO: document custom visitors.
+
+#### `#input_type` and `#output_type`
+
+Every type exposes the type it expects as input and the type it produces as output.
+
+```ruby
+StringToInt = Types::String.transform(Integer, &:to_i)
+StringToInt.input_type  # Types::String
+StringToInt.output_type # Integer
+```
+
+They resolve through a composition, reporting what the chain as a whole consumes and produces — not its individual steps. The steps themselves remain available as `#children`:
 
 ```ruby
-Types::String.metadata[:type] # String
-Types::String.transform(Integer, &:to_i).metadata[:type] # Integer
-# Multiple target types for unions
-(Types::String | Types::Integer).metadata[:type] # [String, Integer]
+chain = Types::String.transform(Integer, &:to_i) >> Types::Integer.transform(Integer) { |i| i * 2 }
+chain.input_type  # Types::String — the chain can only be called with a String
+chain.output_type # Integer       — it can only produce an Integer
+chain.children    # [(Types::String -> Integer), (Types::Integer -> Integer)]
 ```
 
-TODO: document custom visitors.
+For a plain type, both are the type itself. Unions distribute over both sides:
+
+```ruby
+(Types::String | Types::Integer).input_type  # Types::String | Types::Integer
+(Types::String | Types::Integer).output_type # Types::String | Types::Integer
+```
+
+These power type introspection — for example, the JSON Schema visitor builds its schema from `#input_type`, since a schema describes the values a caller must send.
+
+#### Composition type-checks
+
+`#>>` is typed by **subsumption**, like function composition in a statically-typed language: everything the left step *produces* must be acceptable to the right step — i.e. the left's output type must be a **subtype** of the right's input type. If not, `#>>` raises `Plumb::TypeError` at build time, so broken data pipelines fail loudly when you define them, not silently at runtime.
+
+```ruby
+Types::String  >> Types::Integer           # raises: String is not a subtype of Integer
+Types::Numeric >> Types::Integer           # raises: Numeric is broader than Integer
+Types::Integer[0..40] >> Types::Integer[2..10]   # raises: the left can emit values (0,1,11..40) the right rejects
+
+Types::Integer >> Types::Numeric           # ok: every Integer is a Numeric
+Types::Integer[2..10] >> Types::Integer[0..40]   # ok: 2..10 is within 0..40
+```
+
+To **narrow** a value — where only some of what the left produces should pass — use `#[]` (or `#transform(...)[...]`). A refinement is a runtime-checked cast, built directly, and is *not* subject to the composition check:
+
+```ruby
+Types::Integer[0..40][2..10]                       # narrow to 2..10 (runtime-checked)
+Types::String.transform(Integer, &:to_i)[1..10]    # convert, then bound the result
+```
+
+For an arbitrary composition the checker can't prove — not just a matcher constraint — reach for `#/`, the unchecked counterpart of `#>>`. It builds the same refinement and is still validated at runtime, but skips the build-time check; you're asserting the chain is sound. It reads like `Pathname#/` ("join the next segment"):
+
+```ruby
+Types::Integer / Types::Integer[2..10]   # narrow without the build-time check
+Types::String / Types::String[/@/]       # a String you assert is an email downstream
+```
+
+The check is permissive only where types are genuinely unknown: opaque steps (plain procs/lambdas, `#invoke`, `#generate`) and value-level transforms (`#transform`/`#build`) report `Any` on the relevant side and opt out. (`#static` ignores its input, so it never blocks a chain feeding *into* it, but it does declare the value it produces — so `Types::Static['foo'] >> Types::Integer` is flagged.)
+
+For `Types::Hash` schemas, subsumption is record subtyping — the producer must provide every key the consumer requires (as a required key, with a subtype value); it may add extra keys:
+
+```ruby
+# the consumer requires :age, but the producer never provides it:
+Types::Hash[name: Types::String] >> Types::Hash[name: Types::String, age: Types::Integer]
+# => Plumb::TypeError
+
+# a shared key whose value type isn't a subtype:
+Types::Hash[name: Types::String] >> Types::Hash[name: Types::Integer]
+# => Plumb::TypeError
+
+# ok — producer is a subtype of consumer (wider, with subtype values):
+Types::Hash[name: Types::Integer, age: Types::Integer] >> Types::Hash[name: Types::Numeric]
+```
+
+[`#where`](#where) attribute constraints subtype the same way — a constrained type is a subtype of its base, and a constraint is a subtype of a looser one on the same attribute:
+
+```ruby
+Types::Array.where(size: 10) >> Types::Array.where(size: 8..100)     # ok: 10 is within 8..100
+Types::Array.where(size: 10..15) >> Types::Array.where(size: 11..14) # raises: 10..15 isn't within 11..14
+```
+
+#### Subtype checks: `#<=` and `Plumb::Subtyping`
+
+The relation behind the composition check is also available directly. `a <= b` asks "is every value described by `a` also described by `b`?" — i.e. is `a` a subtype/subset of `b`? — with `>=`, `<` and `>` derived from it. `Plumb::Subtyping.subtype?(a, b)` is the same check as a method. Built-in and custom types both participate, and raw Ruby classes/values are accepted on either side (they're normalized):
+
+```ruby
+Types::Integer <= Types::Numeric                # true
+Types::Numeric <= Types::Integer                # false
+Types::String[/@/] <= Types::String             # true (more refined => a subset)
+Types::Integer <= Numeric                       # true (compares against a raw Ruby class)
+Types::Array[Integer] <= Types::Array[Numeric]  # true (covariant in the element type)
+
+big   = Types::Hash[name: Types::String, age: Types::Integer]
+small = Types::Hash[name: Types::String]
+big <= small                                    # true (width + depth subtyping)
+```
 
 ### Other policies
 
@@ -630,7 +820,7 @@ Wraps a step's execution, rescues a specific exception and returns an invalid re
 
 Useful for turning a 3rd party library's exception into an invalid result that plays well with Plumb's type compositions.
 
-Example: this is how `Types::Forms::Date` uses the `:rescue` policy to parse strings with `Date.parse` and turn `Date::Error` exceptions into Plumb errors.
+Example: parsing strings with `Date.parse` and turning `Date::Error` exceptions into Plumb errors.
 
 ```ruby
 # Accept a string that can be parsed into a Date
@@ -810,10 +1000,27 @@ StaffMember = User + Employee # Hash[:name, :age, :company]
 
 #### Hash intersections
 
-Use `Types::Hash#&` to produce a new Hash definition with keys present in both.
+Use `Types::Hash#&` to intersect two hash definitions as maps. It keeps the keys present in **both**, and intersects each shared key's value type:
 
 ```ruby
-intersection = User & Employee # Hash[:name]
+User & Employee # => Hash[name: String]  (only the shared :name survives)
+
+# shared keys have their value types intersected
+Types::Hash[age: Types::Integer[18..]] & Types::Hash[age: Types::Integer[..65]]
+# => Hash[age: Integer[18..65]]
+```
+
+Two closed schemas that share no keys have nothing in common, so the intersection is `Types::Never` — the empty/bottom type, which no value satisfies:
+
+```ruby
+Types::Hash[a: Types::Integer] & Types::Hash[b: Types::String] # => Types::Never
+```
+
+A [`_` catch-all](#undeclared-keys-and-the-_-catch-all) widens what survives, since it admits the other side's extra keys:
+
+```ruby
+Types::Hash[a: Types::String, _: Types::Any] & Types::Hash[a: Types::String, b: Types::Integer]
+# => Hash[a: String, b: Integer]  (:b admitted via the left's catch-all)
 ```
 
 #### `Types::Hash#tagged_by`
@@ -833,18 +1040,41 @@ Events = Types::Hash.tagged_by(
 Events.parse(type: 'name_updated', name: 'Joe') # Uses NameUpdatedEvent definition
 ```
 
-#### `Types::Hash#inclusive`
+#### Undeclared keys and the `_` catch-all
 
-Use `#inclusive` to preserve input keys not defined in the hash schema.
+By default, keys present in the input but **not** declared in the schema are dropped:
 
 ```ruby
-hash = Types::Hash[age: Types::Lax::Integer].inclusive
+Types::Hash[age: Types::Integer].parse(age: 30, name: 'Joe') # => { age: 30 }  (:name dropped)
+```
+
+To control what happens to those undeclared keys, add a special `_` key. It is a **catch-all**: its value type is applied to every key not otherwise declared. The value type you give it decides the behaviour:
+
+| Catch-all | Meaning | Undeclared key `name`… |
+| --- | --- | --- |
+| _(none)_ | drop (default) | is removed |
+| `_: Types::Any` | include, unchanged | is kept as-is |
+| `_: SomeType` | include, validated/coerced | must be a `SomeType` (coerced if the type coerces) |
+| `_: Types::Never` | exclude (strict) | is a validation **error** |
+
+```ruby
+# _: Any — keep every undeclared key, unchanged
+hash = Types::Hash[age: Types::Lax::Integer, _: Types::Any]
+hash.parse(age: '30', name: 'Joe', last_name: 'Bloggs')
+# => { age: 30, name: 'Joe', last_name: 'Bloggs' }
+
+# _: SomeType — every undeclared value must be (or coerce to) that type
+Types::Hash[id: Types::String, _: Types::Integer].parse(id: 'x', a: 1, b: 2)
+# => { id: 'x', a: 1, b: 2 }
+Types::Hash[id: Types::String, _: Types::Integer].resolve(id: 'x', a: 'nope').valid? # => false
 
-# Only :age, is coerced and validated, all other keys are preserved as-is
-hash.parse(age: '30', name: 'Joe', last_name: 'Bloggs') # { age: 30, name: 'Joe', last_name: 'Bloggs' }
+# _: Never — reject any undeclared key (a closed/strict hash)
+strict = Types::Hash[a: Types::String, _: Types::Never]
+strict.resolve(a: 'x').valid?          # => true
+strict.resolve(a: 'x', b: 1).valid?    # => false  (b is not allowed)
 ```
 
-This can be useful if you only care about validating some fields, or to assemble different front and back hashes. For example a client-facing one that validates JSON or form data, and a backend one that runs further coercions or domain validations on some keys.
+`_: Any` is useful when you only care about validating some fields, or to assemble different front and back hashes — for example a client-facing one that validates JSON or form data, and a backend one that runs further coercions on some keys while passing the rest through:
 
 ```ruby
 # Front-end definition does structural validation
@@ -854,15 +1084,29 @@ Front = Types::Hash[price: Integer, name: String, category: String]
 IntToMoney = Types::Integer.build(Money)
 
 # Backend definition turns :price into a Money object, leaves other keys as-is
-Back = Types::Hash[price: IntToMoney].inclusive
+Back = Types::Hash[price: IntToMoney, _: Types::Any]
 
 # Compose the pipeline
 InputHandler = Front >> Back
 
 InputHandler.parse(price: 100_000, name: 'iPhone 15', category: 'smartphones')
-# => { price: #<Money fractional:100000 currency:GBP>, name: 'iPhone 15', category: 'smartphone' }
+# => { price: #<Money fractional:100000 currency:GBP>, name: 'iPhone 15', category: 'smartphones' }
 ```
 
+The catch-all also shows up in generated JSON Schema as `additionalProperties`: `_: Any` → `{}` (anything), `_: Integer` → `{ "type": "integer" }`, and `_: Never` → `{ "not": {} }` (nothing allowed).
+
+#### Typed keys
+
+Keys are not limited to symbols. A key can be any type or matcher, and it matches an input key via `key === other`. So you can key by String, or by a pattern, and mix them with a catch-all:
+
+```ruby
+Types::Hash['name' => Types::String]                 # a String key
+Types::Hash[Types::String[/^id_/] => Types::Integer, # keys matching /^id_/ hold Integers
+            _: Types::Any]                           # everything else passes through
+```
+
+A typed key is **lenient**: input keys that don't match any declared or typed key follow the catch-all rule above (dropped by default). This is different from a homogeneous map (`Types::Hash[Types::Symbol, Types::Integer]`, a `HashMap` — note the comma, not `=>`), which is **strict** (a non-conforming key is an error) and coerces keys through the key type. Use a `HashMap` for "every key/value has this type"; use typed keys for "keys shaped like this map to that".
+
 #### `Types::Hash#filtered`
 
 The `#filtered` modifier returns a valid Hash with the subset of values that were valid, instead of failing the entire result if one or more values are invalid.
@@ -873,17 +1117,97 @@ User.parse(name: 'Joe', age: 40) # => { name: 'Joe', age: 40 }
 User.parse(name: 'Joe', age: 'nope') # => { name: 'Joe' }
 ```
 
+### `Types::Range`
+
+`Types::Range` validates that a value is a Ruby `Range`. On its own it accepts any range:
+
+```ruby
+Types::Range.resolve(1..10)     # valid
+Types::Range.resolve('a'..'z')  # valid
+Types::Range.resolve(5)         # invalid ("must be a Range")
+```
+
+Specialize it with `#[]` to constrain the range's endpoints. The member type is matched against both the range's `#begin` and `#end` (a `nil` bound — an open-ended range — is skipped):
+
+```ruby
+IntRange = Types::Range[Integer]
+IntRange.resolve(1..10)     # valid
+IntRange.resolve('a'..'z')  # invalid (endpoints aren't Integers)
+IntRange.resolve(1..)       # valid (only the present bound is checked)
+```
+
+The member type is any `#===` interface, so a `Range` itself works as the member matcher to bound where the endpoints may fall:
+
+```ruby
+# A range whose endpoints both lie within 1..100
+Percent = Types::Range[1..100]
+Percent.resolve(10..20)   # valid
+Percent.resolve(10..200)  # invalid (200 is outside 1..100)
+```
+
+#### Open-ended ranges with `#where`
+
+Use `#where` with the `begin`/`end` attributes to constrain the range's own endpoints. Passing `end: nil` matches only endless ranges, and `begin: nil` only beginless ranges:
+
+```ruby
+# Endless ranges only, eg. (1..)
+Endless = Types::Range[Integer].where(end: nil)
+Endless.resolve(1..)    # valid
+Endless.resolve(1..10)  # invalid ("must have attribute end === nil")
+
+# Beginless ranges only, eg. (..10)
+Beginless = Types::Range[Integer].where(begin: nil)
+Beginless.resolve(..10)   # valid
+Beginless.resolve(1..10)  # invalid
+```
+
+`#where` values are also full `#===` matchers, so an endpoint can be constrained by a type or another range:
+
+```ruby
+# A range that starts at zero or above
+NonNegativeStart = Types::Range.where(begin: Types::Integer[0..])
+NonNegativeStart.resolve(5..10)   # valid
+NonNegativeStart.resolve(-5..10)  # invalid
+```
+
+#### Composition
+
+`Types::Range` is covariant in its member type and preserves its input value (it validates endpoints without coercing them), so it composes like the other containers. A union absorbs a narrower member into a wider one:
+
+```ruby
+Types::Range[1..10] <= Types::Range[Integer]  # true (covariant)
+
+# The narrower branch is absorbed
+Types::Range[Integer] | Types::Range[1..10]   # => Range[Integer]
+```
+
+#### JSON Schema
+
+A `Types::Range` whose member pins numeric bounds maps to JSON Schema's native keywords, preserving an exclusive end as `exclusiveMaximum`:
+
+```ruby
+Plumb::JSONSchemaVisitor.call(Types::Range[0...100], root: false)
+# => { "type" => "integer", "minimum" => 0, "exclusiveMaximum" => 100 }
+```
+
 ### `Types::SymbolizedHash`
 
 This type turns a hash's keys into symbols by calling `#to_sym` on them, and returning a new Hash.
 
+`SymbolizedHash` is a `Symbol => Any` map. You can use it as a _transform_.
+
 ```ruby
-# Make sure to symbolize keys first
-type = Types::SymbolizedHash > Types::Hash[name: String, age: Integer]
-type.parse('name' => 'Joe', 'age' => 20) # {name: 'Joe', age: 20}
+UserHash = Types::Hash[name: String]
+Types::SymbolizedHash.transform(UserHash).parse('name' => 'Joe') # { name: 'Joe' }
 ```
 
+You can also use the shortcut `#symbolized`
 
+```ruby
+# Symbolize keys, then coerce into a typed Hash.
+type = Types::Hash[name: String, age: Integer].symbolized
+type.parse('name' => 'Joe', 'age' => 20) # {name: 'Joe', age: 20}
+```
 
 ###  maps
 
@@ -947,6 +1271,47 @@ emails = Types::Array[Types::String[/@/]]
 
 Prefer the latter (`Types::Array[Types::String[/@/]]`), as that first validates that each element is a `String` before matching against the regular expression.
 
+#### Chained array maps fuse into a single pass
+
+`Types::Array` is covariant in its element type, so mapping `f` over an array and then mapping `g` is the same as mapping `f >> g` once. Composing two arrays applies that, and the collection is traversed once instead of twice:
+
+```ruby
+Trim      = Types::String.transform(::String, &:strip)
+Downcase  = Types::String.transform(::String, &:downcase)
+Symbolize = Types::String.transform(::Symbol, &:to_sym)
+
+# Written as three separate maps over the collection...
+Tags = Types::Array[Trim] >> Types::Array[Downcase] >> Types::Array[Symbolize]
+
+# ...built as one.
+Tags.class   # => Plumb::ArrayClass
+Tags.inspect # => "Array[(Types::String -> Symbol)]"
+Tags == Types::Array[Trim >> Downcase >> Symbolize] # => true
+
+Tags.parse(['  RUBY ', ' Plumb', 'CSV  ']) # => [:ruby, :plumb, :csv]
+```
+
+This is worth knowing when the element steps are defined apart from one another and only meet at a boundary — you get the single-pass version without hand-fusing it. On a 200-element array the three-stage chain above goes from 154.6µs to 102.2µs per value, and the two intermediate arrays are never built.
+
+Validation is unaffected. The JSON Schema still describes the input side, and errors are still keyed by element index:
+
+```ruby
+Tags.to_json_schema                       # => {"type" => "array", "items" => {"type" => "string"}}
+Tags.resolve(['ok', 42, ' fine ']).errors # => {1 => "Must be a String"}
+```
+
+`Types::Tuple`, the `Types::Hash[K, V]` map form and `Types::Stream` fuse the same way. Fusion needs the element boundary to be provable — what the left element produces must be accepted by the right — so anything the checker can't prove is left as two passes:
+
+```ruby
+# Narrowing isn't provable, so this stays two passes (and `#>>` would reject it outright).
+Types::Array[Trim] / Types::Array[Types::String[/^a/]]
+
+# Different containers, so no functor law to apply.
+Types::Array[Trim] / Types::Stream[Symbolize]
+```
+
+That guard is what keeps errors identical: two passes report stage by stage, so if the right map could reject what the left produced, one pass could surface errors two passes never reach. Records (`Types::Hash[name: ...]`) don't fuse either, since a record can drop, add and make keys optional.
+
 #### Concurrent arrays
 
 Use `Types::Array#concurrent` to process array elements concurrently (using Concurrent Ruby for now).
@@ -1323,7 +1688,7 @@ class DBConfig < Types::Data
 end
 
 class Config < Types::Data
-  attribute :host, Types::Forms::URI::HTTP, writer: true
+  attribute :host, Plumb::Codec::HTTPURIEncoder, writer: true
   attribute :port, Types::Integer.default(80), writer: true
 
   # Nested structs can have writers too
@@ -1388,6 +1753,30 @@ result = CreateUser.resolve(name: 'Joe', age: 40)
 # result.value => User
 ```
 
+##### `#step` (non-strict) and `#step!` (strict)
+
+A pipeline is a sequence of validators/coercions that progressively narrows its data, so **`#step` is non-strict**: it chains with [`#/`](#composition-type-checks), skipping the composition check (a later step may legitimately narrow what an earlier one produced). Use **`#step!`** for the strict [`#>>` check](#composition-type-checks) — a build-time `Plumb::TypeError` if a step could never accept the previous step's output.
+
+```ruby
+pl.step  Types::Hash                      # non-strict: a later step may narrow this
+pl.step! Types::Hash[name: Types::String] # strict: raises if it can't accept the prior output
+```
+
+To add a step that **transforms** the value into a new type, pass the output type followed by a block. This builds a [`#transform`](#transform) — a trusted, declared conversion — and the rest of the pipeline chains from the new type:
+
+```ruby
+User = Data.define(:name)
+
+pipeline = Types::Any.pipeline do |pl|
+  pl.step Types::Hash[name: Types::String]
+  # output type + a block that produces it (the block takes and returns a Result)
+  pl.step(User) { |result| result.valid(User.new(result.value[:name])) }
+end
+
+pipeline.output_type == Plumb::Composable.wrap(User) # true
+pipeline.parse(name: 'Joe') # => #<data User name="Joe">
+```
+
 Pipelines are Plumb steps, so they can be composed further.
 
 ```ruby
@@ -1513,10 +1902,6 @@ Pipe2 = DebuggablePipeline.new do |pl|
 end
 ```
 
-### Plumb::Schema
-
-TODO
-
 ### Recursive types
 
 You can use a proc to defer evaluation of recursive definitions.
@@ -1550,6 +1935,169 @@ LinkedList = Types::Hash[
 
 
 
+### Encoders and Codecs
+
+A one-way coercion can parse an external representation (a date string) into a parsed value (a `Date`), but not back. **Encoders** generalize that into pluggable, two-way serialization, and **Codecs** group encoders and apply them to whole schemas — Ruby data structures to JSON-ready structures and back, for example.
+
+#### Defining encoders
+
+An encoder is a class declaring an input and an output type, with `#decode` (input ⇒ output) and `#encode` (output ⇒ input) methods:
+
+```ruby
+DateRange = Types::Range[Types::Date]
+JSONDateRange = Types::Hash[from: Types::Date, to: Types::Date]
+
+class JSONDateRangeEncoder < Plumb::Encoder[JSONDateRange => DateRange]
+  def encode(range) = { from: range.begin, to: range.end }
+  def decode(hash) = hash[:from]..hash[:to]
+end
+```
+
+By default an encoder behaves exactly like a transform in its declared direction (`JSONDateRange -> DateRange`, running `#decode`). But it is reversible: composed next to a type that matches its *output* side, it transparently runs the inverse.
+
+```ruby
+# Decode: the declared direction.
+FromJSON = JSONDateRange >> JSONDateRangeEncoder >> DateRange
+FromJSON.parse({ from: Date.new(2024, 1, 1), to: Date.new(2024, 2, 1) }) # => Date..Date range
+
+# Encode: inferred from the DateRange on the left.
+ToJSON = DateRange >> JSONDateRangeEncoder >> JSONDateRange
+ToJSON.parse(Date.new(2024, 1, 1)..Date.new(2024, 2, 1)) # => { from: ..., to: ... }
+```
+
+Each direction is a normal Plumb step: it validates its input type, runs your method, and validates the produced value against its output type (a wrong return value is an invalid `Result`, and an exception raised inside `#encode`/`#decode` becomes an invalid `Result` too). Composition is type-checked as usual — `Types::Symbol >> JSONDateRangeEncoder` raises `Plumb::TypeError`.
+
+Where the context gives no signal — schema literals (`Types::Hash[dates: SomeEncoder]`), `#/`, `.parse`, or an `Any`/opaque neighbour — the declared direction is used. `.decoding` (the declared direction) and `.encoding` (the inverse, input/output swapped) are the explicit forms:
+
+```ruby
+JSONDateRangeEncoder.decoding # JSONDateRange -> DateRange, runs #decode
+JSONDateRangeEncoder.encoding # DateRange -> JSONDateRange, runs #encode
+
+JSONDateRangeEncoder.decode(from: Date.new(2024, 1, 1), to: Date.new(2024, 2, 1)) # => a Range
+JSONDateRangeEncoder.encode(Date.new(2024, 1, 1)..Date.new(2024, 2, 1))           # => a Hash
+```
+
+Encoders also express lenient unions — `Types::Date | SomeDateEncoder` accepts a `Date` or decodes a string into one.
+
+#### Codecs
+
+A codec groups encoders and applies them to whole types at composition time. Codecs know nothing about any particular format — only their encoders. Types that are already valid in the target format are declared with `.noop`:
+
+```ruby
+# Plumb::Codec::JSON ships noops for String, Numeric, booleans, Nil and bare
+# Hash/Array, plus built-in string encoders for Dates, Times, URIs,
+# Symbols and Decimals.
+class JSONCodec < Plumb::Codec::JSON
+  encoder JSONDateRangeEncoder
+end
+```
+
+(A subclass encoder registered for an equivalent type — eg. your own Date encoder — takes precedence over an inherited built-in.)
+
+Composing a codec with a type rewrites the type deeply, in either direction:
+
+```ruby
+Person = Types::Hash[name: Types::String, dates: DateRange]
+
+JSONPerson = JSONCodec >> Person # decode: JSON structures -> Person
+JSONPerson.parse({ name: 'Joe', dates: { from: '2024-01-01', to: '2024-02-01' } })
+# => { name: 'Joe', dates: Date(2024-01-01)..Date(2024-02-01) }
+
+EncodedPerson = Person >> JSONCodec # encode: Person -> JSON structures
+EncodedPerson.parse({ name: 'Joe', dates: Date.new(2024, 1, 1)..Date.new(2024, 2, 1) })
+# => { name: 'Joe', dates: { from: '2024-01-01', to: '2024-02-01' } }
+```
+
+`Codec.for(type)` returns both directions as a `[decoding, encoding]` pair:
+
+```ruby
+decoder, encoder = JSONCodec.for(Person)
+decoder.parse(json_data)   # => a Person hash
+encoder.parse(person_hash) # => JSON structures
+```
+
+Note how the `Date` values *inside* `JSONDateRange` were resolved too: an encoder's input type is itself rewritten through the same codec, so nested non-native values are handled by other encoders in the group (here, the built-in `Date` encoder). The rewrite recurses into nested hashes, arrays, tuples, hash maps, union branches, metadata/policy wrappers and `.defer`red recursive types. Matching is by subtyping against each encoder's output type, most-specific encoder first.
+
+Codecs work with any type, not just schemas:
+
+```ruby
+(JSONCodec >> Types::Date).parse('2024-01-01') # => Date
+(Types::Date >> JSONCodec).parse(Date.new(2024, 1, 1)) # => '2024-01-01'
+JSONCodec >> Types::String # => Types::String, unchanged (noop)
+```
+
+Struct classes (`Types::Data` subclasses, or any class that `include`s `Plumb::Attributes`) work too, at any depth — decoding builds instances, encoding takes them apart:
+
+```ruby
+class Company < Types::Data
+  attribute :name, Types::String
+  attribute :founded, Types::Date
+end
+
+decoder, encoder = JSONCodec.for(Company)
+company = decoder.parse({ name: 'ACME', founded: '2024-01-01' }) # => #<Company founded: Date>
+encoder.parse(company) # => { name: 'ACME', founded: '2024-01-01' }
+```
+
+A field whose type is a **converting step** — a `#transform`/`#build` Function, a [`Plumb::Implementation`](#include-plumbimplementationinput--output-to-declare-a-class-types), a struct class — is decoded by rewriting what it *accepts* and putting that in front of it, so the step is fed the decoded value. A `Types::Data` class is one such node (`Hash[…] -> Person`); so is a hand-written equivalent, and both are handled the same way:
+
+```ruby
+class ParseRecord
+  extend Plumb::Implementation[Types::Hash[on: Types::Date] => Record]
+
+  def self._call(result) = result.valid(Record.new(result.value[:on]))
+end
+
+(JSONCodec >> ParseRecord).parse({ on: '2024-01-01' }) # => #<Record on: Date>
+```
+
+Its accepted `Date` is decoded from a string first; the step itself is preserved and still validates what it is handed. A step whose accepted type is already native is left untouched; one whose accepted type the codec can't decode raises, naming the step.
+
+A field that matches no encoder and no noop is a composition-time error naming the field path:
+
+```ruby
+JSONCodec >> Types::Hash[profile: Types::Hash[joined: Types::Any[Time]]]
+# raises Plumb::TypeError: ... field `profile.joined` (Any[Time]) matches no encoder ...
+```
+
+The result of a codec composition is ordinary Plumb algebra — the codec leaves no runtime node behind — so JSON Schema generation works, describing the input side of a decoded schema:
+
+```ruby
+JSONPerson.to_json_schema
+# "dates" is described as { "type" => "object", "properties" => { "from" => { "type" => "string" }, ... } }
+```
+
+#### `Codec::Forms`: string-based formats
+
+The second built-in codec targets HTML forms, query strings and other formats where **every value arrives as a string**. Unlike `Codec::JSON` there are almost no native scalars: strings pass through, untyped containers recurse (Rack-style nested params), and everything else maps through an encoder with a strictly-patterned string input type — integers (`/\A-?\d+\z/`), floats, decimals, booleans (`"true"/"1"`, `"false"/"0"`, case-insensitive), ISO 8601 dates and times, scheme-prefixed URIs, and the empty string for `nil` (so `Types::Date | Types::Nil` decodes `''` to `nil`).
+
+```ruby
+Config = Types::Hash[
+  host: Types::URI::HTTP,
+  port: Types::Integer,
+  active: Types::Boolean,
+  starts_on: Types::Date | Types::Nil
+]
+
+decoder, encoder = Plumb::Codec::Forms.for(Config)
+decoder.parse({ host: 'http://example.com', port: '80', active: '1', starts_on: '' })
+# => { host: URI(...), port: 80, active: true, starts_on: nil }
+encoder.parse({ host: URI.parse('http://example.com'), port: 80, active: true, starts_on: nil })
+# => { host: 'http://example.com', port: '80', active: 'true', starts_on: '' }
+```
+
+`Codec::Forms` replaces the old one-way `Types::Forms` namespace. The input types are strict — actual integers or booleans are *not* accepted on decode, since form data is always strings; apply the codec at the boundary and write schemas in output types.
+
+Format-neutral encoders live at the `Plumb::Codec` level and are registered by both built-in codecs: ISO 8601 `Codec::DateEncoder`/`Codec::TimeEncoder`, RFC 3986 `Codec::URIEncoder`/`HTTPURIEncoder`/`FileURIEncoder`, `Codec::SymbolEncoder` (Symbols travel as strings) and `Codec::DecimalEncoder` (BigDecimals travel as canonical decimal strings — a string, not a number, to keep their precision; this also applies under `Codec::JSON`, where a raw BigDecimal would not be JSON-native). They are also usable per-field (`attribute :host, Plumb::Codec::HTTPURIEncoder`), and the old lenient behaviour is expressible as a union: `Types::Date | Plumb::Codec::DateEncoder`.
+
+Things to know:
+
+* Direction inference needs a typed neighbour. Opaque contexts fall back to the declared direction — use `.decoding`/`.encoding` to be explicit.
+* The JSON Schema of an *encode* pipeline describes what it accepts (its output-typed values), per the library convention that schemas describe accepted inputs. Visit the decode direction for the input-format schema.
+* `.defer`red fields rewrite lazily, so an unmatched type inside one surfaces at first resolution rather than at composition.
+* Registering `noop Types::Hash` / `Types::Array` only covers *untyped* containers — structured schemas (and struct classes) are always recursed into, so a generic noop can't accidentally skip encoding of nested fields.
+* Decoding a struct runs the rewritten schema and then the struct's own validation — correct, but a struct attribute with a non-idempotent transform would apply it twice. Struct attributes should be validators/coercions, as they already must be for `#with`.
+
 ### Custom types
 
 Every Plumb type exposes the following one-method interface:
@@ -1564,25 +2112,62 @@ The `Result::Valid` class has helper methods `#valid(value) => Result::Valid` an
 
 #### Compose procs or lambdas directly
 
-Piping any `#call` object onto Plumb types will wrap your object in a `Plumb::Step` with all methods necessary for further composition.
+Piping any `#call` object onto Plumb types wraps your object in a composable step, with all methods necessary for further composition.
 
 ```ruby
 Greeting = Types::String >> ->(result) { result.valid("Hello #{result.value}") }
 ```
 
-#### Wrap a `#call` object in `Plumb::Step` explicitely
+#### `Plumb::Function[input => output]`
+
+To build a standalone, typed function from a callable — one not already piped onto a type — use `Plumb::Function[]`. Declaring both ends gives you a typed function: the input is validated before your callable runs, and the value it produces is validated against the output type.
+
+```ruby
+Greeting = Plumb::Function[String => String] do |result|
+  result.valid("Hello #{result.value}")
+end
+
+Greeting.parse('Joe') # => 'Hello Joe'
+Greeting.parse(10)    # raises Plumb::ParseError ("Must be a String")
+```
+
+The block takes and returns a [`Result`](#custom-types) — unlike [`#transform`](#transform), whose block takes and returns a plain value. A callable can be passed instead of a block:
+
+```ruby
+Greeting = Plumb::Function[MyGreeter.new, String => String]
+```
+
+Because both ends are declared, the resulting step takes part in [composition type checks](#composition-type-checks) and JSON Schema generation, just like `#transform`:
 
-You can also wrap a proc in `Plumb::Step` explicitly.
+```ruby
+StringLength = Plumb::Function[String => Integer] { |result| result.valid(result.value.size) }
+StringLength.input_type  # => String
+StringLength.output_type # => Integer
+
+Types::Integer >> StringLength # raises Plumb::TypeError at build time
+```
+
+You can also pass a custom `#call(Result) => Result` interface as the first argument, to turn a callable into a typed function.
 
 ```ruby
-Greeting = Plumb::Step.new do |result|
+TypedGreeting = Plumb::Function[Greeting.new('Mr.'), String => String]
+TypedGreeting.parse('Joe') # "Mr. Joe"
+TypedGreeting.parse(10) # raises Plumb::ParseError
+```
+
+
+
+Omit the types when the callable is genuinely untyped. Both ends default to `Types::Any`, and the step opts out of composition checks.
+
+```ruby
+Greeting = Plumb::Function[] do |result|
   result.valid("Hello #{result.value}")
 end
 ```
 
-Note that this example is not prefixed by `Types::String`, so it doesn't first validate that the input is indeed a string.
+Note that this last example doesn't validate that the input is indeed a String, whereas `Plumb::Function[String => String]` does.
 
-However, this means that `Greeting` is a `Plumb::Step` which comes with all the Plumb methods and policies.
+Either way, `Greeting` is a full Plumb step, which comes with all the Plumb methods and policies.
 
 ```ruby
 # Greeting responds to #>>, #|, #default, #transform, etc etc
@@ -1599,11 +2184,11 @@ class Greeting
     @gr = gr
   end
 
-  # The Plumb Step interface
+  # The Plumb step interface
   # @param result [Plumb::Result::Valid]
   # @return [Plumb::Result::Valid, Plumb::Result::Invalid]
   def call(result)
-    result.valid("#{gr} #{result.value}")
+    result.valid("#{@gr} #{result.value}")
   end
 end
 
@@ -1614,7 +2199,7 @@ This is useful when you want to parameterize your custom steps, for example by i
 
 #### Include `Plumb::Composable` to make instance of a class full "steps"
 
-The class above will be wrapped by `Plumb::Step` when piped into other steps, but it doesn't support Plumb methods on its own.
+The class above will be wrapped in a composable step when piped into other steps, but it doesn't support Plumb methods on its own.
 
 Including `Plumb::Composable` makes it support all Plumb methods directly.
 
@@ -1628,9 +2213,9 @@ class Greeting
     @gr = gr
   end
   
-  # The Step interface
+  # The step interface
   def call(result)
-    result.valid("#{gr} #{result.value}")
+    result.valid("#{@gr} #{result.value}")
   end
   
   # This is optional, but it allows you to control your object's #inspect
@@ -1650,15 +2235,149 @@ LoudGreeting = Greeting.new('Hola').default('no greeting').invoke(:upcase)
 class User
   extend Composable
   
-  def self.class(result)
+  def self.call(result)
     # do something here. Perhaps returning a Result with an instance of this class
-    return result.valid(new)
+    result.valid(new)
   end
 end
 ```
 
 This is how [Plumb::Types::Data](#typesdata) is implemented.
 
+#### Include `Plumb::Implementation[input => output]` to declare a class' types
+
+`Plumb::Composable` makes your instances composable, but Plumb knows nothing about what they accept or produce — they're opaque, so they opt out of [composition type-checks](#composition-type-checks) and subtype checks.
+
+`Plumb::Implementation[Input => Output]` is `Composable` plus a declared type pair. It makes your instances behave like a [`Plumb::Function`](#plumbfunctioninput--output): your class owns its `#initialize` and its state, and implements a private `#_call(Result) => Result`.
+
+The mixin owns the public `#call`, which runs the declared checks around your `#_call`:
+
+```
+result.map(input_type).map(_call).map(output_type)
+```
+
+ie. the input is validated (and coerced, if the input type converts) before `#_call` sees it, and what it returns is validated against the output type.
+
+```ruby
+class UserFinder
+  include Plumb::Implementation[Types::UUID::V4 => User]
+
+  def initialize(user_scope)
+    @user_scope = user_scope
+  end
+
+  private def _call(result)
+    user = User.where(level: @user_scope).find_by(id: result.value)
+    return result.invalid(errors: 'no user!') unless user
+
+    result.valid(user)
+  end
+end
+```
+
+Instances are now fully typed steps:
+
+```ruby
+finder = UserFinder.new('admin')
+
+finder.parse(some_uuid)      # => a User. Raises Plumb::ParseError unless the input is a UUID
+finder >> some_other_step    # composition, type-checked at build time
+Types::UUID::V4 >> finder    # ...on both sides
+Types::Integer >> finder     # => Plumb::TypeError: Integer is not a subtype of UUID::V4
+
+finder <= User               # => true. Like a Function, it is identified by what it PRODUCES
+finder.to_json_schema        # describes the INPUT side, like any other conversion
+
+Types::Hash[user: finder]    # use it anywhere a type is expected
+```
+
+Both sides are wrapped with `Plumb::Composable.wrap`, so raw Ruby classes and hash literals work too: `Plumb::Implementation[{id: Types::String} => User]`.
+
+Instances report `#node_name` `:function`, so every visitor, JSON Schema handler and policy that understands a conversion node understands yours. Define your own `#node_name` after the include if you have visitors of your own. Everything else is the [regular extension surface](#participating-in-subtype--composition-checks): override `#subtype_of?`, `#value_preserving?` etc. as needed.
+
+`include Plumb::Implementation` with no pair declares `Any => Any` — the opaque case, equivalent to `Plumb::Function.opaque`.
+
+Subclassing needs no ceremony: `#_call` is an ordinary method, so an override is found by normal lookup and the inherited `#call` keeps checking around it. `super` reaches the parent's `#_call` directly, with no repeated checks.
+
+```ruby
+class AdminFinder < UserFinder
+  # input already validated as a UUID; the User you return is still checked
+  private def _call(result) = result.valid(super.value.becomes(Admin))
+end
+```
+
+#### Extend `Plumb::Implementation[input => output]` to make the class itself a typed step
+
+Just as with [`Plumb::Composable`](#extend-a-class-with-plumbcomposable-to-make-the-class-itself-a-composable-step), `extend` instead of `include` puts the whole interface on the class: no instantiation, the class implements `self._call(result)` and answers `.input_type` / `.output_type`.
+
+```ruby
+class ParseUUID
+  extend Plumb::Implementation[Types::String => Types::UUID::V4]
+
+  def self._call(result) = result.valid(result.value.downcase)
+end
+
+ParseUUID.parse('E1D3...')            # the class IS the step
+ParseUUID >> UserFinder.new('admin')  # composes like any other type
+Types::Hash[id: ParseUUID]
+ParseUUID.to_json_schema
+```
+
+The two forms are alternatives — pick one per class. The extended form deliberately does **not** take over the class' own `#name`, `#inspect`, `#==` or `#<=` (on a class, `<=` means Ruby module ancestry), so ask for the subtype relation explicitly instead:
+
+```ruby
+Plumb::Subtyping.subtype?(ParseUUID, Types::String) # => true
+```
+
+#### Participating in subtype & composition checks
+
+The subtype (`#<=`) and [`#>>` composition](#composition-type-checks) checks are built on a single hook that every `Plumb::Composable` already implements with a sensible default — `#>>` is just `subtype?(produced, accepted)`, so there's nothing extra to implement for composition. A custom type participates **without changing any core library code**: it either relies on the default or overrides the hook. `Plumb::Subtyping` itself only knows the composition algebra (the top type `Types::Any`, the bottom type `Types::Never`, union `#|`, intersection `#&`, refinement/sequencing `#>>`, and conversion `#transform`); everything else is delegated to the type.
+
+The default leans on two methods your type already has:
+
+- `#children` — the sub-types this type is built from, as an array. A type whose single child is a **raw Ruby matcher** (a Class, Range, Regexp or literal — as `Plumb::Constraint` wraps) is treated as *atomic* and compared with Ruby semantics. A type whose children are themselves Plumb types (like `Array`, `Tuple`, `HashMap`) is treated as a **covariant container** — so exposing `#children` is all a custom container needs to compare covariantly.
+- `#==` — structural equality (provided by `Plumb::Composable`).
+
+##### The hook
+
+| Hook | Returns | Used by | Default |
+| --- | --- | --- | --- |
+| `#subtype_of?(other)` | `Boolean` | `#<=`, `Plumb::Subtyping.subtype?`, and so `#>>` | reflexive · atomic · same-class covariant `#children` |
+
+`#subtype_of?` answers "is every value I describe also described by `other`?". It's the leaf step of `subtype?`, reached after the algebra (`Any`/`Never`/`|`/`&`/`>>`/`#transform`) has been peeled away. Override it for bespoke behaviour — **recurse through `Plumb::Subtyping.subtype?`, never through `#<=`** (which would loop back into the algebra). `HashClass` overrides it for record (width + depth + optionality) subtyping.
+
+```ruby
+# An "even integer" refinement that knows it is a subtype of Integer (and
+# therefore Numeric), and defers everything else to the default.
+class EvenInteger
+  include Plumb::Composable
+
+  def call(result)
+    result.value.is_a?(::Integer) && result.value.even? ? result : result.invalid(errors: 'must be even')
+  end
+
+  def subtype_of?(other)
+    Plumb::Subtyping.subtype?(Types::Integer, other) || super
+  end
+
+  private def _inspect = 'EvenInteger'
+end
+
+even = EvenInteger.new
+even <= Types::Integer   # => true
+even <= Types::Numeric   # => true
+even <= Types::String    # => false
+```
+
+##### Type flow: `#input_type` / `#output_type`
+
+The `#>>` check (and the [JSON Schema visitor](#json-schema)) ask what a type accepts and produces; both [default to `self`](#input_type-and-output_type). Override them when your type changes the value or is opaque about it:
+
+- a value-converting step declares a different `#output_type` (what `#transform`/`#build` do via `Plumb::Function`);
+- an opaque step (a wrapped proc, a generator) returns `Types::Any` for both, opting out of the `#>>` compatibility check.
+
+Custom types are **values/leaves** in the algebra — you compose them with the built-in combinators (`#>>`, `#|`, `#transform`, `Types::Any`) rather than re-implementing those.
+
 ### Custom policies
 
 `Plumb.policy` can be used to encapsulate common type compositions, or compositions that can be configurable by parameters.
@@ -1709,7 +2428,7 @@ end
 
 # Usage: annotate fields in a schema
 AccountName = Types::String.admin
-AccountName.metadata # => { type: String, admin: true }
+AccountName.metadata # => { admin: true }
 ```
 
 #### Type-specific policies
@@ -1767,6 +2486,13 @@ Plumb.policy :split, SplitPolicy
 
 Plumb ships with a JSON schema visitor that compiles a type composition into a JSON Schema Hash. All Plumb types support a `#to_json_schema` method.
 
+The generated schema describes the **input** a type accepts (its `#input_type`), not what it produces. So a coercing type advertises the type a caller should send:
+
+```ruby
+# Accepts a String, coerces it to an Integer
+Types::String.transform(Integer, &:to_i).to_json_schema # => { "type" => "string" }
+```
+
 ```ruby
 Payload = Types::Hash[name: String]
 Payload.to_json_schema(root: true)
@@ -1826,12 +2552,57 @@ Types::DateTime.to_json_schema
 # {"type"=>"string", "format"=>"date-time"}
 ```
 
+##### Node names for compositions
+
+Two-sided compositions report one of four `#node_name`s, depending on whether the node is a *computation* (some side changes the value) or a *type* (no side does):
+
+| Node name       | Built by                          | Meaning                                                     |
+| --------------- | --------------------------------- | ----------------------------------------------------------- |
+| `:and`          | `#>>` with a converting side      | Sequential composition — consumes the left's input, produces the right's output |
+| `:intersection` | `#>>`, `#/`, `#where`, `#check`, `#&` | The meet — both sides constrain the *same* value            |
+| `:or`           | `#\|` with a converting branch     | Left-biased choice — a branch may coerce, so the ends differ |
+| `:union`        | `#\|` with value-preserving branches | The join — a plain set of alternatives                     |
+
+For a visitor this matters because an `:intersection` describes one value (merge both sides' specs) while an `:and` may describe a conversion (build from the input side). Visitors that don't need the distinction can register just `on(:and)` / `on(:or)`: `:intersection` and `:union` fall back to those when no specific handler is defined.
+
+### Mermaid diagrams
+
+Because a composition is just a tree of `>>` (sequence) and `|` (choice) nodes, it can also be rendered as a [Mermaid](https://mermaid.js.org) `flowchart`. Every Plumb type supports `#to_mermaid`. `>>` becomes sequential arrows; `|` becomes a fork, where the preceding step fans out to each alternative (and a following step joins them back).
+
+```ruby
+type = (A >> B) | (C >> (D | B))
+puts type.to_mermaid
+```
+
+```mermaid
+flowchart LR
+  start(( ))
+  n1["A"]
+  n2["B"]
+  n3["C"]
+  n4["D"]
+  n5["B"]
+  start --> n1
+  start --> n3
+  n1 --> n2
+  n3 --> n4
+  n3 --> n5
+```
+
+Each box is labelled by the node's metadata `:title` (or `:label`) when present, otherwise by its `#inspect` — so constant-bound types show their constant name. Structural nodes (`>>`, `|`) shape the graph; every other type (steps, transforms, refinements, hashes, arrays, …) renders as a single opaque box. Recursive types (`#defer`) render as one box rather than recursing forever.
+
+The direction is configurable, and the visitor can be used directly:
+
+```ruby
+type.to_mermaid(direction: 'TB')
+Plumb::MermaidVisitor.call(type)
+```
+
 
 
 ## TODO:
 
 - [ ] benchmarks and performace. Compare with `Parametric`, `ActiveModel::Attributes`, `ActionController::StrongParameters`
-- [ ] flesh out `Plumb::Schema`
 - [x] `Plumb::Struct`
 - [x] flesh out and document `Plumb::Pipeline`
 - [ ] document custom visitors