plumb 0.0.18 → 0.2.0.beta.2

data/lib/plumb/composable.rb

@@ -14,14 +14,32 @@ module Plumb
   end
 
   ParseError = Class.new(::TypeError)
+  # Raised by Composable#>> when chaining two steps whose types are provably
+  # incompatible (the left's #output_type is not a subtype of the right's
+  # #input_type).
+  TypeError = Class.new(::TypeError)
   Undefined = UndefinedClass.new.freeze
 
   BLANK_STRING = ''
   BLANK_ARRAY = [].freeze
   BLANK_HASH = {}.freeze
-  BLANK_RESULT = Result.wrap(Undefined)
   NOOP = ->(result) { result }
 
+  # Ruby's explicit conversion methods and the type each produces. Lets
+  # `#transform(:to_i)` expand to a typed transform to Integer (using `:to_i` as
+  # the callable), instead of spelling out `#transform(Integer, &:to_i)`.
+  COERCION_METHODS = {
+    to_s: ::String,
+    to_sym: ::Symbol,
+    to_i: ::Integer,
+    to_f: ::Float,
+    to_r: ::Rational,
+    to_c: ::Complex,
+    to_a: ::Array,
+    to_h: ::Hash,
+    to_proc: ::Proc
+  }.freeze
+
   module Callable
     def resolve(value = Undefined)
       call(Result.wrap(value))
@@ -49,6 +67,11 @@ module Plumb
     # define a #node_name method on the Composable instance
     # #node_name is used by Visitors to determine the type of node.
     def self.included(base)
+      # An anonymous class (`Class.new { include Composable }`) has no name to
+      # derive from: leave #node_name to the instance method below, which reads
+      # the class name at call time (by then it may have been assigned one).
+      return unless base.name
+
       nname = base.name.split('::').last
       nname.gsub!(/([a-z\d])([A-Z])/, '\1_\2')
       nname.downcase!
@@ -81,7 +104,7 @@ module Plumb
 
     def inspect = name.to_s
 
-    def node_name = self.class.name.split('::').last.to_sym
+    def node_name = (self.class.name || 'anonymous').split('::').last.to_sym
   end
 
   # Override #=== and #== for Composable instances.
@@ -99,15 +122,87 @@ module Plumb
       end
     end
 
+    # Compares nodes by exact class and children. Use `instance_of?`, not `is_a?`:
+    # a subclass may change behavior without changing #children, making parent/subclass
+    # equality asymmetric. Subtyping and optimization short-circuit on `==`, so that
+    # asymmetry could discard the narrower node before its behavioral guards run.
+    # @param other [Object]
+    # @return [Boolean]
     def ==(other)
-      other.is_a?(self.class) && other.respond_to?(:children) && other.children == children
+      other.instance_of?(self.class) && other.respond_to?(:children) && other.children == children
+    end
+
+    # Subtype/subset operator. `a <= b` is true when every value described by
+    # `self` is also described by `other` (`other` may be a raw Ruby class or
+    # value; it is normalized). Delegates to the generic Plumb::Subtyping engine.
+    # @param other [Composable, Class, Object]
+    # @return [Boolean]
+    def <=(other)
+      Plumb::Subtyping.subtype?(self, other)
     end
