plumb 0.0.18 → 0.2.0.beta.2

data/lib/plumb/json_schema_visitor.rb

@@ -7,6 +7,11 @@ module Plumb
   class JSONSchemaVisitor
     include VisitorHandlers
 
+    # Raised when a value that has no JSON-native representation would end up in
+    # the generated schema. Register a handler (via `.on(...)`) that converts the
+    # offending type to a JSON-native value to resolve it.
+    InvalidJSONValueError = Class.new(StandardError)
+
     TYPE = 'type'
     PROPERTIES = 'properties'
     REQUIRED = 'required'
@@ -16,6 +21,8 @@ module Plumb
     NOT = 'not'
     ENUM = 'enum'
     CONST = 'const'
+    REF = '$ref'
+    DEFS = '$defs'
     ITEMS = 'items'
     PATTERN = 'pattern'
     MINIMUM = 'minimum'
@@ -25,15 +32,47 @@ module Plumb
     MIN_LENGTH = 'minLength'
     MAX_LENGTH = 'maxLength'
     FORMAT = 'format'
+    EXCLUSIVE_MAXIMUM = 'exclusiveMaximum'
+    FORMAT_MINIMUM = 'formatMinimum'
+    FORMAT_MAXIMUM = 'formatMaximum'
+    FORMAT_EXCLUSIVE_MAXIMUM = 'formatExclusiveMaximum'
     ENVELOPE = {
       '$schema' => 'https://json-schema.org/draft-08/schema#'
     }.freeze
 
     def self.call(node, root: true)
-      data = new.visit(node)
-      return data unless root
-
-      ENVELOPE.merge(data)
+      visitor = new
+      data = visitor.visit(node)
+      # Deferred types register named entries in a `$defs` table and reference
+      # them by `$ref` (see the :deferred handler). Hoist that table to the top of
+      # the document so the root-relative `#/$defs/...` pointers resolve.
+      defs = visitor.defs
+      data = data.merge(DEFS => defs) unless defs.empty?
+      data = ENVELOPE.merge(data) if root
+      normalize_json(data)
+    end
+
+    # Recursively normalize the generated schema into JSON-native values and
+    # fail loudly on anything that has no JSON representation.
+    # Symbols are coerced to strings; everything that isn't a JSON-native value
+    # raises, so the user knows they need to register a custom visitor handler.
+    def self.normalize_json(value)
+      case value
+      when ::Hash
+        value.each_with_object({}) do |(key, val), hash|
+          hash[normalize_json(key)] = normalize_json(val)
+        end
+      when ::Array
+        value.map { |val| normalize_json(val) }
+      when ::Symbol
+        value.to_s
+      when ::String, ::Numeric, true, false, nil
+        value
+      else
+        raise InvalidJSONValueError,
+              "#{value.class} value #{value.inspect} cannot be serialized to JSON Schema. " \
+              'Register a Plumb::JSONSchemaVisitor.on(...) handler that converts it to a JSON-native value.'
+      end
     end
 
     # Some rules that are dependent on combinations of aggregates keys
@@ -45,52 +84,177 @@ module Plumb
 
     private def stringify_keys(hash) = hash.transform_keys(&:to_s)
 
+    # The `$defs` table of materialized Deferred schemas built during this visit,
+    # hoisted to the document root by `.call`. Empty unless a Deferred was visited.
+    def defs = @defs || BLANK_HASH
+
+    # Register a Deferred under a stable `$defs` name and return that name. Keyed
+    # by the RESOLVED target type's identity (not the Deferred wrapper's), so
+    # distinct `defer { … }` wrappers pointing at the same type share one def.
+    # Resolving via #type is cheap (memoized) and does no visitor recursion, so we
+    # can key on it up front. The name is recorded BEFORE the body is visited, so a
+    # self-reference encountered while visiting finds the name already present and
+    # emits a `$ref` instead of recursing forever.
+    private def deferred_ref(node)
+      @defs ||= {}
+      @deferred_names ||= {}.compare_by_identity
+      target = node.type
+      existing = @deferred_names[target]
+      return existing if existing
+
+      name = "Deferred#{@deferred_names.size + 1}"
+      @deferred_names[target] = name
+      @defs[name] = visit(target)
+      name
+    end
+
     on(:any) do |_node, props|
       props
     end
 
