igniter-ledger-client 0.5.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c4fe38120d406045031a3f7bfaae0c29e576b30c539c6632d7b3dc2a1b1d4b85
+  data.tar.gz: eea5c501aa9c2c30a0c512426bd855321de3a4ca8788b4bdc5183bd7755179ee
+SHA512:
+  metadata.gz: 4e32fca6b33da4045e7339df9ff2abf2c863941cbb287bba4758c0b6cc17e60105e509469f588eec33a9b695f68bd9817c4717b609f58ad6999e3794cf378fa7
+  data.tar.gz: 70f56f887565bc4871173b4749a0d3ce99259608148dba12bdef33e0a42fa995b7c76fa263ad60fddf2d312848ae32987d101c49bbfe6184a87876d0814b8745

data/README.md

@@ -0,0 +1,173 @@
+# igniter-ledger-client
+
+Protocol-first client package for Igniter Ledger / Ledger Open Protocol.
+
+Status: pre-v1 skeleton. This package owns the client boundary, not the storage
+engine.
+
+## Purpose
+
+`igniter-ledger-client` is the shared client layer for packages and host apps
+that need to talk to a Ledger/Store endpoint without depending on
+`igniter-ledger` internals.
+
+```text
+Embed / Companion / Web / MCP / Spark adapters
+  -> Igniter::LedgerClient
+  -> Ledger Open Protocol envelope
+  -> local dispatch | remote HTTP | future TCP/pool/outbox transport
+```
+
+The package deliberately has no runtime dependency on `igniter-ledger`.
+
+## Owns
+
+- request/response envelope helpers
+- client error semantics
+- stable Ruby method surface for common Ledger operations
+- transport adapters such as object dispatch and remote HTTP
+- future pooling, timeout, retry, and backpressure policy seams
+
+## Does Not Own
+
+- fact storage engine
+- WAL, segments, compaction, or changefeed internals
+- contract execution
+- Rails, Sidekiq, ActiveRecord, or Spark-specific code
+- Store-to-Ledger package rename
+
+## Example
+
+```ruby
+require "igniter-ledger-client"
+
+client = Igniter::LedgerClient.remote_http(
+  "http://127.0.0.1:7300/v1/dispatch",
+  open_timeout: 1.0,
+  read_timeout: 2.0
+)
+
+client.write(
+  store: :orders,
+  key: "order-1",
+  value: { status: :open },
+  producer: { type: :app, name: :spark }
+)
+
+client.append(
+  history: :order_events,
+  event: { event_id: "evt-1", order_id: "order-1", event: :opened },
+  partition_key: :order_id,
+  producer: { type: :app, name: :spark }
+)
+
+client.read(store: :orders, key: "order-1")
+```
+
+For local/integration tests, wrap any object exposing `dispatch(envelope)` or
+`wire.dispatch(envelope)`:
+
+```ruby
+client = Igniter::LedgerClient.wrap(protocol_interpreter.wire)
+client.metadata_snapshot
+```
+
+When `igniter-ledger` is present in the same process, wrapping
+`LedgerStore#protocol` is the local adoption path:
+
+```ruby
+ledger = Igniter::Ledger::LedgerStore.new
+client = Igniter::LedgerClient.wrap(ledger.protocol)
+```
+
+Package-level adapters should prefer accepting a `client:` argument over
+reaching into Ledger internals. For example, `ContractableReceiptSink` can be
+constructed with `client: client` and still use the same protocol envelope path
+as a remote HTTP client.
+
+## v0 Surface
+
+```ruby
+client.register_descriptor(...)
+client.write(store:, key:, value:, **metadata)
+client.append(history:, event:, key: nil, partition_key: nil, **metadata)
+client.read(store:, key:, as_of: nil)
+client.query(store:, where:, limit: nil, as_of: nil, order: nil)
+client.replay(
+  store: nil,
+  from: nil,
+  to: nil,
+  key: nil,
+  partition_key: nil,
+  partition_value: nil,
+  filter: nil
+)
+client.resolve(relation:, from:, as_of: nil)
+client.causation_chain(store:, key:)
+client.lineage(store:, key:)
+client.fact_ref(fact_id)
+client.subscribe(stores:, cursor: nil) { |event| ... }
+client.metadata_snapshot
+client.descriptor_snapshot
+client.observability_snapshot
+client.compaction_activity(store: nil, kind: nil, since: nil, limit: nil)
+client.close
+```
+
+`append` dispatches the Ledger Open Protocol `append` op and keeps append-only
+history semantics distinct from keyed record writes. `key:` may be sent as
+client metadata for future idempotency work, but protocol v0 returns the
+generated fact key and does not treat `key:` as a stable idempotency guarantee.
+
+`replay` accepts either an explicit protocol `filter:` or convenience arguments
+for store, key, and partition replay. Partition replay sends
+`filter: { store:, partition_key:, partition_value: }` and uses Ledger
+partition indexes when the endpoint is backed by a Ledger protocol interpreter.
+
+`subscribe` returns an idempotently closeable handle and yields
+`Igniter::LedgerClient::Results::ChangeEventResult` objects. Remote HTTP
+subscriptions read SSE from `/v1/events`; `events_url:` can be passed explicitly,
+otherwise it is derived from `/v1/dispatch`. Cursor resume uses the `?cursor=`
+query parameter.
+
+## Docs
+
+- [docs/tracks/ledger-client-protocol-v0.md](docs/tracks/ledger-client-protocol-v0.md)
+  — current implementation/convergence track for this package.
+
+## Error Policy
+
+The client raises `Igniter::LedgerClient::Error` for protocol error envelopes
+and `Igniter::LedgerClient::TransportError` for transport failures.
+
+Successful mutation/read calls return small result objects:
+
+- `write` -> `Igniter::LedgerClient::Results::WriteResult`
+- `append` -> `Igniter::LedgerClient::Results::AppendResult`
+- `register_descriptor` -> `Igniter::LedgerClient::Results::ReceiptResult`
+- `read` -> `Igniter::LedgerClient::Results::ReadResult`
+- `query` -> `Igniter::LedgerClient::Results::QueryResult`
+- `resolve` -> `Igniter::LedgerClient::Results::ResolveResult`
+- `replay` -> `Igniter::LedgerClient::Results::ReplayResult`
+- `causation_chain` -> `Igniter::LedgerClient::Results::CausationChainResult`
+- `lineage` -> `Igniter::LedgerClient::Results::LineageResult`
+- `fact_ref` -> `Igniter::LedgerClient::Results::FactRefResult`
+- `subscribe` events -> `Igniter::LedgerClient::Results::ChangeEventResult`
+
+Result objects expose named readers, `to_h`, and transitional `[]` access.
+`QueryResult#items` is the canonical row shape for query consumers and includes
+`{ key:, value: }` entries; `QueryResult#results` remains the backward-compatible
+value-only list. `ResolveResult` follows the same `items`/`results` convention
+so typed clients can preserve source record keys.
+`causation_chain`, `lineage`, and `fact_ref` are read-only provenance
+introspection calls. `fact_ref` returns compact metadata only; arbitrary
+`fact_by_id` value reads remain outside the public client surface.
+Snapshot-style methods such as `metadata_snapshot` and `observability_snapshot`
+still return raw protocol hashes in v0.
+
+## Package Boundary
+
+`igniter-embed` should not own Store connections, pools, retries, or
+backpressure. Embed emits receipts to an adapter protocol. The adapter can then
+use `igniter-ledger-client` to deliver those receipts locally, remotely, or
+through a host outbox.

