insika 0.0.1 → 0.1.0

data/lib/insika/steer_injector.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Insika
+  # RFC-0015 §5.2 — WHERE a message that arrived mid-run is allowed to enter the
+  # conversation.
+  #
+  # A customer who corrects themselves while the agent is calling tools ("1234567",
+  # three seconds after "queria saber do pedido") should have that land before the
+  # model's next reasoning step, not after the whole run. RubyLLM runs the entire tool
+  # loop inside `chat.ask`, so the only place to append is from inside its callbacks —
+  # which is enough, because they are public and additive:
+  #
+  #   complete_once
+  #     ├─ provider_completion         → assistant message announcing N tool_calls
+  #     ├─ after_message(assistant)    ← N is read here
+  #     └─ handle_tool_calls
+  #          ├─ add_tool_result_message ×N
+  #          │    └─ after_message(tool)  ← counted; the Nth is THE BOUNDARY
+  #          └─ halt_result || complete   ← the next model step sees what we appended
+  #
+  # Counting to N is not an optimization, it is the correctness condition. A `user`
+  # message inserted BETWEEN tool results is rejected outright by Anthropic (all tool
+  # results of a batch must sit together) and merely tolerated by OpenAI.
+  #
+  # Two invariants this object exists to keep:
+  #
+  # · **Tail-append only.** Nothing already sent to the provider is edited, reordered
+  #   or removed. That is what keeps the prompt cache valid, and a cache miss on a
+  #   ~48k-token identity is a real cost, not a theoretical one.
+  # · **A halted batch injects nothing.** With `halt_when` there is no next model step
+  #   (`handle_tool_calls` returns the Halt), so an appended message would sit in the
+  #   transcript unanswered forever. The messages stay in the mailbox and the Executor
+  #   releases them as a follow-up turn.
+  class SteerInjector
+    # chat:   the turn's RubyLLM::Chat (already assembled).
+    # actor:  the turn's TaskActor — the mailbox the steered messages arrive in.
+    # policy: the turn's QueuePolicy (`frame` decides how the text is worded).
+    # emit:   ->(type, data) — the Executor's emitter, already bound to the task.
+    def initialize(chat:, actor:, policy:, emit:)
+      @chat = chat
+      @actor = actor
+      @policy = policy
+      @emit = emit
+      @expected = nil # tool calls announced by the batch in flight (nil = not in one)
+      @seen = 0
+      @halted = false
+      @injected = 0
+    end
+
+    # How many messages this run absorbed (read by specs and by the turn's event).
+    attr_reader :injected
+
+    # RubyLLM `after_tool_result`, with the RAW result — the only place a `Tool::Halt`
+    # is still recognizable. By the time it becomes a `role: tool` message its content
+    # is the payload, indistinguishable from an ordinary result.
+    def tool_result(result)
+      @halted = true if halt?(result)
+    end
+
+    # RubyLLM `after_message`. An assistant message carrying tool calls OPENS a batch;
+    # the Nth tool result CLOSES it, and that is the one boundary where appending is
+    # valid.
+    def message_ended(message)
+      role = field(message, :role).to_s
+      return open_batch(message) if role == "assistant"
+      return unless role == "tool" && @expected
+
+      @seen += 1
+      inject! if @seen >= @expected
+    end
+
+    private
+
+    def open_batch(message)
+      calls = field(message, :tool_calls)
+      size = calls.respond_to?(:size) ? calls.size : 0
+      # A message with no tool call is the model talking, not a batch: leave any
+      # pending message where it is (the turn is about to end, and the Executor
+      # releases it as a follow-up turn rather than answering it half-way).
+      return @expected = nil if size.zero?
+
+      @expected = size
+      @seen = 0
+      @halted = false
+    end
+
+    def inject!
+      @expected = nil
+      return if @halted # nothing will read it: leave it in the mailbox
+
+      texts = @actor.take_user_messages!
+      return if texts.empty?
+
+      texts.each { |text| @chat.add_message(role: :user, content: @policy.frame(text)) }
+      @injected += texts.size
+      # Counts only, never content — the text is already in the transcript, which is the
+      # surface that is allowed to carry it. `task_id`/`session_id` are the event's meta.
+      @emit.call(:turn_steered, { count: texts.size, total: @injected })
+    end
+
+    def halt?(result) = defined?(RubyLLM::Tool::Halt) && result.is_a?(RubyLLM::Tool::Halt)
+
+    def field(message, name)
+      return message.public_send(name) if message.respond_to?(name)
+      return message[name] || message[name.to_s] if message.respond_to?(:[])
+
+      nil
+    end
+  end
+end