+
+    # `self` is a supertype of `other`: every value of `other` is a value of
+    # `self`.
+    def >=(other)
+      Plumb::Subtyping.subtype?(Composable.wrap(other), self)
+    end
+
+    # Strict subtype / supertype.
+    def <(other) = (self <= other) && !(self >= other)
+    def >(other) = (self >= other) && !(self <= other)
+
+    # Leaf hook for Plumb::Subtyping.subtype?, called once the algebra
+    # (Intersection/Or/top, and the #subtype_identity projection that replaces a
+    # converting node with what it produces) has been peeled away. It must NOT
+    # delegate back to #<= (that would recurse); it recurses only through
+    # Plumb::Subtyping.subtype?.
+    #
+    # Default behaviour:
+    #   1. reflexive structural equality;
+    #   2. atomic leaves (a single raw matcher/value) compared via Ruby
+    #      semantics (Plumb::Subtyping.atomic_subtype?);
+    #   3. covariant containers — same class with pairwise-subtype children,
+    #      which covers Array/Tuple/HashMap/Stream and any custom container that
+    #      exposes #children, for free.
+    #
+    # Override for bespoke leaf relations (see HashClass width/depth subtyping).
+    # @param other [Composable]
+    # @return [Boolean]
+    def subtype_of?(other)
+      return true if self == other
+
+      if Plumb::Subtyping.atomic?(self) && Plumb::Subtyping.atomic?(other)
+        # #children contains only the matcher, but a refinement also describes its
+        # base. Check both or an unrelated atomic value may pass on matcher overlap
+        # alone (for example, Value[5.0] against Integer[1..5]).
+        if other.respond_to?(:base) && other.base && !Plumb::Subtyping.subtype?(self, other.base)
+          return false
+        end
+
+        return Plumb::Subtyping.atomic_subtype?(children.first, other.children.first)
+      end
+
+      return false unless other.instance_of?(self.class)
+      return false if children.empty? || children.size != other.children.size
+
+      children.zip(other.children).all? { |c, o| Plumb::Subtyping.subtype?(c, o) }
+    end
+
+    # Mirror of #subtype_of?, for relations the *supertype* owns and the subtype
+    # can't know about (eg. Interface duck-typing: any type is a subtype of an
+    # Interface whose methods its values support). Consulted by
+    # Plumb::Subtyping.subtype? only after #subtype_of? declines. Default: no —
+    # only the subtype side decides. Recurse via Plumb::Subtyping.subtype?, never
+    # #<=. Override for bespoke supertype behaviour (see InterfaceClass).
+    # @param other [Composable]
+    # @return [Boolean]
+    def supertype_of?(other) = false
   end
 
   #  Composable mixes in composition methods to classes.
   # such as #>>, #|, #not, and others.
   # Any Composable class can participate in Plumb compositions.
-  # A host object only needs to implement the Step interface `call(Result::Valid) => Result::Valid | Result::Invalid`
+  # A host object only needs to implement the Step interface `call(Result) => Result`
   module Composable
     include Callable
 
@@ -127,14 +222,22 @@ module Plumb
     #
     # @example
     #   ten = Composable.wrap(10)
-    #   ten.resolve(10) # => Result::Valid
-    #   ten.resolve(11) # => Result::Invalid
+    #   ten.resolve(10) # => a valid Result
+    #   ten.resolve(11) # => an invalid Result
     #
     # @param callable [Object]
     # @return [Composable]
     def self.wrap(callable)
       if callable.is_a?(Composable)
         callable
+      elsif callable.respond_to?(:to_composable)
+        # The context-free resolution hook for objects that become a type on
+        # demand: an Encoder class resolves to its default (declared) direction; a
+        # Codec raises, having no type to become. Used in schema literals,
+        # `Array[Enc]`, `#/`, etc. The composition operators (#>>, #|, #&)
+        # consult #to_plumb_type BEFORE wrapping, so a composed operand can
+        # resolve against context and never reaches this branch.
+        wrap(callable.to_composable)
       elsif callable.is_a?(::Hash)
         HashClass.new(schema: callable)
       elsif callable.is_a?(::Array)
@@ -148,12 +251,31 @@ module Plumb
                        end
         Types::Array[element_type]
       elsif callable.respond_to?(:call)
-        Step.new(callable)
+        Function.opaque(callable)
+      elsif Constraint.literal_matcher?(callable)
+        # Equality literals use ValueClass; broader matchers use Constraint.
+        ValueClass.new(callable)
       else
-        MatchClass.new(callable)
+        Constraint.new(callable)
       end
     end
 