data/lib/igniter/ledger_client/client.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require_relative "envelope"
+require_relative "error"
+require_relative "results"
+require_relative "subscription"
+
+module Igniter
+  module LedgerClient
+    class Client
+      attr_reader :transport
+
+      def initialize(transport:)
+        @transport = transport
+      end
+
+      def register_descriptor(descriptor = nil, **fields)
+        Results.wrap(:register_descriptor, dispatch(:register_descriptor, (descriptor || {}).merge(fields)))
+      end
+
+      def write(store:, key:, value:, **metadata)
+        Results.wrap(:write, dispatch(:write, metadata.merge(store: store, key: key, value: value)))
+      end
+
+      def append(history:, event:, key: nil, partition_key: nil, **metadata)
+        packet = metadata.merge(history: history, event: event)
+        packet[:key] = key if key
+        packet[:partition_key] = partition_key if partition_key
+        Results.wrap(:append, dispatch(:append, packet))
+      end
+
+      def read(store:, key:, as_of: nil)
+        packet = { store: store, key: key }
+        packet[:as_of] = as_of if as_of
+        Results.wrap(:read, dispatch(:read, packet))
+      end
+
+      def query(store:, where:, limit: nil, as_of: nil, order: nil)
+        packet = { store: store, where: where }
+        packet[:limit] = limit if limit
+        packet[:as_of] = as_of if as_of
+        packet[:order] = order if order
+        Results.wrap(:query, dispatch(:query, packet))
+      end
+
+      def replay(store: nil, from: nil, to: nil, key: nil, partition_key: nil, partition_value: nil, filter: nil)
+        packet = {}
+        packet[:from] = from if from
+        packet[:to] = to if to
+        filter_packet = replay_filter(
+          store: store,
+          key: key,
+          partition_key: partition_key,
+          partition_value: partition_value,
+          filter: filter
+        )
+        packet[:filter] = filter_packet if filter_packet
+        Results.wrap(:replay, dispatch(:replay, packet))
+      end
+
+      def resolve(relation:, from:, as_of: nil)
+        packet = { relation: relation, from: from }
+        packet[:as_of] = as_of if as_of
+        Results.wrap(:resolve, dispatch(:resolve, packet))
+      end
+
+      def causation_chain(store:, key:)
+        Results.wrap(:causation_chain, dispatch(:causation_chain, { store: store, key: key }))
+      end
+
+      def lineage(store:, key:)
+        Results.wrap(:lineage, dispatch(:lineage, { store: store, key: key }))
+      end
+
+      def fact_ref(fact_id)
+        Results.wrap(:fact_ref, dispatch(:fact_ref, { fact_id: fact_id }))
+      end
+
+      def metadata_snapshot = dispatch(:metadata_snapshot)
+
+      def descriptor_snapshot = dispatch(:descriptor_snapshot)
+
+      def observability_snapshot = dispatch(:observability_snapshot)
+
+      def compaction_activity(store: nil, kind: nil, since: nil, limit: nil)
+        packet = {}
+        packet[:store] = store if store
+        packet[:kind] = kind if kind
+        packet[:since] = since if since
+        packet[:limit] = limit if limit
+        dispatch(:compaction_activity, packet)
+      end
+
+      def subscribe(stores:, cursor: nil, &block)
+        raise ArgumentError, "subscribe requires a block" unless block
+
+        raise NotImplementedError, "ledger client transport does not support subscriptions" unless transport.respond_to?(:subscribe)
+
+        transport.subscribe(stores: stores, cursor: cursor) do |event|
+          block.call(Results::ChangeEventResult.new(event))
+        end
+      end
+
+      def dispatch(operation, packet = {}, request_id: nil)
+        request = Envelope.request(operation: operation, packet: packet, request_id: request_id)
+        Envelope.result_or_raise(transport.dispatch(request))
+      rescue Error
+        raise
+      rescue StandardError => e
+        raise TransportError.new(e.message, request_id: request&.fetch(:request_id, nil))
+      end
+
+      def close
+        transport.close if transport.respond_to?(:close)
+      end
+
+      private
+
+      def replay_filter(store:, key:, partition_key:, partition_value:, filter:)
+        convenience_filter = {}
+        convenience_filter[:store] = store if store
+        convenience_filter[:key] = key if key
+        convenience_filter[:partition_key] = partition_key if partition_key
+        convenience_filter[:partition_value] = partition_value if partition_value
+
+        raise ArgumentError, "replay filter: cannot be combined with store/key/partition convenience arguments" if filter && !convenience_filter.empty?
+
+        return filter if filter
+        return nil if convenience_filter.empty?
+
+        convenience_filter
+      end
+    end
+  end
+end

