igniter-ledger 0.5.2

data/lib/igniter/store/protocol/wire_envelope.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Igniter
+  module Store
+    module Protocol
+      # OP3 — Wire Envelope: process boundary routing for StoreServer.
+      #
+      # Every request is wrapped in:
+      #   { protocol: :igniter_store, schema_version: 1,
+      #     request_id: "req_...", op: :write_fact,
+      #     packet: { kind: :fact, store: :tasks, key: "t1", value: {} } }
+      #
+      # Every response is:
+      #   { protocol: :igniter_store, schema_version: 1,
+      #     request_id: "req_...",
+      #     status: :ok | :error,
+      #     result: { ... } | error: "message" }
+      #
+      # This layer sits above the CRC32-framed WireProtocol transport and below
+      # application-level handlers.  It is pure Ruby — no I/O, no sockets.
+      # The StoreServer feeds deserialized hashes in and ships serialized responses out.
+      class WireEnvelope
+        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
+
+        def initialize(interpreter)
+          @interpreter = interpreter
+        end
+
+        # Dispatch a single envelope hash.
+        # Returns a response envelope hash (never raises).
+        def dispatch(envelope)
+          envelope  = envelope.transform_keys(&:to_sym)
+          req_id    = envelope[:request_id]
+
+          proto = envelope[:protocol]&.to_sym
+          unless proto == PROTOCOL
+            return error_response(req_id, "Unknown protocol: #{proto.inspect}")
+          end
+
+          op = envelope[:op]&.to_sym
+          unless op && OPERATIONS.include?(op)
+            return error_response(req_id, "Unknown or missing op: #{op.inspect}")
+          end
+
+          packet = (envelope[:packet] || {})
+          packet = packet.transform_keys(&:to_sym) if packet.is_a?(Hash)
+
+          result = route(op, packet)
+          ok_response(req_id, result)
+        rescue => e
+          error_response(req_id, "Internal error: #{e.message}")
+        end
+
+        private
+
+        def route(op, packet)
+          case op
+          when :register_descriptor
+            @interpreter.register(packet)
+
+          when :write
+            @interpreter.write(
+              store:    packet.fetch(:store),
+              key:      packet.fetch(:key),
+              value:    packet.fetch(:value),
+              producer: packet[:producer]
+            )
+
+          when :append
+            @interpreter.append(
+              history:        packet.fetch(:history),
+              event:          packet.fetch(:event),
+              key:            packet[:key],
+              partition_key:  packet[:partition_key],
+              schema_version: packet.fetch(:schema_version, 1),
+              valid_time:     packet[:valid_time],
+              term:           packet[:term],
+              producer:       packet[:producer],
+              derivation:     packet[:derivation]
+            )
+
+          when :write_fact
+            @interpreter.write_fact(packet)
+
+          when :read
+            value = @interpreter.read(
+              store: packet.fetch(:store),
+              key:   packet.fetch(:key),
+              as_of: packet[:as_of]
+            )
+            { value: value, found: !value.nil? }
+
+          when :query
+            items = @interpreter.query(
+              store:  packet.fetch(:store),
+              where:  packet.fetch(:where, {}),
+              order:  packet[:order],
+              limit:  packet[:limit],
+              as_of:  packet[:as_of]
+            )
+            { items: items, results: items.map { |item| item[:value] }, count: items.size }
+
+          when :resolve
+            items = @interpreter.resolve_items(
+              packet.fetch(:relation).to_sym,
+              from:  packet.fetch(:from),
+              as_of: packet[:as_of]
+            )
+            { items: items, results: items.map { |item| item[:value] }, count: items.size }
+
+          when :causation_chain
+            chain = @interpreter.causation_chain(
+              store: packet.fetch(:store),
+              key:   packet.fetch(:key)
+            )
+            { chain: chain, count: chain.size }
+
+          when :lineage
+            @interpreter.lineage(
+              store: packet.fetch(:store),
+              key:   packet.fetch(:key)
+            )
+
+          when :fact_ref
+            ref = @interpreter.fact_ref(packet.fetch(:fact_id))
+            { found: !ref.nil?, ref: ref }
+
+          when :metadata_snapshot
+            @interpreter.metadata_snapshot
+
+          when :descriptor_snapshot
+            @interpreter.descriptor_snapshot
+
+          when :observability_snapshot
+            @interpreter.observability_snapshot
+
+          when :sync_hub_profile
+            @interpreter.sync_hub_profile(
+              as_of:  packet[:as_of],
+              cursor: packet[:cursor],
+              stores: packet[:stores]
+            )
+
+          when :replay
+            facts = @interpreter.replay(
+              from:   packet[:from],
+              to:     packet[:to],
+              filter: packet[:filter]
+            )
+            { facts: facts, count: facts.size }
+
+          when :storage_stats
+            @interpreter.storage_stats(store: packet[:store])
+
+          when :segment_manifest
+            @interpreter.segment_manifest(store: packet[:store])
+
+          when :compaction_activity
+            @interpreter.compaction_activity(
+              store: packet[:store],
+              kind:  packet[:kind],
+              since: packet[:since],
+              limit: packet[:limit]
+            )
+          end
+        end
+
+        def ok_response(request_id, result)
+          {
+            protocol:       PROTOCOL,
+            schema_version: SCHEMA_VERSION,
+            request_id:     request_id,
+            status:         :ok,
+            result:         result
+          }
+        end
+
+        def error_response(request_id, message)
+          {
+            protocol:       PROTOCOL,
+            schema_version: SCHEMA_VERSION,
+            request_id:     request_id,
+            status:         :error,
+            error:          message
+          }
+        end
+      end
+    end
+  end
+end

