predicator 1.2.1 → 2.0.0

data/lib/predicator/evaluator/arithmetic.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module Predicator
+  module Evaluator
+    # The five arithmetic opcodes, as the reference's ISA (docs/isa.md,
+    # section 5) states them: the handlers {Machine} runs for their rows of
+    # {INSTRUCTIONS}, and the rule each applies to its pair of operands.
+    #
+    # Integer and Float stay apart: two Integers answer an Integer, and a
+    # Float on either side answers a Float. A Float answer that is not finite
+    # (an overflow) has no member in the value domain, and is refused as an
+    # EvaluationError with the reason non_finite_number; the reference has no
+    # answer there of its own to follow. Integers have no bound.
+    #
+    # A pair no rule takes is a TypeMismatchError whose reason is the opcode,
+    # or the unbound-variable error when an operand is the undefined an
+    # unbound load pushed.
+    module Arithmetic
+      # What a pair no rule takes answers inside this module.
+      NO_RULE = Object.new.freeze
+
+      # What each opcode's refusal says it wanted.
+      WANTED = {
+        "add" => "a number or a string", "subtract" => "a number or a date", "multiply" => "a number",
+        "divide" => "a number", "modulo" => "an integer"
+      }.freeze
+
+      private
+
+      def add(at) = arithmetic(at, "add") { |left, right| sum(left, right) }
+      def subtract(at) = arithmetic(at, "subtract") { |left, right| difference(left, right) }
+      def multiply(at) = arithmetic(at, "multiply") { |left, right| numbers?(left, right) ? left * right : NO_RULE }
+
+      # The zero check runs before the type check, for an Integer 0 and a
+      # Float 0.0 (negative zero included) alike. Two Integers divide by
+      # truncating toward zero.
+      def divide(at)
+        arithmetic(at, "divide", zero: ->(right) { number?(right) && right.zero? }) do |left, right|
+          next NO_RULE unless numbers?(left, right)
+
+          left.is_a?(Integer) && right.is_a?(Integer) ? truncated_quotient(left, right) : left / right
+        end
+      end
+
+      # Integers only, a Float operand included in the refusal. The zero
+      # check runs before the type check for an Integer 0 alone: a Float 0.0
+      # is a type mismatch, not modulo by zero. The remainder takes the sign
+      # of the dividend.
+      def modulo(at)
+        arithmetic(at, "modulo", zero: ->(right) { right.is_a?(Integer) && right.zero? }) do |left, right|
+          left.is_a?(Integer) && right.is_a?(Integer) ? left.remainder(right) : NO_RULE
+        end
+      end
+
+      # Pops right then left, refuses a zero divisor when zero says so, and
+      # pushes what the rule answers.
+      def arithmetic(at, opcode, zero: nil)
+        return insufficient(opcode) if @stack.size < 2
+
+        right = @stack.pop
+        left = @stack.pop
+        return by_zero(opcode) if zero&.call(right)
+
+        answer = yield(left, right)
+        return mismatch_pair(opcode, WANTED.fetch(opcode), left, right) if NO_RULE.equal?(answer)
+        return non_finite(opcode) if answer.is_a?(Float) && !answer.finite?
+
+        push(at, answer)
+      end
+
+      # Numbers add. Strings join, and a number beside a string is written
+      # as text first. Lists join. A date or a datetime and a duration, in
+      # either order, move the date.
+      def sum(left, right)
+        return left + right if numbers?(left, right) || both?(left, right, String) || both?(left, right, Array)
+        return text(left) + text(right) if text_pair?(left, right)
+
+        shifted(left, right)
+      end
+
+      def text_pair?(left, right) = (left.is_a?(String) && number?(right)) || (number?(left) && right.is_a?(String))
+
+      def text(value) = value.is_a?(String) ? value : number_text(value)
+
+      # A date or a datetime moved forward by a duration on either side.
+      def shifted(left, right)
+        return Chronology.shift(left, right, 1) if Chronology.chronological?(left) && right.is_a?(Duration)
+        return Chronology.shift(right, left, 1) if left.is_a?(Duration) && Chronology.chronological?(right)
+
+        NO_RULE
+      end
+
+      # Numbers subtract. Two dates or datetimes answer the duration between
+      # them, and a date or a datetime minus a duration moves it back. No
+      # string or list rule: subtract never joins.
+      def difference(left, right)
+        return left - right if numbers?(left, right)
+        return Chronology.difference(left, right) if Chronology.chronological?(left) && Chronology.chronological?(right)
+        return Chronology.shift(left, right, -1) if Chronology.chronological?(left) && right.is_a?(Duration)
+
+        NO_RULE
+      end
+
+      def number?(value) = value.is_a?(Integer) || value.is_a?(Float)
+      def numbers?(left, right) = number?(left) && number?(right)
+      def both?(left, right, type) = left.is_a?(type) && right.is_a?(type)
+
+      def number_text(number) = number.is_a?(Float) ? FloatText.spell(number) : number.to_s
+
+      def truncated_quotient(left, right)
+        whole = left.abs / right.abs
+        left.negative? == right.negative? ? whole : -whole
+      end
+
+      # A refused pair: the operand reported is the undefined one, if either
+      # is, so that an unbound load is named.
+      def mismatch_pair(opcode, wanted, left, right)
+        mismatch(opcode, wanted, UNDEFINED.equal?(right) && !UNDEFINED.equal?(left) ? right : left)
+      end
+
+      def by_zero(opcode)
+        reason = opcode == "divide" ? "division_by_zero" : "modulo_by_zero"
+        EvaluationError.new(reason:, message: "#{opcode} was given a zero divisor")
+      end
+
+      def non_finite(opcode)
+        EvaluationError.new(reason: "non_finite_number", message: "#{opcode} answered a float that is not finite")
+      end
+    end
+    private_constant :Arithmetic
+  end
+end

