rom-tiger_beetle 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7372865e0566fe634b9f8e13ee576ea92d29f186f43383fe43a1b43dec1021c6
+  data.tar.gz: 378f7c274cbf5f21d9e2d25dff24179135ac4c4dea47bc745ab74f2a62fc12a2
+SHA512:
+  metadata.gz: f8749d68832fbb1db874d43e57b90e89df304ef70d56bd7da1093ef1b85e69017f500aa4e4a98cb3c6bdb1e6bbeb6e476daa648672d9fc41685822869a88c6d4
+  data.tar.gz: 2438aedb8ee7acb28f0d9f455237a073c1b740c654ae437eb9ebdee7c323b01b97348c9ab60a0394cb04a8f06c34c4c1d33ba178d75efd276f8e71fd7d5b41bf

data/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+## 0.1.0 — 2026-09-10
+
+First supported release. Supports MRI Ruby 3.3 and 3.4 with the TigerBeetle
+Ruby client 0.17.9 and the TigerBeetle 0.17.9 server image.
+
+- Verified with the clean-bundle CI matrix, the complete RSpec suite, and the
+  example against the pinned local server image.
+
+## Unreleased
+
+- Document the current `TigerBeetle::Client.new` setup and per-record `CREATED`/`EXISTS` result handling.
+- Document the supported Ruby 3.3+, TigerBeetle client 0.17.9, and server 0.17.9 compatibility range, including batch limits, ID idempotency, history filters, query scope, and pending transfers.
+- Correct the gem homepage and repository metadata to point to the public `kamalogudah/rom-tiger_beetle` repository.
+
+- Clarify the ID-only query boundary and supported history escape hatches.
+- Validate account/transfer protocol ranges, flags, account identity, and transfer phase invariants before submission.
+
+- Require Ruby 3.3 or newer to match the TigerBeetle 0.17 client.
+- Constrain the TigerBeetle client to the tested `>= 0.17.9, < 0.18` range.
+- Declare `rom` as a development dependency for the specs.
+
+- Initial adapter: `:accounts`/`:transfers` datasets, id-batch lookup, batch create commands, flag bitmask helpers, monotonic id generation.
+- Known gaps: two-phase transfer helpers, linked-chain builder, unconfirmed `get_account_transfers` signature.

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) Paul Oguda
+
+MIT License
+
+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,208 @@
+# rom-tiger_beetle
+
+Experimental [TigerBeetle](https://tigerbeetle.com) support for [ROM](https://rom-rb.org). Uses the [`tigerbeetle`](https://rubygems.org/gems/tigerbeetle) gem (native Zig client via FFI) as the connection adapter.
+
+TigerBeetle is not a general-purpose database — it's an append-only, distributed accounting ledger with exactly two record types (`Account`, `Transfer`) and no arbitrary predicate queries. This adapter reflects that on purpose rather than papering over it with a fake SQL-like interface:
+
+- **Two datasets only** — `:accounts` and `:transfers`, fixed by the protocol.
+- **`where(id: ...)` only** — batch lookup by id, via `lookup_accounts`/`lookup_transfers`. Any other predicate raises `NotImplementedError`.
+- **Create only, batched** — `create_accounts`/`create_transfers`. There is no `Update` or `Delete` command: ledger entries are immutable, and balances only change as a side effect of new transfers.
+- **`TigerBeetle::CommandError`** wraps TigerBeetle's per-item error array (the protocol returns errors inline rather than raising).
+
+Record IDs are cluster-wide idempotency keys, not ledger-scoped identifiers. Keep
+cross-ledger relationships in `user_data_128`, `user_data_64`, or `user_data_32`;
+the account and transfer IDs themselves must be nonzero and less than `2^128 - 1`.
+For normal creates, submit `timestamp: 0` (the default) and let TigerBeetle
+assign it.
+
+Create requests are chunked in input order. Records with the `linked` flag are
+kept together with the rest of their linked chain and are never split across
+requests. A linked chain larger than `batch_size` is rejected before any create
+request is sent.
+
+## Installing
+
+Add `gem "rom-tiger_beetle"` to your Gemfile. You'll need a running TigerBeetle cluster — see `docker-compose.yml` in this repo for a local single-replica setup.
+
+## Example
+
+```ruby
+require "rom"
+require "rom/tiger_beetle"
+
+conf = ROM::Configuration.new(
+  :tiger_beetle,
+  addresses: "3000",
+  client: TigerBeetle::Client.new(
+    cluster_id: 0,
+    replica_addresses: "3000"
+  ),
+  # 8,189 is the documented default, not a guaranteed limit for every server.
+  # Set this to the maximum advertised by your cluster.
+  batch_size: 8_189
+)
+
+class Accounts < ROM::Relation[:tiger_beetle]
+  schema(:accounts, infer: false) do
+    attribute :id, ROM::TigerBeetle::Types::UInt128ID
+    attribute :user_data_128, ROM::TigerBeetle::Types::UInt128.default(0)
+    attribute :user_data_64, ROM::TigerBeetle::Types::UInt64.default(0)
+    attribute :user_data_32, ROM::TigerBeetle::Types::UInt32.default(0)
+    attribute :ledger, ROM::TigerBeetle::Types::UInt32
+    attribute :code, ROM::TigerBeetle::Types::UInt16
+    attribute :flags, ROM::TigerBeetle::Types::UInt16.default(0)
+    # Leave this at zero on create; TigerBeetle assigns the timestamp.
+    attribute :timestamp, ROM::TigerBeetle::Types::UInt64.default(0)
+  end
+end
+
+class Transfers < ROM::Relation[:tiger_beetle]
+  schema(:transfers, infer: false) do
+    attribute :id, ROM::TigerBeetle::Types::UInt128ID
+    attribute :user_data_128, ROM::TigerBeetle::Types::UInt128.default(0)
+    attribute :user_data_64, ROM::TigerBeetle::Types::UInt64.default(0)
+    attribute :user_data_32, ROM::TigerBeetle::Types::UInt32.default(0)
+    attribute :debit_account_id, ROM::TigerBeetle::Types::UInt128ID
+    attribute :credit_account_id, ROM::TigerBeetle::Types::UInt128ID
+    attribute :amount, ROM::TigerBeetle::Types::UInt128
+    attribute :ledger, ROM::TigerBeetle::Types::UInt32
+    attribute :code, ROM::TigerBeetle::Types::UInt16
+    attribute :flags, ROM::TigerBeetle::Types::UInt16.default(0)
+    attribute :pending_id, ROM::TigerBeetle::Types::UInt128.default(0)
+    attribute :timeout, ROM::TigerBeetle::Types::UInt64.default(0)
+    # Leave this at zero on create; TigerBeetle assigns the timestamp.
+    attribute :timestamp, ROM::TigerBeetle::Types::UInt64.default(0)
+  end
+end
+
+conf.register_relation(Accounts, Transfers)
+conf.register_command(
+  Class.new(ROM::TigerBeetle::Commands::CreateAccounts) { relation :accounts; register_as :create },
+  Class.new(ROM::TigerBeetle::Commands::CreateTransfers) { relation :transfers; register_as :create }
+)
+
+rom = ROM.container(conf)
+
+client_wallet = ROM::TigerBeetle::Types.generate_id
+expert_wallet = ROM::TigerBeetle::Types.generate_id
+
+rom.commands[:accounts][:create].call([
+  { id: client_wallet, ledger: 1, code: 1 },
+  { id: expert_wallet, ledger: 1, code: 2 }
+])
+
+rom.commands[:transfers][:create].call([{
+  id: ROM::TigerBeetle::Types.generate_id,
+  debit_account_id: client_wallet,
+  credit_account_id: expert_wallet,
+  amount: 25_000,
+  ledger: 1,
+  code: 10
+}])
+
+rom.relations[:accounts].by_id(client_wallet, expert_wallet).to_a
+```
+
+The adapter passes arrays to the current TigerBeetle Ruby client API. The
+underlying client returns one result object per submitted record; `CREATED` and
+`EXISTS` are successful outcomes. The ROM create command returns the input
+tuples on success and raises `ROM::TigerBeetle::CommandError` when any result
+has another status.
+
+If using the client directly, handle the result objects in the same way:
+
+```ruby
+results = client.create_accounts(accounts)
+successful = [TigerBeetle::CreateAccountStatus::CREATED,
+              TigerBeetle::CreateAccountStatus::EXISTS]
+failures = results.reject { |result| successful.include?(result.status) }
+raise failures.inspect unless failures.empty?
+```
+
+## IDs and batches
+
+Account and transfer IDs are cluster-wide idempotency keys. They are not scoped
+to a ledger, so retries with the same ID return `EXISTS` rather than creating a
+second record. IDs must be nonzero and less than `2^128 - 1`; use
+`ROM::TigerBeetle::Types.generate_id` for new records. Store application
+relationships in `user_data_128`, `user_data_64`, or `user_data_32` instead of
+reusing an ID across ledgers.
+
+Create requests are chunked in input order. The default maximum is 8,189
+records, but the server configured event limit is authoritative; set the
+gateway batch_size to the limit advertised by your cluster. A linked chain
+is kept in one request and a chain larger than `batch_size` is rejected.
+
+## Query and accounting boundaries
+
+This adapter is intentionally ID-only: `where(id: ...)` and `by_id` perform
+batch lookups, and `history_for` and `balances_for` are the only account-scoped
+protocol queries. It does not expose `query_accounts` or `query_transfers`,
+scan datasets, or emulate SQL predicates. Filters such as ledger, code, and
+account flags must be applied by the caller after an explicit ID lookup or by
+using the supported account-history filter.
+
+History and point-in-time balances are available only for accounts created with
+`ROM::TigerBeetle::Flags.account(:history)`. For example:
+
+```ruby
+history = rom.relations[:accounts].history_for(
+  account_id,
+  limit: 100,
+  debits: true,
+  credits: true,
+  reversed: true,
+  timestamp_min: 0,
+  timestamp_max: 0
+)
+balances = rom.relations[:accounts].balances_for(account_id, limit: 100)
+```
+
+The history filter supports `user_data_128`, `user_data_64`, `user_data_32`,
+`code`, `timestamp_min`, `timestamp_max`, `limit`, `reversed`, and explicit
+`flags`. At least one of `debits` or `credits` must be selected, and `limit`
+must be positive.
+
+Creates validate tuple-level protocol boundaries before sending: IDs are nonzero and below 2^128 - 1, ledger and code are nonzero (uint32/uint16), transfer accounts are distinct, amounts are unsigned uint128, and account/transfer flags contain only known bits. TigerBeetle remains authoritative for the relationship between a transfer and its accounts: both accounts must exist and have the same ledger as the transfer. The adapter does not issue hidden account queries to emulate that predicate.
+
+Account debits_posted, debits_pending, credits_posted, and credits_pending are cumulative totals, not signed balances. A posted debit increases debits_posted; a posted credit increases credits_posted; pending transfers affect only pending totals; voided transfers and timed-out pending transfers do not affect posted totals. Posting a pending transfer moves its amount into posted totals, while voiding it removes the pending effect.
+
+## Known gaps
+
+- **Pending transfers** — use `create_pending_transfers`, `post_pending_transfers`, and `void_pending_transfers` on the transfers dataset. A pending transfer has the `pending` flag, a positive `timeout`, and `pending_id: 0`. Posting or voiding it uses the corresponding phase flag and a nonzero `pending_id` referring to the original transfer. Posting moves the amount into posted totals; voiding removes the pending effect without posting it.
+- **No linked-chain (atomic batch) convenience API.** You can set `flags.linked` yourself via `ROM::TigerBeetle::Flags.transfer(:linked)`, but there's no builder that manages the chain for you.
+- **Account history uses complete `AccountFilter` values.** `history_for` reads transfers and `balances_for` reads point-in-time balances. Both require accounts created with `flags.history` set, request debit and credit records with a positive limit, and support `timestamp_min`, `timestamp_max`, `reversed`, user-data, code, and explicit `flags` options for pagination and ordering.
+- **Flag bit positions are asserted from the documented protocol**, not read from the gem's own constants (if it exposes `TigerBeetle::AccountFlags`/`TransferFlags`, prefer those over `ROM::TigerBeetle::Flags`).
+
+## Verification
+
+From a clean checkout, install into Bundler's isolated bundle, start the pinned
+TigerBeetle server, run the complete suite, and execute the example:
+
+```
+bundle install
+docker compose up -d
+bundle exec rspec
+bundle exec ruby example.rb
+docker compose down -v
+```
+
+The example verifies account creation, transfer creation, and the resulting
+posted balances. The GitHub Actions workflow runs this same path for every
+supported matrix entry and uses a fresh temporary bundle, so globally installed
+gems are not used.
+
+## Supported Ruby versions
+
+- MRI 3.3 and 3.4 (the CI-supported matrix)
+
+## Supported dependencies
+
+This adapter is tested with `rom`/`rom-core` 5.4 and TigerBeetle Ruby client
+`0.17.9`. The local spec setup and Docker Compose server use the same
+TigerBeetle `0.17.9` release; the gemspec pins that client version so the
+Ruby/server protocol pair cannot drift.
+
+## License
+
+See `LICENSE.txt`.

data/lib/rom/tiger_beetle/commands/create_accounts.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "rom/commands"
+
+module ROM
+  module TigerBeetle
+    module Commands
+      # There is deliberately no Update or Delete command in this adapter.
+      # TigerBeetle accounts/transfers are append-only ledger entries —
+      # balances change only as a side effect of new transfers, and nothing
+      # is ever mutated or removed in place. Modeling "update" here would
+      # misrepresent what the database actually does.
+      class CreateAccounts < ROM::Commands::Create
+        adapter :tiger_beetle
+
+        def execute(tuples)
+          relation.dataset.insert(tuples)
+        end
+      end
+    end
+  end
+end

data/lib/rom/tiger_beetle/commands/create_pending_transfers.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "rom/commands"
+
+module ROM
+  module TigerBeetle
+    module Commands
+      class CreatePendingTransfers < ROM::Commands::Create
+        adapter :tiger_beetle
+
+        def execute(tuples)
+          relation.dataset.create_pending_transfers(tuples)
+        end
+      end
+    end
+  end
+end

data/lib/rom/tiger_beetle/commands/create_transfers.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "rom/commands"
+
+module ROM
+  module TigerBeetle
+    module Commands
+      class CreateTransfers < ROM::Commands::Create
+        adapter :tiger_beetle
+
+        def execute(tuples)
+          relation.dataset.insert(tuples)
+        end
+      end
+    end
+  end
+end

data/lib/rom/tiger_beetle/commands/post_pending_transfers.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "rom/commands"
+
+module ROM
+  module TigerBeetle
+    module Commands
+      class PostPendingTransfers < ROM::Commands::Create
+        adapter :tiger_beetle
+
+        def execute(tuples)
+          relation.dataset.post_pending_transfers(tuples)
+        end
+      end
+    end
+  end
+end

data/lib/rom/tiger_beetle/commands/void_pending_transfers.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "rom/commands"
+
+module ROM
+  module TigerBeetle
+    module Commands
+      class VoidPendingTransfers < ROM::Commands::Create
+        adapter :tiger_beetle
+
+        def execute(tuples)
+          relation.dataset.void_pending_transfers(tuples)
+        end
+      end
+    end
+  end
+end

data/lib/rom/tiger_beetle/commands.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require "rom/tiger_beetle/commands/create_accounts"
+require "rom/tiger_beetle/commands/create_transfers"
+require "rom/tiger_beetle/commands/create_pending_transfers"
+require "rom/tiger_beetle/commands/post_pending_transfers"
+require "rom/tiger_beetle/commands/void_pending_transfers"

data/lib/rom/tiger_beetle/dataset.rb

@@ -0,0 +1,328 @@
+# frozen_string_literal: true
+
+module ROM
+  module TigerBeetle
+    # TigerBeetle intentionally does not support arbitrary predicate queries
+    # or full-table scans (that's the performance trade-off that makes it
+    # fast). What it supports:
+    #   - batch lookup by id            -> lookup_accounts / lookup_transfers
+    #   - batch create (append-only)    -> create_accounts / create_transfers / two-phase transfer operations
+    #   - id-scoped history queries     -> get_account_transfers / get_account_balances
+    #     (only for accounts created with flags.history set)
+    #
+    # This Dataset reflects that honestly instead of faking a SQL-like
+    # interface: `where` only accepts `:id`, and there is no `update`/general
+    # `delete` because ledger entries are immutable once created.
+    class Dataset
+      include Enumerable
+
+      # 8,189 is the documented default maximum, not a universal server limit.
+      # Configure batch_size to the limit advertised by the cluster.
+      DEFAULT_BATCH_SIZE = 8_189
+      LINKED_FLAG = 1 << 0
+
+      attr_reader :client, :kind, :ids, :batch_size
+
+      def initialize(client:, kind:, ids: nil, batch_size: DEFAULT_BATCH_SIZE)
+        @client = client
+        @kind = kind
+        @ids = ids
+        @batch_size = Integer(batch_size)
+        raise ArgumentError, "batch_size must be greater than zero" unless @batch_size.positive?
+      end
+
+      def where(conditions)
+        unless conditions.keys == [:id]
+          raise NotImplementedError,
+            "TigerBeetle only supports lookup by :id, not arbitrary predicates (#{conditions.keys.inspect}). " \
+            "Use #related history methods (get_account_transfers/get_account_balances) for account-scoped queries instead."
+        end
+
+        new_ids = Array(conditions[:id])
+        self.class.new(client: client, kind: kind, ids: new_ids, batch_size: batch_size)
+      end
+      alias_method :restrict, :where
+
+      def each(&block)
+        return to_enum(:each) unless block_given?
+
+        rows.each(&block)
+      end
+
+      def insert(tuples)
+        batch = Array(tuples).flatten
+        create_method = kind == :accounts ? :create_accounts : :create_transfers
+
+        kind == :accounts ? validate_accounts!(batch) : validate_transfers!(batch, :single)
+
+        results = chunks(batch).flat_map do |chunk|
+          Array(client.public_send(create_method, chunk.map { |t| build(t) }))
+        end
+        errors = results.reject { |result| create_succeeded?(result) }
+
+        unless errors.empty?
+          raise ROM::TigerBeetle::CommandError.new(kind, errors)
+        end
+
+        batch
+      end
+
+      def insert_without_validation(tuples)
+        batch = Array(tuples).flatten
+        create_method = kind == :accounts ? :create_accounts : :create_transfers
+        results = chunks(batch).flat_map { |chunk| Array(client.public_send(create_method, chunk.map { |t| build(t) })) }
+        errors = results.reject { |result| create_succeeded?(result) }
+        raise ROM::TigerBeetle::CommandError.new(kind, errors) unless errors.empty?
+        batch
+      end
+
+      def create_pending_transfers(tuples)
+        transfer_operation(tuples, :pending)
+      end
+
+      def post_pending_transfers(tuples)
+        transfer_operation(tuples, :post_pending)
+      end
+
+      def void_pending_transfers(tuples)
+        transfer_operation(tuples, :void_pending)
+      end
+
+      alias pending_transfers create_pending_transfers
+      alias post_pending post_pending_transfers
+      alias void_pending void_pending_transfers
+
+      private :insert_without_validation
+
+      # Account-scoped transfer history. Accounts must have been created with
+      # flags.history set. `timestamp_min` and `timestamp_max` can be used as
+      # cursors for pagination; `reversed` returns newest records first.
+      def history_for(account_id, **options)
+        account_history(account_id, :get_account_transfers, **options)
+      end
+
+      # Point-in-time balances. Accounts must have been created with
+      # flags.history set, otherwise TigerBeetle cannot retain this history.
+      # The filter options are the same as #history_for.
+      def balances_for(account_id, **options)
+        account_history(account_id, :get_account_balances, **options)
+      end
+      alias account_balances_for balances_for
+
+      TRANSFER_PHASE_FLAGS = { pending: Flags.transfer(:pending), post_pending: Flags.transfer(:post_pending_transfer), void_pending: Flags.transfer(:void_pending_transfer) }.freeze
+      TRANSFER_PHASE_MASK = TRANSFER_PHASE_FLAGS.values.sum
+      TRANSFER_KNOWN_FLAGS = Flags::TRANSFER.values.sum
+      ACCOUNT_KNOWN_FLAGS = Flags::ACCOUNT.values.sum
+      UINT16_MAX = (2**16) - 1
+      UINT32_MAX = (2**32) - 1
+      UINT128_MAX = (2**128) - 1
+      UINT64_MAX = (2**64) - 1
+
+      private
+
+      def account_history(account_id, method_name, limit: 100, user_data_128: 0, user_data_64: 0, user_data_32: 0, code: 0, timestamp_min: 0, timestamp_max: 0, flags: nil, debits: true, credits: true, reversed: false)
+        return [] unless kind == :accounts
+        unless client.respond_to?(method_name)
+          raise NotImplementedError, "installed tigerbeetle gem does not expose this history operation"
+        end
+
+        limit = Integer(limit)
+        raise ArgumentError, "limit must be greater than zero" unless limit.positive?
+        timestamp_min = Integer(timestamp_min)
+        timestamp_max = Integer(timestamp_max)
+        raise ArgumentError, "timestamps must be non-negative" if timestamp_min.negative? || timestamp_max.negative?
+        raise ArgumentError, "timestamp_max must be greater than or equal to timestamp_min" if timestamp_max.positive? && timestamp_max < timestamp_min
+
+        filter_flags = flags.nil? ? 0 : Integer(flags)
+        if flags.nil?
+          filter_flags |= ::TigerBeetle::AccountFilterFlags::DEBITS if debits
+          filter_flags |= ::TigerBeetle::AccountFilterFlags::CREDITS if credits
+        end
+        filter_flags |= ::TigerBeetle::AccountFilterFlags::REVERSED if reversed
+        raise ArgumentError, "at least one of debits or credits must be selected" if (filter_flags & 3).zero?
+
+        # Pass every AccountFilter field explicitly. This keeps the adapter
+        # correct if client defaults change and makes pagination/order visible.
+        filter = ::TigerBeetle::AccountFilter.new(account_id: account_id, user_data_128: Integer(user_data_128), user_data_64: Integer(user_data_64), user_data_32: Integer(user_data_32), code: Integer(code), timestamp_min: timestamp_min, timestamp_max: timestamp_max, limit: limit, flags: filter_flags)
+
+        client.public_send(method_name, filter)
+      end
+
+      def transfer_operation(tuples, mode)
+        raise NotImplementedError, "transfer operations are only available on the transfers dataset" unless kind == :transfers
+        batch = Array(tuples).flatten
+        validate_transfers!(batch, mode)
+        insert_without_validation(batch)
+      end
+
+      def validate_transfers!(batch, mode)
+        batch.each_with_index do |tuple, index|
+          raise ArgumentError, "transfer at index #{index} must be a hash-like object" unless tuple.respond_to?(:[])
+          validate_transfer_fields!(tuple, index)
+          flags = integer_field(tuple, :flags, 0, index)
+          pending_id = integer_field(tuple, :pending_id, 0, index)
+          timeout = integer_field(tuple, :timeout, 0, index)
+          raise ArgumentError, "transfer at index #{index} has invalid flags #{flags.inspect}" if flags.negative? || (flags & ~TRANSFER_KNOWN_FLAGS).positive?
+          raise ArgumentError, "transfer at index #{index} has invalid pending_id #{pending_id.inspect}" if pending_id.negative? || pending_id >= UINT128_MAX
+          raise ArgumentError, "transfer at index #{index} has invalid timeout #{timeout.inspect}" if timeout.negative? || timeout > UINT64_MAX
+          phase_flag = flags & TRANSFER_PHASE_MASK
+          expected_flag = mode == :single ? 0 : TRANSFER_PHASE_FLAGS.fetch(mode)
+          raise ArgumentError, "transfer at index #{index} must be single-phase (no phase flag)" if mode == :single && phase_flag != 0
+          raise ArgumentError, "transfer at index #{index} must use the #{mode} transfer flag" unless mode == :single || phase_flag == expected_flag
+          case mode
+          when :single
+            raise ArgumentError, "pending_id must be zero for a single-phase transfer" unless pending_id.zero?
+            raise ArgumentError, "amount must be greater than zero for a single-phase transfer" unless tuple[:amount].positive?
+            raise ArgumentError, "timeout must be zero for a single-phase transfer" unless timeout.zero?
+          when :pending
+            require_transfer_fields!(tuple, index)
+            raise ArgumentError, "amount must be greater than zero for a pending transfer" unless tuple[:amount].positive?
+            raise ArgumentError, "pending_id must be zero for a pending transfer" unless pending_id.zero?
+            raise ArgumentError, "timeout must be greater than zero for a pending transfer" unless timeout.positive?
+          when :post_pending, :void_pending
+            require_transfer_fields!(tuple, index)
+            if mode == :void_pending
+              raise ArgumentError, "amount must be zero for a void_pending transfer" unless tuple[:amount].zero?
+            else
+              raise ArgumentError, "amount must be greater than zero for a post_pending transfer" unless tuple[:amount].positive?
+            end
+            raise ArgumentError, "pending_id must be nonzero and less than 2^128 - 1 for a #{mode} transfer" unless pending_id.positive? && pending_id < UINT128_MAX
+            raise ArgumentError, "timeout must be zero for a #{mode} transfer" unless timeout.zero?
+          end
+        end
+      end
+
+      def validate_accounts!(batch)
+        batch.each_with_index do |tuple, index|
+          raise ArgumentError, "account at index #{index} must be a hash-like object" unless tuple.respond_to?(:[])
+          validate_uint128_id!(tuple[:id], :id, index, "account")
+          ledger = required_integer!(tuple, :ledger, index, "account")
+          code = required_integer!(tuple, :code, index, "account")
+          flags = integer_field(tuple, :flags, 0, index)
+          validate_range!(ledger, 1, UINT32_MAX, :ledger, index, "account")
+          validate_range!(code, 1, UINT16_MAX, :code, index, "account")
+          validate_range!(flags, 0, ACCOUNT_KNOWN_FLAGS, :flags, index, "account")
+        end
+      end
+
+      def validate_transfer_fields!(tuple, index)
+        validate_uint128_id!(tuple[:id], :id, index, "transfer")
+        debit = tuple[:debit_account_id]
+        credit = tuple[:credit_account_id]
+        validate_uint128_id!(debit, :debit_account_id, index, "transfer")
+        validate_uint128_id!(credit, :credit_account_id, index, "transfer")
+        raise ArgumentError, "debit_account_id and credit_account_id must be distinct at index #{index}" if debit == credit
+        amount = required_integer!(tuple, :amount, index, "transfer")
+        ledger = required_integer!(tuple, :ledger, index, "transfer")
+        code = required_integer!(tuple, :code, index, "transfer")
+        validate_range!(amount, 0, UINT128_MAX, :amount, index, "transfer")
+        validate_range!(ledger, 1, UINT32_MAX, :ledger, index, "transfer")
+        validate_range!(code, 1, UINT16_MAX, :code, index, "transfer")
+      end
+
+      def validate_uint128_id!(value, field, index, record_type)
+        validate_range!(value, 1, UINT128_MAX - 1, field, index, record_type)
+      end
+
+      def required_integer!(tuple, field, index, record_type)
+        value = tuple[field]
+        raise ArgumentError, "#{field} is required for a #{record_type} at index #{index}" unless value.is_a?(Integer)
+        value
+      end
+
+      def validate_range!(value, minimum, maximum, field, index, record_type)
+        unless value.is_a?(Integer) && value.between?(minimum, maximum)
+          raise ArgumentError, "#{field} must be between #{minimum} and #{maximum} for a #{record_type} at index #{index}"
+        end
+      end
+
+      def require_transfer_fields!(tuple, index)
+        %i[id debit_account_id credit_account_id amount ledger code].each do |field|
+          value = tuple[field]
+          raise ArgumentError, "#{field} is required for a two-phase transfer at index #{index}" if value.nil?
+          raise ArgumentError, "#{field} must be a non-negative integer at index #{index}" unless value.is_a?(Integer) && value >= 0
+        end
+      end
+
+      def integer_field(tuple, field, default, index)
+        value = tuple[field]
+        value = default if value.nil?
+        raise ArgumentError, "#{field} must be an integer at index #{index}" unless value.is_a?(Integer)
+        value
+      end
+      private
+
+      def chunks(batch)
+        chunks = []
+        current = []
+
+        linked_groups(batch).each do |group|
+          if group.length > batch_size
+            raise ArgumentError,
+              "linked #{kind} chain has #{group.length} records, exceeding batch_size #{batch_size}"
+          end
+
+          if !current.empty? && current.length + group.length > batch_size
+            chunks << current
+            current = []
+          end
+
+          current.concat(group)
+        end
+
+        chunks << current unless current.empty?
+        chunks
+      end
+
+      def linked_groups(batch)
+        groups = []
+        current = []
+
+        batch.each do |tuple|
+          current << tuple
+          unless linked?(tuple)
+            groups << current
+            current = []
+          end
+        end
+
+        groups << current unless current.empty?
+        groups
+      end
+
+      def linked?(tuple)
+        flags = tuple.respond_to?(:[]) ? tuple[:flags] : tuple.flags
+        !flags.nil? && (Integer(flags) & LINKED_FLAG).positive?
+      end
+
+      def rows
+        return [] if ids.nil? || ids.empty?
+
+        lookup_method = kind == :accounts ? :lookup_accounts : :lookup_transfers
+        Array(client.public_send(lookup_method, ids))
+      end
+
+      def build(tuple)
+        struct_class = kind == :accounts ? ::TigerBeetle::Account : ::TigerBeetle::Transfer
+        struct_class.new(**tuple)
+      end
+
+      def create_succeeded?(result)
+        status_class = kind == :accounts ? ::TigerBeetle::CreateAccountStatus : ::TigerBeetle::CreateTransferStatus
+        status = result.status
+
+        [status_class::CREATED, status_class::EXISTS].include?(status)
+      end
+    end
+
+    class CommandError < StandardError
+      attr_reader :kind, :errors
+
+      def initialize(kind, errors)
+        @kind = kind
+        @errors = errors
+        super("#{errors.size} #{kind} entries failed: #{errors.inspect}")
+      end
+    end
+  end
+end

data/lib/rom/tiger_beetle/flags.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module ROM
+  module TigerBeetle
+    # TigerBeetle::Account#flags and TigerBeetle::Transfer#flags are plain
+    # uint16 bitfields. The tigerbeetle gem may or may not expose named
+    # constants for these (check `defined?(::TigerBeetle::AccountFlags)` at
+    # runtime against whatever version you're on) — these mirror the bit
+    # positions documented at https://docs.tigerbeetle.com/reference/account/
+    # and https://docs.tigerbeetle.com/reference/transfer/, which are stable
+    # across every official client (Go/Java/.NET/Node/Python/Rust).
+    #
+    # Verify against your installed gem version before relying on this in
+    # production — if TigerBeetle::AccountFlags/TransferFlags exist, prefer
+    # those over this fallback.
+    module Flags
+      ACCOUNT = {
+        linked: 1 << 0,
+        debits_must_not_exceed_credits: 1 << 1,
+        credits_must_not_exceed_debits: 1 << 2,
+        history: 1 << 3,
+        imported: 1 << 4,
+        closed: 1 << 5
+      }.freeze
+
+      TRANSFER = {
+        linked: 1 << 0,
+        pending: 1 << 1,
+        post_pending_transfer: 1 << 2,
+        void_pending_transfer: 1 << 3,
+        balancing_debit: 1 << 4,
+        balancing_credit: 1 << 5,
+        closing_debit: 1 << 6,
+        closing_credit: 1 << 7,
+        imported: 1 << 8
+      }.freeze
+
+      def self.account(*names)
+        names.sum { |n| ACCOUNT.fetch(n) }
+      end
+
+      def self.transfer(*names)
+        names.sum { |n| TRANSFER.fetch(n) }
+      end
+    end
+  end
+end

data/lib/rom/tiger_beetle/gateway.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "rom/initializer"
+require "tigerbeetle"
+require "rom/tiger_beetle/dataset"
+
+module ROM
+  module TigerBeetle
+    # ROM::Gateway backed by the `tigerbeetle` gem (native Zig client via FFI).
+    #
+    # TigerBeetle has exactly two datasets, fixed by the protocol: :accounts
+    # and :transfers. There's no arbitrary schema/table creation — this
+    # gateway doesn't pretend otherwise.
+    #
+    # @example basic configuration
+    #   conf = ROM::Configuration.new(:tiger_beetle, addresses: "3000")
+    #
+    #   class Accounts < ROM::Relation[:tiger_beetle]
+    #     schema(:accounts, infer: false) do
+    #       attribute :id, ROM::TigerBeetle::Types::UInt128
+    #       attribute :ledger, ROM::TigerBeetle::Types::UInt32
+    #       attribute :code, ROM::TigerBeetle::Types::UInt32
+    #     end
+    #   end
+    #
+    #   conf.register_relation(Accounts)
+    #   rom = ROM.container(conf)
+    #   rom.relations[:accounts].by_id(100).one
+    class Gateway < ROM::Gateway
+      extend Initializer
+
+      KINDS = %i[accounts transfers].freeze
+
+      # @!attribute [r] addresses
+      #   @return [String] comma-separated replica addresses, e.g. "3000"
+      #     or "127.0.0.1:3000,127.0.0.1:3001"
+      # NOTE: fully-qualified as ROM::Types — our own ROM::TigerBeetle::Types
+      # module (see types.rb) is closer in lexical scope and would otherwise
+      # shadow it here, since it also happens to be named `Types`.
+      option :addresses, ROM::Types::Strict::String
+
+      # @!attribute [r] cluster_id
+      #   @return [Integer]
+      option :cluster_id, ROM::Types::Strict::Integer, default: -> { 0 }
+
+      # Maximum records per create request; configure this to the cluster limit.
+      option :batch_size, ROM::Types::Strict::Integer, default: -> { Dataset::DEFAULT_BATCH_SIZE }
+
+      # @!attribute [r] client
+      #   @return [TigerBeetle::Client]
+      option :client, default: lambda {
+        ::TigerBeetle::Client.new(
+          cluster_id: cluster_id,
+          replica_addresses: addresses
+        )
+      }
+
+      # Get a dataset by its kind (:accounts or :transfers)
+      #
+      # @param kind [Symbol]
+      # @return [Dataset]
+      # @api public
+      def dataset(kind)
+        raise ArgumentError, "unknown TigerBeetle dataset #{kind.inspect}, must be one of #{KINDS}" unless KINDS.include?(kind)
+
+        Dataset.new(client: client, kind: kind, batch_size: batch_size)
+      end
+      alias_method :[], :dataset
+
+      # Return true if a dataset with the given kind exists
+      #
+      # @param kind [Symbol]
+      # @return [Boolean]
+      # @api public
+      def dataset?(kind)
+        KINDS.include?(kind)
+      end
+
+      # @api public
+      def schema
+        KINDS
+      end
+
+      # @api public
+      def disconnect
+        return if @disconnected
+
+        @disconnected = true
+        return unless client&.respond_to?(:close)
+
+        client.close
+      end
+    end
+  end
+end

data/lib/rom/tiger_beetle/relation.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "rom/relation"
+
+module ROM
+  module TigerBeetle
+    class Relation < ROM::Relation
+      adapter :tiger_beetle
+
+      forward :where
+
+      # Convenience for the common "give me these accounts/transfers by id" case.
+      def by_id(*ids)
+        where(id: ids.flatten)
+      end
+
+      def history_for(account_id, **options)
+        dataset.history_for(account_id, **options)
+      end
+
+      def balances_for(account_id, **options)
+        dataset.balances_for(account_id, **options)
+      end
+      alias account_balances_for balances_for
+    end
+  end
+end

data/lib/rom/tiger_beetle/types.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "dry/types"
+
+module ROM
+  module TigerBeetle
+    module Types
+      include Dry.Types()
+
+      # Amounts and ids are unsigned 128-bit integers on the wire; Ruby's
+      # Integer handles the range natively, this gives schemas a matching
+      # range assertion.
+      UInt128 = Types::Integer.constrained(gteq: 0, lteq: (2**128) - 1)
+      UInt128ID = Types::Integer.constrained(gteq: 1, lt: (2**128) - 1)
+      UInt64 = Types::Integer.constrained(gteq: 0, lteq: (2**64) - 1)
+      UInt16 = Types::Integer.constrained(gteq: 0, lteq: (2**16) - 1)
+      UInt32 = Types::Integer.constrained(gteq: 0, lteq: (2**32) - 1)
+
+      # Prefer TigerBeetle-generated time-based ids (monotonic, avoids hot
+      # B-tree pages under concurrent inserts) over sequential integers or
+      # random UUIDs. Wraps ::TigerBeetle.id if the gem exposes it.
+      def self.generate_id
+        if defined?(::TigerBeetle) && ::TigerBeetle.respond_to?(:id)
+          ::TigerBeetle.id
+        else
+          raise NotImplementedError, "installed tigerbeetle gem doesn't expose .id — generate a monotonic 128-bit id yourself"
+        end
+      end
+    end
+  end
+end

data/lib/rom/tiger_beetle/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module ROM
+  module TigerBeetle
+    VERSION = "0.1.0"
+  end
+end

data/lib/rom/tiger_beetle.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "rom/core"
+require "rom/tiger_beetle/version"
+require "rom/tiger_beetle/types"
+require "rom/tiger_beetle/flags"
+require "rom/tiger_beetle/gateway"
+require "rom/tiger_beetle/relation"
+require "rom/tiger_beetle/commands"
+
+ROM.register_adapter(:tiger_beetle, ROM::TigerBeetle)

metadata

@@ -0,0 +1,155 @@
+--- !ruby/object:Gem::Specification
+name: rom-tiger_beetle
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Paul Oguda
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rom-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.2'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.2.5
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.2'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.2.5
+- !ruby/object:Gem::Dependency
+  name: tigerbeetle
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.17.9
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.17.9
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rom
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.2'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.2.5
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.2'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.2.5
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Experimental TigerBeetle support for ROM. Accounts and Transfers only,
+  append-only, batch create + id lookup — no arbitrary queries, updates, or deletes,
+  matching what the TigerBeetle protocol actually supports.
+email: []
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/rom/tiger_beetle.rb
+- lib/rom/tiger_beetle/commands.rb
+- lib/rom/tiger_beetle/commands/create_accounts.rb
+- lib/rom/tiger_beetle/commands/create_pending_transfers.rb
+- lib/rom/tiger_beetle/commands/create_transfers.rb
+- lib/rom/tiger_beetle/commands/post_pending_transfers.rb
+- lib/rom/tiger_beetle/commands/void_pending_transfers.rb
+- lib/rom/tiger_beetle/dataset.rb
+- lib/rom/tiger_beetle/flags.rb
+- lib/rom/tiger_beetle/gateway.rb
+- lib/rom/tiger_beetle/relation.rb
+- lib/rom/tiger_beetle/types.rb
+- lib/rom/tiger_beetle/version.rb
+homepage: https://github.com/kamalogudah/rom-tiger_beetle
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/kamalogudah/rom-tiger_beetle
+  bug_tracker_uri: https://github.com/kamalogudah/rom-tiger_beetle/issues
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: ROM adapter for TigerBeetle
+test_files: []