igniter 0.5.0 → 0.5.2

data/lib/igniter/memory/stores/sqlite.rb

@@ -1,284 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Memory
-    module Stores
-      # SQLite-backed persistent Store implementation.
-      #
-      # Uses SQLite3 with FTS5 for fast full-text search on episode content.
-      # Requires the +sqlite3+ gem (soft dependency — not declared in the gemspec).
-      # Raises +Igniter::Memory::ConfigurationError+ if the gem is not available.
-      #
-      # @example In-memory SQLite (for tests)
-      #   store = Igniter::Memory::Stores::SQLite.new(path: ":memory:")
-      #
-      # @example Persistent file
-      #   store = Igniter::Memory::Stores::SQLite.new(path: "/tmp/agent_memory.db")
-      class SQLite < Store # rubocop:disable Metrics/ClassLength
-        # @param path [String] file path for the database, or ":memory:" for transient storage
-        def initialize(path:) # rubocop:disable Lint/MissingSuper
-          require "sqlite3"
-        rescue LoadError
-          raise ConfigurationError,
-                "SQLite store requires the 'sqlite3' gem. Add it to your Gemfile: gem 'sqlite3'"
-        else
-          @mutex = Mutex.new
-          @db    = ::SQLite3::Database.new(path)
-          @db.results_as_hash = true
-          create_schema!
-        end
-
-        # @see Store#record
-        def record(agent_id:, type:, content:, session_id: nil, outcome: nil, importance: 0.5) # rubocop:disable Metrics/ParameterLists
-          @mutex.synchronize do
-            @db.execute(
-              "INSERT INTO episodes (agent_id, session_id, ts, type, content, outcome, importance) " \
-              "VALUES (?, ?, ?, ?, ?, ?, ?)",
-              [agent_id, session_id, Time.now.to_i, type.to_s, content.to_s, outcome, importance.to_f]
-            )
-            row_to_episode(
-              @db.get_first_row("SELECT * FROM episodes WHERE id = last_insert_rowid()")
-            )
-          end
-        end
-
-        # @see Store#episodes
-        def episodes(agent_id:, last: 50, type: nil) # rubocop:disable Metrics/MethodLength
-          @mutex.synchronize do
-            rows = if type
-                     @db.execute(
-                       "SELECT * FROM episodes WHERE agent_id = ? AND type = ? ORDER BY ts ASC LIMIT ?",
-                       [agent_id, type.to_s, last]
-                     )
-                   else
-                     @db.execute(
-                       "SELECT * FROM episodes WHERE agent_id = ? ORDER BY ts ASC LIMIT ?",
-                       [agent_id, last]
-                     )
-                   end
-            rows.map { |r| row_to_episode(r) }
-          end
-        end
-
-        # @see Store#retrieve
-        def retrieve(agent_id:, query: nil, limit: 10, type: nil) # rubocop:disable Metrics/MethodLength
-          @mutex.synchronize do
-            if query
-              fts_retrieve(agent_id, query, limit, type)
-            else
-              rows = if type
-                       @db.execute(
-                         "SELECT * FROM episodes WHERE agent_id = ? AND type = ? ORDER BY ts ASC LIMIT ?",
-                         [agent_id, type.to_s, limit]
-                       )
-                     else
-                       @db.execute(
-                         "SELECT * FROM episodes WHERE agent_id = ? ORDER BY ts ASC LIMIT ?",
-                         [agent_id, limit]
-                       )
-                     end
-              rows.map { |r| row_to_episode(r) }
-            end
-          end
-        end
-
-        # @see Store#store_fact
-        def store_fact(agent_id:, key:, value:, confidence: 1.0) # rubocop:disable Metrics/MethodLength
-          @mutex.synchronize do
-            serialized = value.to_s
-            @db.execute(
-              "INSERT OR REPLACE INTO facts (agent_id, key, value, confidence, updated_at) " \
-              "VALUES (?, ?, ?, ?, ?)",
-              [agent_id, key.to_s, serialized, confidence.to_f, Time.now.to_i]
-            )
-            row_to_fact(
-              @db.get_first_row("SELECT * FROM facts WHERE agent_id = ? AND key = ?", [agent_id, key.to_s])
-            )
-          end
-        end
-
-        # @see Store#facts
-        def facts(agent_id:)
-          @mutex.synchronize do
-            rows = @db.execute("SELECT * FROM facts WHERE agent_id = ?", [agent_id])
-            rows.each_with_object({}) do |row, hash|
-              fact = row_to_fact(row)
-              hash[fact.key] = fact
-            end
-          end
-        end
-
-        # @see Store#record_reflection
-        def record_reflection(agent_id:, summary:, system_patch: nil, applied: false)
-          @mutex.synchronize do
-            @db.execute(
-              "INSERT INTO reflections (agent_id, ts, summary, system_patch, applied) " \
-              "VALUES (?, ?, ?, ?, ?)",
-              [agent_id, Time.now.to_i, summary, system_patch, applied ? 1 : 0]
-            )
-            row_to_reflection(
-              @db.get_first_row("SELECT * FROM reflections WHERE id = last_insert_rowid()")
-            )
-          end
-        end
-
-        # @see Store#reflections
-        def reflections(agent_id:, applied: nil) # rubocop:disable Metrics/MethodLength
-          @mutex.synchronize do
-            rows = if applied.nil?
-                     @db.execute("SELECT * FROM reflections WHERE agent_id = ? ORDER BY ts ASC", [agent_id])
-                   else
-                     @db.execute(
-                       "SELECT * FROM reflections WHERE agent_id = ? AND applied = ? ORDER BY ts ASC",
-                       [agent_id, applied ? 1 : 0]
-                     )
-                   end
-            rows.map { |r| row_to_reflection(r) }
-          end
-        end
-
-        # @see Store#apply_reflection
-        def apply_reflection(id:)
-          @mutex.synchronize do
-            changes_before = @db.changes
-            @db.execute("UPDATE reflections SET applied = 1 WHERE id = ?", [id])
-            @db.changes > changes_before || @db.changes == 1
-          end
-        end
-
-        # @see Store#clear
-        def clear(agent_id:)
-          @mutex.synchronize do
-            @db.execute("DELETE FROM episodes WHERE agent_id = ?", [agent_id])
-            @db.execute("DELETE FROM facts WHERE agent_id = ?", [agent_id])
-            @db.execute("DELETE FROM reflections WHERE agent_id = ?", [agent_id])
-          end
-        end
-
-        private
-
-        def fts_retrieve(agent_id, query, limit, type) # rubocop:disable Metrics/MethodLength
-          rows = if type
-                   @db.execute(
-                     "SELECT e.* FROM episodes e " \
-                     "JOIN episodes_fts fts ON fts.rowid = e.id " \
-                     "WHERE fts.content MATCH ? AND e.agent_id = ? AND e.type = ? " \
-                     "ORDER BY e.ts ASC LIMIT ?",
-                     [query.to_s, agent_id, type.to_s, limit]
-                   )
-                 else
-                   @db.execute(
-                     "SELECT e.* FROM episodes e " \
-                     "JOIN episodes_fts fts ON fts.rowid = e.id " \
-                     "WHERE fts.content MATCH ? AND e.agent_id = ? " \
-                     "ORDER BY e.ts ASC LIMIT ?",
-                     [query.to_s, agent_id, limit]
-                   )
-                 end
-          rows.map { |r| row_to_episode(r) }
-        rescue ::SQLite3::Exception
-          # FTS5 match error (e.g. invalid query syntax) — fall back to LIKE
-          fallback_retrieve(agent_id, query, limit, type)
-        end
-
-        def fallback_retrieve(agent_id, query, limit, type) # rubocop:disable Metrics/MethodLength
-          q = "%#{query}%"
-          rows = if type
-                   @db.execute(
-                     "SELECT * FROM episodes WHERE agent_id = ? AND type = ? AND content LIKE ? " \
-                     "ORDER BY ts ASC LIMIT ?",
-                     [agent_id, type.to_s, q, limit]
-                   )
-                 else
-                   @db.execute(
-                     "SELECT * FROM episodes WHERE agent_id = ? AND content LIKE ? " \
-                     "ORDER BY ts ASC LIMIT ?",
-                     [agent_id, q, limit]
-                   )
-                 end
-          rows.map { |r| row_to_episode(r) }
-        end
-
-        def row_to_episode(row) # rubocop:disable Metrics/MethodLength
-          return nil unless row
-
-          Episode.new(
-            id: row["id"],
-            agent_id: row["agent_id"],
-            session_id: row["session_id"],
-            ts: row["ts"],
-            type: row["type"],
-            content: row["content"],
-            outcome: row["outcome"],
-            importance: row["importance"]
-          )
-        end
-
-        def row_to_fact(row)
-          return nil unless row
-
-          Fact.new(
-            id: row["id"],
-            agent_id: row["agent_id"],
-            key: row["key"],
-            value: row["value"],
-            confidence: row["confidence"],
-            updated_at: row["updated_at"]
-          )
-        end
-
-        def row_to_reflection(row)
-          return nil unless row
-
-          ReflectionRecord.new(
-            id: row["id"],
-            agent_id: row["agent_id"],
-            ts: row["ts"],
-            summary: row["summary"],
-            system_patch: row["system_patch"],
-            applied: row["applied"] == 1
-          )
-        end
-
-        def create_schema! # rubocop:disable Metrics/MethodLength
-          @db.execute_batch(<<~SQL)
-            CREATE TABLE IF NOT EXISTS episodes (
-              id         INTEGER PRIMARY KEY AUTOINCREMENT,
-              agent_id   TEXT NOT NULL,
-              session_id TEXT,
-              ts         INTEGER NOT NULL,
-              type       TEXT NOT NULL,
-              content    TEXT NOT NULL,
-              outcome    TEXT,
-              importance REAL NOT NULL DEFAULT 0.5
-            );
-            CREATE INDEX IF NOT EXISTS idx_ep_agent ON episodes(agent_id, ts);
-            CREATE VIRTUAL TABLE IF NOT EXISTS episodes_fts USING fts5(
-              content, content='episodes', content_rowid='id'
-            );
-            CREATE TRIGGER IF NOT EXISTS ep_ai AFTER INSERT ON episodes BEGIN
-              INSERT INTO episodes_fts(rowid, content) VALUES (new.id, new.content);
-            END;
-            CREATE TABLE IF NOT EXISTS facts (
-              id         INTEGER PRIMARY KEY AUTOINCREMENT,
-              agent_id   TEXT NOT NULL,
-              key        TEXT NOT NULL,
-              value      TEXT,
-              confidence REAL DEFAULT 1.0,
-              updated_at INTEGER,
-              UNIQUE(agent_id, key)
-            );
-            CREATE TABLE IF NOT EXISTS reflections (
-              id           INTEGER PRIMARY KEY AUTOINCREMENT,
-              agent_id     TEXT NOT NULL,
-              ts           INTEGER NOT NULL,
-              summary      TEXT,
-              system_patch TEXT,
-              applied      INTEGER DEFAULT 0
-            );
-          SQL
-        end
-      end
-    end
-  end
-end