data/lib/predicator/evaluator/calls.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Predicator
+  module Evaluator
+    # The `call` opcode, as the reference's ISA (docs/isa.md, section 5)
+    # states it: the handler {Machine} runs for its row of {INSTRUCTIONS}.
+    #
+    # `call` pops its argument count of values, the deepest first, and pushes
+    # what the named function answers. The name is looked up first among the
+    # functions the caller passed to this evaluation, then in the package's
+    # library ({Library}); nothing else is reachable, and nothing is
+    # registered globally.
+    #
+    # Every refusal is an EvaluationError, and except for too few values on
+    # the stack (reason insufficient_arguments) its reason is its message,
+    # as the reference writes them:
+    #
+    # - a name neither holds: `Unknown function: NAME`;
+    # - a count of arguments the function does not take:
+    #   `Function NAME() expects COUNTS arguments, got N`, where COUNTS is a
+    #   count, the counts it takes joined by " or ", or "at least" a count;
+    # - a library function refusing its arguments: the library's sentence,
+    #   e.g. `len() expects a string argument`;
+    # - a function that raises: `Function NAME() raised: ` and the
+    #   exception's inspect.
+    #
+    # A host function is called with a copy of each argument
+    # ({Boundary.copy}), so that nothing it does to a list, a map or a
+    # String it is handed changes the context or a value the evaluation
+    # holds. Its answer is checked against the value domain: one outside it
+    # is refused with an EvaluationError carrying the boundary's reason
+    # (unsupported_host_value, non_finite_number, cyclic_value or
+    # depth_limit_exceeded), and nothing is pushed.
+    module Calls
+      # How a library function refuses its arguments: the message is the
+      # refusal's reason. Raised and rescued inside a call; it never leaves
+      # one.
+      class Refusal < StandardError; end
+
+      include Library
+
+      # The counts of arguments a host's callable takes, as a Range: its
+      # required positional parameters up to those and its optional ones,
+      # with no end when it takes a rest parameter. A Proc is read as a
+      # lambda would be, so a block's missing arguments are refused rather
+      # than read as null.
+      def self.counts(callable)
+        parameters = parameters_of(callable)
+        required = parameters.count { |kind, _| kind == :req }
+        return (required..) if parameters.any? { |kind, _| kind == :rest }
+
+        required..(required + parameters.count { |kind, _| kind == :opt })
+      end
+
+      def self.parameters_of(callable)
+        case callable
+        when Proc then callable.parameters(lambda: true)
+        when Method then callable.parameters
+        else callable.method(:call).parameters
+        end
+      end
+      private_class_method :parameters_of
+
+      private
+
+      # Pops arg_count values, calls the named function with them, first
+      # argument deepest, and pushes its answer.
+      def call_function(at, name, arg_count)
+        if @stack.size < arg_count
+          return EvaluationError.new(
+            reason: "insufficient_arguments",
+            message: "Function #{name}() expects #{arg_count} arguments, but only #{@stack.size} values on stack"
+          )
+        end
+
+        args = @stack.pop(arg_count)
+        answer = dispatch(name, args)
+        answer.is_a?(Answered) ? push(at, answer.value) : answer
+      end
+
+      # What a call that succeeded answered, kept apart from the error value
+      # a refused call answers, since a function may answer any value.
+      Answered = Data.define(:value)
+      private_constant :Answered
+
+      def dispatch(name, args)
+        callable, counts = resolve(name)
+        return call_error("Unknown function: #{name}") unless callable
+        return call_error(wrong_count(name, counts, args.size)) unless counts.include?(args.size)
+        return host_call(name, callable, args) if @functions.key?(name)
+
+        Answered.new(callable.call(*args))
+      rescue ClockFault then raise
+      rescue Refusal => e
+        call_error(e.message)
+      rescue StandardError => e
+        call_error("Function #{name}() raised: #{e.inspect}")
+      end
+
+      # Calls a host function with a copy of each argument, answering its
+      # answer, or the refusal of one outside the value domain ({Boundary}).
+      def host_call(name, callable, args)
+        answer = callable.call(*args.map { |arg| Boundary.copy(arg) })
+        Boundary.refusal(answer, "Function #{name}() answered a value that") || Answered.new(answer)
+      end
+
+      # The callable a name reaches and the counts of arguments it takes: a
+      # host function first, then the library's.
+      def resolve(name)
+        host = @functions[name]
+        return [host, Calls.counts(host)] if host
+
+        entry = Library::FUNCTIONS[name]
+        [method(entry.handler), entry.counts] if entry
+      end
+
+      def wrong_count(name, counts, given)
+        described =
+          if counts.end.nil? then "at least #{counts.begin}"
+          else counts.to_a.join(" or ")
+          end
+        "Function #{name}() expects #{described} arguments, got #{given}"
+      end
+
+      def call_error(message) = EvaluationError.new(reason: message, message:)
+    end
+    private_constant :Calls
+  end
+end

