igniter-ledger 0.5.2

data/lib/igniter/store/tbackend_adapter_descriptor.rb

@@ -0,0 +1,307 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+
+module Igniter
+  module Store
+    class TBackendAdapterDescriptor
+      KIND = "ledger_tbackend_adapter_descriptor"
+      DIAGNOSTICS_KIND = "ledger_tbackend_adapter_descriptor_diagnostics"
+      ADAPTER_KIND = "ledger_open_protocol"
+      ADAPTER_VERSION = "0.1.0"
+      CONTRACT_VERSION = "tbackend.v0"
+      PROTOCOL = "igniter_store"
+      EVIDENCE_MODE = "receipt_required"
+      DEFAULT_ADAPTER_REF = "adapter:ledger-open-protocol/package-descriptor-v0"
+
+      READ_OPS = %w[read query fact_ref].freeze
+      APPEND_OPS = %w[write write_fact append].freeze
+      REPLAY_OPS = %w[replay sync_hub_profile].freeze
+      SNAPSHOT_OPS = %w[metadata_snapshot descriptor_snapshot sync_hub_profile].freeze
+      TBACKEND_OPS = {
+        "read" => READ_OPS,
+        "append" => APPEND_OPS,
+        "replay" => REPLAY_OPS,
+        "snapshot" => SNAPSHOT_OPS,
+        "compact" => %w[compact],
+        "subscribe" => %w[subscribe]
+      }.freeze
+
+      CURSOR_POLICY = {
+        ordered: "forward",
+        cursor_kinds: ["timestamp"],
+        truncation_reported: true,
+        tie_breaker: "timestamp_then_fact_id_required"
+      }.freeze
+
+      NON_AUTHORIZATION = {
+        runtime_binding: false,
+        ledger_reads: false,
+        ledger_writes: false,
+        ledger_append: false,
+        ledger_replay: false,
+        ledger_compact: false,
+        ledger_subscribe: false,
+        migration_execution: false
+      }.freeze
+
+      attr_reader :metadata_snapshot,
+                  :descriptor_snapshot,
+                  :payload
+
+      def self.build(metadata_snapshot:, descriptor_snapshot:, schema_fingerprint:, adapter_ref: nil,
+                     ledger_protocol_ops: nil)
+        new(
+          metadata_snapshot: metadata_snapshot,
+          descriptor_snapshot: descriptor_snapshot,
+          schema_fingerprint: schema_fingerprint,
+          adapter_ref: adapter_ref,
+          ledger_protocol_ops: ledger_protocol_ops
+        )
+      end
+
+      def initialize(metadata_snapshot:, descriptor_snapshot:, schema_fingerprint:, adapter_ref: nil,
+                     ledger_protocol_ops: nil)
+        @metadata_snapshot = normalize_hash(metadata_snapshot, :metadata_snapshot)
+        @descriptor_snapshot = normalize_hash(descriptor_snapshot, :descriptor_snapshot)
+        @payload = build_payload(
+          schema_fingerprint: require_value(:schema_fingerprint, schema_fingerprint),
+          adapter_ref: adapter_ref || DEFAULT_ADAPTER_REF,
+          ledger_protocol_ops: normalize_ops(
+            ledger_protocol_ops || metadata_snapshot_value(:ledger_protocol_ops) || metadata_snapshot_value(:protocol_ops)
+          )
+        )
+        freeze
+      end
+
+      def descriptor_hash
+        payload.fetch(:descriptor_hash)
+      end
+
+      def descriptor_registry_hash
+        payload.fetch(:descriptor_registry_hash)
+      end
+
+      def ledger_protocol_ops
+        payload.fetch(:ledger_protocol_ops)
+      end
+
+      def supported_tbackend_ops
+        payload.fetch(:supported_tbackend_ops)
+      end
+
+      def hook_methods
+        payload.fetch(:hook_methods)
+      end
+
+      def capabilities
+        payload.fetch(:capabilities)
+      end
+
+      def history_axes
+        payload.fetch(:history_axes)
+      end
+
+      def cursor_policy
+        payload.fetch(:cursor_policy)
+      end
+
+      def diagnostics(requirement = {})
+        requirement = normalize_hash(requirement, :requirement)
+        missing_ops = missing(:required_ops, :supported_tbackend_ops, requirement)
+        missing_hook_methods = missing(:required_hook_methods, :hook_methods, requirement)
+        missing_capabilities = missing(:required_capabilities, :capabilities, requirement)
+        missing_axes = missing(:history_axes, :history_axes, requirement)
+        schema_fingerprint_match = schema_fingerprint_match?(requirement)
+        blocked = missing_ops.any? ||
+                  missing_hook_methods.any? ||
+                  missing_capabilities.any? ||
+                  missing_axes.any? ||
+                  !schema_fingerprint_match
+
+        deep_freeze(
+          kind: DIAGNOSTICS_KIND,
+          status: blocked ? "blocked" : "ok",
+          missing_ops: missing_ops,
+          missing_hook_methods: missing_hook_methods,
+          missing_capabilities: missing_capabilities,
+          missing_axes: missing_axes,
+          schema_fingerprint_match: schema_fingerprint_match,
+          descriptor_hash: descriptor_hash,
+          descriptor_registry_hash: descriptor_registry_hash
+        )
+      end
+
+      def to_h
+        payload
+      end
+
+      private
+
+      def build_payload(schema_fingerprint:, adapter_ref:, ledger_protocol_ops:)
+        supported_tbackend_ops = derive_supported_tbackend_ops(ledger_protocol_ops)
+        hook_methods = []
+        capabilities = []
+        history_axes = []
+
+        if history_read_supported?(supported_tbackend_ops)
+          hook_methods << "read_as_of"
+          capabilities << "history_read"
+          history_axes << "valid_time"
+        end
+
+        if bihistory_supported?
+          hook_methods << "bihistory_at"
+          capabilities << "bihistory_read"
+          history_axes << "transaction_time"
+        end
+
+        descriptor_registry_hash = self.class.canonical_hash(
+          metadata_snapshot: metadata_snapshot,
+          descriptor_snapshot: descriptor_snapshot
+        )
+
+        payload_without_hash = {
+          kind: KIND,
+          adapter_kind: ADAPTER_KIND,
+          adapter_ref: adapter_ref,
+          adapter_version: ADAPTER_VERSION,
+          contract_version: CONTRACT_VERSION,
+          protocol: PROTOCOL,
+          protocol_schema_version: protocol_schema_version,
+          ledger_protocol_ops: ledger_protocol_ops,
+          supported_tbackend_ops: supported_tbackend_ops,
+          hook_methods: hook_methods,
+          capabilities: capabilities,
+          history_axes: history_axes,
+          cursor_policy: CURSOR_POLICY,
+          schema_fingerprint: schema_fingerprint,
+          descriptor_registry_hash: descriptor_registry_hash,
+          evidence_mode: EVIDENCE_MODE,
+          source_snapshots: {
+            metadata_snapshot_present: true,
+            descriptor_snapshot_present: true
+          },
+          non_authorization: NON_AUTHORIZATION
+        }
+
+        deep_freeze(payload_without_hash.merge(
+                      descriptor_hash: self.class.canonical_hash(payload_without_hash)
+                    ))
+      end
+
+      def protocol_schema_version
+        metadata_snapshot[:schema_version] || descriptor_snapshot[:schema_version]
+      end
+
+      def derive_supported_tbackend_ops(ledger_protocol_ops)
+        TBACKEND_OPS.filter_map do |tbackend_op, ledger_ops|
+          tbackend_op if (ledger_protocol_ops & ledger_ops).any?
+        end
+      end
+
+      def history_read_supported?(supported_tbackend_ops)
+        supported_tbackend_ops.include?("read") && store_descriptors.any? do |descriptor|
+          descriptor_capabilities(descriptor).include?("as_of_read")
+        end
+      end
+
+      def bihistory_supported?
+        history_descriptors.any?
+      end
+
+      def store_descriptors
+        Array(metadata_snapshot[:stores]) + Array(descriptor_snapshot[:stores])
+      end
+
+      def history_descriptors
+        Array(metadata_snapshot[:histories]) + Array(descriptor_snapshot[:histories])
+      end
+
+      def descriptor_capabilities(descriptor)
+        Array(descriptor[:capabilities]).map(&:to_s)
+      end
+
+      def missing(requirement_key, descriptor_key, requirement)
+        required = Array(requirement[requirement_key]).map(&:to_s)
+        actual = Array(payload.fetch(descriptor_key)).map(&:to_s)
+        required - actual
+      end
+
+      def schema_fingerprint_match?(requirement)
+        required = requirement[:schema_fingerprint]
+        required.nil? || required == payload.fetch(:schema_fingerprint)
+      end
+
+      def metadata_snapshot_value(key)
+        metadata_snapshot[key]
+      end
+
+      def normalize_ops(value)
+        Array(value).map(&:to_s).uniq.freeze
+      end
+
+      def require_value(name, value)
+        raise ArgumentError, "#{name} is required" if value.nil?
+
+        value
+      end
+
+      def normalize_hash(value, name)
+        raise ArgumentError, "#{name} must be a hash" unless value.respond_to?(:to_h)
+
+        value.to_h.each_with_object({}) do |(key, entry), hash|
+          normalized_key = key.respond_to?(:to_sym) ? key.to_sym : key
+          hash[normalized_key] = normalize_value(entry)
+        end
+      end
+
+      def normalize_value(value)
+        case value
+        when Hash
+          normalize_hash(value, :value)
+        when Array
+          value.map { |entry| normalize_value(entry) }
+        else
+          value
+        end
+      end
+
+      def deep_freeze(value)
+        case value
+        when Array
+          value.map { |entry| deep_freeze(entry) }.freeze
+        when Hash
+          value.transform_values { |entry| deep_freeze(entry) }.freeze
+        else
+          value.freeze
+        end
+      end
+
+      class << self
+        def canonical_hash(value)
+          "sha256:#{Digest::SHA256.hexdigest(JSON.generate(canonical_value(value)))}"
+        end
+
+        private
+
+        def canonical_value(value)
+          case value
+          when Hash
+            value.keys.map(&:to_s).sort.each_with_object({}) do |key, hash|
+              original_key = value.key?(key.to_sym) ? key.to_sym : key
+              hash[key] = canonical_value(value.fetch(original_key))
+            end
+          when Array
+            value.map { |entry| canonical_value(entry) }
+          when Symbol
+            value.to_s
+          else
+            value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/igniter/store/tcp_adapter.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "socket"
+require "json"
+require_relative "wire_protocol"
+
+module Igniter
+  module Store
+    # TCP transport adapter for the Igniter Store Open Protocol.
+    #
+    # Exposes Protocol::Interpreter over a framed TCP (or Unix socket) connection
+    # using the same WireProtocol CRC32 framing as the legacy StoreServer path.
+    # Each request frame carries a WireEnvelope JSON object; each response frame
+    # carries the WireEnvelope response JSON object.
+    #
+    # This is the new envelope dispatch path (default port 7401). The legacy
+    # StoreServer path (port 7400) is separate and unchanged.
+    #
+    # Usage:
+    #   adapter = TCPAdapter.new(interpreter: interpreter, port: 7401)
+    #   adapter.start_async
+    #   adapter.wait_until_ready
+    #   adapter.stop
+    class TCPAdapter
+      include WireProtocol
+
+      def initialize(interpreter:, port: 7401, host: "127.0.0.1", transport: :tcp)
+        @interpreter    = interpreter
+        @port           = port
+        @host           = host
+        @transport      = transport
+        @stopped        = false
+        @threads        = []
+        @threads_mutex  = Mutex.new
+        @ready_mutex    = Mutex.new
+        @ready_cond     = ConditionVariable.new
+        @ready          = false
+        @server         = build_server
+        # Socket is bound during initialize — signal ready immediately so that
+        # wait_until_ready is race-free even before start is called.
+        signal_ready
+      end
+
+      # Runs the accept loop in the current thread (blocks until #stop).
+      def start
+        until @stopped
+          begin
+            socket = @server.accept
+          rescue IOError, Errno::EBADF
+            break
+          end
+          t = Thread.new(socket) { |s| handle_client(s) }
+          @threads_mutex.synchronize { @threads << t }
+        end
+      end
+
+      # Starts the accept loop in a background thread. Returns self.
+      def start_async
+        @thread = Thread.new do
+          Thread.current.abort_on_exception = false
+          start
+        end
+        wait_until_ready
+        self
+      end
+
+      # Blocks until the server socket is bound and ready.
+      def wait_until_ready(timeout: 2)
+        @ready_mutex.synchronize do
+          deadline = Time.now + timeout
+          until @ready
+            remaining = deadline - Time.now
+            raise "TCPAdapter did not become ready within #{timeout}s" if remaining <= 0
+            @ready_cond.wait(@ready_mutex, remaining)
+          end
+        end
+        self
+      end
+
+      def stop
+        @stopped = true
+        @server&.close rescue nil
+        @thread&.join(2) rescue nil
+        @threads_mutex.synchronize { @threads.each { |t| t.join(1) rescue nil } }
+        self
+      end
+
+      def bind_address
+        @transport == :unix ? @host : "#{@host}:#{@port}"
+      end
+
+      private
+
+      def build_server
+        case @transport
+        when :tcp  then TCPServer.new(@host, @port)
+        when :unix then UNIXServer.new(@host)
+        else raise ArgumentError, "Unknown transport: #{@transport.inspect}. Use :tcp or :unix"
+        end
+      end
+
+      def signal_ready
+        @ready_mutex.synchronize { @ready = true; @ready_cond.broadcast }
+      end
+
+      def handle_client(socket)
+        socket.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_NODELAY, true) rescue nil
+        loop do
+          body = read_frame(socket)
+          break unless body
+
+          envelope = JSON.parse(body, symbolize_names: true)
+          result   = @interpreter.wire.dispatch(envelope)
+          socket.write(encode_frame(JSON.generate(result)))
+        end
+      rescue IOError, Errno::ECONNRESET, Errno::EPIPE
+        # client disconnected cleanly
+      rescue => e
+        # unexpected error — log and close
+        $stderr.puts "TCPAdapter: client error: #{e.class}: #{e.message}" rescue nil
+      ensure
+        socket.close rescue nil
+        @threads_mutex.synchronize { @threads.delete(Thread.current) }
+      end
+    end
+  end
+end