data/lib/igniter/ledger_client/envelope.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Igniter
+  module LedgerClient
+    module Envelope
+      PROTOCOL = :igniter_store
+      SCHEMA_VERSION = 1
+
+      OPERATIONS = %i[
+        register_descriptor
+        write
+        append
+        write_fact
+        read
+        query
+        resolve
+        causation_chain
+        lineage
+        fact_ref
+        metadata_snapshot
+        descriptor_snapshot
+        observability_snapshot
+        sync_hub_profile
+        replay
+        storage_stats
+        segment_manifest
+        compaction_activity
+      ].freeze
+
+      module_function
+
+      def request(operation:, packet: {}, request_id: nil)
+        operation = operation.to_sym
+        raise ArgumentError, "unknown ledger op: #{operation.inspect}" unless OPERATIONS.include?(operation)
+
+        {
+          protocol: PROTOCOL,
+          schema_version: SCHEMA_VERSION,
+          request_id: request_id || generate_request_id,
+          op: operation,
+          packet: packet || {}
+        }
+      end
+
+      def ok?(response)
+        normalize(response)[:status]&.to_sym == :ok
+      end
+
+      def result_or_raise(response)
+        response = normalize(response)
+        return response[:result] if ok?(response)
+
+        raise Error.new(
+          response[:error] || "ledger client request failed",
+          response: response,
+          request_id: response[:request_id]
+        )
+      end
+
+      def normalize(hash)
+        hash.to_h.transform_keys(&:to_sym)
+      end
+
+      def generate_request_id
+        "req_#{SecureRandom.hex(12)}"
+      end
+    end
+  end
+end

