insika 0.0.1 → 0.2.0

data/lib/insika/session_actor.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require "async"
+require "async/queue"
+require "time" # Time#iso8601 for the arrival record on :turn_coalesced
+
+module Insika
+  # Sessions as Actors: one fiber per session with a FIFO queue
+  # of turns, executed ONE AT A TIME. Restores the "one owner at a time"
+  # invariant of the transcript that two concurrent `send_message` calls on the
+  # same `session_id` would break (read-modify-write on the Session Store). Turns
+  # from distinct sessions stay concurrent; one-shot/history (no session_id) do
+  # not go through here.
+  #
+  # Lives in the SUPERVISED scope: the loop is a child of the supervisor, not of
+  # the request — it outlives the connection. The turn itself (spawned by the
+  # Executor) is also born on the supervisor; the SessionActor only AWAITS it to
+  # serialize.
+  #
+  # it is also where an inbound message for a BUSY session is routed.
+  # That decision belongs here and nowhere else — this is already the object that
+  # owns "one turn at a time for this session". Putting it in the HTTP handler
+  # would duplicate the invariant; putting it in the Executor would mix turn
+  # execution with queue policy.
+  class SessionActor
+    def initialize(session_id:, executor:, parent: Async::Task.current)
+      @session_id = session_id
+      @executor = executor
+      @queue = Async::Queue.new
+      @running = false
+      # The turn currently sitting at the door: created and :queued, but not yet
+      # released to run. `collect` merges into THIS one. nil whenever there is
+      # nothing mergeable — which is the common case and the safe default.
+      @pending = nil
+      @loop = parent.async { |t| t.annotate("session:#{session_id}"); run_loop }
+    end
+
+    # Enqueues a turn (FIFO). Non-blocking: the handler responds with an
+    # immediate {task_id:} even if the turn stays :queued behind another. -> task.id.
+    #
+    # `policy` (a QueuePolicy) opens the debounce window for this turn; nil or a
+    # policy without a window behaves exactly as before — dequeued and run at once.
+    def enqueue(task, profile:, resume_from: nil, policy: nil)
+      @queue.enqueue([task, profile, resume_from, policy])
+      task.id
+    end
+
+    # merge a fragment into the turn waiting at the door.
+    # -> the task id it joined, or nil when there is nothing to merge into (no
+    # pending turn, the window has closed, or the turn already started). nil is
+    # the caller's signal to create a task of its own.
+    #
+    # Runs on the REQUEST's fiber, not the loop's; both are on the same reactor
+    # and neither yields between the check and the write below, so the "is it
+    # still mergeable" test and the append cannot interleave.
+    def collect(text)
+      pending = @pending
+      return nil if pending.nil?
+
+      @executor.task_store.append_message(pending[:task_id], text)
+      pending[:count] += 1
+      # A merged fragment leaves NO task of its own (see #hold_at_the_door), so this
+      # is the only record that it arrived as a separate message. Kept as arrival
+      # times — never the text — and shipped on :turn_coalesced, so "the customer
+      # says they sent the order number" is answerable without the store carrying an
+      # orphan task per fragment.
+      pending[:arrivals] << Time.now.utc.iso8601
+      pending[:version] += 1 # tells a sleeping debounce window that more arrived
+      pending[:task_id]
+    rescue ArgumentError
+      # The turn left :queued between the read of @pending and the append (it was
+      # released while we were deciding). Not an error: the caller falls back to
+      # creating its own task, which is exactly `followup`.
+      nil
+    end
+
+    def running? = @running
+    def depth = @queue.size
+
+    # The turn this session is running RIGHT NOW, or nil when idle or still at the
+    # door. `steer` needs the Task itself and not just its id: whether a turn can
+    # absorb a message at all depends on what kind of turn it is (a workflow has no
+    # chat), and reading that off the object avoids a store round-trip on the
+    # request's path.
+    attr_reader :current_task
+
+    # Is there a turn at the door that `collect` could still merge into?
+    def collecting? = !@pending.nil?
+
+    # Is the loop still alive? (the Executor revalidates before reusing from the
+    # cache — a dead loop would black-hole queued turns).
+    def alive? = !!@loop&.running?
+
+    # Shuts down the loop (server shutdown / tests — the loop blocks forever on
+    # dequeue when idle).
+    def stop = @loop&.stop
+
+    private
+
+    def run_loop
+      loop do
+        task, profile, resume_from, policy = @queue.dequeue # blocks when empty
+        task = hold_at_the_door(task, policy)
+        @running = true
+        @current_task = task
+        begin
+          @executor.run_serial(task, profile: profile, resume_from: resume_from)
+        rescue StandardError
+          # run_serial already maps turn errors; this rescue is defense: an
+          # unexpected error must NEVER bring down the session loop (Async::Stop <
+          # Exception is not captured -> #stop ends the loop normally).
+          nil
+        ensure
+          @running = false
+          @current_task = nil
+        end
+      end
+    end
+
+    # the debounce window. Sleeps on the LOOP's fiber, never on the
+    # request's, so the POST is acked immediately and the platform does not retry.
+    # Returns the task to run (re-read from the store when fragments merged into it,
+    # since the in-memory Task is a frozen snapshot of an older message).
+    def hold_at_the_door(task, policy)
+      return task unless policy&.debounce?
+
+      @pending = { task_id: task.id, count: 1, version: 0, arrivals: [Time.now.utc.iso8601] }
+      begin
+        wait_for_quiet(policy)
+        merged = @pending[:count]
+        arrivals = @pending[:arrivals]
+      ensure
+        # The window is closed BEFORE the turn runs, under every exit path: a
+        # `collect` that slipped in here would append to a task about to be read.
+        @pending = nil
+      end
+
+      return task if merged == 1
+
+      @executor.emit_coalesced(task, merged: merged, arrivals: arrivals)
+      @executor.task_store.find(task.id) || task
+    end
+
+    # Sleeps in `debounce_ms` slices, restarting whenever a fragment arrives
+    # (`version` moved), until either a slice passes in silence or the total
+    # deferral reaches `debounce_max_ms` — the ceiling that stops a customer who
+    # keeps typing from postponing their own answer forever.
+    def wait_for_quiet(policy)
+      quiet = policy.debounce_ms / 1000.0
+      deadline = monotonic + (policy.debounce_max_ms / 1000.0)
+
+      loop do
+        mark = @pending[:version]
+        Async::Task.current.sleep(quiet)
+        break if @pending[:version] == mark # a full slice of silence
+        break if monotonic >= deadline
+      end
+    end
+
+    def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  end
+end