data/lib/igniter/memory.rb

@@ -1,80 +0,0 @@
-# frozen_string_literal: true
-
-require "igniter/errors"
-require "igniter/memory/episode"
-require "igniter/memory/fact"
-require "igniter/memory/reflection_record"
-require "igniter/memory/store"
-require "igniter/memory/stores/in_memory"
-require "igniter/memory/stores/sqlite"
-require "igniter/memory/reflection_cycle"
-require "igniter/memory/agent_memory"
-require "igniter/memory/memorable"
-
-module Igniter
-  # Pluggable episodic memory system for Agents and Skills.
-  #
-  # Agents and Skills can record what happened (episodes), store learned facts,
-  # and trigger reflection cycles that analyse past behaviour.
-  #
-  # == Quick start
-  #
-  #   require "igniter/memory"
-  #
-  #   class MyAgent < Igniter::Agent
-  #     include Igniter::Memory::Memorable
-  #     enable_memory  # uses the global default InMemory store
-  #   end
-  #
-  # == Custom store
-  #
-  #   Igniter::Memory.default_store = Igniter::Memory::Stores::SQLite.new(path: "/tmp/mem.db")
-  #
-  #   class MyAgent < Igniter::Agent
-  #     include Igniter::Memory::Memorable
-  #     enable_memory store: Igniter::Memory.default_store
-  #   end
-  #
-  # == Global configuration
-  #
-  #   Igniter::Memory.configure do |m|
-  #     m.default_store = Igniter::Memory::Stores::SQLite.new(path: "/var/app/memory.db")
-  #   end
-  module Memory
-    # Raised when a required dependency (e.g. sqlite3 gem) is missing or when
-    # Memory is misconfigured.
-    ConfigurationError = Class.new(Igniter::Error)
-
-    class << self
-      # Returns the global default store, creating an InMemory store on first access.
-      #
-      # @return [Store]
-      def default_store
-        @default_store ||= Stores::InMemory.new
-      end
-
-      # Override the global default store.
-      #
-      # @param store [Store]
-      # @return [Store]
-      attr_writer :default_store
-
-      # Yield self for block-style configuration.
-      #
-      # @example
-      #   Igniter::Memory.configure do |m|
-      #     m.default_store = Igniter::Memory::Stores::SQLite.new(path: "/tmp/mem.db")
-      #   end
-      def configure
-        yield self
-      end
-
-      # Reset module-level state (primarily useful in tests).
-      #
-      # @return [void]
-      def reset!
-        @default_store = nil
-      end
-    end
-  end
-end

