plumb 0.2.0.beta.1 → 0.2.0.beta.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 04bf6f39fffef2ead633842bb41f5cc202bcb837f93de6b39eec34af2db4f3cb
-  data.tar.gz: e28fdab916fb639c37106cb1f7200e364ae0267588ee91b628782c1a8a5587b5
+  metadata.gz: 119f529616c7dfe5fe87e12e26e9cf91f3cb4c28fd19cacf89dc15c271e534de
+  data.tar.gz: 514598daebbf8a7ee477b68c8dd05cb74e9c5102da4f9f7f8a682f2de5939a66
 SHA512:
-  metadata.gz: d310e169c82bfddb24fc1f63a5e8965b9f47e03e00743e7cde1729b5bc54cf0e2a01100ec98497149aa958f2864d4680610efa854310afcab8e4da855ad0db61
-  data.tar.gz: d65eaf8128e53a7c21f4247a489f11d50da0a9b5178836524a20dfd3a89055463e9c7865dd91a552d3c7d0a1dc73a0fc7c874b77d8c06d532ee01aacf8459249
+  metadata.gz: 8997e52706716448c59bff278df20b9768aa0cc1e7d870c3e6dce8d01d15bf248c1ceefd7cff3b91a78462d0a56b8645f1a7085ca6a809aa9701cb4b26bdf862
+  data.tar.gz: e4dcaa6edaf31597fe1985efea84656a4efb1e9ba75a1f72ad9316a36257af79b4f36bafdd3d051f632ee0a7b005cbac3e07d9e051d12d5b7ff18aae8842e077

data/README.md

@@ -519,6 +519,27 @@ str.parse() # 'nope'
 str.parse('yup') # 'yup'
 ```
 
+A block generates the value on every invocation, instead of returning a fixed one:
+
+```ruby
+id = Types::UUID::V4.default { SecureRandom.uuid }
+id.parse() # a fresh UUID each time
+```
+
+The step _declares_ the type it defaults — so a `Types::Date.default { Date.today }`
+is still a `Date` for subtyping, JSON Schema and [Codecs](#encoders-and-codecs) — and
+what the block returns is checked against it, failing where it is defaulted rather
+than somewhere downstream.
+
+What is checked is the type's **output**, and the type itself is not re-run on the
+generated value: a converting type expects the block to produce the converted value.
+
+```ruby
+int = Types::String.transform(::Integer, &:to_i)
+int.default { 10 }.parse()    # 10
+int.default { '10' }.parse()  # raises — a String is not what this type produces
+```
+
 Note that this is syntax sugar for:
 
 ```ruby
@@ -835,6 +856,9 @@ type.resolve('2024-02-02') # => Result::Valid with Date object
 type.resolve('2024-') # => Result::Invalid with error message
 ```
 
+The guard keeps the type it wraps: the example above is still a `Date` for subtyping,
+JSON Schema and [Codecs](#encoders-and-codecs).
+
 ### `Types::Interface`
 
 Use this for objects that must respond to one or more methods.
@@ -2067,6 +2091,34 @@ JSONPerson.to_json_schema
 # "dates" is described as { "type" => "object", "properties" => { "from" => { "type" => "string" }, ... } }
 ```
 
+#### Codec instances: a registry of pre-built pairs
+
+Composing a codec rewrites the whole type tree, so it belongs at boot — not on the path of every message. A codec _instance_ is a registry of `[decoder, encoder]` pairs, each built once by `register` and then looked up by key:
+
+```ruby
+CODECS = JSONCodec.new do |c|
+  c.register('person.created', Person)
+  c.register('company.created', Company)
+  c.register(Types::Date) # the key defaults to the type itself
+end
+
+CODECS.decode('person.created', payload)   # => a Person hash
+CODECS.encode('person.created', person)    # => JSON structures
+CODECS.decode(Types::Date, '2024-01-01')   # => Date
+```
+
+Keys are yours to choose — a message name, a content type, the type itself. `decode` and `encode` only `#parse`, so the rewrite is paid for once.
+
+An instance built with a block is frozen when the block returns. Without one it stays open, and `register` chains:
+
+```ruby
+registry = JSONCodec.new
+registry.register('day', Types::Date).register('person', Person)
+registry.freeze
+```
+
+`key?` asks what is registered; an unknown key raises `Plumb::Codec::NoEntryError` (a `KeyError`). Payloads are still validated by their type — a bad one raises `Plumb::ParseError` as usual.
+
 #### `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`).