data/lib/igniter/store/wire_protocol.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "zlib"
+
+module Igniter
+  module Store
+    # Shared CRC32-framed binary encoding for WAL files and network transport.
+    #
+    # Frame layout:
+    #   [4 bytes BE uint32: body_len][body_len bytes: body][4 bytes BE uint32: CRC32(body)]
+    #
+    # A frame with a mismatched CRC or truncated body signals corruption /
+    # connection loss — the caller should stop reading.
+    module WireProtocol
+      FRAME_HEADER_SIZE = 4
+      FRAME_CRC_SIZE    = 4
+
+      def encode_frame(body)
+        body_b = body.b
+        [body_b.bytesize].pack("N") << body_b << [Zlib.crc32(body)].pack("N")
+      end
+
+      # Reads one frame from +io+. Returns the body String on success, nil on
+      # truncation or CRC mismatch.
+      def read_frame(io)
+        header = io.read(FRAME_HEADER_SIZE)
+        return nil if header.nil? || header.bytesize < FRAME_HEADER_SIZE
+
+        len  = header.unpack1("N")
+        body = io.read(len)
+        return nil if body.nil? || body.bytesize < len
+
+        crc_bytes = io.read(FRAME_CRC_SIZE)
+        return nil if crc_bytes.nil? || crc_bytes.bytesize < FRAME_CRC_SIZE
+
+        return nil unless Zlib.crc32(body) == crc_bytes.unpack1("N")
+
+        body
+      end
+    end
+  end
+end