+    # Resolve `other` against a composition context and wrap it as a
+    # Composable — the full normalization for the RIGHT operand of a
+    # composition operator. Consults the operand's #to_plumb_type hook when it
+    # has one (raw values — procs, hash literals — don't, and skip straight to
+    # wrapping), so callers never need a #respond_to? check. EVERY custom
+    # operator implementation should route its operand through here.
+    #
+    # @param other [Object] the right operand
+    # @param op [Symbol] the composition operator being resolved (:>>, :| or :&)
+    # @param left [Composable] the left operand
+    # @return [Composable]
+    def self.resolve_operand(other, op:, left:)
+      other = other.to_plumb_type(op:, left:) if other.respond_to?(:to_plumb_type)
+      wrap(other)
+    end
+
     # A helper to wrap a block in a Step that will defer execution.
     # This so that types can be used recursively in compositions.
     # @example
@@ -165,35 +287,228 @@ module Plumb
       Deferred.new(definition || block)
     end
 
+    def input_type = self
+    def output_type = self
+
+    # Composition-context resolution hook, consulted on the RIGHT operand of
+    # #>>, #| and #& before wrapping/type-checking — via
+    # Composable.resolve_operand, which any custom operator implementation
+    # should route its operand through. It lets an operand
+    # resolve itself against the composition context: an Encoder picks the
+    # direction to run in from what `left` produces; a Codec builds an encode
+    # rewrite of `left`'s output. The returned value replaces the operand in
+    # the composition. Default: identity — every ordinary type composes as
+    # itself.
+    #
+    # @param op [Symbol] the composition operator (:>>, :| or :&)
+    # @param left [Composable] the left operand
+    # @return [Composable]
+    def to_plumb_type(op:, left:) = self
+
+    # The type that carries this node's identity for the subtype relation. A
+    # value-preserving type IS its own identity (the default). A value-converting
+    # type is identified by what it *produces*, so it projects onto a DISTINCT
+    # type (see Function#subtype_identity => output_type): Plumb::Subtyping.subtype?
+    # reduces `a <= b` to `produced(a) <= b` before consulting the leaf hooks.
+    #
+    # CONTRACT: only return a value other than `self` when that value is a
+    # genuinely different node. Returning `self` here is a no-op (subtype? guards
+    # with `!equal?(self)`, so it simply won't reduce); returning a node whose own
+    # #subtype_identity loops back would recurse forever. This is the extension
+    # point for building custom transforming types that play well with subtyping
+    # WITHOUT subclassing Function.
+    def subtype_identity = self
+
+    # The type this step accepts as the consumer of a `left >> self` chain — the
+    # values its #call processes without rejecting outright. Defaults to what it
+    # takes as input (its resolved #input_type): right for plain matchers and for
+    # conversion/consumer types (Function, Stream, Pipeline — they accept their
+    # declared input, so they need no override). Two kinds of type override it:
+    #   - a refinement (And): its #input_type is only the type the chain opens
+    #     with and would drop the constraint it adds, so it accepts its *output*;
+    #   - a Hash: it relaxes each field to what that field accepts.
+    # Consulted by Plumb::Subtyping when checking `#>>`.
+    def accepted_type = Plumb::Subtyping.resolved_input(self)
+
+    # Whether running this step twice in a row is the same as running it once,
+    # i.e. it validates without changing the value. Lets `#>>` drop a redundant
+    # `X >> X`. Default false; only types that never transform the value opt in
+    # (see Constraint). A transform must NOT be idempotent — `X >> X` would
+    # apply it twice.
+    def idempotent? = false
+
+    # Whether this type returns its input value UNCHANGED on success — a
+    # coreflexive refinement (a pure filter). Lets `#|` absorb a redundant
+    # branch (`Integer | Numeric == Numeric`) without dropping a coercion. See
+    # Optimizer.reduce_union, which memoizes this per frozen node in TypeCache.
+    # Default false; refinements opt in, transforms stay false. A covariant
+    # container (Array/Tuple/HashMap) preserves the value exactly when all its
+    # element/child types do — so `Array[Integer] >> Array[Numeric]` collapses
+    # like the scalar `Integer >> Numeric` — while a container that reshapes the
+    # value (a filtered map dropping entries, a record dropping undeclared keys)
+    # stays false. A stronger property than #idempotent? (value-preserving ⟹
+    # idempotent).
+    def value_preserving? = false
+
+    # Fuse `self >> other` into a single node when the runtime checks at the
+    # boundary between them are provably redundant, or nil when fusion doesn't
+    # apply. A reduction rung in Optimizer.reduce_step, so both `#>>` and `#/`
+    # reach it. Implemented by Function (transform fusion) and CovariantFusion
+    # (the functor law for containers).
+    def fuse_with(_other) = nil
+
+    # Can Function#fuse_with drop this node's boundary checks? Only the node
+    # knows: the answer is yes exactly when its #call runs the standard
+    # input -> fn -> output mapping, so the checks removed at a seam are checks
+    # it would really have run. Default false — a node opts in by saying so.
+    # @see Function#fusable_step?
+    def fusable_step? = false
+
+    # BOUNDARY ABSORPTION — the one-sided companions to #fuse_with, for a seam
+    # where only one side is a typed step and the other is a plain type. A typed
+    # step already RUNS its boundary types as steps (`result.map(input).map(fn)
+    # .map(output)`), so a neighbouring type can move into the matching slot and
+    # the node then does the same work in one hop instead of two.
+    #
+    #   `self >> type` -> #absorb_output(type), asked of the LEFT (the step)
+    #   `type >> self` -> #absorb_input(type),  asked of the RIGHT (the step)
+    #
+    # Return the rebuilt node, or nil to decline. Implemented by Function (which
+    # owns the soundness conditions) and re-associated by And, so a step in the
+    # middle of a chain is reachable. Reached from Optimizer.reduce_step as its
+    # LAST rung: absorption only fires where no other reduction applies.
+    def absorb_output(_type) = nil
+    def absorb_input(_type) = nil
+
     # Chain two composable objects together.
     # A.K.A "and" or "sequence"
     # @example
     #   Step1 >> Step2 >> Step3
     #
