rbbb 0.1.0.pre.3

data/lib/rbbb/event.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module RBBB
+  # Immutable fact emitted by an accepted engine command.
+  class Event
+    VISIBILITIES = %i[public privileged].freeze
+
+    attr_reader :type, :visibility, :data
+
+    def initialize(type:, visibility:, data: {})
+      raise ArgumentError, "unknown event visibility" unless VISIBILITIES.include?(visibility)
+
+      @type = type.to_s.freeze
+      @visibility = visibility
+      @data = deep_freeze(data.transform_keys(&:to_s))
+      freeze
+    end
+
+    def public?
+      visibility == :public
+    end
+
+    def privileged?
+      visibility == :privileged
+    end
+
+    def to_h
+      {"type" => type}.merge(data)
+    end
+
+    private
+
+    def deep_freeze(value)
+      case value
+      when Hash
+        value.transform_values { |nested| deep_freeze(nested) }.freeze
+      when Array
+        value.map { |nested| deep_freeze(nested) }.freeze
+      else
+        value.freeze
+      end
+    end
+  end
+end

data/lib/rbbb/increment_schedule.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module RBBB
+  # Lower-bound tiers used to select the increment for an exact amount.
+  class IncrementSchedule
+    Tier = Struct.new(:from_minor_units, :amount_minor_units, keyword_init: true) do
+      def to_h
+        {
+          "from_minor_units" => from_minor_units,
+          "amount_minor_units" => amount_minor_units
+        }
+      end
+    end
+
+    attr_reader :tiers
+
+    def initialize(tiers)
+      @tiers = Array(tiers).map do |tier|
+        unless tier.respond_to?(:transform_keys)
+          raise InvalidConfiguration, "increment tier must be an object"
+        end
+
+        values = tier.transform_keys(&:to_s)
+        Tier.new(
+          from_minor_units: values.fetch("from_minor_units"),
+          amount_minor_units: values.fetch("amount_minor_units")
+        ).freeze
+      end
+      validate_tier_types!
+      @tiers = @tiers.sort_by(&:from_minor_units)
+
+      validate!
+      @tiers.freeze
+      freeze
+    rescue KeyError => e
+      raise InvalidConfiguration, "increment tier is missing #{e.key}"
+    end
+
+    def increment_for(minor_units)
+      unless minor_units.is_a?(Integer) && minor_units >= 0
+        raise InvalidConfiguration, "increment lookup amount must be a non-negative integer"
+      end
+
+      tiers.reverse_each.find { |tier| tier.from_minor_units <= minor_units }.amount_minor_units
+    end
+
+    def to_a
+      tiers.map(&:to_h)
+    end
+
+    private
+
+    def validate_tier_types!
+      tiers.each do |tier|
+        unless Money.amount?(tier.from_minor_units)
+          raise InvalidConfiguration,
+            "increment lower bounds must be non-negative integers no greater than #{Money::MAX_MINOR_UNITS}"
+        end
+        unless Money.amount?(tier.amount_minor_units) && tier.amount_minor_units.positive?
+          raise InvalidConfiguration,
+            "increments must be positive integers no greater than #{Money::MAX_MINOR_UNITS}"
+        end
+      end
+    end
+
+    def validate!
+      raise InvalidConfiguration, "increment schedule must contain at least one tier" if tiers.empty?
+      unless tiers.first.from_minor_units == 0
+        raise InvalidConfiguration, "increment schedule must begin at zero"
+      end
+
+      duplicate = tiers.each_cons(2).find do |left, right|
+        left.from_minor_units == right.from_minor_units
+      end
+      raise InvalidConfiguration, "increment lower bounds must be unique" if duplicate
+    end
+  end
+end