data/lib/insika/session_store.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "time"
+
+module Insika
+  # Domain store for sessions. Persists transcript + vars
+  # over an injected Insika::Store, with a fixed schema
+  # `session:<id>` in the "sessions" scope.
+  #
+  # The persisted transcript is the SOURCE OF TRUTH for reconstruction; live
+  # events are just delivery state. The message shape
+  # (`{"role"=>, "content"=>}`, role ∈ user|assistant|system|tool) is the
+  # same one `Runner#seed_history` already consumes — the Executor converts nothing.
+  #
+  # Normalizes symbol→string on WRITE (the backend only guarantees round-trip of
+  # JSON types); READ returns the data as it comes from the backend
+  # (string keys), never symmetrizing back to symbols.
+  class SessionStore
+    include Coercion
+
+    SCOPE = "sessions"
+    KEY_PREFIX = "session:"
+
+    Session = Data.define(:id, :messages, :vars, :memory_refs,
+                          :created_at, :updated_at)
+
+    # store: any Insika::Store (Memory, SQLite, ...) — injected by the
+    # composition root (config/wiring.rb). SessionStore does not know the
+    # concrete backend.
+    def initialize(store:)
+      @store = store
+    end
+
+    # -> Session; ArgumentError if id already exists (a duplicate session is a
+    # domain violation — it never overwrites silently).
+    def create(id: SecureRandom.uuid, vars: {})
+      key = key_for(id)
+      raise ArgumentError, "session already exists: #{id}" unless @store.get(SCOPE, key).nil?
+
+      now = timestamp
+      record = {
+        "id" => id.to_s,
+        "messages" => [],
+        "vars" => deep_stringify(vars),
+        "memory_refs" => [],
+        "created_at" => now,
+        "updated_at" => now
+      }
+      @store.set(SCOPE, key, record)
+      to_session(record)
+    end
+
+    # -> Session | nil
+    def find(id)
+      record = @store.get(SCOPE, key_for(id))
+      record && to_session(record)
+    end
+
+    # -> Session (transcript += messages). Read-modify-write on the task's own
+    # fiber, without a lock. Each message gets an "at" (ISO8601 UTC) if not
+    # provided. NotFoundError if the session does not exist.
+    #
+    # CONCURRENCY LIMITATION (R2c): the RMW (read record -> += -> set) is
+    # atomic ONLY because the SessionActor serializes turns of the same session
+    # (one owner at a time). That serialization exists solely in SUPERVISED mode
+    # (the actor loop lives on the supervisor). Two concurrent send_message on the
+    # same session_id OUTSIDE that path (e.g. calling append_messages directly, or
+    # a non-supervised deployment) would interleave read/set and LOSE messages —
+    # there is no compare-and-swap here. Route same-session writes through the
+    # SessionActor; see session_actor.rb.
+    def append_messages(id, messages)
+      record = fetch!(id)
+      incoming = (messages.is_a?(Hash) ? [messages] : Array(messages))
+                 .map { |msg| stamp(deep_stringify(msg)) }
+      record["messages"] += incoming
+      record["updated_at"] = timestamp
+      @store.set(SCOPE, key_for(id), record)
+      to_session(record)
+    end
+
+    # -> Session (SHALLOW merge: an existing nested key is replaced wholesale,
+    # not merged). NotFoundError if absent.
+    def update_vars(id, vars)
+      record = fetch!(id)
+      record["vars"] = record["vars"].merge(deep_stringify(vars))
+      record["updated_at"] = timestamp
+      @store.set(SCOPE, key_for(id), record)
+      to_session(record)
+    end
+
+    # -> bool (delegates to the backend: false for a nonexistent id)
+    def delete(id)
+      @store.delete(SCOPE, key_for(id))
+    end
+
+    # -> enumerates ids without the "session:" prefix. Without a block,
+    # returns an Enumerator.
+    def each_id
+      return enum_for(:each_id) unless block_given?
+
+      @store.list(SCOPE, KEY_PREFIX).each do |key|
+        yield key.delete_prefix(KEY_PREFIX)
+      end
+    end
+
+    private
+
+    def key_for(id)
+      "#{KEY_PREFIX}#{id}"
+    end
+
+    # Loads the raw record; NotFoundError if absent (nonexistent session ->
+    # HTTP 404). Backend errors (StoreError) propagate without re-wrapping.
+    def fetch!(id)
+      record = @store.get(SCOPE, key_for(id))
+      raise Insika::NotFoundError, "session not found: #{id}" if record.nil?
+
+      record
+    end
+
+    def to_session(record)
+      Session.new(
+        id: record["id"],
+        messages: record["messages"],
+        vars: record["vars"],
+        memory_refs: record["memory_refs"],
+        created_at: record["created_at"],
+        updated_at: record["updated_at"]
+      )
+    end
+
+    # Stamps "at" (ISO8601 UTC) on the message when absent; preserves whatever is provided.
+    def stamp(message)
+      message["at"] ||= timestamp
+      message
+    end
+
+    def timestamp
+      Time.now.utc.iso8601
+    end
+  end
+end