+    # Type-checks the composition by subsumption: everything `self` produces
+    # must be acceptable to `other` (`self`'s output a subtype of `other`'s
+    # input), else it raises Plumb::TypeError — eg. `String >> Integer`, or
+    # `Integer[0..40] >> Integer[2..10]` (the left can emit values the right
+    # rejects). To narrow a value, use `#[]` / `#transform(...)[...]` (a
+    # refinement is a runtime-checked cast, built directly and not subtype-
+    # checked). The check is permissive only where types are unknown: opaque
+    # steps (plain procs, transforms, narrowing matchers) report Any and opt out.
+    #
     # @param other [Composable]
+    # @raise [Plumb::TypeError] when `self`'s output is not a subtype of `other`'s input.
     # @return [And]
     def >>(other)
-      And.new(self, Composable.wrap(other))
+      other = Composable.resolve_operand(other, op: :>>, left: self)
+      # `X >> X` is redundant for a value-preserving validator (eg. Types::String):
+      # validating the same value twice is the same as once. Gated on #idempotent?
+      # so transforms — where `X >> X` would apply the change twice — never collapse.
+      return self if idempotent? && self == other
+
+      Plumb::Subtyping.check_composable!(self, other)
+      # Drop what `other` re-asserts that `self` already guarantees. reduce_step
+      # folds a base-type gate into a Constraint chain (`Integer[0..100] >>
+      # Integer[-10..110]` -> `Integer[0..100]`, `::Integer` validated once);
+      # redundant_refinement? does the same for any value-preserving `other` that
+      # `self` already subsumes (`String.where(size: 3..10) >> .where(size: 0..)`
+      # -> the former). A non-redundant `other` (a transform, or a narrowing
+      # refinement) stays an And.
+      Plumb::Optimizer.rewrite_step(self, other)
+    end
+
+    # Compose like #>> but WITHOUT the strict subtype check — the escape hatch
+    # for chains the checker can't prove safe but you know are (eg. a narrowing
+    # like `Types::Integer / Types::Integer[1..10]`, or feeding a producer whose
+    # output you know the right side accepts). You assert the composition is
+    # valid; it is still runtime-checked when data flows through. Reduces and
+    # builds the same refinement as #>> (just skipping the build-time check), so
+    # the result participates in subtyping like any other refinement. The `/` reads as
+    # `Pathname#/` does — "join the next segment". When `self` is the Any top the
+    # right side stands alone, consistent with #[].
+    #
+    # @param other [Composable]
+    # @return [Composable]
+    def /(other)
+      constrain(Composable.wrap(other))
     end
 
     # Chain two composable objects together as a disjunction ("or").