data/lib/predicator/evaluator/casts.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module Predicator
+  module Evaluator
+    # The `cast` opcode, as the reference's ISA (docs/isa.md, section 5)
+    # states it: the handler {Machine} runs for `cast`, and the conversion
+    # matrix it reads through.
+    #
+    # The operand is one of the seven scalar type names in {TYPE_NAMES}; any
+    # other operand is an unknown instruction. The cast pops one value and
+    # pushes what that value is as the named type. It never fails but on an
+    # empty stack: undefined converts to undefined, a value already of the
+    # type passes through, and a conversion that cannot produce a value of
+    # the type answers undefined (null, a list and a map included).
+    #
+    # The conversions:
+    #
+    # - integer: a float truncates toward zero; the text of an integer (an
+    #   optional minus and decimal digits, nothing else) parses.
+    # - float: an integer widens; the text of a number (an optional minus,
+    #   digits and an optional fraction, no exponent) parses.
+    # - string: an integer in decimal, a float as {FloatText} writes it, a
+    #   boolean as `true` or `false`, a date as `YYYY-MM-DD`, a datetime in
+    #   UTC as {Predicator::DateTime#to_s} writes it, a duration in the
+    #   literal grammar {DurationText} writes.
+    # - boolean: exactly the text `true` or `false`.
+    # - date: a datetime's calendar date in UTC; the text of an ISO 8601
+    #   calendar date that names a real date.
+    # - datetime: a date at midnight UTC; the text of an ISO 8601 datetime
+    #   carrying a UTC offset, as the instant it names.
+    # - duration: the text of a duration literal, read as {DurationText}
+    #   reads it.
+    #
+    # A map carrying the seven units the reference's duration always holds
+    # (years to seconds), each an Integer, casts as a duration: it passes
+    # through `::duration` and is written by `::string` in the literal
+    # grammar. The map is read by its String unit names, as `relative_date`
+    # reads one. `object_set` on a duration answers the map of its units
+    # with the key written; when that key is not a unit name, the cast
+    # writes the duration's own units, as the reference's cast does after
+    # its `object_set`. When the key is a unit name the two part: this reads
+    # the unit written (`days` set to 5 on `3d` writes `5d`, `milliseconds`
+    # set to 500 writes `3d500ms`, a unit set to a non-Integer is
+    # undefined), while the reference keeps its duration's own unit (`3d`),
+    # since its durations carry their units under keys a written String key
+    # does not replace. A String-keyed map from the context that carries
+    # the unit names is a duration here and undefined in the reference. A
+    # map whose units are not all Integers casts to undefined.
+    #
+    # The text forms `::date` and `::datetime` read are the reference's, as
+    # {IsoText} states them.
+    #
+    # Where the reference raises rather than answering, this answers
+    # undefined: an integer or a number's text too large for a finite Float
+    # (the domain holds no other) and an instant {IsoText} refuses for its
+    # year. A number's text too close to zero for any other Float reads as
+    # zero, signed as the text is, as the reference reads it.
+    module Casts
+      # The type names a cast converts to.
+      TYPE_NAMES = %w[integer float string boolean date datetime duration].freeze
+
+      # The units a map carries to be read as a duration.
+      DURATION_KEYS = %w[years months weeks days hours minutes seconds].freeze
+
+      INTEGER_TEXT = /\A-?[0-9]+\z/
+      FLOAT_TEXT = /\A-?[0-9]+(?:\.[0-9]+)?\z/
+
+      # The method that converts to each type.
+      CONVERTERS = TYPE_NAMES.to_h { |name| [name, :"cast_to_#{name}"] }.freeze
+
+      private
+
+      def cast(at, type_name)
+        return insufficient("cast") if @stack.empty?
+
+        value = @stack.pop
+        push(at, UNDEFINED.equal?(value) ? UNDEFINED : send(CONVERTERS.fetch(type_name), value))
+      end
+
+      def cast_to_integer(value)
+        case value
+        when Integer then value
+        when Float then value.truncate
+        when String then INTEGER_TEXT.match?(value) ? Integer(value, 10) : UNDEFINED
+        else UNDEFINED
+        end
+      end
+
+      def cast_to_float(value)
+        case value
+        when Float then value
+        when Integer then value.abs < FloatText::CEILING ? value.to_f : UNDEFINED
+        when String then FLOAT_TEXT.match?(value) ? float_of_text(value) : UNDEFINED
+        else UNDEFINED
+        end
+      end
+
+      # The Float nearest the number the text writes ({FloatText.read}), or
+      # undefined when it is too large for one.
+      def float_of_text(text) = FloatText.read(text) || UNDEFINED
+
+      def cast_to_string(value)
+        case value
+        when String then value
+        when Float then FloatText.spell(value)
+        when Integer, true, false, Predicator::Date, Predicator::DateTime then value.to_s
+        else cast_duration_text(value)
+        end
+      end
+
+      def cast_duration_text(value)
+        duration = cast_duration(value)
+        duration ? DurationText.write(duration) : UNDEFINED
+      end
+
+      def cast_to_boolean(value)
+        case value
+        when true, false then value
+        when "true" then true
+        when "false" then false
+        else UNDEFINED
+        end
+      end
+
+      def cast_to_date(value)
+        case value
+        when Predicator::Date then value
+        when Predicator::DateTime then Civil.date_of(value)
+        when String then IsoText.read_date(value) || UNDEFINED
+        else UNDEFINED
+        end
+      end
+
+      def cast_to_datetime(value)
+        case value
+        when Predicator::DateTime then value
+        when Predicator::Date then Civil.instant_at(value)
+        when String then IsoText.read_datetime(value) || UNDEFINED
+        else UNDEFINED
+        end
+      end
+
+      def cast_to_duration(value)
+        return DurationText.read(value) || UNDEFINED if value.is_a?(String)
+
+        cast_duration(value) ? value : UNDEFINED
+      end
+
+      # A duration, or a map carrying the seven units read as one, or nil.
+      def cast_duration(value)
+        return value if value.is_a?(Duration)
+
+        as_duration(value) if value.is_a?(Hash) && DURATION_KEYS.all? { |key| value.key?(key) }
+      end
+    end
+    private_constant :Casts
+  end
+end