data/lib/igniter/mesh/announcer.rb

@@ -1,55 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Mesh
-    # Announces this node's identity to seed nodes at startup and withdraws
-    # the registration on graceful shutdown.
-    #
-    # All network errors are swallowed — a seed being temporarily down must
-    # not prevent the local node from starting. The background Poller will
-    # re-register once the seed recovers.
-    class Announcer
-      def initialize(config)
-        @config = config
-      end
-
-      # POST self-manifest to every configured seed. No-op if peer_name or
-      # local_url are not configured.
-      def announce_all
-        return unless announceable?
-
-        @config.seeds.each { |url| announce_to(url) }
-      end
-
-      # DELETE self from every configured seed. Best-effort — errors are ignored.
-      def deannounce_all
-        return unless @config.peer_name
-
-        @config.seeds.each { |url| deannounce_from(url) }
-      end
-
-      private
-
-      def announceable?
-        @config.peer_name && !@config.peer_name.to_s.strip.empty? &&
-          @config.local_url && !@config.local_url.to_s.strip.empty?
-      end
-
-      def announce_to(seed_url)
-        Igniter::Server::Client.new(seed_url, timeout: 5).register_peer(
-          name: @config.peer_name,
-          url: @config.local_url,
-          capabilities: @config.local_capabilities
-        )
-      rescue Igniter::Server::Client::ConnectionError
-        nil
-      end
-
-      def deannounce_from(seed_url)
-        Igniter::Server::Client.new(seed_url, timeout: 5).unregister_peer(@config.peer_name)
-      rescue Igniter::Server::Client::ConnectionError
-        nil
-      end
-    end
-  end
-end