+    # When one value-preserving branch subsumes the other (`Integer | Numeric`,
+    # or `X | X`), the union absorbs to the wider branch — see
+    # Optimizer.reduce_union. Functions/containers never reduce (they may accept
+    # inputs the survivor rejects), so coercion unions are preserved.
     #
     # @param other [Composable]
-    # @return [Or]
+    # @return [Composable]
     def |(other)
-      Or.new(self, Composable.wrap(other))
+      other = Composable.resolve_operand(other, op: :|, left: self)
+      return self if other.is_a?(NeverClass) # X | Never == X
+
+      Plumb::Optimizer.rewrite_union(self, other)
+    end
+
+    # Intersection ("and"/meet) — the symmetric dual of #|. Builds the greatest
+    # lower bound of `self` and `other`: the type describing values that satisfy
+    # BOTH. Unlike #>>, it is order-independent and not subtype-checked. The
+    # reducer (Subtyping.intersect) narrows where it can — intersecting Ranges/
+    # Sets (`Integer[2..] & Integer[0..100]` == `Integer[2..100]`), covariant
+    # containers, and distributing over unions — and collapses a PROVABLY-empty
+    # intersection to `Types::Never` (`Integer[2..10] & Integer[11..100]`,
+    # `String & Integer`). When it can prove neither a narrowing nor emptiness it
+    # falls back to `Conjunction.build` — a runtime intersection where both sides
+    # must pass.
+    #
+    # @param other [Composable]
+    # @return [Composable]
+    def &(other)
+      other = Composable.resolve_operand(other, op: :&, left: self)
+      Plumb::Subtyping.intersect(self, other) || Conjunction.build(self, other)
     end
 
     # Transform value. Requires specifying the resulting type of the value after transformation.
     # @example
     #   Types::String.transform(Types::Symbol, &:to_sym)
     #
-    # @param target_type [Class] what type this step will transform the value to
+    # Shorthand: a single conversion symbol (see COERCION_METHODS) expands to a
+    # typed transform to the method's result type, using the symbol as the
+    # callable. When the input's base Ruby type is known, it also validates that
+    # the type actually responds to the method.
+    # @example
+    #   Types::String.transform(:to_i)   # => Transform to Integer, via :to_i
+    #   Types::Integer.transform(:to_sym) # raises: Integer has no #to_sym
+    #
+    # @param target_type [Class, Symbol] the output type, or a conversion symbol
     # @param callable [#call, nil] a callable that will be applied to the value, or nil if block provided
     # @param block [Proc] a block that will be applied to the value, or nil if callable provided
-    # @return [And]
+    # @return [Function]
     def transform(target_type, callable = nil, &block)