data/lib/predicator/evaluator/chronology.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Predicator
+  module Evaluator
+    # The date arithmetic `add` and `subtract` reach for, as the reference
+    # states it at the tag the corpus names (its ISA, docs/isa.md, section 5,
+    # and its duration module where the ISA is silent).
+    #
+    # Two dates are apart by a duration in whole days and two datetimes by a
+    # duration in whole seconds, truncated toward zero; a date beside a
+    # datetime is read at midnight UTC. A date moved by a duration stays a
+    # date and a datetime stays a datetime. A month counts as 30 days and a
+    # year as 365, with no calendar rule and no month-end clamp: the
+    # reference's own conversion, which it calls approximate.
+    #
+    # The module holds no state.
+    module Chronology
+      MICROS_PER_SECOND = 1_000_000
+
+      # The day count of each date unit of a duration.
+      DAYS = { weeks: 7, months: 30, years: 365 }.freeze
+
+      # The second count of each time unit of a duration.
+      SECONDS = { minutes: 60, hours: 3600 }.freeze
+
+      module_function
+
+      # Whether value is a date or a datetime.
+      def chronological?(value) = value.is_a?(Predicator::Date) || value.is_a?(Predicator::DateTime)
+
+      # left minus right, both dates or datetimes, as a duration.
+      def difference(left, right)
+        if left.is_a?(Predicator::Date) && right.is_a?(Predicator::Date)
+          return Duration.new(days: Civil.days_of(left) - Civil.days_of(right))
+        end
+
+        Duration.new(seconds: truncated_seconds(micros(left) - micros(right)))
+      end
+
+      # anchor (a date or a datetime) moved by duration, forward when sign is
+      # 1 and back when it is -1.
+      def shift(anchor, duration, sign)
+        if anchor.is_a?(Predicator::Date)
+          return Civil.date_of_days(Civil.days_of(anchor) + (sign * whole_days(duration)))
+        end
+
+        moved = micros(anchor) + (sign * datetime_step(duration))
+        Predicator::DateTime.new(epoch_seconds: moved.div(MICROS_PER_SECOND), microsecond: moved % MICROS_PER_SECOND)
+      end
+
+      # The days a date moves by: the date units, then the whole days the
+      # time units add up to, truncated toward zero. Milliseconds do not move
+      # a date.
+      def whole_days(duration)
+        time = duration.seconds + SECONDS.sum { |unit, seconds| duration.public_send(unit) * seconds }
+        date_days(duration) + truncated(time, Civil::SECONDS_PER_DAY)
+      end
+
+      # The microseconds a datetime moves by. A positive milliseconds moves it
+      # by milliseconds; any other duration moves it by whole seconds, its
+      # milliseconds left out, as the reference splits the two.
+      def datetime_step(duration)
+        seconds = duration.seconds + SECONDS.sum { |unit, factor| duration.public_send(unit) * factor } +
+                  (date_days(duration) * Civil::SECONDS_PER_DAY)
+        step = seconds * MICROS_PER_SECOND
+        duration.milliseconds.positive? ? step + (duration.milliseconds * 1000) : step
+      end
+
+      def date_days(duration) = duration.days + DAYS.sum { |unit, days| duration.public_send(unit) * days }
+
+      # A date at midnight UTC, or a datetime, as microseconds since the epoch.
+      def micros(value)
+        return Civil.days_of(value) * Civil::SECONDS_PER_DAY * MICROS_PER_SECOND if value.is_a?(Predicator::Date)
+
+        (value.epoch_seconds * MICROS_PER_SECOND) + value.microsecond
+      end
+
+      def truncated_seconds(micros) = truncated(micros, MICROS_PER_SECOND)
+
+      # amount divided by unit, truncated toward zero.
+      def truncated(amount, unit)
+        whole = amount.abs / unit
+        amount.negative? ? -whole : whole
+      end
+    end
+    private_constant :Chronology
+  end
+end