data/lib/igniter/ledger_client/error.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Igniter
+  module LedgerClient
+    class Error < StandardError
+      attr_reader :response, :request_id
+
+      def initialize(message, response: nil, request_id: nil)
+        super(message)
+        @response = response
+        @request_id = request_id
+      end
+    end
+
+    class TransportError < Error; end
+  end
+end

data/lib/igniter/ledger_client/results.rb

@@ -0,0 +1,406 @@
+# frozen_string_literal: true
+
+module Igniter
+  module LedgerClient
+    module Results
+      module HashAccess
+        def [](key)
+          to_h[key.to_sym]
+        end
+      end
+
+      class ReceiptResult
+        include HashAccess
+
+        FIELDS = %i[
+          schema_version
+          kind
+          status
+          name
+          store
+          key
+          fact_id
+          value_hash
+          warnings
+          errors
+          derived
+        ].freeze
+
+        attr_reader(*FIELDS)
+
+        def initialize(raw = {})
+          data = self.class.normalize(raw)
+          @schema_version = data[:schema_version]
+          @kind = token(data[:kind])
+          @status = token(data[:status])
+          @name = token(data[:name])
+          @store = token(data[:store])
+          @key = data[:key]
+          @fact_id = data[:fact_id]
+          @value_hash = data[:value_hash]
+          @warnings = Array(data[:warnings]).freeze
+          @errors = Array(data[:errors]).freeze
+          @derived = Array(data[:derived]).freeze
+          freeze
+        end
+
+        def accepted? = status == :accepted
+
+        def rejected? = status == :rejected
+
+        def deduplicated? = status == :deduplicated
+
+        def to_h
+          {
+            schema_version: schema_version,
+            kind: kind,
+            status: status,
+            name: name,
+            store: store,
+            key: key,
+            fact_id: fact_id,
+            value_hash: value_hash,
+            warnings: warnings,
+            errors: errors,
+            derived: derived
+          }.compact
+        end
+
+        def self.normalize(raw)
+          hash = if raw.respond_to?(:to_h)
+                   raw.to_h
+                 else
+                   FIELDS.each_with_object({}) do |field, acc|
+                     acc[field] = raw.public_send(field) if raw.respond_to?(field)
+                   end
+                 end
+
+          hash.to_h.transform_keys(&:to_sym)
+        end
+
+        private
+
+        def token(value)
+          value.is_a?(String) ? value.to_sym : value
+        end
+      end
+
+      class WriteResult < ReceiptResult
+      end
+
+      class AppendResult < ReceiptResult
+      end
+
+      class ReadResult
+        include HashAccess
+
+        attr_reader :value
+
+        def initialize(raw = {})
+          data = normalize(raw)
+          @value = data[:value]
+          @found = data.key?(:found) ? boolean(data[:found]) : !value.nil?
+          freeze
+        end
+
+        def found? = @found
+
+        def to_h
+          { value: value, found: found? }
+        end
+
+        private
+
+        def normalize(raw)
+          hash = raw.respond_to?(:to_h) ? raw.to_h : {}
+          hash.each_with_object({}) { |(key, value), acc| acc[key.to_sym] = value }
+        end
+
+        def boolean(value)
+          value ? true : false
+        end
+      end
+
+      class QueryResult
+        include HashAccess
+
+        attr_reader :items, :results, :count
+
+        def initialize(raw = {})
+          data = normalize(raw)
+          @items = normalize_items(data[:items]).freeze
+          @results = Array(data[:results] || items.map { |item| item[:value] }).freeze
+          @count = data.key?(:count) ? data[:count].to_i : [items.size, results.size].max
+          freeze
+        end
+
+        def to_h
+          { items: items, results: results, count: count }
+        end
+
+        private
+
+        def normalize(raw)
+          hash = raw.respond_to?(:to_h) ? raw.to_h : {}
+          hash.each_with_object({}) { |(key, value), acc| acc[key.to_sym] = value }
+        end
+
+        def normalize_items(raw_items)
+          Array(raw_items).map do |item|
+            data = item.to_h.transform_keys(&:to_sym)
+            { key: data[:key], value: normalize_value(data[:value] || {}) }
+          end
+        end
+
+        def normalize_value(value)
+          return value unless value.is_a?(Hash)
+
+          value.each_with_object({}) { |(key, entry), acc| acc[key.to_sym] = entry }
+        end
+      end
+
+      class ResolveResult
+        include HashAccess
+
+        attr_reader :items, :results, :count
+
+        def initialize(raw = {})
+          data = normalize(raw)
+          @items = normalize_items(data[:items]).freeze
+          @results = Array(data[:results] || items.map { |item| item[:value] }).freeze
+          @count = data.key?(:count) ? data[:count].to_i : [items.size, results.size].max
+          freeze
+        end
+
+        def to_h
+          { items: items, results: results, count: count }
+        end
+
+        private
+
+        def normalize(raw)
+          return { results: raw } if raw.is_a?(Array)
+
+          hash = raw.respond_to?(:to_h) ? raw.to_h : {}
+          hash.each_with_object({}) { |(key, value), acc| acc[key.to_sym] = value }
+        end
+
+        def normalize_items(raw_items)
+          Array(raw_items).map do |item|
+            data = item.to_h.transform_keys(&:to_sym)
+            { key: data[:key], value: normalize_value(data[:value] || {}) }
+          end
+        end
+
+        def normalize_value(value)
+          return value unless value.is_a?(Hash)
+
+          value.each_with_object({}) { |(key, entry), acc| acc[key.to_sym] = entry }
+        end
+      end
+
+      class ReplayResult
+        include HashAccess
+
+        attr_reader :facts, :count
+
+        def initialize(raw = {})
+          data = normalize(raw)
+          @facts = Array(data[:facts]).freeze
+          @count = data.key?(:count) ? data[:count].to_i : facts.size
+          freeze
+        end
+
+        def to_h
+          { facts: facts, count: count }
+        end
+
+        private
+
+        def normalize(raw)
+          hash = raw.respond_to?(:to_h) ? raw.to_h : {}
+          hash.each_with_object({}) { |(key, value), acc| acc[key.to_sym] = value }
+        end
+      end
+
+      class CausationChainResult
+        include HashAccess
+
+        attr_reader :chain, :count
+
+        def initialize(raw = {})
+          data = normalize(raw)
+          @chain = Array(data[:chain]).map { |entry| normalize_hash(entry) }.freeze
+          @count = data.key?(:count) ? data[:count].to_i : chain.size
+          freeze
+        end
+
+        def to_h
+          { chain: chain, count: count }
+        end
+
+        private
+
+        def normalize(raw)
+          return { chain: raw } if raw.is_a?(Array)
+
+          normalize_hash(raw)
+        end
+
+        def normalize_hash(raw)
+          raw.respond_to?(:to_h) ? raw.to_h.transform_keys(&:to_sym) : {}
+        end
+      end
+
+      class LineageResult
+        include HashAccess
+
+        attr_reader :subject, :chain, :depth, :derived_by, :proof_hash
+
+        def initialize(raw = {})
+          data = normalize_hash(raw)
+          @subject = normalize_hash(data[:subject]).freeze
+          @chain = Array(data[:chain]).map { |entry| normalize_hash(entry) }.freeze
+          @depth = data.key?(:depth) ? data[:depth].to_i : chain.size
+          @derived_by = Array(data[:derived_by]).map { |entry| normalize_hash(entry) }.freeze
+          @proof_hash = data[:proof_hash]
+          freeze
+        end
+
+        def to_h
+          {
+            subject: subject,
+            chain: chain,
+            depth: depth,
+            derived_by: derived_by,
+            proof_hash: proof_hash
+          }
+        end
+
+        private
+
+        def normalize_hash(raw)
+          raw.respond_to?(:to_h) ? raw.to_h.transform_keys(&:to_sym) : {}
+        end
+      end
+
+      class FactRefResult
+        include HashAccess
+
+        attr_reader :ref
+
+        def initialize(raw = {})
+          data = normalize_hash(raw)
+          @ref = data[:ref] ? normalize_hash(data[:ref]).freeze : nil
+          @found = if data.key?(:found)
+                     data[:found] ? true : false
+                   else
+                     !ref.nil?
+                   end
+          freeze
+        end
+
+        def found? = @found
+
+        def to_h
+          { found: found?, ref: ref }
+        end
+
+        private
+
+        def normalize_hash(raw)
+          raw.respond_to?(:to_h) ? raw.to_h.transform_keys(&:to_sym) : {}
+        end
+      end
+
+      class ChangeEventResult
+        include HashAccess
+
+        attr_reader :sequence, :store, :key, :fact_id, :value_hash, :cursor, :raw
+
+        def initialize(raw = {})
+          @raw = raw
+          data = normalize(raw)
+          @cursor = normalize_cursor(data[:cursor])
+          @sequence = (data[:sequence] || cursor[:sequence])&.to_i
+          @store = token(data[:store])
+          @key = data[:key]
+          @fact_id = data[:fact_id]
+          @value_hash = data[:value_hash] || fact_value_hash(raw)
+          freeze
+        end
+
+        def to_h
+          {
+            sequence: sequence,
+            store: store,
+            key: key,
+            fact_id: fact_id,
+            value_hash: value_hash,
+            cursor: cursor,
+            raw: raw
+          }.compact
+        end
+
+        private
+
+        def normalize(raw)
+          hash = if raw.respond_to?(:to_h)
+                   raw.to_h
+                 else
+                   %i[sequence store key fact_id value_hash cursor].each_with_object({}) do |field, acc|
+                     acc[field] = raw.public_send(field) if raw.respond_to?(field)
+                   end
+                 end
+
+          hash.to_h.transform_keys(&:to_sym)
+        end
+
+        def normalize_cursor(cursor)
+          return {} unless cursor
+
+          cursor.to_h.transform_keys(&:to_sym).freeze
+        end
+
+        def fact_value_hash(raw)
+          return raw.fact.value_hash if raw.respond_to?(:fact) && raw.fact.respond_to?(:value_hash)
+
+          nil
+        end
+
+        def token(value)
+          value.is_a?(String) ? value.to_sym : value
+        end
+      end
+
+      module_function
+
+      def wrap(operation, raw)
+        case operation.to_sym
+        when :register_descriptor
+          ReceiptResult.new(raw)
+        when :write
+          WriteResult.new(raw)
+        when :append
+          AppendResult.new(raw)
+        when :read
+          ReadResult.new(raw)
+        when :query
+          QueryResult.new(raw)
+        when :resolve
+          ResolveResult.new(raw)
+        when :replay
+          ReplayResult.new(raw)
+        when :causation_chain
+          CausationChainResult.new(raw)
+        when :lineage
+          LineageResult.new(raw)
+        when :fact_ref
+          FactRefResult.new(raw)
+        else
+          raw
+        end
+      end
+    end
+  end
+end