data/lib/igniter/store/protocol.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "protocol/receipt"
+require_relative "protocol/handlers/store_handler"
+require_relative "protocol/handlers/history_handler"
+require_relative "protocol/handlers/access_path_handler"
+require_relative "protocol/handlers/relation_handler"
+require_relative "protocol/handlers/projection_handler"
+require_relative "protocol/handlers/derivation_handler"
+require_relative "protocol/handlers/command_handler"
+require_relative "protocol/handlers/effect_handler"
+require_relative "protocol/handlers/subscription_handler"
+require_relative "protocol/interpreter"
+require_relative "protocol/sync_profile"
+require_relative "protocol/wire_envelope"
+
+module Igniter
+  module Store
+    module Protocol
+      # Convenience factory: Protocol.new returns a fresh Interpreter backed by
+      # an in-memory IgniterStore.  Pass an existing store to wrap it instead.
+      def self.new(store = nil)
+        Interpreter.new(store || IgniterStore.new)
+      end
+    end
+  end
+end

data/lib/igniter/store/read_cache.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require "monitor"
+
+module Igniter
+  module Store
+    class ReadCache
+      include MonitorMixin
+
+      DEFAULT_LRU_CAP = 1_000
+
+      def initialize(lru_cap: DEFAULT_LRU_CAP)
+        super()
+        @entries         = {}
+        @consumers       = Hash.new { |hash, key| hash[key] = [] }
+        @scope_consumers = Hash.new { |hash, key| hash[key] = [] }
+        @lru_cap         = lru_cap
+        # Tracks insertion/access order for time-travel cache entries only.
+        # Current-state entries (as_of: nil) live until explicit invalidation.
+        # Ruby Hash preserves insertion order; delete+reinsert = move to MRU.
+        @lru_order = {}
+      end
+
+      def register_consumer(store, callable)
+        synchronize { @consumers[store] << callable }
+      end
+
+      def register_scope_consumer(store, scope, callable)
+        synchronize { @scope_consumers[[store, scope]] << callable }
+      end
+
+      def get(store:, key:, as_of: nil, ttl: nil)
+        cache_key = [store, key, as_of]
+        entry = synchronize do
+          e = @entries[cache_key]
+          if e && as_of
+            @lru_order.delete(cache_key)
+            @lru_order[cache_key] = true
+          end
+          e
+        end
+        return nil unless entry
+
+        if ttl
+          age = Process.clock_gettime(Process::CLOCK_REALTIME) - entry.fetch(:cached_at)
+          return nil if age > ttl
+        end
+
+        entry.fetch(:fact)
+      end
+
+      def put(store:, key:, fact:, as_of: nil)
+        cache_key = [store, key, as_of]
+        synchronize do
+          @entries[cache_key] = {
+            fact:      fact,
+            cached_at: Process.clock_gettime(Process::CLOCK_REALTIME)
+          }
+          if as_of
+            @lru_order[cache_key] = true
+            evict_lru_if_needed
+          end
+        end
+      end
+
+      def get_scope(store:, scope:, as_of: nil, ttl: nil)
+        cache_key = [:scope, store, scope, as_of]
+        entry = synchronize do
+          e = @entries[cache_key]
+          if e && as_of
+            @lru_order.delete(cache_key)
+            @lru_order[cache_key] = true
+          end
+          e
+        end
+        return nil unless entry
+
+        if ttl
+          age = Process.clock_gettime(Process::CLOCK_REALTIME) - entry.fetch(:cached_at)
+          return nil if age > ttl
+        end
+
+        entry.fetch(:facts)
+      end
+
+      def put_scope(store:, scope:, facts:, as_of: nil)
+        cache_key = [:scope, store, scope, as_of]
+        synchronize do
+          @entries[cache_key] = {
+            facts:     facts,
+            cached_at: Process.clock_gettime(Process::CLOCK_REALTIME)
+          }
+          if as_of
+            @lru_order[cache_key] = true
+            evict_lru_if_needed
+          end
+        end
+      end
+
+      # +scope_changes+ is a Hash of { scope_name => :changed | :unchanged | :unknown }
+      # produced by IgniterStore#update_scope_indices.  Scope consumers are only
+      # notified for scopes that are :changed or :unknown (conservative).  Scopes
+      # marked :unchanged are skipped — their membership did not change and firing
+      # their consumers would be a false-positive thundering herd.
+      def invalidate(store:, key: nil, scope_changes: {})
+        point_targets, scope_notifications = synchronize do
+          affected_scopes = []
+          @entries.delete_if do |cache_key, _entry|
+            should_delete = if cache_key[0] == :scope && cache_key[1] == store
+              affected_scopes << cache_key[2]
+              true
+            else
+              cache_key[0] == store && (key.nil? || cache_key[1] == key)
+            end
+            @lru_order.delete(cache_key) if should_delete
+            should_delete
+          end
+
+          notify_scopes = affected_scopes.uniq.reject do |scope|
+            scope_changes[scope] == :unchanged
+          end
+
+          scope_notifs = notify_scopes.map do |scope|
+            [scope, @scope_consumers[[store, scope]].dup]
+          end
+
+          [@consumers[store].dup, scope_notifs]
+        end
+
+        point_targets.each { |t| notify(t, store, key) }
+        scope_notifications.each do |scope, targets|
+          targets.each { |t| notify_scope(t, store, scope) }
+        end
+      end
+
+      def lru_size
+        synchronize { @lru_order.size }
+      end
+
+      private
+
+      def evict_lru_if_needed
+        while @lru_order.size > @lru_cap
+          oldest_key, = @lru_order.first
+          @lru_order.delete(oldest_key)
+          @entries.delete(oldest_key)
+        end
+      end
+
+      def notify(target, store, key)
+        target.call(store, key)
+      rescue StandardError
+        nil
+      end
+
+      def notify_scope(target, store, scope)
+        target.call(store, scope)
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/igniter/store/schema_graph.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Store
+    class SchemaGraph
+      def initialize
+        @paths       = Hash.new { |hash, key| hash[key] = [] }
+        @projections = {}
+        @derivations = []
+        @scatters    = []
+        @relations   = {}
+        @retention   = {}
+        # Raw protocol descriptor storage (OP2 — metadata export)
+        @store_descriptors        = {}
+        @history_descriptors      = {}
+        @command_descriptors      = {}
+        @effect_descriptors       = {}
+        @subscription_descriptors = {}
+      end
+
+      def register(path)
+        @paths[path.store] << path
+        self
+      end
+
+      def paths_for(store)
+        @paths[store].dup
+      end
+
+      def consumers_for(store)
+        @paths[store].flat_map { |path| path.consumers.to_a }.uniq
+      end
+
+      def path_for(store:, scope:)
+        @paths[store].find { |path| path.scope == scope }
+      end
+
+      def registered_stores
+        @paths.keys
+      end
+
+      # --- Projection registry ---
+
+      def register_projection(projection_path)
+        @projections[projection_path.name] = projection_path
+        self
+      end
+
+      def projection_for(name:)
+        @projections[name]
+      end
+
+      # All projections whose reads list includes the given store.
+      def projections_for_store(store:)
+        @projections.values.select { |p| p.reads.include?(store) }
+      end
+
+      # Compact snapshot of all registered projections, keyed by name.
+      # Parallel to metadata_snapshot for access paths.
+      def projection_snapshot
+        @projections.transform_values do |p|
+          {
+            name:           p.name,
+            reads:          p.reads,
+            relations:      p.relations,
+            consumer_hint:  p.consumer_hint,
+            reactive:       p.reactive,
+            store_count:    p.reads.size,
+            relation_count: p.relations.size
+          }
+        end
+      end
+
+      # --- Derivation registry ---
+
+      def register_derivation(derivation_rule)
+        @derivations << derivation_rule
+        self
+      end
+
+      # All derivation rules whose source_store matches the given store.
+      def derivations_for_store(store:)
+        @derivations.select { |r| r.source_store == store }
+      end
+
+      # Compact snapshot of registered derivation rules (rule callables omitted).
+      def derivation_snapshot
+        @derivations.map.with_index do |r, i|
+          {
+            index:          i,
+            source_store:   r.source_store,
+            source_filters: r.source_filters,
+            target_store:   r.target_store,
+            target_key:     r.target_key.respond_to?(:call) ? :callable : r.target_key,
+            has_rule:       true
+          }
+        end
+      end
+
+      # --- Scatter Derivation registry ---
+
+      def register_scatter(scatter_rule)
+        @scatters << scatter_rule
+        self
+      end
+
+      # All scatter rules whose source_store matches the given store.
+      def scatters_for_store(store:)
+        @scatters.select { |r| r.source_store == store }
+      end
+
+      # Compact snapshot of registered scatter rules (rule callables omitted).
+      def scatter_snapshot
+        @scatters.map.with_index do |r, i|
+          {
+            index:        i,
+            source_store: r.source_store,
+            partition_by: r.partition_by,
+            target_store: r.target_store,
+            has_rule:     true
+          }
+        end
+      end
+
+      # --- Relation registry ---
+
+      def register_relation(relation_rule)
+        @relations[relation_rule.name] = relation_rule
+        self
+      end
+
+      def relation_for(name:)
+        @relations[name]
+      end
+
+      def registered_relations
+        @relations.keys
+      end
+
+      # Compact snapshot of all registered relations (no callables — pure metadata).
+      def relation_snapshot
+        @relations.transform_values do |r|
+          {
+            name:      r.name,
+            source:    r.source,
+            partition: r.partition,
+            target:    r.target,
+            index_store: :"__rel_#{r.name}"
+          }
+        end
+      end
+
+      # --- Retention registry ---
+
+      def register_retention(store, policy)
+        @retention[store] = policy
+        self
+      end
+
+      # Returns the RetentionPolicy for store, or nil (meaning :permanent / no compaction).
+      def retention_for(store:)
+        @retention[store]
+      end
+
+      # Stores with an explicitly registered retention policy (any strategy).
+      def retention_stores
+        @retention.keys
+      end
+
+      # Compact snapshot of all registered retention policies.
+      def retention_snapshot
+        @retention.transform_values { |p| { strategy: p.strategy, duration: p.duration } }
+      end
+
+      # --- Raw descriptor storage (OP2 — metadata export) ---
+
+      def register_store_descriptor(descriptor)
+        @store_descriptors[descriptor[:name].to_sym] = descriptor
+        self
+      end
+
+      def register_history_descriptor(descriptor)
+        @history_descriptors[descriptor[:name].to_sym] = descriptor
+        self
+      end
+
+      def register_subscription_descriptor(descriptor)
+        @subscription_descriptors[descriptor[:name].to_sym] = descriptor
+        self
+      end
+
+      def register_command_descriptor(descriptor)
+        owner = descriptor[:owner].to_sym
+        name = descriptor[:name].to_sym
+        @command_descriptors[owner] ||= {}
+        @command_descriptors[owner][name] = descriptor
+        self
+      end
+
+      def register_effect_descriptor(descriptor)
+        owner = descriptor[:owner].to_sym
+        name = descriptor[:name].to_sym
+        @effect_descriptors[owner] ||= {}
+        @effect_descriptors[owner][name] = descriptor
+        self
+      end
+
+      def command_snapshot
+        @command_descriptors
+      end
+
+      def effect_snapshot
+        @effect_descriptors
+      end
+
+      # Snapshot of all raw protocol-level descriptors registered via OP1.
+      def descriptor_snapshot
+        {
+          stores:        @store_descriptors,
+          histories:     @history_descriptors,
+          commands:      @command_descriptors,
+          effects:       @effect_descriptors,
+          subscriptions: @subscription_descriptors
+        }
+      end
+
+      # Returns a compact snapshot of all registered access paths keyed by store.
+      # Each entry describes how the engine routes scope queries for that store:
+      # scope name, lookup strategy, active filters, cache TTL, and consumer count.
+      # Index descriptors (which fields are co-indexed) remain manifest/facade
+      # metadata — they are a schema contract, not an engine routing concern.
+      def metadata_snapshot
+        @paths.each_with_object({}) do |(store, paths), snapshot|
+          snapshot[store] = paths.map do |path|
+            {
+              store:          path.store,
+              scope:          path.scope,
+              lookup:         path.lookup,
+              filters:        path.filters,
+              cache_ttl:      path.cache_ttl,
+              consumer_count: path.consumers.to_a.size
+            }
+          end
+        end
+      end
+    end
+  end
+end