plumb 0.0.18 → 0.2.0.beta.2

data/lib/plumb/encoder.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+require 'plumb/composable'
+require 'plumb/function'
+
+module Plumb
+  # A reversible, type-aware transform between two representations of a value —
+  # an input type and an output type. Neither side need be a "wire" format: a
+  # serialized string and a parsed Ruby object, or one in-memory data structure
+  # and another, are equally valid. Declared class-based, with the types given
+  # as a one-pair Hash literal:
+  #
+  #   DateRange = Types::Range[Types::Date]
+  #   JSONDateRange = Types::Hash[from: Types::Date, to: Types::Date]
+  #
+  #   class JSONDateRangeEncoder < Plumb::Encoder[JSONDateRange => DateRange]
+  #     def encode(range) = { from: range.begin, to: range.end }
+  #     def decode(hash) = hash[:from]..hash[:to]
+  #   end
+  #
+  # The DEFAULT direction is the declared one (`input => output`, running
+  # #decode) — an encoder composes like a normal Function:
+  #
+  #   JSONDateRange >> JSONDateRangeEncoder >> DateRange   # decode
+  #
+  # Composed next to a type that matches its OUTPUT side instead, it
+  # transparently runs the inverse (#encode, input/output swapped):
+  #
+  #   DateRange >> JSONDateRangeEncoder >> JSONDateRange   # encode
+  #
+  # When the context gives no signal (schema literals, `#/`, `.parse`, an
+  # opaque/Any neighbour) the default direction is used; `.decoding` /
+  # `.encoding` are the explicit escape hatches. Each direction is a plain
+  # {Function} whose proc runs the encoder's method — so subtyping, `#>>`
+  # composition checks and reductions, visitors and the JSON Schema all work
+  # on it with no encoder-specific machinery.
+  class Encoder
+    # Build the parameterized superclass: `Encoder[Input => Output]`.
+    # The pair is a one-pair Hash literal; both sides are wrapped as Plumb
+    # types (a raw Hash becomes a HashClass, so
+    # `Encoder[{from: Date} => DateRange]` works).
+    #
+    # @param pair [Hash] a one-pair Hash: input type => output type
+    # @return [Class]
+    def self.[](pair)
+      unless pair.is_a?(::Hash) && pair.size == 1
+        raise ArgumentError,
+              "#{self}[Input => Output] expects a one-pair Hash (eg. Encoder[Types::String => Types::Date]), " \
+              "got #{pair.inspect}"
+      end
+
+      input, output = pair.first
+      input = Composable.wrap(input)
+      output = Composable.wrap(output)
+      # Singleton methods (unlike class ivars) are inherited by the user's
+      # subclass, so `class Foo < Encoder[A => B]` gets .input_type/.output_type.
+      Class.new(self) do
+        define_singleton_method(:input_type) { input }
+        define_singleton_method(:output_type) { output }
+      end
+    end
+
+    class << self
+      def input_type
+        raise ArgumentError,
+              "#{inspect} declares no types; define it as `class #{inspect} < Plumb::Encoder[Input => Output]`"
+      end
+
+      alias output_type input_type
+
+      # The input type to rewrite for a particular matched output type.
+      # Fixed for a normal encoder — the declared input type, regardless of what
+      # matched. A GENERIC encoder (one whose output_type is a container top like
+      # Types::Range, matching any Range[member]) overrides this to BUILD its input
+      # from the matched node's structure, so `Range[Date]` yields a
+      # `from: Date, to: Date` input and `Range[Integer]` a `from: Integer, …` one.
+      # The codec then rewrites that member type through itself as usual. Mirrors
+      # how the Rewriter reads an Array's element type off the matched node.
+      # @param matched_type [Composable] the type this encoder matched
+      # @return [Composable]
+      def input_type_for(_matched_type) = input_type
+
+      # The default step: the declared `input_type -> output_type` direction,
+      # running #decode. A plain Function — #call validates the input type,
+      # runs the encoder's method, and validates the produced value against
+      # the output type (a wrong return value becomes an invalid Result, not
+      # silent corruption); subtyping identity, accepted type and `#>>` checks
+      # all come with Function. Memoized per subclass (steps are frozen).
+      # @return [Function]
+      def decoding
+        @decoding ||= build_step(:decode, input_type, output_type)
+      end
+
+      # The inverse step: `output_type -> input_type`, running #encode.
+      # @return [Function]
+      def encoding
+        @encoding ||= build_step(:encode, output_type, input_type)
+      end
+
+      # A direction step with one or both sides substituted — used by
+      # Codec::Rewriter to splice in a rewritten input type or a narrowed
+      # output type, keeping each rewritten field a single Function node.
+      #
+      # The substitutions name the ENCODER's declared sides, not the step's
+      # positions, so the caller doesn't have to transpose them per direction:
+      # `input_side` always replaces the declared input, `output_side` the
+      # declared output, whichever end of the step each lands on.
+      # @return [Function]
+      def step(direction, input_side: nil, output_side: nil)
+        base = direction == :decode ? decoding : encoding
+        return base unless input_side || output_side
+
+        in_t, out_t = direction == :decode ? [input_side, output_side] : [output_side, input_side]
+        Function.new(in_t || base.input_type, out_t || base.output_type, base.fn)
+      end
+
+      # Composition-context direction pick when the encoder is the RIGHT
+      # operand (see Composable#to_plumb_type). For `left >> Enc`, orient by
+      # what `left` produces; for a union/intersection, branches describe the
+      # same produced value, so orient by what the sibling produces relative to
+      # what each direction produces. Falls back to the default direction —
+      # the ordinary composition check raises if it genuinely doesn't fit.
+      def to_plumb_type(op:, left:)
+        produced = Plumb::Subtyping.resolved_output(Composable.wrap(left))
+        # `left >> Enc` feeds `left`'s output into the step; in a union/
+        # intersection the branches describe the same produced value.
+        pick_direction(produced, op == :>> ? :consumes : :produces)
+      end
+
+      # Left-position composition (`Enc >> X`, `Enc | X`, ...): a Class has no
+      # Composable operators, so these singleton versions orient against the
+      # right operand and delegate to the oriented step.
+      def >>(other) = oriented_against(other, :>>) >> other
+      def |(other) = oriented_against(other, :|) | other
+      def &(other) = oriented_against(other, :&) & other
+
+      def /(other) = decoding / other
+
+      # Direct use runs the default direction — also the Composable.wrap hook
+      # for context-free positions (schema literals, `Array[Enc]`, `#/`).
+      def to_composable = decoding
+      def call(result) = decoding.call(result)
+      def resolve(...) = decoding.resolve(...)
+      def parse(...) = decoding.parse(...)
+
+      # Value-level conveniences for each direction.
+      def encode(value) = encoding.parse(value)
+      def decode(value) = decoding.parse(value)
+
+      private
+
+      # Build one direction as a plain Function. The transform proc wraps the
+      # encoder's method: exceptions raised inside #encode/#decode become
+      # invalid Results.
+      def build_step(direction, in_type, out_type)
+        if instance_method(direction).owner == Encoder
+          raise ArgumentError, "#{inspect} must implement ##{direction} to be used in this direction"
+        end
+
+        run = new.freeze.method(direction)
+        encoder_class = self
+        step_proc = lambda do |result|
+          result.valid!(run.call(result.value))
+        rescue StandardError => e
+          result.invalid!(errors: "#{encoder_class.inspect}##{direction} failed: #{e.message}")
+        end
+        Function.new(in_type, out_type, step_proc)
+      end
+
+      # Orientation for the LEFT-position operators above, where the encoder
+      # must PRODUCE something the sibling fits: for `>>` the sibling consumes
+      # what we produce, so orient by what it ACCEPTS; in a union/intersection
+      # both sides describe the same resulting value, so orient by what it
+      # produces.
+      def oriented_against(other, op)
+        other = Composable.wrap(other)
+        produced = op == :>> ? Plumb::Subtyping.accepted_type(other) : Plumb::Subtyping.resolved_output(other)
+        pick_direction(produced, :produces)
+      end
+
+      # Pick a direction by matching `candidate` against the two declared sides.
+      # `orient` says which relation `candidate` stands in to this encoder:
+      #   :consumes — it is fed INTO the step (a `>>` neighbour's output), so it
+      #               must match the side the step reads;
+      #   :produces — it is what the step must yield (a union sibling's value,
+      #               or a `>>` right side's accepted input).
+      # Decode (the declared direction) wins ties and is the fallback: encode is
+      # chosen only when it is the unambiguous fit, so an ambiguous, opaque or
+      # unmatched candidate keeps the declared direction and the ordinary
+      # composition check reports it if it genuinely doesn't fit.
+      def pick_direction(candidate, orient)
+        decode_side, encode_side = orient == :consumes ? [input_type, output_type] : [output_type, input_type]
+        return encoding if Plumb::Subtyping.subtype?(candidate, encode_side) &&
+                           !Plumb::Subtyping.subtype?(candidate, decode_side)
+
+        decoding
+      end
+    end
+
+    # The value-level contract. These are also the sentinels build_step checks
+    # (`instance_method(direction).owner == Encoder`), so using an encoder in a
+    # direction it doesn't implement fails at BUILD time with a better message
+    # than these — which is why they stay deliberately plain.
+    def encode(_value) = raise(NotImplementedError, "#{self.class} must implement #encode(value)")
+    def decode(_value) = raise(NotImplementedError, "#{self.class} must implement #decode(value)")
+  end
+end