data/lib/igniter/ledger_client/subscription.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Igniter
+  module LedgerClient
+    class Subscription
+      attr_accessor :error
+
+      def initialize(&close_proc)
+        @close_proc = close_proc
+        @closed = false
+        @mutex = Mutex.new
+      end
+
+      def close
+        close_proc = nil
+        @mutex.synchronize do
+          return self if @closed
+
+          @closed = true
+          close_proc = @close_proc
+        end
+
+        close_proc&.call
+        self
+      end
+
+      def closed?
+        @mutex.synchronize { @closed }
+      end
+    end
+  end
+end

data/lib/igniter/ledger_client/transports/object_dispatch.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require_relative "../subscription"
+
+module Igniter
+  module LedgerClient
+    module Transports
+      class ObjectDispatch
+        def initialize(target)
+          @target = target
+        end
+
+        def dispatch(envelope)
+          if @target.respond_to?(:dispatch)
+            @target.dispatch(envelope)
+          elsif @target.respond_to?(:wire)
+            @target.wire.dispatch(envelope)
+          elsif @target.respond_to?(:protocol) && @target.protocol.respond_to?(:wire)
+            @target.protocol.wire.dispatch(envelope)
+          else
+            raise ArgumentError, "object does not expose dispatch(envelope), wire.dispatch(envelope), or protocol.wire.dispatch(envelope)"
+          end
+        end
+
+        def subscribe(stores:, cursor: nil, &block)
+          raise ArgumentError, "subscribe requires a block" unless block
+
+          feed = changefeed_source
+          raise NotImplementedError, "object dispatch target does not expose changefeed.subscribe" unless feed.respond_to?(:subscribe)
+
+          replay(feed, stores: stores, cursor: cursor, handler: block) if cursor
+          handle = feed.subscribe(stores: stores) { |event| block.call(event) }
+          Subscription.new { handle.close }
+        end
+
+        def close
+          @target.close if @target.respond_to?(:close)
+        end
+
+        private
+
+        def changefeed_source
+          @target.changefeed if @target.respond_to?(:changefeed)
+        end
+
+        def replay(feed, stores:, cursor:, handler:)
+          return unless feed.respond_to?(:replay)
+
+          store_filter = Array(stores).empty? ? nil : stores
+          result = feed.replay(cursor: normalize_cursor(cursor), stores: store_filter)
+          raise TransportError, "changefeed cursor is too old" if result[:status].to_sym == :cursor_too_old
+
+          Array(result[:events]).each { |event| handler.call(event) }
+        end
+
+        def normalize_cursor(cursor)
+          return cursor if cursor.is_a?(Hash)
+
+          { sequence: cursor.to_i }
+        end
+      end
+    end
+  end
+end