-      self >> Transform.new(target_type, callable || block)
+      if target_type.is_a?(::Symbol) && callable.nil? && block.nil? && (out = COERCION_METHODS[target_type])
+        return coercion_transform(target_type, out)
+      end
+
+      # Explicit output type + a coercion symbol as the callable
+      # (eg. `#transform(::Numeric, :to_f)`). Since the symbol's result type is
+      # known, we can compare it against the declared output at composition time:
+      #  - `ret <= target_type`  => the produced value is always within the
+      #    declared type, so the runtime output check is redundant (guaranteed).
+      #  - `ret` and `target_type` disjoint (neither is a subtype of the other)
+      #    => no value can be an instance of both, so the transform would reject
+      #    EVERY input. That's a composition error, not a runtime one — raise now.
+      #  - otherwise (`target_type < ret`, a genuine narrowing) => may or may not
+      #    hold at runtime; leave the output check to do its job.
+      if callable.is_a?(::Symbol) && block.nil? && (ret = COERCION_METHODS[callable])
+        guaranteed = false
+        if target_type.is_a?(::Module)
+          if ret <= target_type
+            guaranteed = true
+          elsif !(target_type <= ret)
+            raise ArgumentError,
+                  ":#{callable} produces a #{ret}, which is never a #{target_type}"
+          end
+        end
+        return transform_step(target_type, callable.to_proc, guaranteed:)
+      end
+
+      transform_step(target_type, callable || block || Plumb::NOOP)
     end
 
     # Pass the value through an arbitrary validation
@@ -202,9 +517,11 @@ module Plumb
     #
     # @param errors [String] error message to use when validation fails
     # @param block [Proc] a block that will be applied to the value
-    # @return [And]
+    # @return [Constraint]
     def check(errors = 'did not pass the check', &block)
-      self >> MatchClass.new(block, error: errors, label: errors)
+      # A refinement, not a sequence: build the matcher over `self` as its base so
+      # the checked value keeps `self`'s type (`User.check { … }` is still a User).
+      Constraint.new(block, base: self, error: errors, label: errors)
     end
 
     # Return a new Step with added metadata, or build step metadata if no argument is provided.
@@ -253,7 +570,7 @@ module Plumb
     # @param value [Object]
     # @rerurn [And]
     def value(val)
-      self >> ValueClass.new(val)
+      constrain(ValueClass.new(val))
     end
 
     # Alias of `#[]`
@@ -262,12 +579,47 @@ module Plumb
     #   email = Types::String['@']
     #
     # @param args [Array<Object>]
-    # @return [And]
+    # @return [Constraint]
     def match(*args)
-      self >> MatchClass.new(*args)
-    end
+      # A refinement returns a base-carrying Constraint directly (not an
+      # `And(self, matcher)`): the matcher records `self` as its base, so it
+      # subtypes and composes as "a `self` narrowed by the matcher". When `self`
+      # is the Any top the matcher stands alone (`Any[String]` == the String
+      # matcher), matching the collapsing `AnyClass#>>` provides. Routed through
+      # Constraint.narrow so stacked Range refinements intersect
+      # (`Integer[0..100][10..]` == `Integer[10..100]`).
+      base = is_a?(AnyClass) ? nil : self
+      # A bare equality literal uses ValueClass so `Any[5]` and `Value[5]` share
+      # one subtype identity. A based literal remains a Constraint.
+      return ValueClass.new(args.first) if base.nil? && args.size == 1 && Constraint.literal_matcher?(args.first)
+
+      Constraint.narrow(base, *args)
+    end
+
+    # Sugar over #match: a splatted list of values becomes a Set membership
+    # matcher, so `Integer[1, 2, 3]` == `Integer[Set[1, 2, 3]]` (and composes /
+    # reduces like any Set constraint). A single argument is used as-is — a Range,
+    # Regexp, Set, class or literal value.
+    # @example
+    #   Types::String['a', 'b', 'c'] # one of these three strings
+    def [](*args) = match(args.size > 1 ? ::Set.new(args) : args.first)
+
+    # Narrow `self` with a constraint. A constraint refines rather than
+    # sequences a new type, so this bypasses the #>> composition type-check
+    # (eg. `Generic[::URI::HTTP]` narrows a URI to an HTTP URI). When `self` is
+    # the Any top type the constraint stands alone (`Any[::String]` == the
+    # String matcher), preserving the collapsing that `AnyClass#>>` provides.
+    # Applies the same base-type reduction as #>> (see Optimizer.reduce_step), so
+    # `Integer[0..40] / Integer[2..10]` re-parents to `Integer[0..40][2..10]`
+    # rather than re-checking `::Integer`. `reduce_step` bails for a non-Constraint
+    # constraint (eg. #value's ValueClass), leaving the And.
+    # @param constraint [Composable]
+    # @return [Composable]
+    private def constrain(constraint)
+      return constraint if is_a?(AnyClass)
 