-    on(:pipeline) do |node, props|
-      visit_children(node, props)
+    # The bottom type matches nothing — JSON Schema `{ "not": {} }` (the empty
+    # schema `{}` matches everything, so its negation matches nothing).
+    on(:never) do |_node, props|
+      props.merge('not' => {})
     end
 
-    on(:step) do |node, props|
-      props.merge(stringify_keys(node._metadata))
+    on(:pipeline) do |node, props|
+      visit_children(node, props)
     end
 
     on(:interface) do |_node, props|
       props
     end
 
-    # Trying to visit the deferred could go into infinite recursion
-    # if a type is deferring to itself
-    # Not clear what deferred types would mean for JSON Schema anyway.
+    # A Deferred materializes to a concrete type (via #type), but that type may
+    # reference the Deferred back (a recursive/self-referential schema), so we
+    # can't inline it — that would recurse forever. Instead each Deferred becomes a
+    # named `$defs` entry referenced by `$ref`, the standard JSON Schema idiom for
+    # recursion. `deferred_ref` builds the def (once) and returns its name; `.call`
+    # hoists the `$defs` table to the document root.
     on(:deferred) do |node, props|
-      props
+      props.merge(REF => "#/#{DEFS}/#{deferred_ref(node)}")
     end
 
     on(:hash) do |node, props|
-      props.merge(
+      # Named (literal) keys become properties/required. Typed/catch-all keys are
+      # not fixed property names: the `_` catch-all becomes `additionalProperties`
+      # (a schema; `{}` for Any = any value), and a pattern-backed typed key becomes
+      # a `patternProperties` entry (reusing the Regexp -> `pattern` handler).
+      literal = node.literal_fields
+      schema = {
         TYPE => 'object',
-        PROPERTIES => node._schema.each_with_object({}) do |(key, value), hash|
+        PROPERTIES => literal.each_with_object({}) do |(key, value), hash|
           hash[key.to_s] = visit(value)
         end,
-        REQUIRED => node._schema.reject { |key, _value| key.optional? }.keys.map(&:to_s)
-      )
+        REQUIRED => literal.reject { |key, _value| key.optional? }.keys.map(&:to_s)
+      }
+
+      schema['additionalProperties'] = visit(node.catch_all_type) if node.catch_all_type
+
+      patterns = node.matcher_fields.each_with_object({}) do |(key, value), h|
+        next if key.catch_all?
+
+        pattern = visit(key.matcher)[PATTERN]
+        h[pattern] = visit(value) if pattern
+      end
+      schema['patternProperties'] = patterns unless patterns.empty?
+
+      props.merge(schema)
     end
 
     on(:data) do |node, props|
       visit_name :hash, node._schema, props
     end
 