data/lib/igniter/ledger_client/transports/remote_http.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+require_relative "../subscription"
+
+module Igniter
+  module LedgerClient
+    module Transports
+      class RemoteHTTP
+        attr_reader :uri, :events_uri, :open_timeout, :read_timeout
+
+        def initialize(endpoint, events_url: nil, open_timeout: 1.0, read_timeout: 2.0, write_timeout: nil, headers: {})
+          @uri = normalize_endpoint(endpoint)
+          @events_uri = normalize_events_endpoint(events_url)
+          @open_timeout = open_timeout
+          @read_timeout = read_timeout
+          @write_timeout = write_timeout
+          @headers = headers
+        end
+
+        def dispatch(envelope)
+          request = Net::HTTP::Post.new(uri)
+          request["Content-Type"] = "application/json"
+          @headers.each { |key, value| request[key.to_s] = value }
+          request.body = JSON.generate(envelope)
+
+          response = http.request(request)
+          raise TransportError, "ledger HTTP #{uri} returned #{response.code}" unless response.code.to_i.between?(200, 299)
+
+          JSON.parse(response.body, symbolize_names: true)
+        rescue JSON::ParserError => e
+          raise TransportError, "invalid ledger HTTP response: #{e.message}"
+        end
+
+        def subscribe(stores:, cursor: nil, &block)
+          raise ArgumentError, "subscribe requires a block" unless block
+
+          http_client = nil
+          thread = nil
+          subscription = Subscription.new do
+            http_client&.finish if http_client&.started?
+            thread&.join(1) unless Thread.current.equal?(thread)
+          rescue IOError, SystemCallError
+            nil
+          end
+
+          thread = Thread.new do
+            stream_uri = events_stream_uri(stores: stores, cursor: cursor)
+            request = Net::HTTP::Get.new(stream_uri)
+            request["Accept"] = "text/event-stream"
+            @headers.each { |key, value| request[key.to_s] = value }
+            http_client = http_for(stream_uri)
+            http_client.request(request) do |response|
+              raise TransportError, "ledger SSE #{stream_uri} returned #{response.code}" unless response.code.to_i.between?(200, 299)
+
+              read_sse(response, subscription, &block)
+            end
+          rescue StandardError => e
+            subscription.error = e unless subscription&.closed?
+          ensure
+            subscription&.close unless subscription&.closed?
+          end
+          subscription
+        end
+
+        private
+
+        def http
+          http_for(uri)
+        end
+
+        def http_for(target_uri)
+          Net::HTTP.new(target_uri.host, target_uri.port).tap do |client|
+            client.use_ssl = target_uri.scheme == "https"
+            client.open_timeout = open_timeout if open_timeout
+            client.read_timeout = read_timeout if read_timeout
+            client.write_timeout = @write_timeout if @write_timeout && client.respond_to?(:write_timeout=)
+          end
+        end
+
+        def normalize_endpoint(endpoint)
+          parsed = URI(endpoint.to_s)
+          parsed.path = "/v1/dispatch" if parsed.path.nil? || parsed.path.empty? || parsed.path == "/"
+          parsed
+        end
+
+        def normalize_events_endpoint(events_url)
+          return derive_events_uri unless events_url
+
+          parsed = URI(events_url.to_s)
+          parsed.path = "/v1/events" if parsed.path.nil? || parsed.path.empty? || parsed.path == "/"
+          parsed
+        end
+
+        def derive_events_uri
+          uri.dup.tap do |parsed|
+            parsed.path = parsed.path.end_with?("/v1/dispatch") ? parsed.path.sub(%r{/v1/dispatch\z}, "/v1/events") : "/v1/events"
+          end
+        end
+
+        def events_stream_uri(stores:, cursor:)
+          events_uri.dup.tap do |parsed|
+            params = URI.decode_www_form(parsed.query.to_s)
+            store_names = Array(stores).map(&:to_s).reject(&:empty?)
+            params << ["stores", store_names.join(",")] unless store_names.empty?
+            sequence = cursor_sequence(cursor)
+            params << ["cursor", sequence.to_s] if sequence
+            parsed.query = params.empty? ? nil : URI.encode_www_form(params)
+          end
+        end
+
+        def cursor_sequence(cursor)
+          return nil unless cursor
+
+          data = cursor.respond_to?(:to_h) ? cursor.to_h.transform_keys(&:to_sym) : { sequence: cursor }
+          data[:sequence]
+        end
+
+        def read_sse(response, subscription, &block)
+          buffer = +""
+          response.read_body do |chunk|
+            break if subscription&.closed?
+
+            buffer << chunk
+            while (frame = next_sse_frame(buffer))
+              event = parse_sse_frame(frame)
+              block.call(event) if event
+            end
+          end
+        end
+
+        def next_sse_frame(buffer)
+          idx = buffer.index("\n\n")
+          sep_len = 2
+          unless idx
+            idx = buffer.index("\r\n\r\n")
+            sep_len = 4
+          end
+          return nil unless idx
+
+          buffer.slice!(0, idx + sep_len)
+        end
+
+        def parse_sse_frame(frame)
+          event_id = nil
+          data_lines = []
+
+          frame.each_line do |line|
+            line = line.chomp
+            event_id = line.sub("id: ", "") if line.start_with?("id: ")
+            data_lines << line.sub("data: ", "") if line.start_with?("data: ")
+          end
+          return nil if data_lines.empty?
+
+          data = JSON.parse(data_lines.join("\n"), symbolize_names: true)
+          data[:sequence] ||= event_id.to_i if event_id
+          data
+        rescue JSON::ParserError => e
+          raise TransportError, "invalid ledger SSE event: #{e.message}"
+        end
+      end
+    end
+  end
+end