data/lib/rbbb/money.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module RBBB
+  # Exact monetary value represented without floating point.
+  class Money
+    include Comparable
+
+    # Largest amount any RFC 0001 field may carry. Every conforming
+    # implementation must produce identical results, so amounts share the
+    # interoperable integer bound in RBBB::MAX_SAFE_INTEGER.
+    MAX_MINOR_UNITS = MAX_SAFE_INTEGER
+
+    attr_reader :currency, :minor_units
+
+    # True when value is a non-negative integer inside the interoperable range.
+    def self.amount?(value)
+      value.is_a?(Integer) && value >= 0 && value <= MAX_MINOR_UNITS
+    end
+
+    def initialize(currency:, minor_units:)
+      unless currency.is_a?(String) && currency.match?(/\A[A-Z]{3}\z/)
+        raise InvalidMoney, "currency must be a three-letter uppercase code"
+      end
+      raise InvalidMoney, "minor_units must be an integer" unless minor_units.is_a?(Integer)
+      if minor_units.abs > MAX_MINOR_UNITS
+        raise InvalidMoney, "minor_units must not exceed #{MAX_MINOR_UNITS}"
+      end
+
+      @currency = currency.freeze
+      @minor_units = minor_units
+      freeze
+    end
+
+    def <=>(other)
+      ensure_same_currency!(other)
+      minor_units <=> other.minor_units
+    end
+
+    def +(other)
+      ensure_same_currency!(other)
+      self.class.new(currency: currency, minor_units: minor_units + other.minor_units)
+    end
+
+    def -(other)
+      ensure_same_currency!(other)
+      self.class.new(currency: currency, minor_units: minor_units - other.minor_units)
+    end
+
+    def ==(other)
+      other.is_a?(Money) && currency == other.currency && minor_units == other.minor_units
+    end
+    alias eql? ==
+
+    def hash
+      [currency, minor_units].hash
+    end
+
+    def to_h
+      {"currency" => currency, "minor_units" => minor_units}
+    end
+
+    private
+
+    def ensure_same_currency!(other)
+      unless other.is_a?(Money) && other.currency == currency
+        raise InvalidMoney, "money operations require matching currencies"
+      end
+    end
+  end
+end

data/lib/rbbb/state.rb