+    # A refinement (`And`): both sides describe the SAME value. Build from the
+    # input side and fold in the output side when it shares the input's type (a
+    # constraint such as `pattern`/`minimum`/`format`), or when the input is
+    # untyped. Both sides are validators over one value, so both are visited.
+    # A factored union `And(base, Or(suffix, …))` (built by Composable#| when
+    # branches share a base type). Unlike the generic `:and` handler, the
+    # disjunction is a *refinement* of the base, not a different type: render the
+    # base, then fold the (type-less) disjunction's `anyOf` into that same spec.
+    on(:refined_union) do |node, props|
+      base, disjunction = node.type.children # the And's two sides, not its io types
+      props = visit(base, props)             # base -> {type: …}
+      visit(disjunction, props)              # Or(suffixes) -> merge anyOf into it
+    end
+
+    # A MEET (`Intersection`): both sides constrain the SAME value, so both specs
+    # describe it and both are merged — the left contributes the type, the right
+    # the narrowing keywords (`pattern`, `minimum`, `format`, …). No shape test is
+    # needed, which is the whole difference from the `:and` handler below: two
+    # sides that disagreed on `type` would describe an uninhabitable value, and
+    # `#&` folds that to Never before a schema is ever asked for.
+    on(:intersection) do |node, props|
+      left, right = node.children.map { |c| visit(c) }
+      merge_same_type_specs(props, left, right)
+    end
+
+    # A COMPOSITION (`And`): the right side may convert, so the two sides can
+    # describe genuinely different types. A JSON Schema describes accepted INPUTS,
+    # so build from the left and fold the right in only when it cannot contradict
+    # it — when the left is untyped (all we know comes from the right), or when
+    # both agree on `type` (the right is then narrowing the same type). When they
+    # disagree, the right is a conversion target and is dropped.
     on(:and) do |node, props|
       left, right = node.children.map { |c| visit(c) }
-      type = right[TYPE] || left[TYPE]
-      props = props.merge(left).merge(right)
-      props = props.merge(TYPE => type) if type
-      props
+      if !left.key?(TYPE) || left[TYPE] == right[TYPE]
+        merge_same_type_specs(props, left, right)
+      else
+        props.merge(left)
+      end
+    end
+
+    # Combine two specs that describe the SAME value: merge both sets of keywords
+    # and keep whichever `type` is present. Shared by the two handlers above, which
+    # differ only in WHEN they are allowed to do this.
+    private def merge_same_type_specs(props, left, right)
+      merged = props.merge(left).merge(right)
+      type = left[TYPE] || right[TYPE]
+      type ? merged.merge(TYPE => type) : merged
     end
 
-    # A "default" value is usually an "or" of expected_value | (undefined >> static_value)
+    # A conversion (`Function`) produces a genuinely different value. A JSON
+    # Schema describes accepted *inputs*, so it is built from the input side and
+    # the output is dropped — and crucially NOT visited, so a transform whose
+    # output type has no schema handler (eg. a custom class via #build) is fine.
+    # Only when the input is untyped (eg. `Any.transform(::Integer)`) do we fall
+    # back to the output type, since that is then all we know.
+    # Encoder steps (see Plumb::Encoder) are plain Functions, so this covers
+    # them too: a decode-direction step's input IS the encoded form, which is
+    # why `Codec >> Type` describes the encoded side of a schema.
+    on(:function) do |node, props|
+      left = visit(node.input_type)
+      return props.merge(left) if left.key?(TYPE)
+
+      props.merge(left).merge(visit(node.output_type))
+    end
+
+    # A filtered Hash may drop any field, so its schema is its relaxed
+    # (all-optional) output.
+    on(:filtered_hash) do |node, props|
+      props.merge(visit(node.output_type))
+    end
+
+    # A JOIN (`Union`): every branch passes its value through, so this is a plain
+    # `anyOf` over the branch schemas. Nothing here has to look for a default: a
+    # `#default` is `(Undefined >> Static) | type`, whose first branch converts, so
+    # it is always a `:or` and never reaches this handler.
+    on(:union) do |node, props|
+      any_of = node.children.map { |c| visit(c) }.uniq.filter(&:any?)
+      return props.merge(any_of.first) if any_of.size == 1
+
+      props.merge(ANY_OF => splice_any_of(any_of))
+    end
+
+    # A CHOICE (`Or`): a branch may convert, which is what makes the two special
+    # shapes below possible.
+    #
+    # A "default" value is `expected_value | (undefined >> static_value)`: the
+    # static branch's spec is a DEFAULT rather than an alternative, so it is folded
+    # into the other branch instead of becoming an `anyOf` arm.
     on(:or) do |node, props|
       left, right = node.children.map { |c| visit(c) }
       any_of = [left, right].uniq.filter(&:any?)