data/lib/insika/settings_store.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module Insika
+  # GENERAL deploy settings: timeouts, streaming and
+  # compaction. A single record in the ConfigStore (scope "settings", key "general").
+  # A read always returns the DEFAULTS overlaid by whatever was authored — so
+  # a brand-new deploy (empty store) already responds with coherent config, and the Studio
+  # only persists the delta. Shallow merge at the top, deep in `compaction` (sub-hash).
+  #
+  # Not to be confused with the transport `CONFIG` (bind/port/token, ENV+freeze at
+  # boot): this is editable RUNTIME config, durable in the same backend.
+  class SettingsStore
+    SCOPE = "settings"
+    KEY   = "general"
+
+    # STRICT config, settings layer (— "no silent config compat: every
+    # schema migration explicit"). The settings record carries a `schema_version`;
+    # every shape change is a numbered migration here, applied ONLY by the explicit
+    # `migrate!` (Studio settings saves never silently reinterpret old-shaped data).
+    # v1 is the baseline: a pre-versioning record (no `schema_version`) reads as 0 and
+    # `insika doctor --fix` stamps it to 1. Add a real change as MIGRATIONS[2] = proc
+    # and bump SCHEMA_VERSION.
+    SCHEMA_VERSION = 1
+    MIGRATIONS = {}.freeze # target_version(Integer) => ->(record_hash){ migrated_hash }
+
+    DEFAULTS = {
+      "schema_version" => SCHEMA_VERSION,
+      "streaming" => true,
+      "request_timeout" => 120,
+      "max_retries" => 2,
+      "turn_timeout" => 120,
+      "tool_timeout" => 30,
+      "compaction" => { "enabled" => false, "keep_last" => 20 },
+      # LLM config v2. Platform-wide model layer, resolved by the
+      # ModelResolver under an agent that pins no model of its own:
+      #   default_model/default_provider -> the platform default (Chat > Agent > HERE)
+      #   fallback_models -> ordered chain ["provider/model" | "model", ...] tried
+      #                      when the primary is NOT a user pin (source semantics)
+      #   utility_model   -> slot for cheap internal tasks (titles, distillation,
+      #                      compaction); reserved for later wiring.
+      "default_model" => nil,
+      "default_provider" => nil,
+      "fallback_models" => [],
+      "utility_model" => nil,
+      # Reasoning control (4-layer: Chat > Agent > Model > Global). `thinking`
+      # is the GLOBAL default (off/on/low/medium/high; nil = provider default);
+      # `model_params` is the PER-MODEL layer, a map "<provider/model>"|"<model>" ->
+      # { "thinking" => ... }. Both resolved by the ModelResolver.
+      "thinking" => nil,
+      "model_params" => {},
+      # Evals (panel by). The GRADERS are platform config, so
+      # the operator picks them in the Studio instead of remembering a CLI flag:
+      #   judges        -> [{ "model" =>, "provider" => }, …]. [] = deterministic
+      #                    asserts only (rubric'd cases read as judge_pending).
+      #   aggregate     -> median | mean | min — how the panel's scores become the one
+      #                    the report and the baseline read.
+      #   min_agreement -> fraction of judges that must pass for the case to pass.
+      #   quorum        -> samples per judge (variance), on top of the panel.
+      #   tolerance     -> max judge-score drop before it counts as a regression.
+      # Additive key: reads overlay DEFAULTS, so no numbered migration is due (only a
+      # later SHAPE change to this key would earn one).
+      "evals" => {
+        "judges" => [],
+        "aggregate" => "median",
+        "min_agreement" => 0.5,
+        "quorum" => 1,
+        "tolerance" => 0.05
+      },
+      # Edge limits — the platform layer of the EdgeLimiter.
+      # nil/0 = off (opt-in). chat_rate_limit = turn attempts per chat per
+      # chat_rate_window (s); agent_token_ceiling = total tokens per agent per
+      # agent_token_window (s). limit_response overrides the safe reply.
+      # Per-agent overrides live in profile.limits (same keys, sans windows).
+      "edge" => {
+        "chat_rate_limit" => nil,
+        "chat_rate_window" => 60,
+        "agent_token_ceiling" => nil,
+        "agent_token_window" => 86_400,
+        "limit_response" => nil
+      }
+    }.freeze
+
+    def initialize(config_store:)
+      @cs = config_store
+    end
+
+    # -> Hash (defaults overlaid by the authored values). String keys (Store contract).
+    def get
+      deep_merge(DEFAULTS, stored)
+    end
+
+    # Merges the patch over the current one and persists. -> Hash (resulting settings).
+    # Unknown keys are preserved (the Studio decides the screen's schema).
+    def update(patch)
+      merged = deep_merge(get, stringify(patch || {}))
+      @cs.put(SCOPE, KEY, merged)
+      merged
+    end
+
+    # RAW persisted schema version (bypasses the DEFAULTS overlay, which would always
+    # report the current one). nil = no settings persisted yet (fresh deploy — nothing
+    # to migrate); an Integer otherwise, 0 for a pre-versioning record.
+    def stored_schema_version
+      raw = stored
+      return nil if raw.empty?
+
+      Integer(raw["schema_version"] || 0)
+    end
+
+    # Which numbered migrations still need to run. [] when fresh or already current.
+    def pending_migrations
+      from = stored_schema_version
+      return [] if from.nil? || from >= SCHEMA_VERSION
+
+      ((from + 1)..SCHEMA_VERSION).to_a
+    end
+
+    # Applies the pending migrations EXPLICITLY (in order) and stamps the version. No-op
+    # when fresh or already current. -> resulting schema_version (Integer).
+    def migrate!
+      data = stored
+      return SCHEMA_VERSION if data.empty?
+
+      pending_migrations.each do |version|
+        migration = MIGRATIONS[version]
+        data = stringify(migration.call(data)) if migration
+      end
+      data["schema_version"] = SCHEMA_VERSION
+      @cs.put(SCOPE, KEY, data)
+      SCHEMA_VERSION
+    end
+
+    private
+
+    def stored
+      @cs.get(SCOPE, KEY) || {}
+    end
+
+    def deep_merge(base, override)
+      base.merge(override) do |_key, a, b|
+        a.is_a?(Hash) && b.is_a?(Hash) ? deep_merge(a, b) : b
+      end
+    end
+
+    def stringify(obj)
+      case obj
+      when Hash then obj.each_with_object({}) { |(k, v), acc| acc[k.to_s] = stringify(v) }
+      when Array then obj.map { |v| stringify(v) }
+      when Symbol then obj.to_s
+      else obj
+      end
+    end
+  end
+end