@@ -0,0 +1,462 @@
+# frozen_string_literal: true
+
+module RBBB
+  # Replayable aggregate state for one independent bidding unit.
+  class State
+    Position = Struct.new(
+      :maximum_minor_units,
+      :priority,
+      :executed_minor_units,
+      keyword_init: true
+    ) do
+      def to_h
+        {
+          "maximum_minor_units" => maximum_minor_units,
+          "priority" => priority,
+          "executed_minor_units" => executed_minor_units
+        }
+      end
+    end
+
+    attr_reader :version, :positions, :leader_id, :standing_minor_units,
+      :next_required_minor_units, :reserve_status, :opens_at, :closes_at,
+      :last_effective_at, :reserve_minor_units, :authorization_history,
+      :reserve_history, :voided_bid_ids, :status, :result, :winner_id,
+      :winning_minor_units
+
+    # Aggregate snapshot keys owned by the bidding unit. A host adds
+    # auction_id, bidding_unit_id, and currency to complete
+    # specification/state/aggregate.schema.json.
+    SNAPSHOT_KEYS = %w[
+      version status opens_at closes_at last_effective_at reserve_minor_units
+      reserve_status leader_id standing_minor_units next_required_minor_units
+      positions authorization_history reserve_history voided_bid_ids result
+      winner_id winning_minor_units
+    ].freeze
+
+    # Public projection keys owned by the bidding unit, per
+    # specification/state/bidding-unit.schema.json. Never add an identity,
+    # a maximum, a reserve amount, or audit history here.
+    PUBLIC_VIEW_KEYS = %w[
+      version status opens_at closes_at standing_minor_units
+      next_required_minor_units reserve_status result winning_minor_units
+    ].freeze
+
+    # Keys every privileged state-transition event carries. Closing adds
+    # status, result, winner_id, and winning_minor_units.
+    TRANSITION_KEYS = %w[
+      aggregate_version closes_at reserve_minor_units reserve_status leader_id
+      standing_minor_units next_required_minor_units positions
+      authorization_history reserve_history voided_bid_ids
+    ].freeze
+
+    def self.empty(configuration)
+      new(
+        version: 0,
+        positions: {},
+        leader_id: nil,
+        standing_minor_units: nil,
+        next_required_minor_units: configuration.opening_minor_units,
+        reserve_status: configuration.reserve_minor_units.nil? ? nil : "reserve_not_met",
+        reserve_minor_units: configuration.reserve_minor_units,
+        opens_at: configuration.opens_at,
+        closes_at: configuration.closes_at,
+        last_effective_at: nil,
+        authorization_history: [],
+        reserve_history: [],
+        voided_bid_ids: [],
+        status: "open"
+      )
+    end
+
+    # Rebuild a validated state from a `State#to_h` snapshot. Identity keys
+    # added by the host are ignored; every snapshot key must be present.
+    def self.from_h(snapshot)
+      raise InvalidState, "snapshot must be an object" unless snapshot.respond_to?(:transform_keys)
+
+      values = snapshot.transform_keys(&:to_s)
+      missing = SNAPSHOT_KEYS.reject { |key| values.key?(key) }
+      raise InvalidState, "snapshot is missing #{missing.join(', ')}" if missing.any?
+
+      new(
+        version: values.fetch("version"),
+        positions: values.fetch("positions"),
+        leader_id: values.fetch("leader_id"),
+        standing_minor_units: values.fetch("standing_minor_units"),
+        next_required_minor_units: values.fetch("next_required_minor_units"),
+        reserve_status: values.fetch("reserve_status"),
+        reserve_minor_units: values.fetch("reserve_minor_units"),
+        opens_at: values.fetch("opens_at"),
+        closes_at: values.fetch("closes_at"),
+        last_effective_at: values.fetch("last_effective_at"),
+        authorization_history: values.fetch("authorization_history"),
+        reserve_history: values.fetch("reserve_history"),
+        voided_bid_ids: values.fetch("voided_bid_ids"),
+        status: values.fetch("status"),
+        result: values.fetch("result"),
+        winner_id: values.fetch("winner_id"),
+        winning_minor_units: values.fetch("winning_minor_units")
+      )
+    rescue NoMethodError, TypeError
+      raise InvalidState, "snapshot is malformed"
+    end
+
+    # Rebuild a validated state from one privileged state-transition event
+    # (or its data hash). Every transition carries the full aggregate
+    # snapshot, so a host can checkpoint from the latest transition instead
+    # of replaying the stream from version 0. `opens_at` is fixed by
+    # configuration and is not repeated in events.
+    def self.from_transition(configuration, event_or_data)
+      data = event_or_data.respond_to?(:data) ? event_or_data.data : event_or_data
+      raise InvalidState, "transition data must be an object" unless data.respond_to?(:transform_keys)
+
+      values = data.transform_keys(&:to_s)
+      missing = TRANSITION_KEYS.reject { |key| values.key?(key) }
+      raise InvalidState, "transition is missing #{missing.join(', ')}" if missing.any?
+
+      from_h(
+        "version" => values.fetch("aggregate_version"),
+        "status" => values.fetch("status", "open"),
+        "opens_at" => configuration.opens_at,
+        "closes_at" => values["closes_at"],
+        "last_effective_at" => values["effective_at"],
+        "reserve_minor_units" => values["reserve_minor_units"],
+        "reserve_status" => values["reserve_status"],
+        "leader_id" => values["leader_id"],
+        "standing_minor_units" => values["standing_minor_units"],
+        "next_required_minor_units" => values["next_required_minor_units"],
+        "positions" => values["positions"],
+        "authorization_history" => values["authorization_history"],
+        "reserve_history" => values["reserve_history"],
+        "voided_bid_ids" => values["voided_bid_ids"],
+        "result" => values["result"],
+        "winner_id" => values["winner_id"],
+        "winning_minor_units" => values["winning_minor_units"]
+      )
+    end
+
+    def initialize(version:, positions:, leader_id:, standing_minor_units:,
+      next_required_minor_units:, reserve_status: nil, opens_at: nil, closes_at: nil,
+      last_effective_at: nil, reserve_minor_units: nil,
+      authorization_history: [], reserve_history: [],
+      voided_bid_ids: [], status: "open", result: nil, winner_id: nil,
+      winning_minor_units: nil)
+      @version = version
+      @positions = positions.each_with_object({}) do |(bidder_id, position), copy|
+        copy[bidder_id.to_s.freeze] = coerce_position(position)
+      end.freeze
+      @leader_id = leader_id&.to_s&.freeze
+      @standing_minor_units = standing_minor_units
+      @next_required_minor_units = next_required_minor_units
+      @reserve_status = reserve_status&.to_s&.freeze
+      @reserve_minor_units = reserve_minor_units
+      @opens_at = coerce_timestamp(opens_at, "opens_at")
+      @closes_at = coerce_timestamp(closes_at, "closes_at")
+      @last_effective_at = coerce_timestamp(last_effective_at, "last_effective_at")
+      @authorization_history = authorization_history.map do |entry|
+        coerce_authorization(entry)
+      end.freeze
+      @reserve_history = reserve_history.map do |entry|
+        coerce_reserve_change(entry)
+      end.freeze
+      @voided_bid_ids = voided_bid_ids.map { |bid_id| bid_id.to_s.freeze }.freeze
+      @status = status.to_s.freeze
+      @result = result&.to_s&.freeze
+      @winner_id = winner_id&.to_s&.freeze
+      @winning_minor_units = winning_minor_units
+      validate!
+      freeze
+    end
+
+    def position_for(bidder_id)
+      positions[bidder_id.to_s]
+    end
+
+    def bid_record_for(bid_id)
+      authorization_history.find do |entry|
+        entry.fetch("type") == "place_bid" && entry.fetch("bid_id") == bid_id.to_s
+      end
+    end
+
+    def bidding_started?
+      authorization_history.any? { |entry| entry.fetch("type") == "place_bid" }
+    end
+
+    def closed?
+      status == "closed"
+    end
+
+    # Full privileged aggregate snapshot. Together with the host's
+    # auction_id, bidding_unit_id, and currency it satisfies
+    # specification/state/aggregate.schema.json and round-trips through
+    # `State.from_h`. It contains identities, maxima, the reserve amount, and
+    # audit history; never publish it.
+    def to_h
+      {
+        "version" => version,
+        "status" => status,
+        "opens_at" => Timestamp.dump(opens_at),
+        "closes_at" => Timestamp.dump(closes_at),
+        "last_effective_at" => Timestamp.dump(last_effective_at),
+        "reserve_minor_units" => reserve_minor_units,
+        "reserve_status" => reserve_status,
+        "leader_id" => leader_id,
+        "standing_minor_units" => standing_minor_units,
+        "next_required_minor_units" => next_required_minor_units,
+        "positions" => positions.transform_values(&:to_h),
+        "authorization_history" => authorization_history.map(&:dup),
+        "reserve_history" => reserve_history.map(&:dup),
+        "voided_bid_ids" => voided_bid_ids.dup,
+        "result" => result,
+        "winner_id" => winner_id,
+        "winning_minor_units" => winning_minor_units
+      }
+    end
+
+    # Public query projection. Together with the host's auction_id,
+    # bidding_unit_id, and currency it satisfies
+    # specification/state/bidding-unit.schema.json. It never carries a
+    # bidder, leader, or winner identity, a maximum, the reserve amount, or
+    # audit history.
+    def public_view
+      {
+        "version" => version,
+        "status" => status,
+        "opens_at" => Timestamp.dump(opens_at),
+        "closes_at" => Timestamp.dump(closes_at),
+        "standing_minor_units" => standing_minor_units,
+        "next_required_minor_units" => next_required_minor_units,
+        "reserve_status" => reserve_status,
+        "result" => result,
+        "winning_minor_units" => winning_minor_units
+      }
+    end
+
+    private
+
+    def coerce_timestamp(value, field)
+      return nil if value.nil?
+
+      Timestamp.parse(value)
+    rescue ArgumentError
+      raise InvalidState, "#{field} must be a valid ISO 8601 timestamp"
+    end
+
+    def coerce_position(position)
+      return position if position.is_a?(Position) && position.frozen?
+
+      values = position.respond_to?(:to_h) ? position.to_h.transform_keys(&:to_s) : {}
+      Position.new(
+        maximum_minor_units: values.fetch("maximum_minor_units"),
+        priority: values.fetch("priority"),
+        executed_minor_units: values.fetch("executed_minor_units")
+      ).freeze
+    rescue KeyError => e
+      raise InvalidState, "position is missing #{e.key}"
+    end
+
+    def coerce_authorization(entry)
+      values = entry.respond_to?(:to_h) ? entry.to_h.transform_keys(&:to_s) : {}
+      normalized = {
+        "type" => values.fetch("type").to_s.freeze,
+        "bidder_id" => values.fetch("bidder_id").to_s.freeze,
+        "maximum_minor_units" => values.fetch("maximum_minor_units"),
+        "priority" => values.fetch("priority")
+      }
+      if normalized.fetch("type") == "place_bid"
+        normalized["bid_id"] = values.fetch("bid_id").to_s.freeze
+      end
+      normalized.freeze
+    rescue KeyError => e
+      raise InvalidState, "authorization is missing #{e.key}"
+    end
+
+    def coerce_reserve_change(entry)
+      values = entry.respond_to?(:to_h) ? entry.to_h.transform_keys(&:to_s) : {}
+      {
+        "old_reserve_minor_units" => values.fetch("old_reserve_minor_units"),
+        "new_reserve_minor_units" => values.fetch("new_reserve_minor_units"),
+        "priority" => values.fetch("priority")
+      }.freeze
+    rescue KeyError => e
+      raise InvalidState, "reserve change is missing #{e.key}"
+    end
+
+    def validate!
+      raise InvalidState, "version must be a non-negative integer" unless version.is_a?(Integer) && version >= 0
+      unless next_required_minor_units.is_a?(Integer) && next_required_minor_units >= 0
+        raise InvalidState, "next required amount must be a non-negative integer"
+      end
+      unless [nil, "reserve_not_met", "reserve_met"].include?(reserve_status)
+        raise InvalidState, "reserve status is invalid"
+      end
+      unless valid_optional_minor_units?(reserve_minor_units)
+        raise InvalidState, "reserve must be a non-negative integer or nil"
+      end
+      if reserve_minor_units.nil? != reserve_status.nil?
+        raise InvalidState, "reserve and reserve status must be present together"
+      end
+      raise InvalidState, "state is missing opens_at" if opens_at.nil?
+      raise InvalidState, "state is missing closes_at" if closes_at.nil?
+      if opens_at >= closes_at
+        raise InvalidState, "opens_at must be earlier than closes_at"
+      end
+      validate_authorization_history!
+      validate_reserve_history!
+      validate_lifecycle!
+      if leader_id && !positions.key?(leader_id)
+        raise InvalidState, "leader must have a position"
+      end
+      if leader_id.nil? != standing_minor_units.nil?
+        raise InvalidState, "leader and standing amount must be present together"
+      end
+
+      positions.each_value do |position|
+        unless position.maximum_minor_units.is_a?(Integer) && position.maximum_minor_units >= 0
+          raise InvalidState, "maximums must be non-negative integers"
+        end
+        unless position.priority.is_a?(Integer) && position.priority.positive? && position.priority <= version
+          raise InvalidState, "position priority must belong to the applied event stream"
+        end
+        unless position.executed_minor_units.is_a?(Integer) &&
+            position.executed_minor_units.between?(0, position.maximum_minor_units)
+          raise InvalidState, "executed amount must be between zero and maximum"
+        end
+      end
+
+      return unless leader_id
+
+      leader = positions.fetch(leader_id)
+      unless standing_minor_units.is_a?(Integer) &&
+          standing_minor_units.between?(0, leader.maximum_minor_units)
+        raise InvalidState, "standing amount must be within the leader maximum"
+      end
+      # The next required amount saturates at the interoperable bound, so the
+      # two are permitted to be equal only when both sit on that bound.
+      saturated = standing_minor_units == Money::MAX_MINOR_UNITS &&
+        next_required_minor_units == Money::MAX_MINOR_UNITS
+      unless saturated || next_required_minor_units > standing_minor_units
+        raise InvalidState, "next required amount must exceed standing amount"
+      end
+
+      ranked_leader = positions.min_by do |bidder_id, position|
+        [-position.maximum_minor_units, position.priority, bidder_id]
+      end.first
+      raise InvalidState, "leader does not match maximum priority" unless ranked_leader == leader_id
+    end
+
+    def validate_authorization_history!
+      priorities = authorization_history.map { |entry| entry.fetch("priority") }
+      unless priorities.all? { |priority| priority.is_a?(Integer) }
+        raise InvalidState, "authorization priority must belong to the event stream"
+      end
+      unless priorities == priorities.sort && priorities.uniq == priorities
+        raise InvalidState, "authorization priorities must be unique and ordered"
+      end
+
+      bid_ids = []
+      authorization_history.each do |entry|
+        unless %w[place_bid maximum_reduced].include?(entry.fetch("type"))
+          raise InvalidState, "authorization type is invalid"
+        end
+        unless entry.fetch("maximum_minor_units").is_a?(Integer) &&
+            entry.fetch("maximum_minor_units") >= 0
+          raise InvalidState, "authorization maximum must be a non-negative integer"
+        end
+        if entry.fetch("bidder_id").empty?
+          raise InvalidState, "authorization bidder ID must be present"
+        end
+        unless entry.fetch("priority").positive? && entry.fetch("priority") <= version
+          raise InvalidState, "authorization priority must belong to the event stream"
+        end
+        next unless entry.fetch("type") == "place_bid"
+
+        bid_id = entry.fetch("bid_id")
+        raise InvalidState, "authorization bid ID must be present" if bid_id.empty?
+
+        bid_ids << bid_id
+      end
+      raise InvalidState, "bid IDs must be unique" unless bid_ids.uniq == bid_ids
+      unless voided_bid_ids.uniq == voided_bid_ids
+        raise InvalidState, "voided bid IDs must be unique"
+      end
+      unless voided_bid_ids.all? { |bid_id| bid_ids.include?(bid_id) }
+        raise InvalidState, "voided bid IDs must refer to accepted bids"
+      end
+    end
+
+    def validate_reserve_history!
+      priorities = reserve_history.map { |entry| entry.fetch("priority") }
+      valid_priorities = priorities.all? do |priority|
+        priority.is_a?(Integer) && priority.positive? && priority <= version
+      end
+      unless valid_priorities
+        raise InvalidState, "reserve change priority must belong to the event stream"
+      end
+      unless priorities == priorities.sort && priorities.uniq == priorities
+        raise InvalidState, "reserve change priorities must be unique and ordered"
+      end
+      unless (priorities & authorization_history.map { |entry| entry.fetch("priority") }).empty?
+        raise InvalidState, "state history priorities must be unique"
+      end
+
+      reserve_history.each do |entry|
+        unless valid_optional_minor_units?(entry.fetch("old_reserve_minor_units")) &&
+            valid_optional_minor_units?(entry.fetch("new_reserve_minor_units"))
+          raise InvalidState, "reserve change values must be non-negative integers or nil"
+        end
+      end
+      reserve_history.each_cons(2) do |previous, current|
+        unless previous.fetch("new_reserve_minor_units") ==
+            current.fetch("old_reserve_minor_units")
+          raise InvalidState, "reserve change history must be continuous"
+        end
+      end
+      if reserve_history.any? &&
+          reserve_history.last.fetch("new_reserve_minor_units") != reserve_minor_units
+        raise InvalidState, "current reserve must match reserve change history"
+      end
+    end
+
+    def valid_optional_minor_units?(value)
+      value.nil? || (value.is_a?(Integer) && value >= 0)
+    end
+
+    def validate_lifecycle!
+      unless %w[open closed].include?(status)
+        raise InvalidState, "bidding status is invalid"
+      end
+      if status == "open"
+        unless result.nil? && winner_id.nil? && winning_minor_units.nil?
+          raise InvalidState, "open bidding cannot have a closing result"
+        end
+        return
+      end
+
+      unless %w[sold no_sale no_bid].include?(result)
+        raise InvalidState, "closed bidding result is invalid"
+      end
+      case result
+      when "sold"
+        unless leader_id && winner_id == leader_id && winning_minor_units == standing_minor_units
+          raise InvalidState, "sold result must match the standing leader and amount"
+        end
+        if reserve_status == "reserve_not_met"
+          raise InvalidState, "sold result requires reserve to be met"
+        end
+      when "no_sale"
+        unless leader_id && standing_minor_units && reserve_status == "reserve_not_met"
+          raise InvalidState, "no-sale result requires a leader below reserve"
+        end
+        unless winner_id.nil? && winning_minor_units.nil?
+          raise InvalidState, "no-sale result cannot have a winner"
+        end
+      when "no_bid"
+        unless leader_id.nil? && standing_minor_units.nil? &&
+            winner_id.nil? && winning_minor_units.nil?
+          raise InvalidState, "no-bid result cannot have a standing bid or winner"
+        end
+      end
+    end
+  end
+end