-    def [](val) = match(val)
+      Plumb::Optimizer.rewrite_refinement(self, constraint)
+    end
 
     #  Support #as_node.
     class Node
@@ -296,6 +648,17 @@ module Plumb
 
       def call(result) = type.call(result)
 
+      # A Node is a transparent wrapper (it only re-labels its node_name): it
+      # delegates type-flow to the wrapped type.
+      def input_type = type.input_type
+      def output_type = type.output_type
+      def value_preserving? = type.value_preserving?
+
+      # Inspect as the wrapped type. Constant-assigned nodes (Types::Boolean,
+      # Email) are renamed by constant assignment and ignore this; a runtime node
+      # (eg. a factored :refined_union) would otherwise show "Composable::Node".
+      private def _inspect = type.inspect
+
       # Two nodes are equal when they wrap the same type with the same
       # node_name and args. The default Composable#== compares #children,
       # but a Node holds its identity in @node_name/@type/@args, so without
@@ -326,8 +689,14 @@ module Plumb
     #   type = Types::Array.where(size: 1..10)
     #   type = Types::String.where(bytesize: 1..10)
     #
-    # @param attrs [Hash]
+    # @param attrs [Hash{Symbol, String => Object}] attribute name => matcher
     def where(attrs)
+      unless attrs.is_a?(::Hash) && !attrs.empty?
+        raise ArgumentError,
+              '#where expects a non-empty Hash of attribute => matcher ' \
+              "(eg. `where(size: 1..10)`), got #{attrs.inspect}"
+      end
+
       attrs.reduce(self) do |t, (name, value)|
         t >> AttributeValueMatch.new(t, name, value)
       end
@@ -344,11 +713,11 @@ module Plumb
     # Mode 1.b: #policy(:name) a single policy without an argument
     # Mode 2: #policy(p1: value, p2: value) multiple policies with arguments
     # The latter mode will be expanded to multiple #policy calls.
-    # @return [Step]
+    # @return [Composable]
     def policy(*args, &blk)
       case args
       in [::Symbol => name, *rest] # #policy(:name, arg)
-        types = Array(metadata[:type]).uniq
+        types = Plumb.resolve_base_types(output_type).uniq
 
         bargs = [self]
         arg = Undefined
@@ -385,7 +754,45 @@ module Plumb
     # @param factory_method [Symbol] method to call on the class to instantiate it.
     # @return [And]
     def build(cns, factory_method = :new, &block)