@@ -100,10 +264,18 @@ module Plumb
         val = any_of[defidx.zero? ? 1 : 0]
         props.merge(val).merge(DEFAULT => any_of[defidx][DEFAULT])
       else
-        props.merge(ANY_OF => any_of)
+        props.merge(ANY_OF => splice_any_of(any_of))
       end
     end
 
+    # anyOf is associative, so splice a child that is itself a BARE `anyOf` (a
+    # nested disjunction from an n-ary factored union) into this level to keep the
+    # schema flat. Only when it is pure anyOf — other keys would be lost, and a
+    # default-bearing branch is deliberately left un-spliced (see :or).
+    private def splice_any_of(any_of)
+      any_of.flat_map { |s| s.keys == [ANY_OF] ? s[ANY_OF] : [s] }.uniq
+    end
+
     on(:not) do |node, props|
       props.merge(NOT => visit_children(node))
     end
@@ -120,10 +292,6 @@ module Plumb
       visit(value, props)
     end
 
-    on(:transform) do |node, props|
-      visit_children(node, props)
-    end
-
     on(:undefined) do |_node, props|
       props
     end
@@ -162,7 +330,10 @@ module Plumb
     end
 
     on(:options_policy) do |node, props|
-      props.merge(ENUM => node.arg)
+      # Only an Array argument maps to `enum`. Any other argument was delegated
+      # to a Constraint by the policy, so its schema (eg. `minimum`/
+      # `maximum` for a Range) has already been built by visiting the children.
+      node.arg.is_a?(::Array) ? props.merge(ENUM => node.arg) : props
     end
 
     on(:with_size_attribute) do |node, props|
@@ -201,12 +372,19 @@ module Plumb
       props
     end
 
-    on(:match) do |node, props|
+    on(:constraint) do |node, props|
+      # A refinement matcher describes its base first (eg. `Integer[1..10]` gets
+      # `type: integer` from the base Integer), then folds in the matcher's own
+      # constraint (`minimum`/`maximum`/`pattern`/`const`).
+      props = visit(node.base, props) if node.base
+
       # Set const if primitive
       matcher = node.children.first
       props = case matcher
               when ::String, ::Symbol, ::Numeric
                 props.merge(CONST => matcher)
+              when ::Date, ::Time # also covers ::DateTime
+                props.merge(CONST => matcher.iso8601)
               else
                 props
               end
@@ -262,15 +440,32 @@ module Plumb
       props.merge(PATTERN => node.source, TYPE => props[TYPE] || 'string')
     end
 
+    # A Set is a membership matcher (`Set#===` is `include?`), so it maps to
+    # `enum` — the same shape the :options_policy handler produces for an Array
+    # argument. `Integer[1, 2, 3]` / `Integer[Set[1, 2, 3]]` build a Constraint
+    # whose base sets `type` and whose Set matcher folds in the members here.
+    on(::Set) do |node, props|
+      props.merge(ENUM => node.to_a)
+    end
+
     on(::Range) do |node, props|
       element = node.begin || node.end
       opts = visit(element.class)
-      if element.is_a?(::Numeric)
+      case element
+      when ::Numeric
         opts[MINIMUM] = node.min if node.begin
+        opts[MAXIMUM] = node.max if node.end
+      when ::Date, ::Time # also covers ::DateTime
+        # JSON Schema has no native min/max for date/time strings, so use the
+        # `formatMinimum`/`formatMaximum` keywords (the format-assertion
+        # convention also supported by ajv) alongside `format`.
+        opts[FORMAT_MINIMUM] = node.begin.iso8601 if node.begin
         if node.end
