rbbb 0.1.0.pre.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b73b49d61e104b20d7f14c8894477fd34079184c053d115d25cc8fca098a16b5
+  data.tar.gz: 206540fe6a06c4cdec54b076eab100e8fe712e103ca3f6ec4bb7acc3b185eb49
+SHA512:
+  metadata.gz: 8424b68bfbf71aeeb87cf4cffa988719db1a78719c38e0d1d44b2e1979e237ae0edfca3b80638c7bae536fc83170d1ed0c1e893ce247eeffaa08ba9b52404b99
+  data.tar.gz: 6e46a05de2032c7ef7f745b917bffd29f23034cc3b3e1f09b66f6c3019f9709aa53392c24f6e98e163c04c502aacef32dab37502510b1e123e24cbae3570a7f2

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 R Triple B contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,159 @@
+# RBBB Ruby reference engine
+
+This directory contains the pure-Ruby reference implementation of the RBBB
+specification.
+
+> [!WARNING]
+> The gem is an early RFC 0001 implementation. It is not production ready and
+> must not be used in a live auction.
+
+The engine will remain independent of Rails, databases, HTTP, jobs, and
+authentication. Its public decision boundary is:
+
+```ruby
+decision = engine.decide(current_state, command)
+new_state = engine.apply(current_state, decision.events)
+```
+
+The current implementation covers exact minor-unit money, configurable
+increment tiers, opening bids, proxy competition, earlier-equal priority,
+proxy clipping, challenger minimums, private leader maximum increases, and
+confidential reserve pricing and status. It also enforces authoritative closing
+times, configurable per-unit soft-close extensions, and bidder withdrawal of
+unexecuted proxy authority. Authorized operator bid voiding preserves the
+original bid, deterministically recomputes standing and executed amounts, and
+emits host-facing notification intent. Audited operator commands may also
+change closing time and reserve under the RFC's pre-bid and post-bid
+constraints without unwinding already executed amounts. Explicit ordered
+closing produces `sold`, `no_sale`, or `no_bid` terminal state. Persistence,
+networking, service-level idempotency, and authentication are not implemented.
+
+The pure engine records `operator_id`; it does not authenticate or authorize
+that identity. A host must authorize the operator before submitting any
+operator command and must deliver or retry any requested notifications.
+
+```ruby
+configuration = RBBB::Configuration.new(
+  currency: "USD",
+  opening_minor_units: 10_000,
+  increments: [{from_minor_units: 0, amount_minor_units: 1_000}],
+  opens_at: "2026-09-01T12:00:00Z",
+  closes_at: "2026-09-01T13:00:00Z",
+  extension: {trigger_window_seconds: 300, duration_seconds: 300}
+)
+engine = RBBB::Engine.new(configuration)
+state = engine.initial_state
+
+decision = engine.decide(state, {
+  command_id: "command-1",
+  type: "place_bid",
+  bidder_id: "bidder-a",
+  maximum_minor_units: 50_000,
+  effective_at: "2026-09-01T12:10:00Z"
+})
+state = engine.apply(state, decision.events) if decision.accepted?
+```
+
+### Rejected commands
+
+A command that cannot be applied yields `decision.rejected?` and no events.
+`decision.rejection` is a frozen hash holding `command_id`, `reason` (one of
+the enumerated codes in `specification/rejections/rejection.schema.json`), and
+`status: "rejected"`, and at most one reason-specific field:
+`executed_floor_minor_units`, present only with
+`maximum_below_executed_amount`. There is no open-ended details object, and
+the rejection is already the complete document the schema describes; a
+service adapter must transmit it without adding or removing fields. The
+normative rules live in
+`specification/contract.md` under "Service envelope and core inputs" and the
+rejection paragraph under "Events and visibility". A host must return
+`executed_floor_minor_units` only to the bidder who issued the rejected
+command and must never place it in a public projection.
+
+```ruby
+decision = engine.decide(state, {
+  command_id: "command-2",
+  type: "reduce_maximum",
+  bidder_id: "bidder-a",
+  maximum_minor_units: 5_000,
+  effective_at: "2026-09-01T12:11:00Z"
+})
+if decision.rejected?
+  decision.rejection
+  # => {"command_id" => "command-2",
+  #     "status" => "rejected",
+  #     "reason" => "maximum_below_executed_amount",
+  #     "executed_floor_minor_units" => 10_000}
+end
+```
+
+## Snapshots, checkpoints, and the public view
+
+`State#to_h` is the full privileged aggregate snapshot. With the host's
+`auction_id`, `bidding_unit_id`, and `currency` added it satisfies
+`specification/state/aggregate.schema.json`, and `RBBB::State.from_h`
+rebuilds a validated state from it. It contains bidder identities, maxima,
+the reserve amount, and audit history, so it must never be published.
+
+Every privileged state-transition event already carries that snapshot, so a
+host can checkpoint from the latest transition instead of replaying the
+stream from version 0:
+
+```ruby
+transition = decision.events.find { |event| event.privileged? && event.type == "maximum_accepted" }
+restored = engine.restore(transition)          # or RBBB::State.from_transition(configuration, transition)
+restored.to_h == state.to_h                     # => true
+```
+
+`State#public_view` is the public query projection. With the same three host
+fields added 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; serve it rather than hand-rolling a projection
+from the aggregate.
+
+## Install the evaluation gem
+
+Version `0.1.0.pre.3` is an experimental evaluation package. It has no runtime
+dependencies and supports Ruby 3.2 and newer. Install the exact prerelease from
+RubyGems.org:
+
+```sh
+gem install rbbb --version 0.1.0.pre.3
+ruby -rrbbb -e 'puts [RBBB::VERSION, RBBB::SPECIFICATION_VERSION, RBBB::RELEASE_STATUS].join(" ")'
+```
+
+To build the same version from a reviewed checkout:
+
+```sh
+cd ruby/engine
+bundle exec rake package:verify
+gem build rbbb.gemspec
+gem install ./rbbb-0.1.0.pre.3.gem
+ruby -rrbbb -e 'puts [RBBB::VERSION, RBBB::SPECIFICATION_VERSION, RBBB::RELEASE_STATUS].join(" ")'
+```
+
+For local application evaluation with Bundler:
+
+```ruby
+gem "rbbb", path: "/path/to/rbbb/ruby/engine"
+```
+
+The [matching GitHub release](https://github.com/willtmc/rbbb/releases) carries
+the same `.gem` artifact and its SHA-256 checksum.
+
+The installed package exposes its implementation version, claimed
+specification version, and release status as `RBBB::VERSION`,
+`RBBB::SPECIFICATION_VERSION`, and `RBBB::RELEASE_STATUS`. A package version is
+not, by itself, a production-readiness or compatibility claim.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake
+```
+
+The default task includes `package:verify`, which builds the gem in a temporary
+directory, checks the exact file allowlist, installs it into an isolated gem
+home, and runs a bid through the installed artifact. Run `bundle exec rake
+package:verify` when only that check is needed.

data/lib/rbbb/configuration.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module RBBB
+  # Immutable bidding-unit configuration consumed by the pure engine.
+  #
+  # RFC 0001 defines only timed bidding units, so +opens_at+ and +closes_at+
+  # are required alongside currency, opening amount, and increments.
+  class Configuration
+    attr_reader :currency, :opening_minor_units, :reserve_minor_units,
+      :increment_schedule, :opens_at, :closes_at, :extension
+
+    def self.from_h(attributes)
+      values = attributes.transform_keys(&:to_s)
+      new(
+        currency: values.fetch("currency"),
+        opening_minor_units: values.fetch("opening_minor_units"),
+        reserve_minor_units: values["reserve_minor_units"],
+        increments: values.fetch("increments"),
+        opens_at: values.fetch("opens_at"),
+        closes_at: values.fetch("closes_at"),
+        extension: values["extension"]
+      )
+    rescue KeyError => e
+      raise InvalidConfiguration, "configuration is missing #{e.key}"
+    end
+
+    def initialize(currency:, opening_minor_units:, increments:, reserve_minor_units: nil,
+      opens_at: nil, closes_at: nil, extension: nil)
+      Money.new(currency: currency, minor_units: opening_minor_units)
+      unless Money.amount?(opening_minor_units)
+        raise InvalidConfiguration, "opening amount must be a non-negative integer no greater than #{Money::MAX_MINOR_UNITS}"
+      end
+      if !reserve_minor_units.nil? && !Money.amount?(reserve_minor_units)
+        raise InvalidConfiguration, "reserve must be a non-negative integer no greater than #{Money::MAX_MINOR_UNITS}"
+      end
+
+      @currency = currency.freeze
+      @opening_minor_units = opening_minor_units
+      @reserve_minor_units = reserve_minor_units
+      @increment_schedule = IncrementSchedule.new(increments)
+      @opens_at = parse_timestamp(opens_at, "opens_at")
+      @closes_at = parse_timestamp(closes_at, "closes_at")
+      if @opens_at >= @closes_at
+        raise InvalidConfiguration, "opens_at must be earlier than closes_at"
+      end
+      @extension = normalize_extension(extension)
+      freeze
+    rescue InvalidMoney => e
+      raise InvalidConfiguration, e.message
+    end
+
+    def increment_for(minor_units)
+      increment_schedule.increment_for(minor_units)
+    end
+
+    private
+
+    def parse_timestamp(value, field)
+      raise InvalidConfiguration, "configuration is missing #{field}" if value.nil?
+
+      Timestamp.parse(value)
+    rescue ArgumentError
+      raise InvalidConfiguration, "#{field} must be a valid ISO 8601 timestamp"
+    end
+
+    def normalize_extension(extension)
+      return nil if extension.nil?
+      unless extension.respond_to?(:transform_keys)
+        raise InvalidConfiguration, "extension must be an object"
+      end
+
+      values = extension.transform_keys(&:to_s)
+      trigger = values["trigger_window_seconds"]
+      duration = values["duration_seconds"]
+      # Seconds share the interoperable integer bound so closing-time
+      # arithmetic (command time plus duration) stays representable in every
+      # implementation and inside the RFC 3339 four-digit-year range.
+      unless trigger.is_a?(Integer) && trigger >= 0 && trigger <= MAX_SAFE_INTEGER
+        raise InvalidConfiguration,
+          "extension trigger window must be a non-negative integer no greater than #{MAX_SAFE_INTEGER}"
+      end
+      unless duration.is_a?(Integer) && duration.positive? && duration <= MAX_SAFE_INTEGER
+        raise InvalidConfiguration,
+          "extension duration must be a positive integer no greater than #{MAX_SAFE_INTEGER}"
+      end
+
+      {
+        "trigger_window_seconds" => trigger,
+        "duration_seconds" => duration
+      }.freeze
+    end
+  end
+end

data/lib/rbbb/decision.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module RBBB
+  # Accepted events or one stable rejection from evaluating a command.
+  class Decision
+    # The constant status every rejection carries. The pure engine emits the
+    # complete rejection document defined by
+    # specification/rejections/rejection.schema.json; a service adapter must
+    # transmit it without adding or removing fields.
+    REJECTED_STATUS = "rejected"
+
+    # Rejection fields beyond command_id, status, and reason, keyed by the only
+    # reason that may carry them. Mirrors the rejection schema; there is
+    # deliberately no open-ended details object.
+    REASON_SPECIFIC_FIELDS = {
+      "maximum_below_executed_amount" => %w[executed_floor_minor_units].freeze
+    }.freeze
+
+    attr_reader :events, :rejection
+
+    def self.accepted(events)
+      new(events: events, rejection: nil)
+    end
+
+    def self.rejected(command_id:, reason:, executed_floor_minor_units: nil)
+      rejection = {"command_id" => command_id, "status" => REJECTED_STATUS, "reason" => reason}
+      allowed = REASON_SPECIFIC_FIELDS.fetch(reason, [])
+
+      if allowed.include?("executed_floor_minor_units")
+        unless executed_floor_minor_units.is_a?(Integer) && executed_floor_minor_units >= 0
+          raise ArgumentError, "#{reason} requires a non-negative integer executed_floor_minor_units"
+        end
+
+        rejection["executed_floor_minor_units"] = executed_floor_minor_units
+      elsif !executed_floor_minor_units.nil?
+        raise ArgumentError, "executed_floor_minor_units is only reported for maximum_below_executed_amount"
+      end
+
+      new(events: [], rejection: rejection.freeze)
+    end
+
+    def initialize(events:, rejection:)
+      @events = events.freeze
+      @rejection = rejection
+      freeze
+    end
+
+    def accepted?
+      rejection.nil?
+    end
+
+    def rejected?
+      !accepted?
+    end
+  end
+end