data/lib/insika/store.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Insika
+  # Minimal persistence contract.
+  # Namespace-scoped KV, transactional when the backend supports it.
+  # Every implementation passes the SAME contract suite
+  # (lib/insika/testing/store_contract.rb — requirable from outside the repo,
+  # RFC-0018 A4). Values must be JSON-serializable.
+  #
+  # scope: String — separates domains/tenants (e.g. "sessions", "tasks:tenant_x")
+  # key:   Hierarchical String (e.g. "task:123", "checkpoint:123:turn:4")
+  #
+  # Contract rules (verified by the suite):
+  # - get on a nonexistent key -> nil (never an exception)
+  # - set overwrites silently (last-write-wins)
+  # - round-trip preserves JSON types; Symbols become Strings (the domain
+  #   normalizes at the boundary)
+  # - list(scope) returns only keys of the scope, ordered lexicographically;
+  #   prefix filters by start_with?
+  # - a nested transaction reuses the outer transaction (no SAVEPOINT)
+  # - a serialization failure on write -> Insika::StoreError (fail-fast)
+  #
+  # Backends `include Store` and override the five methods; any forgotten
+  # method raises NotImplementedError (fail-fast, better than a distant
+  # NoMethodError).
+  module Store
+    # -> Object | nil (deserialized)
+    def get(scope, key)
+      raise NotImplementedError, "#{self.class}#get"
+    end
+
+    # -> value (the SAME object passed in, not the round-trip)
+    def set(scope, key, value)
+      raise NotImplementedError, "#{self.class}#set"
+    end
+
+    # -> true | false (did it exist?)
+    def delete(scope, key)
+      raise NotImplementedError, "#{self.class}#delete"
+    end
+
+    # -> [String] keys ordered lexicographically
+    def list(scope, prefix = nil)
+      raise NotImplementedError, "#{self.class}#list"
+    end
+
+    # -> the block's result; atomic if the backend supports it
+    def transaction(&blk)
+      raise NotImplementedError, "#{self.class}#transaction"
+    end
+  end
+end

data/lib/insika/stores/memory.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Insika
+  module Stores
+    # In-memory backend for dev/test.
+    # Serializes JSON even in memory: exact parity of type semantics
+    # with SQLite — the contract suite is honest.
+    # No lock: cooperative fibers do not preempt in the middle of a Hash
+    # operation.
+    class Memory
+      include Store
+
+      def initialize
+        @data = new_store
+        @tx_depth = 0
+        @snapshot = nil
+      end
+
+      def get(scope, key)
+        raw = @data[scope][key]
+        return nil if raw.nil?
+
+        JSON.parse(raw)
+      end
+
+      def set(scope, key, value)
+        @data[scope][key] = serialize(value)
+        value
+      end
+
+      def delete(scope, key)
+        !@data[scope].delete(key).nil?
+      end
+
+      def list(scope, prefix = nil)
+        keys = @data[scope].keys.sort
+        prefix ? keys.select { |k| k.start_with?(prefix) } : keys
+      end
+
+      # Snapshot at the start of the outermost transaction; an exception at any
+      # level -> restore the snapshot and re-propagate (a REAL rollback).
+      # A nested one reuses the outer (no SAVEPOINT).
+      def transaction
+        if @tx_depth.positive?
+          @tx_depth += 1
+          begin
+            return yield
+          ensure
+            @tx_depth -= 1
+          end
+        end
+
+        @snapshot = deep_snapshot
+        @tx_depth = 1
+        begin
+          yield
+        rescue StandardError
+          restore_snapshot
+          raise
+        ensure
+          @tx_depth = 0
+          @snapshot = nil
+        end
+      end
+
+      # JSON model types + Symbol (coerced to String on write).
+      # Any other type is "garbage" and must be rejected.
+      JSONABLE = [NilClass, TrueClass, FalseClass, Integer, Float,
+                  String, Symbol].freeze
+      private_constant :JSONABLE
+
+      private
+
+      def new_store
+        Hash.new { |h, scope| h[scope] = {} }
+      end
+
+      # Enforces the contract's type model at the boundary:
+      # Symbol/symbol-key become String; a type outside the JSON model ->
+      # StoreError on WRITE (fail-fast; never writes garbage).
+      #
+      # Does not use `JSON.generate(strict: true)`: under json 2.7.1 (the pinned
+      # version) `strict` rejects Symbol, which would violate the Symbol coercion.
+      # The explicit validation is independent of the json version and gives the
+      # SAME semantics as SQLite.
+      # The transaction block's exception (from the caller) propagates without
+      # wrapping; only a backend error becomes StoreError.
+      def serialize(value)
+        ensure_jsonable!(value)
+        JSON.generate(value)
+      rescue JSON::GeneratorError => e
+        raise Insika::StoreError, "value not serializable: #{e.message}"
+      end
+
+      def ensure_jsonable!(value)
+        case value
+        when *JSONABLE then nil
+        when Array then value.each { |v| ensure_jsonable!(v) }
+        when Hash then value.each { |k, v| ensure_jsonable!(k); ensure_jsonable!(v) }
+        else
+          raise Insika::StoreError,
+                "value not serializable: #{value.class} not allowed in JSON"
+        end
+      end
+
+      # Deep dup: the values are already JSON strings (immutable in practice),
+      # so a per-scope dup is enough — there is no nested mutable structure.
+      def deep_snapshot
+        @data.each_with_object({}) { |(scope, kv), acc| acc[scope] = kv.dup }
+      end
+
+      # Recreates the Hash with the default proc (otherwise @data[scope] on a
+      # new scope after rollback would raise) and restores only the snapshot's
+      # scopes — scopes created inside the transaction disappear.
+      def restore_snapshot
+        @data = new_store
+        @snapshot.each { |scope, kv| @data[scope] = kv }
+      end
+    end
+  end
+end