data/lib/igniter/mesh/config.rb

@@ -1,45 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Mesh
-    # Configuration for the local mesh node: registered peers and local identity.
-    class Config
-      attr_accessor :peer_name, :local_capabilities, :seeds, :discovery_interval,
-                    :auto_announce, :local_url, :gossip_fanout
-      attr_reader   :peers, :peer_registry
-
-      def initialize
-        @peer_name          = nil
-        @local_capabilities = []
-        @peers              = []
-        @peer_registry      = PeerRegistry.new
-        @seeds              = []
-        @discovery_interval = 30
-        @auto_announce      = true
-        @local_url          = nil
-        @gossip_fanout      = 3
-      end
-
-      # Register a remote peer by name.
-      #
-      #   Igniter::Mesh.configure do |c|
-      #     c.add_peer "orders-node", url: "http://orders.internal:4567",
-      #                               capabilities: [:orders, :inventory]
-      #   end
-      def add_peer(name, url:, capabilities: [])
-        @peers << Peer.new(name: name, url: url, capabilities: capabilities)
-        self
-      end
-
-      # All static peers that advertise a given capability.
-      def peers_with_capability(capability)
-        @peers.select { |p| p.capable?(capability) }
-      end
-
-      # Find a static peer by its registered name. Returns nil if not found.
-      def peer_named(name)
-        @peers.find { |p| p.name == name.to_s }
-      end
-    end
-  end
-end

data/lib/igniter/mesh/discovery.rb

@@ -1,39 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Mesh
-    # Orchestrates the full dynamic-discovery lifecycle:
-    #
-    #   1. Announce self to all seeds (POST /v1/mesh/peers).
-    #   2. Immediately poll all seeds for their known peer list (GET /v1/mesh/peers).
-    #   3. Start the background Poller to keep the registry up to date.
-    #
-    # On #stop:
-    #   1. Deannounce self from all seeds (DELETE /v1/mesh/peers/:name), best-effort.
-    #   2. Stop the background Poller.
-    class Discovery
-      def initialize(config)
-        @config    = config
-        @announcer = Announcer.new(config)
-        @poller    = Poller.new(config)
-      end
-
-      def start
-        @announcer.announce_all
-        @poller.poll_once
-        @poller.start
-        self
-      end
-
-      def stop
-        @announcer.deannounce_all
-        @poller.stop
-        self
-      end
-
-      def running?
-        @poller.running?
-      end
-    end
-  end
-end

data/lib/igniter/mesh/errors.rb