@@ -2616,7 +2668,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/ismasan/plumb.
+Bug reports and pull requests are welcome on GitHub at [github.com/ismasan/plumb](https://github.com/ismasan/plumb).
 
 ## License
 

data/lib/plumb/array_class.rb

@@ -45,22 +45,17 @@ module Plumb
     def output_type = Plumb::Subtyping.map_children(self) { |c| Plumb::Subtyping.resolved_output(c) }
 
     def concurrent
-      ConcurrentArrayClass.new(element_type:)
+      concurrent_class.new(element_type:)
     end
 
     def stream
       StreamClass.new(element_type:)
     end
 
+    # A lenient version of this Array: it accepts any Array and emits one with only
+    # the valid elements, dropping the rest. @see FilteredArray
     def filtered
-      Constraint.new(::Array) >> Function.opaque(inspect: "Array[#{element_type}].filtered",
-                                                identity: [:filtered_array, element_type]) do |result|
-        arr = result.value.each.with_object([]) do |e, memo|
-          r = element_type.resolve(e)
-          memo << r.value if r.valid?
-        end
-        result.valid!(arr)
-      end
+      filtered_class.new(element_type:)
     end
 
     def call(result)
@@ -78,6 +73,12 @@ module Plumb
 
     attr_reader :element_type
 
+    # Named, not hardcoded, so the two combine in EITHER order: each subclass points
+    # at the variant that keeps what it already is, instead of the second call
+    # dropping the first.
+    def concurrent_class = ConcurrentArrayClass
+    def filtered_class = FilteredArray
+
     def _inspect
       %(Array[#{element_type}])
     end
@@ -136,6 +137,68 @@ module Plumb
 
         [values, errors]
       end
+
+      def filtered_class = ConcurrentFilteredArray
+    end
+
+    # Same element type as an ArrayClass, but drops invalid elements instead of
+    # rejecting the whole Array. Being an ArrayClass is what keeps it rewritable: a
+    # visitor — or a Codec — that maps the element type rebuilds a FilteredArray, not
+    # a plain one. @see HashMap::FilteredHashMap, the same arrangement for maps.
+    class FilteredArray < self
+      # It drops elements, so it changes the value whatever its element type does.
+      def value_preserving? = false
+
+      # Lenient: it never rejects an Array, so as a #>> consumer it accepts any
+      # enumerable — without this `Types::Array >> Array[String].filtered` is an
+      # illegal narrowing.
+      def accepted_type = Types::Each
+
+      # `Array[T].filtered.stream` IS `Array[T].stream.filtered` — a filtered Stream
+      # drops the same elements, lazily.
+      def stream = super.filtered
+
+      def call(result)
+        return result.invalid!(errors: 'is not an Array') unless ::Array === result.value
+
+        result.valid!(valid_elements(result.value))
+      end
+
+      private
+
+      def concurrent_class = ConcurrentFilteredArray
+
+      # The only thing the concurrent variant replaces. No errors to collect, unlike
+      # #map_array_elements — an invalid element is simply not there.
+      def valid_elements(array)
+        array.each.with_object([]) do |e, memo|
+          r = element_type.resolve(e)
+          memo << r.value if r.valid?
+        end
+      end
+
+      def _inspect = "Array[#{element_type}].filtered"
+    end
+
+    # Both at once, reached from either side (`.filtered.concurrent`,
+    # `.concurrent.filtered`), and itself under both.
+    class ConcurrentFilteredArray < FilteredArray
+      private
+
+      def filtered_class = ConcurrentFilteredArray
+
+      # A rejected future re-raises, as ConcurrentArrayClass does: an element step
+      # that RAISED is a bug to surface, not an element to drop.
+      def valid_elements(array)
+        futures = array.map { |e| Concurrent::Future.execute { element_type.resolve(e) } }
+
+        futures.each_with_object([]) do |future, memo|
+          r = future.value # blocks until settled; nil when rejected
+          raise future.reason if future.rejected?
+
+          memo << r.value if r.valid?
+        end
+      end
     end
   end
 end

data/lib/plumb/codec.rb

@@ -32,9 +32,8 @@ module Plumb
   # algebra, so parsing, subtyping and visitors work on it unchanged. It works
   # on any type, not just Hash schemas: `JSONCodec >> Types::Date` returns the
   # matched encoder's decode step.
+  #
   class Codec
-    include Composable
-
     class << self
       # Register one or more Encoder subclasses, in matching-priority order.
       # The registry is inheritable: subclassing a codec extends it, and a
@@ -46,7 +45,7 @@ module Plumb
             raise ArgumentError, "expected an Encoder subclass, got #{enc.inspect}"
           end
 
-          own_encoders << enc
+          encoders << enc
         end
         self
       end
@@ -56,154 +55,179 @@ module Plumb
       # nothing. Real encoders always match first, so a noop never shadows a
       # registered encoder for the same type.
       def noop(*types)
-        types.each { |t| own_noop_types << Composable.wrap(t) }
+        types.each { |t| noop_types << Composable.wrap(t) }
         self
       end
 
-      # All registered encoders, inherited first, own last (later registrations
-      # win ties in matching).
-      def encoders = inherited_registry(:encoders, own_encoders)
+      # A subclass starts from a COPY of its parent's registries and appends its own,
+      # so `encoders` reads inherited-first, own-last (later registrations win ties in
+      # matching). Copied at subclass time rather than resolved at read time because
+      # registration happens in a class body: a parent is complete before a subclass
+      # of it exists.
+      def inherited(subclass)
+        super
+        subclass.encoders = encoders.dup
+        subclass.noop_types = noop_types.dup
+      end
 
-      # All registered pass-through types, inherited first.
-      def noop_types = inherited_registry(:noop_types, own_noop_types)
+      def encoders = @encoders ||= []
+      def noop_types = @noop_types ||= []
 
-      # Class-level composition delegates to a memoized instance, so a Codec
-      # subclass composes directly: `JSONCodec >> Person`.
-      def instance = @instance ||= new
-      def >>(other) = instance >> other
-      def |(other) = instance | other
-      def &(other) = instance & other
-      def for(type) = instance.for(type)
-      def to_plumb_type(op:, left:) = instance.to_plumb_type(op:, left:)
-      def to_composable = instance
-      def call(result) = instance.call(result)
+      # Only #inherited seeds a registry; everything else registers through
+      # #encoder / #noop.
+      attr_writer :encoders, :noop_types
+      protected :encoders=, :noop_types=
 
-      private
+      # Decode direction: rewrite `other` so it accepts the encoders' input form
+      # and produces the output values `other` describes. The rewritten type
+      # REPLACES the composition — no codec node remains.
+      def >>(other)
+        Rewriter.new(self, :decode).call(Composable.wrap(other))
+      end
 
-      # A registry a subclass extends rather than replaces: whatever the
-      # ancestor exposes under `name`, plus this class's own registrations.
-      def inherited_registry(name, own)
-        inherited = superclass.respond_to?(name) ? superclass.public_send(name) : BLANK_ARRAY
-        inherited + own
+      # Both directions for a type, as a [decoding, encoding] pair:
+      #
+      #   decoder, encoder = Plumb::Codec::JSON.for(Person)
+      #   decoder.parse(input_data) # => a Person hash
+      #   encoder.parse(person)     # => output structures
+      #
+      # @param type [Composable, Object]
+      # @return [Array(Composable, Composable)]
+      def for(type)
+        type = Composable.wrap(type)
+        [self >> type, type >> self]
+      end
+
+      # Encode direction, reached when the codec is the RIGHT operand
+      # (`Person >> JSONCodec` — see Composable.resolve_operand): build an encode
+      # rewrite of what `left` produces. Composable#>> then composes
+      # `And(left, rewrite)`: the left validates its input once, the
+      # rewrite encodes. Building from `left`'s OUTPUT (not `left` itself)
+      # avoids re-running its coercions on already-parsed values.
+      def to_plumb_type(op:, left:)
+        unless op == :>>
+          raise Plumb::TypeError, "#{inspect} only composes with #>> (got #{op}); a Codec is not a value type"
+        end
+
+        left = Composable.wrap(left)
+        # A plain-include struct wraps as an opaque Step (output Any), so its
+        # rewrite target is the struct node itself, not its resolved output.
+        target = Plumb::Attributes.struct_class(left) ? left : Plumb::Subtyping.resolved_output(left)
+        Rewriter.new(self, :encode).call(target)
       end
 
-      def own_encoders = @own_encoders ||= []
-      def own_noop_types = @own_noop_types ||= []
-    end
+      def |(_other) = raise Plumb::TypeError, "#{inspect} only composes with #>>; a Codec is not a value type"
+      alias & |
 
-    attr_reader :encoders, :noop_types
+      # A Codec is not a value type, and has no node to stand in for one. Both of
+      # these say so at the point of the mistake — without #to_composable,
+      # Composable.wrap would see a `#call` and build an opaque step out of the class.
+      def to_composable = raise(Plumb::TypeError, "#{inspect} is not a type; compose it with a type via #>>")
 
-    # @param extra_encoders [Array<Class>] encoders for this instance, appended
-    #   after (and winning ties over) the class-level registry.
-    def initialize(*extra_encoders)
-      @encoders = self.class.encoders + extra_encoders
-      @noop_types = self.class.noop_types
-      @noop_union = @noop_types.reduce(:|)
-      freeze
-    end
+      def call(_result)
+        raise Plumb::TypeError, "#{inspect} is not a runtime type; compose it with a type via #>>"
+      end
 
-    # Decode direction: rewrite `other` so it accepts the encoders' input form
-    # and produces the output values `other` describes. The rewritten type
-    # REPLACES the composition — no codec node remains.
-    def >>(other)
-      Rewriter.new(self, :decode).call(Composable.wrap(other))
-    end
+      # The best matching encoder for `type`, or nil. Matching is against each
+      # encoder's output type — schemas are written in output
+      # terms in both directions. Most-specific wins; equivalent types
+      # tie-break to the last registered; incomparable multi-matches raise.
+      def encoder_for(type, path = BLANK_ARRAY)
+        matches = encoders.select { |e| Plumb::Subtyping.subtype?(type, e.output_type) }
+        return nil if matches.empty?
+        return matches.first if matches.size == 1
 
-    # Both directions for a type, as a [decoding, encoding] pair:
-    #
-    #   decoder, encoder = Plumb::Codec::JSON.for(Person)
-    #   decoder.parse(input_data) # => a Person hash
-    #   encoder.parse(person)     # => output structures
-    #
-    # @param type [Composable, Object]
-    # @return [Array(Composable, Composable)]
-    def for(type)
-      type = Composable.wrap(type)
-      [self >> type, type >> self]
-    end
+        minimal = matches.reject do |e|
+          # e is dominated when another match's output type is strictly narrower.
+          matches.any? do |o|
+            !o.equal?(e) && Plumb::Subtyping.strict_subtype?(o.output_type, e.output_type)
+          end
+        end
 
-    # Encode direction, reached when the codec is the RIGHT operand
-    # (`Person >> JSONCodec` — see Composable#to_plumb_type): build an encode
-    # rewrite of what `left` produces. Composable#>> then composes
-    # `And(left, rewrite)`: the left validates its input once, the
-    # rewrite encodes. Building from `left`'s OUTPUT (not `left` itself)
-    # avoids re-running its coercions on already-parsed values.
-    def to_plumb_type(op:, left:)
-      unless op == :>>
-        raise Plumb::TypeError, "#{inspect} only composes with #>> (got #{op}); a Codec is not a value type"
-      end
-
-      left = Composable.wrap(left)
-      # A plain-include struct wraps as an opaque Step (output Any), so its
-      # rewrite target is the struct node itself, not its resolved output.
-      target = Plumb::Attributes.struct_class(left) ? left : Plumb::Subtyping.resolved_output(left)
-      Rewriter.new(self, :encode).call(target)
-    end
+        first = minimal.first
+        unless minimal.all? { |e| Plumb::Subtyping.equivalent?(e.output_type, first.output_type) }
+          raise Plumb::TypeError,
+                "#{inspect}: #{at_path(path)} (#{type.inspect}) matches multiple incomparable encoders: " \
+                "#{minimal.map(&:inspect).join(', ')}. Register a more specific encoder or restructure."
+        end
 
-    def |(_other) = raise Plumb::TypeError, "#{inspect} only composes with #>>; a Codec is not a value type"
-    alias & |
+        minimal.last
+      end
 
-    def call(_result)
-      raise Plumb::TypeError, "#{inspect} is not a runtime type; compose it with a type via #>>"
-    end
+      # Is `type` (one side of it, per direction) covered by the registered noop
+      # types? Decode checks what the type ACCEPTS (it will be fed raw input
+      # data); encode checks what it PRODUCES (its output lands in the encoded
+      # document).
+      def noop?(type, direction)
+        return false unless noop_union
 
-    # The best matching encoder for `type`, or nil. Matching is against each
-    # encoder's output type — schemas are written in output
-    # terms in both directions. Most-specific wins; equivalent types
-    # tie-break to the last registered; incomparable multi-matches raise.
-    def encoder_for(type, path = BLANK_ARRAY)
-      matches = encoders.select { |e| Plumb::Subtyping.subtype?(type, e.output_type) }
-      return nil if matches.empty?
-      return matches.first if matches.size == 1
-
-      minimal = matches.reject do |e|
-        # e is dominated when another match's output type is strictly narrower.
-        matches.any? do |o|
-          !o.equal?(e) && Plumb::Subtyping.strict_subtype?(o.output_type, e.output_type)
-        end
+        side = direction == :decode ? Plumb::Subtyping.accepted_type(type) : Plumb::Subtyping.resolved_output(type)
+        # A pure filter with an opaque side is judged by the type itself: a
+        # bare-matcher Constraint (a branch of a factored refinement union, eg.
+        # the `String[/\Atrue\z/i] | String['1']` boolean input type) reports Any
+        # as its accepted type, but as a value-preserving refinement it IS its
+        # own honest description.
+        side = type if side.is_a?(AnyClass) && Plumb::Subtyping.value_preserving?(type)
+        Plumb::Subtyping.subtype?(side, noop_union)
       end
 
-      first = minimal.first
-      unless minimal.all? { |e| Plumb::Subtyping.equivalent?(e.output_type, first.output_type) }
-        raise Plumb::TypeError,
-              "#{inspect}: #{at_path(path)} (#{type.inspect}) matches multiple incomparable encoders: " \
-              "#{minimal.map(&:inspect).join(', ')}. Register a more specific encoder or restructure."
+      # Is this concrete VALUE covered by the noop types? Used for Static nodes,
+      # whose fixed value can be validated directly — subtyping over the node
+      # can't relate an atomic Static to a container noop (`Static[[]]` vs
+      # `Types::Array`), but the value itself can just be checked.
+      def noop_value?(value)
+        return false unless noop_union
+
+        noop_union === value
       end
 
-      minimal.last
+      def at_path(path) = path.empty? ? 'the root type' : "field `#{path.join('.')}`"
+
+      # Named, so an anonymous `Class.new(Codec)` still says what it carries.
+      def inspect = "#{name || superclass.name}[#{encoders.map(&:inspect).join(', ')}]"
+
+      private
+
+      # Derived from #noop_types, so resolved once — after boot, when the first
+      # composition asks.
+      def noop_union
+        return @noop_union if defined?(@noop_union)
+
+        @noop_union = noop_types.reduce(:|)
+      end
     end
 
-    # Is `type` (one side of it, per direction) covered by the registered noop
-    # types? Decode checks what the type ACCEPTS (it will be fed raw input
-    # data); encode checks what it PRODUCES (its output lands in the encoded
-    # document).
-    def noop?(type, direction)
-      return false unless @noop_union
-
-      side = direction == :decode ? Plumb::Subtyping.accepted_type(type) : Plumb::Subtyping.resolved_output(type)
-      # A pure filter with an opaque side is judged by the type itself: a
-      # bare-matcher Constraint (a branch of a factored refinement union, eg.
-      # the `String[/\Atrue\z/i] | String['1']` boolean input type) reports Any
-      # as its accepted type, but as a value-preserving refinement it IS its
-      # own honest description.
-      side = type if side.is_a?(AnyClass) && Plumb::Subtyping.value_preserving?(type)
-      Plumb::Subtyping.subtype?(side, @noop_union)
+    Entry = Data.define(:decoder, :encoder)
+    NoEntryError = Class.new(KeyError)
+
+    def initialize(&)
+      @entries = {}
+      return unless block_given?
+
+      yield self
+      freeze
     end
 
-    # Is this concrete VALUE covered by the noop types? Used for Static nodes,
-    # whose fixed value can be validated directly — subtyping over the node
-    # can't relate an atomic Static to a container noop (`Static[[]]` vs
-    # `Types::Array`), but the value itself can just be checked.
-    def noop_value?(value)
-      return false unless @noop_union
+    def freeze
+      @entries.freeze
+      super
+    end
 
-      @noop_union === value
+    # Named, not splatted: both sides are types that #parse, so a swapped pair would
+    # decode where it should encode without anything raising.
+    def register(key, type = key)
+      decoder, encoder = self.class.for(type)
+      @entries[key] = Entry.new(decoder:, encoder:)
+      self
     end
 
-    def at_path(path) = path.empty? ? 'the root type' : "field `#{path.join('.')}`"
+    def key?(key) = @entries.key?(key)
 
-    private def _inspect
-      "#{self.class == Codec ? 'Plumb::Codec' : self.class.name}[#{encoders.map(&:inspect).join(', ')}]"
+    def decode(key, payload) = entry(key).decoder.parse(payload)
+    def encode(key, payload) = entry(key).encoder.parse(payload)
+
+    def inspect
+      %(#<#{self.class}:#{object_id} [#{@entries.size} entries]>)
     end
 
     # The deep rewrite walker. Top-down, per node:
@@ -293,11 +317,16 @@ module Plumb
           return NodeMapper.map(type) { |t| visit(t, path) }
         end
 
+        # Before encoder matching, for the Static reason: a source IS a subtype of what
+        # it declares, so an encoder would replace the code that produces the value.
+        return visit_source(type, path) if source_step?(type)
+
         enc = encoder_for(type, path)
         return replace(type, enc, path) if enc
 
         case type
         when HashClass then visit_hash(type, path)
+        when FilteredHash then visit_filtered_hash(type, path)
         when ArrayClass, StreamClass then visit_array(type, path)
         when TupleClass then visit_tuple(type, path)
         when HashMap then visit_hash_map(type, path)
@@ -311,13 +340,37 @@ module Plumb
         end
       end
 
-      # A leaf: nothing to recurse into structurally. It survives when the
-      # format already carries it (the noop check), or — decoding — when the
+      # A leaf: nothing to recurse into structurally. It survives when it is OPAQUE,
+      # when the format already carries it (the noop check), or — decoding — when the
       # codec can bridge what it CONSUMES.
       def visit_leaf(type, path)
+        return type if opaque_step?(type)
+
         bridge_input(type, path) || noop_or_fail(type, path)
       end
 
+      # An OPAQUE step (`Any -> Any`) is a black box — a `#generate` generator, a bare
+      # proc in a schema. It names no type to rewrite, so it passes through, and what
+      # it emits lands unencoded, exactly as its `Any` output says.
+      def opaque_step?(type) = type.is_a?(Plumb::TypedStep) && type.opaque?
+
+      # A SOURCE step declares `Any -> T`: it produces a T out of whatever it is
+      # handed. The `#default { }` generator is one.
+      def source_step?(type)
+        type.is_a?(Plumb::TypedStep) && type.input_type.is_a?(AnyClass) && !type.output_type.is_a?(AnyClass)
+      end
+
+      # DECODE: leave it alone. Accepting `Any` it already accepts the encoded form,
+      # and it produces the decoded value itself (`Date.default { Date.today }` yields
+      # a Date, not a wire string).
+      #
+      # ENCODE: the rewrite is composed AFTER the type it encodes (see
+      # Codec#to_plumb_type), so the source has already run and the T it declared is
+      # what sits here. Rewriting the node would run the generator a second time.
+      def visit_source(type, path)
+        @direction == :decode ? type : visit(type.output_type, path)
+      end
+
       # DECODE: a converting leaf (a Function, a Plumb::Implementation — any node
       # whose accepted type is a distinct node) consumes values the encoded
       # document does not carry: `Hash[time: Time] -> Thing` wants a Time, a JSON
@@ -443,12 +496,10 @@ module Plumb
         # constant) still rewrite their input once.
         input = enc.input_type_for(type)
         rewritten_input = @input_memo.fetch(type) do
-          begin
-            @input_stack.push(enc)
-            @input_memo[type] = visit(input, path + ["<#{enc.inspect} input>"])
-          ensure
-            @input_stack.pop
-          end
+          @input_stack.push(enc)
+          @input_memo[type] = visit(input, path + ["<#{enc.inspect} input>"])
+        ensure
+          @input_stack.pop
         end
 
         # Splice the input into the step unless it is the encoder's declared
@@ -480,6 +531,21 @@ module Plumb
         end
       end
 
+      # DECODE rewrites the schema a filter FILTERS and rebuilds the filter around it,
+      # so decoding happens inside it, per field: #bridge_input's spliced step would
+      # decode the whole hash first, making one unreadable field fatal — what
+      # .filtered exists to avoid. (The filtered Array and HashMap need none of this;
+      # being containers they rewrite through #visit_array / #visit_hash_map.)
+      #
+      # ENCODE: `resolved_output` reduces the filter to its relaxed schema before the
+      # rewrite, so this is only reached defensively.
+      def visit_filtered_hash(type, path)
+        return visit(type.output_type, path) unless @direction == :decode
+
+        schema = visit(type.input_type, path)
+        schema.equal?(type.input_type) ? type : schema.filtered
+      end
+
       def visit_array(type, path)
         return noop_or_fail(type, path) if type.children.first.is_a?(AnyClass) # untyped — a leaf
 
@@ -507,11 +573,16 @@ module Plumb
         NodeMapper.map_children(type) { |variant| visit(variant, path) }
       end
 
+      # Rewriting can collapse two branches onto the SAME node — encoding a
+      # `#default { }`, both resolve to the type. Keep one: the second is unreachable,
+      # and a failing encode would otherwise report its errors twice.
       def visit_or(type, path)
         left, right = type.children
         l = visit(left, path)
         r = visit(right, path)
-        l.equal?(left) && r.equal?(right) ? type : Disjunction.build(l, r)
+        return type if l.equal?(left) && r.equal?(right)
+
+        l == r ? l : Disjunction.build(l, r)
       end
 
       # A MEET: a data-bearing type refined by pure filters (a #where's
@@ -560,27 +631,41 @@ module Plumb
       # Rewriting it too decodes twice: #bridge_input splices `b`'s own decode step in
       # front, the already-decoded value hits a step expecting the encoded form, and the
       # pipeline rejects everything. A step only counts as having consumed the wire if
-      # its rewrite actually CHANGED it.
+      # its rewrite actually CHANGED it — or if it is a black box, which says the same
+      # thing: what it hands on is unknown. `Types::Integer.generate { 1 }` is
+      # `(opaque >> Integer)`, and rewriting that Integer into the codec's
+      # `String -> Integer` step would feed it the generated Integer and reject
+      # everything.
       def visit_composition(type, path)
         left, right = type.children
         l = pure_refinement?(left) ? left : visit(left, path)
-        # `right` receives what `left` produced, so it faces the wire only when
-        # `left`'s rewrite left it unchanged.
-        wire_consumed = @direction == :decode && !l.equal?(left)
-        r = pure_refinement?(right) || wire_consumed ? right : visit(right, path)
+        r = pure_refinement?(right) || wire_consumed?(left, l) ? right : visit(right, path)
 
         l.equal?(left) && r.equal?(right) ? type : Conjunction.build(l, r)
       end
 
+      # Encoding, nothing consumes a wire: every step is rewritten in place.
+      def wire_consumed?(left, rewritten)
+        return false unless @direction == :decode
+
+        !rewritten.equal?(left) || opaque_step?(rewritten) || source_step?(rewritten)
+      end
+
       # A pure refinement carries no encodable type — it filters the adjacent
       # type's values. A baseless Constraint refining a sibling qualifies, but a
       # base-type Constraint — `Types::Date` IS `Constraint(::Date)` — is data an
       # encoder must see (eg. in `Types::Date.where(year: ...)` ==
       # `And(Constraint(::Date), AVM)`), and so is a baseless Module gate, which
       # names a type rather than filtering one.
+      #
+      # `Any` is the TRIVIAL filter, so it qualifies too — but only ALONGSIDE a sibling
+      # that carries a type; on its own it is still a leaf, and still an error. It gets
+      # here from an opaque step's output slot, which is what `resolved_output` leaves
+      # behind (`Integer.generate { 1 }` resolves to `(Any >> Integer)`): the value is
+      # unknown until the Integer beside it vouches for it, and that is what to encode.
       def pure_refinement?(child)
         case child
-        when AttributeValueMatch, ValueClass, Not then true
+        when AttributeValueMatch, ValueClass, Not, AnyClass then true
         when Constraint then child.base.nil? && !child.matcher.is_a?(::Module)
         else false
         end
@@ -608,7 +693,6 @@ module Plumb
                 'Register an encoder for it, or declare it with .noop.'
         end
       end
-
     end
 
     # ------------------------------------------------------------------
@@ -634,9 +718,10 @@ module Plumb
       def decode(str) = ::Date.parse(str)
     end
 
-    # Time <=> ISO 8601 date-time string ("2024-08-30T20:15:23Z").
+    # Time <=> ISO 8601 date-time string ("2024-08-30T20:15:23.456789Z").
+    #
     class TimeEncoder < Encoder[Types::String[TIME_EXPR].metadata(format: 'date-time') => Types::Time]
-      def encode(time) = time.iso8601
+      def encode(time) = time.iso8601(6)
       def decode(str) = ::Time.parse(str)
     end
 
@@ -791,5 +876,11 @@ module Plumb
       encoder DateEncoder, TimeEncoder, SymbolEncoder, DecimalEncoder
       encoder URIEncoder, HTTPURIEncoder, FileURIEncoder
     end
+
+    private
+
+    def entry(key)
+      @entries.fetch(key) { raise NoEntryError, "no encoder/decoder registered for #{key}" }
+    end
   end
 end

data/lib/plumb/composable.rb

@@ -232,8 +232,8 @@ module Plumb
         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 class to its instance. Used in schema literals,
+        # 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.

data/lib/plumb/hash_class.rb

@@ -453,11 +453,12 @@ module Plumb
     # A filtered Hash is lenient: it accepts ANY hash and drops invalid/missing/
     # extra fields (it never rejects a Hash), so as a #>> consumer it accepts any
     # hash-like value. (Its #input_type still declares the schema it relaxes.)
-    # Memoized at the class level (instances are frozen; Types isn't loaded yet
-    # when this file is).
-    def self.each_pair_interface = @each_pair_interface ||= Types::Interface[:each_pair]
+    def accepted_type = Types::EachPair
 
-    def accepted_type = FilteredHash.each_pair_interface
+    # Re-derived, NOT rebuilt around the old #fn: the filter closes over the schema it
+    # was built from, so Function#with_children returns a node that inspects as the
+    # new schema and still filters by the old one.
+    def with_children(children) = children.first.filtered
 
     # Neither boundary check runs — the per-field validation in HashClass#filtered
     # subsumes both. Overriding #call is also what excludes this node from fusion,

data/lib/plumb/hash_map.rb

@@ -93,11 +93,7 @@ module Plumb
       # entries (it never rejects a Hash), so as a #>> consumer it accepts any
       # hash-like value — not itself. Without this, `Hash >> Hash[K, V].filtered`
       # would be flagged as an illegal narrowing.
-      # Memoized at the class level (instances are frozen; Types isn't loaded
-      # yet when this file is).
-      def self.each_pair_interface = @each_pair_interface ||= Types::Interface[:each_pair]
-
-      def accepted_type = FilteredHashMap.each_pair_interface
+      def accepted_type = Types::EachPair
 
       def call(result)
         result.invalid(errors: 'must be a Hash') unless result.value.is_a?(::Hash)

data/lib/plumb/stream_class.rb

@@ -41,11 +41,7 @@ module Plumb
     # #>> composition check. This lets a producer of a raw Enumerator/Array (eg.
     # a CSV enumerator) feed a Stream. Covariant Stream[X] <= Stream[Y]
     # subtyping is unaffected (that goes through #subtype_of? / #children).
-    # Memoized at the class level (instances are frozen; Types isn't loaded yet
-    # when this file is) — #call hits it on every data invocation.
-    def self.each_interface = @each_interface ||= Types::Interface[:each]
-
-    def input_type = StreamClass.each_interface
+    def input_type = Types::Each
 
     # The [Step] interface
     # @param result [Result]

data/lib/plumb/types.rb

@@ -96,11 +96,16 @@ module Plumb
   # Works with a block too:
   #   date = Type::Any[Date].default { Date.today }
   #
+  # A generated default declares, and is checked against, `type`'s OUTPUT — not `type`
+  # itself, which would re-run a conversion on a value the block already produced
+  # (`Types::String.transform(::Integer).default { 10 }` generates the Integer).
+  # Declaring it also tells the rest of the library what fills this position: without
+  # it the branch resolves to `Any`, and a Codec has nothing to encode.
   policy :default, helper: true do |type, value = Undefined, &block|
     val_type = if value == Undefined
-                 Function.opaque(inspect: 'default proc', identity: [:default, block]) do |result|
-                   result.valid(block.call)
-                 end
+                 fn = ->(result) { result.valid(block.call) }
+                 Function.new(Types::Any, Plumb::Subtyping.resolved_output(type), fn,
+                              inspect: 'default proc', identity: [:default, block])
                else
                  Types::Static[value]
                end
@@ -112,12 +117,20 @@ module Plumb
   # Expect a specific exception class, and return an invalid result if it is raised.
   # Usage:
   #   type = Types::String.build(Date, :parse).policy(:rescue, Date::Error)
+  #
+  # The guard returns what `type` returned, so it declares `type`'s OUTPUT — opaque,
+  # it would erase the type it wraps (the closure is invisible) and resolve to `Any`.
+  # Unchecked: `type` already validated what it produced. The INPUT stays `Any`, or
+  # `type`'s own input check runs a second time, outside the rescue.
   policy :rescue do |type, exception_class|
-    Function.opaque(inspect: 'Rescue', identity: [:rescue, type, exception_class]) do |result|
+    fn = lambda do |result|
       type.call(result)
     rescue exception_class => e
       result.invalid(errors: e.message)
     end
+
+    GuaranteedFunction.new(Types::Any, Plumb::Subtyping.resolved_output(type), fn,
+                           inspect: 'Rescue', identity: [:rescue, type, exception_class])
   end
 
   # Split a string into an array. Default separator is /\s*,\s*/
@@ -168,6 +181,10 @@ module Plumb
     Email = String[URI::MailTo::EMAIL_REGEXP].as_node(:email)
     Date = Any[::Date]
     Time = Any[::Time]
+    # What a lenient container accepts (a Stream, a `.filtered` Array/Hash/HashMap).
+    # Here, not beside those classes, because Types is loaded after all of them.
+    Each = Interface[:each]
+    EachPair = Interface[:each_pair]
 
     # A type that recursively converts string keys to symbols in nested hashes.
     # This is commonly used for normalizing payload data in commands and events.

data/lib/plumb/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Plumb
-  VERSION = '0.2.0.beta.1'
+  VERSION = '0.2.0.beta.2'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: plumb
 version: !ruby/object:Gem::Version
-  version: 0.2.0.beta.1
+  version: 0.2.0.beta.2
 platform: ruby
 authors:
 - Ismael Celis