data/lib/igniter/store.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Store
+    NATIVE = false unless const_defined?(:NATIVE) # overwritten by native.rb when extension loads
+  end
+end
+
+require_relative "store/native" # attempt to load Rust extension
+require_relative "store/access_path"
+require_relative "store/fact"              # Ruby Struct + Fact.from_h (always loaded)
+require_relative "store/fact_log"          # Ruby FactLog + native all_facts patch
+require_relative "store/wire_protocol"
+require_relative "store/file_backend"      # Ruby FileBackend + native snapshot patch
+require_relative "store/server_config"
+require_relative "store/server_logger"
+require_relative "store/subscription_registry"
+require_relative "store/change_event"
+require_relative "store/changefeed_buffer"
+require_relative "store/network_backend"
+require_relative "store/store_server"
+require_relative "store/igniter_store"
+require_relative "store/read_cache"
+require_relative "store/schema_graph"
+require_relative "store/protocol"
+require_relative "store/http_adapter"
+require_relative "store/tcp_adapter"
+require_relative "store/codecs"
+require_relative "store/segmented_file_backend"
+require_relative "store/mcp_adapter"
+require_relative "store/contractable_receipt_sink"
+require_relative "store/tbackend_adapter_descriptor"
+
+module Igniter
+  module Store
+    class << self
+      def memory
+        IgniterStore.new
+      end
+
+      def open(path)
+        IgniterStore.open(path)
+      end
+
+      # Open (or create) a segmented WAL store at +root_dir+.
+      # Facts from all stores are partitioned into per-store, per-time-bucket
+      # segment files under root_dir/wal/.
+      def segmented(root_dir, **opts)
+        backend = SegmentedFileBackend.new(root_dir, **opts)
+        store   = IgniterStore.new(backend: backend)
+        backend.replay.each { |fact| store.__send__(:replay, fact) }
+        store
+      end
+
+      def access_path(...)
+        AccessPath.new(...)
+      end
+    end
+
+    LedgerStore = IgniterStore unless const_defined?(:LedgerStore)
+    LedgerServer = StoreServer unless const_defined?(:LedgerServer)
+    LedgerNetworkBackend = NetworkBackend unless const_defined?(:LedgerNetworkBackend)
+  end
+end

data/lib/igniter-ledger.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative "igniter/store"
+require_relative "igniter/ledger"

data/lib/igniter-store.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+warn "igniter-store is deprecated; require igniter-ledger instead" if $VERBOSE
+
+require_relative "igniter-ledger"