-          max = node.end
-          max -= 1 if node.exclude_end?
-          opts[MAXIMUM] = max
+          if node.exclude_end?
+            opts[FORMAT_EXCLUSIVE_MAXIMUM] = node.end.iso8601
+          else
+            opts[FORMAT_MAXIMUM] = node.end.iso8601
+          end
         end
       end
       props.merge(opts)
@@ -328,10 +523,6 @@ module Plumb
       }
     end
 
-    on(:build) do |node, props|
-      visit_children(node, props)
-    end
-
     on(:array) do |node, _props|
       items_props = visit_children(node)
       { TYPE => 'array', ITEMS => items_props }
@@ -347,6 +538,33 @@ module Plumb
       { TYPE => 'array', 'prefixItems' => items }
     end
 
+    # A Types::Range whose member type pins the bounds (`Types::Range[0...100]`)
+    # maps to the member's scalar schema plus JSON Schema's native bound
+    # keywords. Unlike the range-*matcher* handler below (`on(::Range)`), this
+    # preserves an exclusive end as `exclusiveMaximum` rather than approximating
+    # it as `maximum - 1` (which also can't be computed for float ranges).
+    # A member with no bounds (`Types::Range[Integer]`) falls back to its own
+    # schema.
+    on(:range) do |node, _props|
+      member = node.children.first
+      matcher = member.respond_to?(:children) ? member.children.first : nil
+      next visit(member) unless matcher.is_a?(::Range)
+
+      element = matcher.begin || matcher.end
+      opts = visit(element.class)
+      case element
+      when ::Numeric
+        opts[MINIMUM] = matcher.begin if matcher.begin
+        opts[matcher.exclude_end? ? EXCLUSIVE_MAXIMUM : MAXIMUM] = matcher.end if matcher.end
+      when ::Date, ::Time # also covers ::DateTime
+        opts[FORMAT_MINIMUM] = matcher.begin.iso8601 if matcher.begin
+        if matcher.end
+          opts[matcher.exclude_end? ? FORMAT_EXCLUSIVE_MAXIMUM : FORMAT_MAXIMUM] = matcher.end.iso8601
+        end
+      end
+      opts
+    end
+
     on(:tagged_hash) do |node, _props|
       required = Set.new
       result = {
@@ -373,5 +591,6 @@ module Plumb
 
       result.merge(REQUIRED => required.to_a)
     end
+
   end
 end

data/lib/plumb/key.rb

@@ -1,6 +1,19 @@
 # frozen_string_literal: true
 
+require 'plumb/composable'
+
 module Plumb
+  # A hash-schema key. Two flavours:
+  #
+  #   * a LITERAL key — a Symbol or String name (`name:`, `'name' =>`). It is
+  #     matched by exact lookup and carries `#to_key`/`#to_sym`. A trailing `?`
+  #     (`name?:`) marks it optional. This is the common case and behaves exactly
+  #     as before.
+  #   * a MATCHER key — any Plumb type / `#===` object used as a key
+  #     (`Types::String[/^id_/] => ...`, or the `_` catch-all which wraps
+  #     `Types::Any`). It matches other keys via `matcher === other_key`, has no
+  #     single `#to_key`, and is inherently optional (it imposes no specific
+  #     required key).
   class Key
     # OPTIONAL_EXP = /(\w+)(\?)?$/
     OPTIONAL_EXP = /(?<word>[A-Za-z0-9_$]+)(?<qmark>\?)?/
@@ -9,27 +22,58 @@ module Plumb
       key.is_a?(Key) ? key : new(key, symbolize:)
     end
 
-    attr_reader :to_key, :to_sym, :node_name
+    attr_reader :to_key, :to_sym, :node_name, :matcher
 
     def initialize(key, optional: false, symbolize: false)
-      key_type = symbolize ? Symbol : key.class
-      match = OPTIONAL_EXP.match(key.to_s)
-      key = match[:word]
-      @to_key = key_type == Symbol ? key.to_sym : key
-      @to_sym = @to_key.to_sym
-      @optional = !match[:qmark].nil? ? true : optional
       @node_name = :key
+      if key.is_a?(::Symbol) || key.is_a?(::String)
+        key_type = symbolize ? Symbol : key.class
+        match = OPTIONAL_EXP.match(key.to_s)
+        name = match[:word]
+        @to_key = key_type == Symbol ? name.to_sym : name
+        @to_sym = @to_key.to_sym
+        @optional = !match[:qmark].nil? ? true : optional
+        @matcher = @to_key
+        @literal = true
+      else
+        # A type/matcher key. It matches other keys structurally, so it has no
+        # concrete #to_key and never imposes a required key.
+        @matcher = Composable.wrap(key)
+        @to_key = nil
+        @to_sym = nil
+        @optional = true
+        @literal = false
+      end
       freeze
     end
 
-    def to_s = @to_key.to_s
+    # A concrete Symbol/String key (exact lookup) vs a type/matcher key.
+    def literal? = @literal
 
-    def hash
-      @to_key.hash
-    end
+    # The `_` catch-all: a matcher key over the Any top, so it matches every key.
+    def catch_all? = !@literal && @matcher.is_a?(AnyClass)
+
+    # Does this key match `other` (a raw hash key)? Literal keys match by `==`
+    # (`Symbol#===`/`String#===`); matcher keys by `matcher === other`.
+    def match?(other) = @matcher === other
+
+    def to_s = (@to_key || @matcher).to_s
+
+    # Dedupe/lookup identity. Literal keys hash by name (unchanged); matcher keys
+    # hash by matcher class (structural equality disambiguates via #eql?), so two
+    # `_` catch-alls collapse. Two keys are eql? when both literal with the same
+    # name, or both matchers with equal matchers — optionality is deliberately
+    # ignored (so `name?`/`name` collapse), and HashClass#== compares it separately.
+    def hash = @literal ? @to_key.hash : @matcher.class.hash
 
     def eql?(other)
-      other.hash == hash
+      return false unless other.is_a?(Key)
+
+      if @literal
+        other.literal? && @to_key == other.to_key
+      else
+        !other.literal? && @matcher == other.matcher
+      end
     end
 
     def optional?
@@ -37,7 +81,13 @@ module Plumb
     end
 
     def inspect
-      "#{@to_key}#{'?' if @optional}"
+      if @literal
+        "#{@to_key}#{'?' if @optional}"
+      elsif catch_all?
+        '_'
+      else
+        @matcher.inspect
+      end
     end
   end
 end

data/lib/plumb/mermaid_visitor.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require 'plumb/visitor_handlers'
+
+module Plumb
+  # Renders a type composition as a Mermaid `flowchart`, so the flow-control
+  # algebra can be visualised. `>>` (And) becomes sequential arrows; `|` (Or)
+  # becomes a fork — the predecessor fans out to each alternative.
+  #
+  # Every `visit` returns `{ entries:, exits: }` — the node ids an incoming
+  # arrow should point INTO, and the ids outgoing arrows leave FROM — and
+  # accumulates node/edge lines as a side effect (the same stateful pattern
+  # JSONSchemaVisitor uses for `$defs`). And connects `left.exits -> right.entries`
+  # (a join over a preceding Or's branches); Or unions both branches' entries and
+  # exits without a node of its own, so whatever precedes it forks to both.
+  #
+  # @example
+  #   ((A >> B) | (C >> (D | B))).to_mermaid
+  class MermaidVisitor
+    include VisitorHandlers
+
+    def self.call(node, direction: 'LR')
+      new.render(node, direction:)
+    end
+
+    def initialize
+      @nodes = []
+      @edges = []
+      @counter = 0
+    end
+
+    def render(node, direction: 'LR')
+      root = visit(node)
+      # A top-level Or has more than one entry; anchor them to a synthetic start
+      # node so the diagram reads as a single connected fork.
+      entries = root[:entries]
+      if entries.size > 1
+        @nodes.unshift('start(( ))')
+        @edges = entries.map { |e| "start --> #{e}" } + @edges
+      end
+
+      lines = ["flowchart #{direction}"]
+      (@nodes + @edges).each { |line| lines << "  #{line}" }
+      lines.join("\n")
+    end
+
+    # Unknown nodes render as a single labeled box rather than raising, so any
+    # leaf type (Step, Transform, Constraint, Hash, Array, Boolean, …) degrades
+    # gracefully — mirrors MetadataVisitor's recursing override.
+    def on_missing_handler(node, _props, _method_name)
+      box(node)
+    end
+
+    # `>>` — sequence: connect the left's exits to the right's entries.
+    on(:and) do |node, _props|
+      left = visit(node.children[0])
+      right = visit(node.children[1])
+      connect(left[:exits], right[:entries])
+      { entries: left[:entries], exits: right[:exits] }
+    end
+
+    # `|` — fork: no node of its own; union both branches so a preceding step
+    # forks to both entries and a following step joins both exits.
+    on(:or) do |node, _props|
+      left = visit(node.children[0])
+      right = visit(node.children[1])
+      { entries: left[:entries] + right[:entries], exits: left[:exits] + right[:exits] }
+    end
+
+    # Transparent wrappers — recurse into the single inner composition.
+    on(:pipeline) do |node, _props|
+      visit(node.children[0])
+    end
+
+    on(:policy) do |node, _props|
+      visit(node.children[0])
+    end
+
+    # A Metadata node is a box; its label comes from its own metadata (see #label_for).
+    on(:metadata) do |node, _props|
+      box(node)
+    end
+
+    # A Deferred is (possibly) recursive, so render it as an opaque box and do
+    # NOT recurse — mirrors why JSONSchemaVisitor special-cases Deferred.
+    on(:deferred) do |node, _props|
+      box(node)
+    end
+
+    private
+
+    def box(node)
+      id = next_id
+      @nodes << %(#{id}["#{escape(label_for(node))}"])
+      { entries: [id], exits: [id] }
+    end
+
+    def connect(from_ids, to_ids)
+      from_ids.each do |from|
+        to_ids.each { |to| @edges << "#{from} --> #{to}" }
+      end
+    end
+
+    def next_id
+      @counter += 1
+      "n#{@counter}"
+    end
+
+    # Prefer a node's OWN metadata title/label, else fall back to #inspect. Only
+    # nodes that carry metadata directly are consulted — calling #metadata on an
+    # And/Or would merge the whole subtree's metadata (wrong for a single box).
+    def label_for(node)
+      md = own_metadata(node)
+      md[:title] || md[:label] || node.inspect
+    end
+
+    def own_metadata(node)
+      case node.node_name
+      when :metadata then node.metadata
+      when :step then node._metadata
+      else BLANK_HASH
+      end
+    rescue StandardError
+      BLANK_HASH
+    end
+
+    def escape(label) = label.to_s.gsub('"', '#quot;')
+  end
+end

data/lib/plumb/metadata.rb

@@ -12,8 +12,12 @@ module Plumb
       freeze
     end
 
+    # Metadata nodes include their wrapped type in equality; otherwise unrelated
+    # types carrying the same metadata could collapse during subtype reductions.
+    # @param other [Object]
+    # @return [Boolean]
     def ==(other)
-      other.is_a?(self.class) && @metadata == other.metadata
+      other.instance_of?(self.class) && type == other.type && @metadata == other.metadata
     end
 
     def metadata(data = Undefined)
@@ -24,6 +28,11 @@ module Plumb
       end
     end
 
+    # Metadata is a transparent wrapper: it delegates type-flow to the wrapped
+    # type.
+    def input_type = type.input_type
+    def output_type = type.output_type
+
     def call(result) = type.call(result)
 
     private def _inspect = "Metadata[#{type}, #{@metadata.inspect}]"