data/lib/plumb/function.rb

@@ -0,0 +1,347 @@
+# frozen_string_literal: true
+
+require 'plumb/composable'
+require 'plumb/typed_step'
+
+module Plumb
+  # A value-converting join, built by `Composable#transform` / `#build`.
+  # Unlike `And` (a refinement), a `Function` changes the value: it validates
+  # the input (`input_type`), applies `fn`, then declares `output_type`
+  # as the produced type. The input constraints do NOT carry through to the
+  # output, so for subtyping a `Function` is identified by what it *produces*
+  # (its `output_type`). See Plumb::Subtyping.subtype?.
+  class Function
+    include Composable
+    include TypedStep
+
+    # Build a typed function from an input => output pair and a
+    # callable that produces the new value.
+    #
+    #   Plumb::Function[String => Integer] { |result| result.valid(result.value.size) }
+    #   Plumb::Function[callable, String => Integer]
+    #
+    # The callable takes and returns a Result (unlike Composable#transform, whose
+    # block takes a value). With no types, both ends default to Types::Any and
+    # this delegates to .opaque (use that directly if you want an #inspect label).
+    # When input and output are the same type and there's nothing to apply, this
+    # is just that type, so it's returned as-is.
+    #
+    # @param args [Array] (in => out), (callable), or (callable, in => out)
+    # @yield [Result] Result => Result
+    # @return [Composable]
+    def self.[](*args, &block)
+      input_type = Types::Any
+      output_type = Types::Any
+      fn = block || NOOP
+
+      case args
+      in []
+        # no types, no callable: defaults apply
+      in [clb, Hash => inout] if clb.respond_to?(:call)
+        raise ArgumentError, 'expected a callable or a block, not both' if block
+
+        fn = clb
+        input_type, output_type = __set_types(inout)
+      in [clb] if clb.respond_to?(:call)
+        raise ArgumentError, 'expected a callable or a block, not both' if block
+
+        fn = clb
+      in [Hash => inout]
+        input_type, output_type = __set_types(inout)
+      else
+        raise ArgumentError,
+              'expected Plumb::Function[input_type => output_type], Plumb::Function[callable] ' \
+              "or Plumb::Function[callable, input_type => output_type]. Got #{args.inspect}"
+      end
+
+      return input_type if input_type == output_type && fn == NOOP
+
+      if fn == NOOP
+        raise ArgumentError,
+              "defined a function (#{input_type} -> #{output_type}), but no explicit " \
+              "transform block or callable given. \n" \
+              "Should be Plumb::Function[#{input_type} => #{output_type}] { |r| r.valid(new_value_here) }"
+      end
+
+      return opaque(fn) if input_type == Types::Any && output_type == Types::Any
+
+      new(input_type, output_type, fn)
+    end
+
+    # Build an OPAQUE function around a bare `#call(Result) => Result` callable
+    # — see #opaque?. This is what `Composable.wrap` produces for anything
+    # callable, and the canonical builder for the no-declared-types case:
+    # `Function[callable]` is sugar for it and returns the same thing.
+    #
+    # It exists separately only because it takes an `inspect` label, which `.[]`
+    # cannot: declaring any keyword there would make Ruby route the bare hash in
+    # `Function[callable, String => Integer]` into keywords ("unknown keyword:
+    # String") and break that form.
+    #
+    # A GuaranteedFunction, because an opaque function's output check IS `Any`,
+    # which no value can fail: skipping it is provably redundant rather than a
+    # shortcut, which is exactly what that subclass encodes. (The input check is
+    # `Any` too and equally redundant, but #call has to run *some* input check
+    # for typed functions, so that hop stays.)
+    #
+    # Takes the callable positionally, or as a block:
+    #
+    #   Plumb::Function.opaque(some_callable)
+    #   Plumb::Function.opaque(inspect: 'filtered') { |result| result.valid(...) }
+    #
+    # @param callable [#call, nil] Result => Result
+    # @param inspect [String, nil] label to #inspect as, instead of the types
+    # @param identity [Object, nil] what the step IS, for #==. An opaque function
+    #   declares no types, so its callable is all that distinguishes it; pass a
+    #   deterministic token when the block is built fresh per call (see
+    #   Composable#invoke).
+    # @yield [Result] Result => Result
+    # @return [GuaranteedFunction]
+    def self.opaque(callable = nil, inspect: nil, identity: nil, &block)
+      raise ArgumentError, 'expected a callable or a block, not both' if callable && block
+
+      fn = callable || block
+      raise ArgumentError, 'expected a callable or a block' unless fn.respond_to?(:call)
+
+      GuaranteedFunction.new(Types::Any, Types::Any, fn, inspect:, identity:, wrapper: true)
+    end
+
+    def self.__set_types(inout)
+      return [Types::Any, Types::Any] if inout.empty?
+      raise ArgumentError, 'expected single key input_type => output_type' if inout.size > 1
+
+      input_type = Composable.wrap(inout.keys.first)
+      output_type = Composable.wrap(inout.values.first)
+      [input_type, output_type]
+    end
+    private_class_method :__set_types
+
+    # `fn` is the value-level callable — `#call(Result) => Result`. Exposed so
+    # the Decorator can rebuild the node around it, and so an opaque function
+    # can be resolved back to the object it wraps (see Plumb::Attributes.struct_class).
+    attr_reader :children, :input_type, :output_type, :fn, :identity
+
+    # @param inspect [String, nil] label to #inspect as, instead of the types
+    # @param identity [Object, nil] what this function IS, for `#==` — see #==.
+    #   Defaults to `fn`, which is correct whenever `fn` is the caller's own
+    #   callable rather than a wrapper built around it.
+    # @param wrapper [Boolean] whether this node merely WRAPS a caller-supplied
+    #   callable — see #wraps_callable?. Set by .opaque, the only builder that does.
+    def initialize(input_type, output_type, fn = Plumb::NOOP, inspect: nil, identity: nil, wrapper: false)
+      @input_type = input_type
+      @output_type = output_type
+      @fn = fn
+      @inspect_label = inspect
+      @identity = identity || fn
+      @wraps_callable = wrapper
+      @children = [input_type, output_type].freeze
+      freeze
+    end
+
+    # Is this node a plain WRAPPER around a callable the caller handed to Plumb (what
+    # `Composable.wrap` / `.opaque` build), rather than a #transform / #build /
+    # coercion whose #fn is a lambda Plumb built around a value-level block? It is what
+    # singles out a node whose #fn is worth reaching for — a struct class, or a proc a
+    # decorator wants to replace. @see Plumb::Attributes.struct_class
+    #
+    # DECLARED at construction, and not derivable from the types, which say nothing
+    # about it: boundary absorption moves a neighbouring type INTO a wrapper's slot, so
+    # `Types::Integer >> some_proc` is a wrapper with a typed end. @see #absorb_input
+    def wraps_callable? = @wraps_callable
+
+    # Equal when they declare the same types AND apply the same transformation.
+    #
+    # The default Composable#== compares #children, which for a Function is only
+    # `[input_type, output_type]` — so it called any two `String -> Integer` steps
+    # equal regardless of what they do, and any two OPAQUE functions equal regardless
+    # of their callable. A reducer reading #== as node identity then dropped one:
+    # `wrap(proc_a) & wrap(proc_b)` returned just `proc_a`.
+    #
+    # Compared on #identity, not #fn, because #transform wraps the caller's callable in
+    # a FRESH lambda per call — comparing #fn would make two identically-built
+    # transforms unequal, and with them every schema containing one. #identity is the
+    # caller's own callable, or a deterministic token the builder chose (see
+    # Composable#build), so two anonymous blocks still compare unequal.
+    def ==(other)
+      other.is_a?(self.class) &&
+        other.input_type == input_type &&
+        other.output_type == output_type &&
+        other.identity == identity
+    end
+
+    # A Function's #children are [input_type, output_type], so rebuilding it around
+    # new ones also has to carry the callable, the inspect label and the #==
+    # identity — none of which a caller can see. @see Plumb::NodeMapper
+    def with_children(children)
+      self.class.new(children[0], children[1], @fn,
+                     inspect: @inspect_label, identity: @identity, wrapper: @wraps_callable)
+    end
+
+    private def _inspect
+      @inspect_label || %((#{@input_type.inspect} -> #{@output_type.inspect}))
+    end
+
+    def call(result)
+      result.map(@input_type).map(@fn).map(@output_type)
+    end
+
+    # Wraps this function with its output check for fusion.
+    # @return [Proc]
+    # @see #fuse_with
+    protected def fn_with_output_check
+      fn = @fn
+      out = @output_type
+      ->(result) { result.map(fn).map(out) }
+    end
+
+    # Fuses compatible functions while retaining this function's output check;
+    # declared subtype compatibility does not prove what the callable returns.
+    # Returns nil (no fusion) unless:
+    #   - both #calls are the standard input->fn->output mapping (see #fusible?);
+    #   - what self produces is a DIRECT subtype of what other declares as
+    #     input. check_composable! is looser — it relaxes container fields via
+    #     accepted_type (the `encode >> decode` case), and there other's input
+    #     check does real per-field work and must keep running;
+    #   - the dropped check is value-preserving: a coercing input type changes the
+    #     value, so it must keep running.
+    #
+    # @param other [Function]
+    # @return [Function, nil]
+    def fuse_with(other)
+      return nil unless fusable_step? && other.fusable_step?
+      return nil unless Plumb::Subtyping.subtype?(@output_type, other.input_type)
+      return nil unless Plumb::Subtyping.value_preserving?(other.input_type)
+      # Converting output checks must remain explicit between nodes.
+      return nil unless !checks_output? || Plumb::Subtyping.value_preserving?(@output_type)
+
+      fn1 = checks_output? ? fn_with_output_check : @fn
+      fn2 = other.fn
+      # Rebuild as one of the two standard classes, not `other.class`: a node is
+      # fusable because it kept #call, which says nothing about its constructor,
+      # and this one takes (input, output, fn). What has to survive is whether the
+      # final output check still runs — so ask `other`, which may not be a
+      # Function at all (see Implementation::TypeInterface).
+      klass = other.checks_output? ? Function : GuaranteedFunction
+      klass.new(@input_type, other.output_type, ->(result) { result.map(fn1).map(fn2) },
+                identity: [identity, other.identity])
+    end
+
+    # Take `type` as this node's OUTPUT slot, for `self >> type` — so
+    # `(Integer -> Any) >> Types::Float` becomes `(Integer -> Float)`, one node
+    # running one Float check instead of two nodes running an Any hop and a Float
+    # check. @see Composable#absorb_output for the shape; the conditions are here.
+    #
+    # The conditions are about THE SLOT — what is dropped — not about the neighbour.
+    # For `F(B => C) >> D` taking D into the C slot:
+    #
+    #   - C is CHECKED (a plain Function). Its check goes, so C must not TRANSFORM
+    #     (`value_preserving?(C)`, or the value the node produces changes) and D must
+    #     reject everything C rejected. `D <= C` states the latter only while D is
+    #     value-preserving: the subtype relation identifies a converting D by what it
+    #     PRODUCES, and what matters here is what it ACCEPTS. `Types::Static[10] <=
+    #     Types::Integer` holds — its value IS an Integer — yet a Static accepts
+    #     anything, so absorbing it would swallow the dropped Integer check and turn an
+    #     invalid `'abc'` into a valid `10`.
+    #   - C is UNCHECKED (a GuaranteedFunction). Nothing is dropped, so there is nothing
+    #     to prove and D may convert freely — it runs in the slot exactly where the
+    #     no-op ran. When the guarantee already implies D there is nothing to win, and
+    #     that redundant gate is reduce_step's to drop, so decline. Otherwise D takes the
+    #     slot and the node becomes a plain Function, since the check has to run: the
+    #     guarantee goes with the type that carried it.
+    #
+    # Validity, value and order are preserved either way. The ERROR TEXT of a value both
+    # C and D would reject becomes D's, the same trade Optimizer.reduce_union makes when
+    # it absorbs a union branch.
+    def absorb_output(type)
+      return nil unless absorbable? && !step_neighbour?(type)
+
+      if checks_output?
+        return nil unless Plumb::Subtyping.value_preserving?(@output_type)
+        return nil unless Plumb::Subtyping.value_preserving?(type)
+        return nil unless Plumb::Subtyping.subtype?(type, @output_type)
+
+        with_children([@input_type, type])
+      else
+        return nil if Plumb::Subtyping.subtype?(@output_type, type)
+
+        Function.new(@input_type, type, @fn, identity: @identity, wrapper: @wraps_callable)
+      end
+    end
+
+    # Take `type` as this node's INPUT slot, for `type >> self` — so
+    # `Types::Integer >> ->(r) { ... }` becomes `(Integer -> Any)` rather than
+    # `And(Integer, (Any -> Any))`. With #absorb_output, that is what collapses
+    # `Types::Integer >> ->(r) { r } >> Types::Float` to `(Integer -> Float)`:
+    # a little typed pipeline with arbitrary code in the middle.
+    #
+    # Again the conditions are about THE SLOT. For `A >> F(B => C)` taking A into the B
+    # slot, B's check is what goes, so B must not TRANSFORM and A must reject everything
+    # B rejected — `value_preserving?(B) && A <= B`. Here `A <= B` says exactly the right
+    # thing whatever A is: the relation identifies a converting A by what it PRODUCES,
+    # and what B sees IS what A produced. Whether A preserves the value is irrelevant —
+    # A runs either way, in the slot or beside it.
+    #
+    # SCOPE: only an `Any` slot, where both conditions hold trivially and no check is
+    # dropped at all, so errors are preserved verbatim too. The general form is the
+    # left-hand gate drop Optimizer declines, and costs what that costs; see the note in
+    # its header.
+    def absorb_input(type)
+      return nil unless absorbable? && !step_neighbour?(type)
+      return nil unless @input_type.is_a?(AnyClass)
+
+      with_children([type, @output_type])
+    end
+
+    # May a neighbouring type move into one of this node's slots? Only when #call is
+    # the canonical mapping — a replaced #call runs different checks, and nothing can
+    # be assumed about the slots (the same question #fusable_step? asks) — and only
+    # when this node renders as its TYPES. A LABELLED function (#generate, #invoke,
+    # the :default and :rescue policies, a filtered container) inspects as its label
+    # instead, so a type absorbed into a slot would vanish from #inspect; for those the
+    # label is the more useful reading, and the type runs as its own step.
+    private def absorbable? = standard_call? && @inspect_label.nil?
+
+    # Is `type` itself a TYPED STEP? Then the seam belongs to #fuse_with rather than
+    # here: it composes the two fns instead of nesting one node inside the other's slot,
+    # and where fusion declines (two opaque wrappers) both nodes stay so that each #fn
+    # remains reachable. A ROUTING rule, not a soundness one — which rewrite owns the
+    # pair. Everything else is a type, and a type runs as a step whether it sits in a
+    # slot or beside one.
+    private def step_neighbour?(type) = type.is_a?(Plumb::TypedStep)
+
+    # DERIVED, not declared: this family's #call is Function's full
+    # input -> fn -> output or GuaranteedFunction's input -> fn (whose missing
+    # output check is provably redundant, not skipped). Anything else replaced it.
+    #
+    # Asking the method table rather than trusting a class list makes the answer
+    # fail-safe — a new subclass with custom semantics is excluded because it
+    # overrode #call, not because someone remembered to exclude it. FilteredHash
+    # (per-field validation, neither boundary check) is caught that way, so this
+    # file no longer has to know that class exists.
+    # @see Plumb::TypedStep#fusable_step?
+    def standard_call?
+      owner = method(:call).owner
+      owner.equal?(Function) || owner.equal?(GuaranteedFunction)
+    end
+  end
+
+  # A Function whose output check is known *at build time* to be redundant, so
+  # it is simply not run. Two ways to earn that: the proc provably produces
+  # output_type (eg. a `:to_i` coercion always yields an Integer), or the
+  # output_type is `Any`, which nothing can fail — the opaque case, see
+  # Function.opaque. Choosing the class at build time means
+  # #call carries no per-call `guaranteed?` branch — the check is simply absent.
+  # It inherits Function's node_name (:function) and `is_a?(Function)`, so
+  # visitors, JSON-schema, subtyping and the decorator treat it as a Function;
+  # only the produced value's output re-validation is dropped. @output_type is
+  # still kept as metadata (inference / JSON schema / subtyping).
+  class GuaranteedFunction < Function
+    def call(result)
+      result.map(@input_type).map(@fn)
+    end
+
+    # The whole point of the class: no output check runs, so a seam has none to
+    # drop here. @see Plumb::TypedStep#checks_output?
+    def checks_output? = false
+  end
+end