-      self >> Build.new(cns, factory_method:, &block)
+      # Without a block the callable is a fresh lambda per call, so name what the
+      # step actually IS — the (class, factory method) pair — as its identity.
+      transform_step(cns, block || ->(value) { cns.send(factory_method, value) },
+                     identity: block || [cns, factory_method])
+    end
+
+    # Build a Function that validates the input (self), applies a value-level
+    # callable, and declares `target_type` as the (validated) output type.
+    # @param identity [Object, nil] what the step IS, for Function#==. Defaults to
+    #   `callable`; pass it explicitly when `callable` is itself built fresh here
+    #   and so would differ between two identical constructions (see #build).
+    private def transform_step(target_type, callable, guaranteed: false, identity: nil)
+      klass = guaranteed ? GuaranteedFunction : Function
+      # Flip the cursor in place with the transformed value — the transform owns
+      # the result it is handed (the argument is evaluated first, reading the
+      # pre-transform value), so no fresh Result is needed.
+      #
+      # The wrapper lambda is new on every call, so it cannot serve as the node's
+      # identity — `callable` (the caller's own) does.
+      klass.new(self, Composable.wrap(target_type),
+                ->(result) { result.valid!(callable.call(result.value)) },
+                identity: identity || callable)
+    end
+
+    # Expand `#transform(:to_i)` into a typed transform to `output_type`, using
+    # the conversion symbol itself as the callable. If the input's base Ruby
+    # type(s) can be resolved, validate that they define the method (so
+    # `Types::Integer.transform(:to_sym)` fails loudly at build time).
+    private def coercion_transform(method_name, output_type)
+      bases = Plumb.resolve_base_types(self)
+      unless bases.empty? || bases.all? { |k| k.is_a?(::Module) && k.method_defined?(method_name) }
+        raise Plumb::TypeError,
+              "cannot #transform(#{method_name.inspect}): " \
+              "#{bases.map(&:inspect).join(' / ')} does not define ##{method_name}"
+      end
+
+      # The output type IS the coercion method's result type, so the produced
+      # value is guaranteed to match — skip the runtime output check.
+      transform_step(output_type, method_name.to_proc, guaranteed: true)
     end
 
     # Always return a static value, regardless of the input.
@@ -398,12 +805,6 @@ module Plumb
     # @param value [Object]
     # @return [And]
     def static(value)
-      my_type = Array(metadata[:type]).first
-      unless my_type.nil? || value.instance_of?(my_type)
-        raise ArgumentError,
-              "can't set a static #{value.class} value for a #{my_type} step"
-      end
-
       StaticClass.new(value) >> self
     end
 
@@ -419,7 +820,9 @@ module Plumb
       generator ||= block
       raise ArgumentError, 'expected a generator' unless generator.respond_to?(:call)
 
-      Step.new(->(r) { r.valid(generator.call) }, 'generator') >> self
+      Function.opaque(inspect: 'generator', identity: [:generate, generator]) do |r|
+        r.valid(generator.call)
+      end >> self
     end
 
     # Build a Plumb::Pipeline with this object as the starting step.
@@ -445,18 +848,29 @@ module Plumb
       JSONSchemaVisitor.call(self, root:)
     end
 
+    # Render this composition as a Mermaid `flowchart`. `>>` becomes sequential
+    # arrows and `|` becomes a fork. See Plumb::MermaidVisitor.
+    # @option direction [String] flowchart direction ('LR', 'TB', …)
+    # @return [String]
+    def to_mermaid(direction: 'LR')
+      MermaidVisitor.call(self, direction:)
+    end
+
     # Build a step that will invoke one or more methods on the value.
     # Ex 1: Types::String.invoke(:downcase)
     # Ex 2: Types::Array.invoke(:[], 1)
     # Ex 3 chain of methods: Types::String.invoke([:downcase, :to_sym])
-    # @return [Step]
+    # @return [Composable]
     def invoke(*args, &block)
       case args
       in [::Symbol => method_name, *rest]
-        self >> Step.new(
-          ->(result) { result.valid(result.value.public_send(method_name, *rest, &block)) },
-          [method_name.inspect, rest.inspect].join(' ')
-        )
+        label = [method_name.inspect, rest.inspect].join(' ')
+        # The block is new on each call, but the step it implements is determined
+        # by the method and its arguments — so name that as the identity, and two
+        # `invoke(:downcase)` steps stay #== (see Function#==).
+        self >> Function.opaque(inspect: label, identity: [:invoke, method_name, rest, block]) do |result|
+          result.valid(result.value.public_send(method_name, *rest, &block))
+        end
       in [Array => methods] if methods.all? { |m| m.is_a?(Symbol) }
         methods.reduce(self) { |step, method| step.invoke(method) }
       else
@@ -468,7 +882,5 @@ end
 
 require 'plumb/deferred'
 require 'plumb/attribute_value_match'
-require 'plumb/transform'
 require 'plumb/policy'
-require 'plumb/build'
 require 'plumb/metadata'