data/lib/igniter/ledger_client.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative "ledger_client/envelope"
+require_relative "ledger_client/error"
+require_relative "ledger_client/results"
+require_relative "ledger_client/subscription"
+require_relative "ledger_client/client"
+require_relative "ledger_client/transports/object_dispatch"
+require_relative "ledger_client/transports/remote_http"
+
+module Igniter
+  module LedgerClient
+    def self.wrap(target)
+      return target if target.is_a?(Client)
+
+      Client.new(transport: Transports::ObjectDispatch.new(target))
+    end
+
+    def self.remote_http(endpoint, **options)
+      Client.new(transport: Transports::RemoteHTTP.new(endpoint, **options))
+    end
+  end
+end

data/lib/igniter-ledger-client.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "igniter/ledger_client"

metadata

@@ -0,0 +1,52 @@
+--- !ruby/object:Gem::Specification
+name: igniter-ledger-client
+version: !ruby/object:Gem::Version
+  version: 0.5.2
+platform: ruby
+authors:
+- Alexander
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: 'Small client-side package for the Igniter Ledger/Open Protocol boundary:
+  envelopes, transports, errors, and stable client methods without embedding the storage
+  engine.'
+email:
+- alexander.s.fokin@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/igniter-ledger-client.rb
+- lib/igniter/ledger_client.rb
+- lib/igniter/ledger_client/client.rb
+- lib/igniter/ledger_client/envelope.rb
+- lib/igniter/ledger_client/error.rb
+- lib/igniter/ledger_client/results.rb
+- lib/igniter/ledger_client/subscription.rb
+- lib/igniter/ledger_client/transports/object_dispatch.rb
+- lib/igniter/ledger_client/transports/remote_http.rb
+homepage: https://github.com/alexander-s-f/igniter
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Protocol-first Ledger client package for Igniter
+test_files: []