data/lib/insika/shutdown.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Insika
+  # shutdown is a drain, not a kill (docs/DEPLOY.md, process model
+  # The serving arms install this around the Executor. On the first
+  # SIGTERM/SIGINT the process stops accepting new turns (`Executor#begin_drain!`
+  # — a turn arriving mid-drain is left `:queued` for the next boot's recovery)
+  # and waits up to `timeout` seconds for the in-flight ones; only then does the
+  # ordinary stop proceed. A second signal skips the wait — the operator insisting
+  # means now. Whatever the deadline abandons dies `:running` with the process and
+  # the next boot generation's task sweep replays it from its checkpoint
+  # (side-effect skip on resume is what makes that replay safe).
+  #
+  # Mechanics, because trap context is narrow: the handler writes ONE byte into a
+  # self-pipe and returns. A plain watcher THREAD — not a fiber: at install time
+  # the serving reactor may not exist yet, and the drain must not depend on it —
+  # blocks on that pipe, runs the drain, and then delivers the stop the trap
+  # withheld by raising Interrupt in the serving thread. That is exactly the
+  # exception async-container's own trap would have raised, so everything
+  # downstream (Falcon worker teardown, reactor close, Litestream's final sync)
+  # is unchanged; this class only buys the turns time before it.
+  class Shutdown
+    DEFAULT_TIMEOUT = 20 # seconds — the number DEPLOY.md records and entrypoint.sh builds on
+    POLL = 0.05
+
+    # The one-call form the serving arms use: resolves the deadline, sets the
+    # traps, parks the watcher. The CALLING thread is captured as the stop target
+    # — install from the thread that runs the server.
+    #
+    # `executors:` drains N graphs on one signal. Signals are a
+    # PROCESS concern, and `Signal.trap` keeps only the last handler — so a second
+    # `install` per graph would silently leave the earlier graphs dying mid-turn.
+    # The host installs ONCE, naming every graph it embedded. `executor:` is the
+    # single-graph sugar every serving arm still uses.
+    def self.install(executor: nil, executors: nil, timeout: nil, logger: $stdout, signals: %w[INT TERM])
+      new(executors: executors || executor, timeout: timeout || default_timeout,
+          logger: logger).install!(signals)
+    end
+
+    # INSIKA_DRAIN_TIMEOUT (validated by EnvSchema); absent/garbage -> the default.
+    def self.default_timeout
+      Integer(EnvSchema.read("INSIKA_DRAIN_TIMEOUT").to_s)
+    rescue ArgumentError
+      DEFAULT_TIMEOUT
+    end
+
+    # `interrupt` is the injectable stop delivery (specs); the default raises
+    # Interrupt in `target`, the thread that installed the traps.
+    def initialize(executor: nil, executors: nil, timeout:, logger: $stdout,
+                   target: Thread.current, interrupt: nil)
+      @executors = Array(executors || executor)
+      @timeout = timeout
+      @logger = logger
+      @target = target
+      @interrupt = interrupt || -> { @target.raise(Interrupt) }
+      @reader, @writer = IO.pipe
+      @signaled = false
+    end
+
+    attr_reader :timeout
+
+    def install!(signals = %w[INT TERM])
+      signals.each { |sig| Signal.trap(sig) { signal_received } }
+      @thread = Thread.new { watch }
+      @thread.name = "insika-shutdown"
+      self
+    end
+
+    # Runs in TRAP context: a flag flip and a pipe write, nothing else — except
+    # when the drain is already underway, where a repeated signal means "stop
+    # waiting" and the Interrupt is delivered immediately.
+    def signal_received
+      return @interrupt.call if @signaled
+
+      @signaled = true
+      begin
+        @writer.write_nonblock("!")
+      rescue IOError, SystemCallError
+        nil # pipe gone (process already unwinding): nothing left to schedule
+      end
+    end
+
+    # The watcher's whole life: parked on the pipe until the first signal, then
+    # drain and hand the stop back to the normal path.
+    def watch
+      @reader.read(1)
+      drain
+      @interrupt.call
+    end
+
+    # Closes the intake and waits for the in-flight turns, bounded by the
+    # deadline. With N executors the intake of EVERY one closes first, before any
+    # waiting: draining them in sequence would let graph B keep taking turns while
+    # graph A spends the deadline. -> { drained: bool, abandoned: [task ids] }
+    def drain
+      @executors.each(&:begin_drain!)
+      log("shutdown: draining — #{in_flight.size} turn(s) in flight, deadline #{@timeout}s")
+      deadline = monotonic + @timeout
+      sleep(POLL) until in_flight.empty? || monotonic >= deadline
+
+      abandoned = in_flight
+      if abandoned.empty?
+        log("shutdown: drained clean")
+      else
+        log("shutdown: deadline reached — abandoning #{abandoned.size} turn(s); " \
+            "recovery replays them at the next boot")
+      end
+      { drained: abandoned.empty?, abandoned: abandoned }
+    end
+
+    private
+
+    # The turns still running across every graph this shutdown owns.
+    def in_flight = @executors.flat_map(&:in_flight)
+
+    def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+    # Observability only: a logger failure must never alter the drain.
+    def log(message)
+      @logger&.puts(message)
+    rescue StandardError
+      nil
+    end
+  end
+end