data/lib/insika/stores/sqlite.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+require "async/semaphore"
+
+module Insika
+  module Stores
+    # SQLite backend — the production default.
+    # A single kv table; the domain lives in the scopes. One handle per process,
+    # writes in a transaction serialized by an Async::Semaphore.
+    class SQLite
+      include Store
+
+      DDL = <<~SQL
+        CREATE TABLE IF NOT EXISTS kv (
+          scope      TEXT    NOT NULL,
+          key        TEXT    NOT NULL,
+          value      TEXT    NOT NULL,
+          updated_at TEXT    NOT NULL,
+          PRIMARY KEY (scope, key)
+        ) WITHOUT ROWID;
+      SQL
+
+      # JSON model types + Symbol (coerced to String on write).
+      # Any other type is "garbage" and must be rejected. Identical to
+      # Stores::Memory — both backends share the SAME type model
+      # (the contract suite is honest).
+      JSONABLE = [NilClass, TrueClass, FalseClass, Integer, Float,
+                  String, Symbol].freeze
+      private_constant :JSONABLE
+
+      # lazy require: the core installs without the sqlite3 gem
+      # when only Memory is used.
+      def initialize(path:, serializer: JSON)
+        require "sqlite3"
+
+        @serializer = serializer
+        @db = SQLite3::Database.new(path)
+        @write_semaphore = Async::Semaphore.new(1)
+        @tx_owner = nil
+
+        # Multi-process boot (N Falcon workers opening the SAME file at the
+        # same time): `PRAGMA journal_mode = WAL` on a new file needs an
+        # EXCLUSIVE lock and may return SQLITE_BUSY right then — the busy
+        # timeout alone does NOT cover the journal-mode switch. Hence: timeout
+        # FIRST (covers the DDL and the hot path) + retry with backoff around
+        # the initialization (covers the WAL-switch race). Idempotent:
+        # reopening already-in-WAL is a no-op.
+        #
+        # `busy_handler_timeout=`, NOT `busy_timeout=`: the C-level handler
+        # sleeps holding the GVL, so a worker waiting on another PROCESS's
+        # write lock would stall every fiber it is running for up to the full
+        # timeout (measured: a waiter blocks the winner's own commit). The
+        # Ruby-level handler sleeps in Ruby — the scheduler keeps the rest of
+        # the worker breathing while this handle waits its turn.
+        @db.busy_handler_timeout = 5_000
+        with_busy_retry do
+          @db.execute("PRAGMA journal_mode = WAL")
+          @db.execute("PRAGMA synchronous = NORMAL")
+          @db.execute_batch(DDL)
+        end
+        # The WITHOUT ROWID PRIMARY KEY (scope, key) is already the prefix index —
+        # there is no extra index to create.
+      rescue ::SQLite3::Exception => e
+        raise Insika::StoreError, "failed to open #{path}: #{e.message}"
+      end
+
+      # Short retry for SQLITE_BUSY at INITIALIZATION (the WAL-switch race at
+      # multi-process boot). ~10 attempts × 60ms ≈ 0.6s worst case — enough
+      # for the winning process to finish the journal-mode switch. Only
+      # here; the hot path uses `busy_timeout` + the in-process semaphore.
+      def with_busy_retry(attempts: 10, backoff: 0.06)
+        tries = 0
+        begin
+          yield
+        rescue ::SQLite3::Exception => e
+          raise unless e.message =~ /lock|busy/i
+
+          tries += 1
+          raise if tries >= attempts
+
+          sleep(backoff)
+          retry
+        end
+      end
+      private :with_busy_retry
+
+      def close
+        @db&.close
+        nil
+      end
+
+      def get(scope, key)
+        row = @db.get_first_value(
+          "SELECT value FROM kv WHERE scope = ? AND key = ?", [scope, key]
+        )
+        row.nil? ? nil : @serializer.parse(row)
+      rescue ::SQLite3::Exception => e
+        raise Insika::StoreError, e.message
+      end
+
+      def set(scope, key, value)
+        serialized = serialize(value)               # fail-fast BEFORE writing
+        transaction do
+          @db.execute(
+            "INSERT OR REPLACE INTO kv (scope, key, value, updated_at) " \
+            "VALUES (?, ?, ?, ?)",
+            [scope, key, serialized, Time.now.utc.iso8601]
+          )
+        end
+        value
+      end
+
+      def delete(scope, key)
+        transaction do
+          @db.execute("DELETE FROM kv WHERE scope = ? AND key = ?", [scope, key])
+          @db.changes.positive?
+        end
+      end
+
+      def list(scope, prefix = nil)
+        keys = @db.execute(
+          "SELECT key FROM kv WHERE scope = ? ORDER BY key", [scope]
+        ).map(&:first)
+        prefix ? keys.select { |k| k.start_with?(prefix) } : keys
+      rescue ::SQLite3::Exception => e
+        raise Insika::StoreError, e.message
+      end
+
+      # BEGIN IMMEDIATE ... COMMIT/ROLLBACK, serialized by the semaphore.
+      # A nested one reuses the outer transaction.
+      def transaction(&blk)
+        return yield if @tx_owner == Fiber.current
+
+        @write_semaphore.acquire do
+          begin
+            @db.transaction(:immediate)
+            @tx_owner = Fiber.current
+            result = yield
+            @db.commit
+            result
+          rescue StandardError
+            @db.rollback if @db.transaction_active?
+            raise
+          ensure
+            @tx_owner = nil
+          end
+        end
+      rescue ::SQLite3::Exception => e
+        raise Insika::StoreError, e.message
+      end
+
+      private
+
+      # Enforces the contract's type model at the boundary:
+      # Symbol/symbol-key become String; a type outside the JSON model ->
+      # StoreError on WRITE (fail-fast; never writes garbage).
+      #
+      # Does NOT use `generate(strict: true)`: under json 2.7.1 (the version that
+      # ships with ruby 3.3.5 pinned in Gemfile.lock) `strict` REJECTS Symbol,
+      # which would violate the Symbol coercion. The explicit validation
+      # is independent of the json version and gives the SAME semantics as Memory.
+      def serialize(value)
+        ensure_jsonable!(value)
+        @serializer.generate(value)
+      rescue JSON::GeneratorError => e
+        raise Insika::StoreError, "value not serializable: #{e.message}"
+      end
+
+      def ensure_jsonable!(value)
+        case value
+        when *JSONABLE then nil
+        when Array then value.each { |v| ensure_jsonable!(v) }
+        when Hash then value.each { |k, v| ensure_jsonable!(k); ensure_jsonable!(v) }
+        else
+          raise Insika::StoreError,
+                "value not serializable: #{value.class} not allowed in JSON"
+        end
+      end
+    end
+  end
+end