data/lib/predicator/evaluator/compare.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module Predicator
+  module Evaluator
+    # The `compare` opcode's answer for one operator and one pair of values,
+    # as the reference's ISA (docs/isa.md, section 5, `compare`) states it.
+    #
+    # Strict equality is decided first and answers a boolean over every
+    # value, undefined and null included. Every other operator propagates:
+    # undefined on either side, or a pair whose types do not match, answers
+    # undefined, never an error. Null has no type peer, so every non-strict
+    # comparison involving it answers undefined too.
+    #
+    # The module holds no state.
+    module Compare
+      # The operators `compare` accepts; any other operand is an unknown
+      # instruction.
+      OPERATORS = %w[GT LT EQ GTE LTE NE STRICT_EQ STRICT_NE].freeze
+
+      # What each ordering operator makes of an order (-1, 0 or 1).
+      ORDERED = {
+        "GT" => lambda(&:positive?), "LT" => lambda(&:negative?),
+        "GTE" => ->(order) { order >= 0 }, "LTE" => ->(order) { order <= 0 }
+      }.freeze
+
+      # The type of each kind of value a comparison matches a pair on.
+      KINDS = {
+        Integer => :number, Float => :number, TrueClass => :boolean, FalseClass => :boolean,
+        String => :string, Array => :list, Predicator::Date => :chronological,
+        Predicator::DateTime => :chronological, Predicator::Duration => :duration, Hash => :map
+      }.freeze
+
+      module_function
+
+      # The comparison of left and right under operator: true, false or
+      # {Predicator::UNDEFINED}.
+      def call(operator, left, right)
+        case operator
+        when "STRICT_EQ" then strict?(left, right)
+        when "STRICT_NE" then !strict?(left, right)
+        else loose(operator, left, right)
+        end
+      end
+
+      def loose(operator, left, right)
+        return UNDEFINED unless peers?(left, right)
+        return loose_equal?(left, right, by_instant: false) == (operator == "EQ") if %w[EQ NE].include?(operator)
+
+        order = Order.order(left, right)
+        order.nil? ? UNDEFINED : ORDERED.fetch(operator).call(order)
+      end
+
+      # The type a comparison matches a pair on: integer and float are one
+      # type here, and a date and a datetime are one type. Null and undefined
+      # have none.
+      def kind(value) = KINDS.fetch(value.class) { KINDS.find { |type, _| value.is_a?(type) }&.last }
+
+      def peers?(left, right) = !kind(left).nil? && kind(left) == kind(right)
+
+      def undefined?(value) = UNDEFINED.equal?(value)
+
+      # Strict equality: the same member of the domain with the same value.
+      # It does not bridge integer and float, and a date is never strictly
+      # equal to a datetime. The walk is iterative, so a pair nested deeper
+      # than the stack is compared rather than exhausting it; two lists or
+      # maps that are one object are equal without a walk.
+      def strict?(left, right)
+        pairs = [[left, right]]
+        until pairs.empty?
+          a, b = pairs.pop
+          return false unless strict_pair?(a, b) { |member, other| pairs.push([member, other]) }
+        end
+        true
+      end
+
+      # One pair of a strict walk: false when it differs, else true, having
+      # handed each member pair of two lists or two maps to the block.
+      def strict_pair?(left, right, &)
+        return right.instance_of?(left.class) && left == right unless container?(left)
+        return true if left.equal?(right)
+
+        right.is_a?(left.is_a?(Array) ? Array : Hash) && left.size == right.size && queued(left, right, &)
+      end
+
+      # Hands each member pair of two lists of one size, or of two maps of
+      # one size, to the block; false when a key of the left map is missing
+      # from the right.
+      def queued(left, right)
+        if left.is_a?(Array)
+          left.each_index { |at| yield(left[at], right[at]) }
+          return true
+        end
+
+        left.all? { |key, member| right.key?(key) && (yield(member, right[key]) || true) }
+      end
+
+      def container?(value) = value.is_a?(Array) || value.is_a?(Hash)
+
+      # Loose equality: numbers by value across integer and float, a date
+      # and a datetime by the instant each names. Undefined equals nothing,
+      # itself included; null equals only null. Two members of a list or a
+      # map follow the member rule (member_pair?). The walk is iterative, as
+      # strict? is.
+      def loose_equal?(left, right, by_instant:)
+        pairs = [[left, right, false]]
+        until pairs.empty?
+          a, b, member = pairs.pop
+          return false unless loose_pair?(a, b, member, by_instant) { |x, y| pairs.push([x, y, true]) }
+        end
+        true
+      end
+
+      # One pair of a loose walk: false when it differs, else true, having
+      # handed each member pair of two lists or two maps to the block.
+      def loose_pair?(left, right, member, by_instant, &)
+        verdict = member_rule(left, right, by_instant) if member
+        return verdict unless verdict.nil?
+        return left.nil? && right.nil? if absent?(left) || absent?(right)
+
+        peers?(left, right) && peers_equal?(left, right, &)
+      end
+
+      # Two values of one type: equal, or their member pairs handed to the
+      # block.
+      def peers_equal?(left, right, &)
+        return instant(left) == instant(right) if kind(left) == :chronological
+        return left == right unless container?(left)
+
+        left.equal?(right) || (left.size == right.size && queued(left, right, &))
+      end
+
+      # The member rule, or nil when it does not decide: two undefined
+      # members are the same member, and a date member and a datetime member
+      # differ whatever instants they name, unless by_instant asks for the
+      # instant alone.
+      def member_rule(left, right, by_instant)
+        return left.equal?(right) if undefined?(left) || undefined?(right)
+
+        false if !by_instant && date_against_datetime?(left, right)
+      end
+
+      def absent?(value) = value.nil? || undefined?(value)
+
+      def date_against_datetime?(left, right)
+        (left.is_a?(Predicator::Date) && right.is_a?(Predicator::DateTime)) ||
+          (left.is_a?(Predicator::DateTime) && right.is_a?(Predicator::Date))
+      end
+
+      # A date or a datetime as the instant it names, a date at midnight UTC.
+      def instant(value)
+        return [value.epoch_seconds, value.microsecond] if value.is_a?(Predicator::DateTime)
+
+        [Civil.days_of(value) * Civil::SECONDS_PER_DAY, 0]
+      end
+    end
+    private_constant :Compare
+  end
+end