@@ -1,31 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Mesh
-    # Raised when a capability-routed remote node has no alive peers.
-    # Inherits from PendingDependencyError so the resolver transitions
-    # the node to :pending (same as await/distributed workflow nodes).
-    class DeferredCapabilityError < Igniter::PendingDependencyError
-      attr_reader :capability
-
-      def initialize(capability, deferred_result, message = nil)
-        @capability = capability
-        super(deferred_result, message || "No alive peer with capability :#{capability}")
-      end
-    end
-
-    # Raised when a pinned_to peer is unavailable.
-    # Inherits from ResolutionError so the resolver transitions the node
-    # to :failed and surfaces it as an operational incident requiring
-    # manual intervention.
-    class IncidentError < Igniter::ResolutionError
-      attr_reader :peer_name
-
-      def initialize(peer_name, message = nil, context: {})
-        @peer_name = peer_name
-        super(message || "Pinned peer '#{peer_name}' is unreachable — manual intervention required",
-              context: context)
-      end
-    end
-  end
-end

data/lib/igniter/mesh/gossip.rb

@@ -1,47 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Mesh
-    # Executes a single peer-to-peer gossip round.
-    #
-    # Picks up to config.gossip_fanout random peers from the local PeerRegistry
-    # (excluding self), fetches their GET /v1/mesh/peers lists, and registers
-    # any newly discovered peers. This decentralises topology exchange: once seeds
-    # bootstrap the registry, peers continue spreading topology information among
-    # themselves even if seeds become unavailable.
-    #
-    # Errors from individual peers are swallowed — a dead peer must not abort
-    # the round for the remaining candidates.
-    class GossipRound
-      def initialize(config)
-        @config = config
-      end
-
-      def run
-        pick_candidates.each { |peer| exchange_with(peer) }
-      end
-
-      private
-
-      def pick_candidates
-        @config.peer_registry.all
-               .reject { |p| p.url == @config.local_url }
-               .sample(@config.gossip_fanout)
-      end
-
-      def exchange_with(peer) # rubocop:disable Metrics/AbcSize
-        peers = Igniter::Server::Client.new(peer.url, timeout: 5).list_peers
-        peers.each do |pd|
-          next if pd[:name].nil? || pd[:url].nil?
-          next if pd[:name] == @config.peer_name
-
-          @config.peer_registry.register(
-            Peer.new(name: pd[:name], url: pd[:url], capabilities: pd[:capabilities] || [])
-          )
-        end
-      rescue Igniter::Server::Client::ConnectionError
-        nil
-      end
-    end
-  end
-end

data/lib/igniter/mesh/peer.rb

@@ -1,21 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Mesh
-    # Immutable value object representing a peer in the static mesh.
-    class Peer
-      attr_reader :name, :url, :capabilities
-
-      def initialize(name:, url:, capabilities: [])
-        @name         = name.to_s.freeze
-        @url          = url.to_s.chomp("/").freeze
-        @capabilities = Array(capabilities).map(&:to_sym).freeze
-        freeze
-      end
-
-      def capable?(capability)
-        @capabilities.include?(capability.to_sym)
-      end
-    end
-  end
-end

data/lib/igniter/mesh/peer_registry.rb

@@ -1,51 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Mesh
-    # Thread-safe registry for dynamically discovered peers.
-    #
-    # Stores peers indexed by name so that registering the same peer twice
-    # (e.g. from two different seeds) is idempotent and the latest wins.
-    class PeerRegistry
-      def initialize
-        @peers = {}
-        @mutex = Mutex.new
-      end
-
-      # Register (or update) a peer. Thread-safe.
-      def register(peer)
-        @mutex.synchronize { @peers[peer.name] = peer }
-      end
-
-      # Remove a peer by name. No-op if not registered.
-      def unregister(name)
-        @mutex.synchronize { @peers.delete(name.to_s) }
-      end
-
-      # All currently registered peers (snapshot).
-      def all
-        @mutex.synchronize { @peers.values.dup }
-      end
-
-      # Peers that advertise a given capability.
-      def peers_with_capability(capability)
-        all.select { |p| p.capable?(capability) }
-      end
-
-      # Find a peer by name. Returns nil if not found.
-      def peer_named(name)
-        @mutex.synchronize { @peers[name.to_s] }
-      end
-
-      # Remove all registered peers. Useful in tests.
-      def clear
-        @mutex.synchronize { @peers.clear }
-      end
-
-      # Number of registered peers.
-      def size
-        @mutex.synchronize { @peers.size }
-      end
-    end
-  end
-end