insika 0.2.0 → 0.7.0

data/lib/insika/soak/runner.rb

@@ -0,0 +1,554 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+require "zlib"
+require "fileutils"
+require "time"
+require "optparse"
+
+module Insika
+  module Soak
+    # The arrival-rate runner: sustain a declared load against a
+    # live deploy for N hours, poll vitals hourly, append every observation to
+    # the results file as it happens. It computes NO verdict (C5 does, offline)
+    # and never retries a turn — a failed turn is evidence, not a problem to
+    # smooth over. Threads, not fibers: the tool that measures the reactor
+    # should not share its failure modes.
+    class Runner
+      # One failed precondition, named (P1..P5 per the techspec §7.2).
+      Failure = Data.define(:check, :message)
+
+      # Preflight refused the run. The failures name what was wrong; nothing
+      # was written and no traffic past the probes was fired.
+      class PreflightError < Insika::Error
+        attr_reader :failures
+
+        def initialize(failures)
+          @failures = failures
+          super(failures.map(&:message).join("; "))
+        end
+      end
+
+      USAGE = <<~TXT
+        insika soak — the 72h soak runner
+
+        Usage: insika soak --run | --verify FILE | --preflight [options]
+
+        Modes:
+          --run                  fire the soak (mutually exclusive with --verify)
+          --verify FILE          re-read an archived run; NO traffic, no network
+          --preflight            run every precondition check and exit
+          --dry-run              print the plan + one sample request, send nothing
+
+        Options:
+          --envelope PATH        the frozen envelope (required)
+          --agent ID             the soak agent (default: from envelope)
+          --out DIR              where the results file lands (default: soak-out)
+          --resume FILE          continue an interrupted run, recording the gap
+
+        Environment:
+          INSIKA_URL              base URL of the engine (default: http://localhost:9292)
+          OPENCLAW_GATEWAY_TOKEN  Bearer; falls back to ADMIN_TOKEN, then "local-demo"
+      TXT
+
+      # Poisson inter-arrival seconds: `-mean * Math.log(1.0 - rand)`. Seeded,
+      # so a re-run with the same seed is the same arrival sequence. The rate is
+      # expressed in the ARRIVAL unit (sessions per hour when session_turns > 1);
+      # the envelope's turns_per_hour is divided by session_turns before this.
+      def self.arrivals(seed:, rate_per_hour:, count:)
+        rng = Random.new(seed)
+        mean = 3600.0 / rate_per_hour
+        Array.new(count) { -mean * Math.log(1.0 - rng.rand) }
+      end
+
+      # CLI entry (bin/insika delegates here). -> exit status.
+      def self.main(argv, stdout: $stdout, stderr: $stderr, env: ENV, http: nil)
+        opts = { out: "soak-out" }
+        modes = []
+        OptionParser.new do |o|
+          o.banner = "Usage: insika soak --run | --verify FILE | --preflight [options]"
+          o.on("-h", "--help", "show this help") { stdout.puts USAGE; return 0 }
+          o.on("--run", "fire the soak") { modes << :run }
+          o.on("--verify FILE", "re-read an archived run") { |v| modes << [:verify, v] }
+          o.on("--preflight", "run every precondition check") { modes << :preflight }
+          o.on("--dry-run", "print the plan, send nothing") { modes << :dry_run }
+          o.on("--envelope PATH") { |v| opts[:envelope] = v }
+          o.on("--agent ID") { |v| opts[:agent] = v }
+          o.on("--out DIR") { |v| opts[:out] = v }
+          o.on("--resume FILE") { |v| opts[:resume] = v }
+        end.parse!(argv)
+
+        if modes.length != 1
+          stderr.puts "insika soak: choose exactly one of --run, --verify, --preflight, --dry-run\n\n#{USAGE}"
+          return 2
+        end
+        if opts[:envelope].nil?
+          stderr.puts "insika soak: --envelope PATH is required (the deployment's frozen envelope)\n\n#{USAGE}"
+          return 2
+        end
+
+        mode = modes.first
+        if mode.is_a?(Array) && mode.first == :verify
+          return verify(mode[1], envelope_path: opts[:envelope], stdout: stdout, stderr: stderr)
+        end
+
+        envelope = Envelope.load(opts[:envelope])
+        runner = new(envelope: envelope, agent: opts[:agent], out: opts[:out],
+                     env: env, http: http, stdout: stdout, stderr: stderr)
+
+        case mode
+        when :dry_run
+          stdout.puts runner.dry_run_plan
+          0
+        when :preflight
+          failures = runner.preflight
+          if failures.empty?
+            stdout.puts "preflight OK — every precondition holds"
+            0
+          else
+            failures.each { |f| stderr.puts "preflight #{f.check}: #{f.message}" }
+            2
+          end
+        when :run
+          status = runner.run(resume: opts[:resume], traps: true)
+          status == :complete ? 0 : 1
+        end
+      rescue OptionParser::ParseError => e
+        stderr.puts "insika soak: #{e.message}\n\n#{USAGE}"
+        2
+      rescue PreflightError => e
+        e.failures.each { |f| stderr.puts "preflight #{f.check}: #{f.message}" }
+        stderr.puts "insika soak: refusing to start"
+        2
+      rescue Insika::ConfigError => e
+        stderr.puts "insika soak: #{e.message}"
+        2
+      end
+
+      # Pure fold over the archived file — no traffic, no network, no clock.
+      def self.verify(path, envelope_path: nil, stdout: $stdout, stderr: $stderr)
+        raise Insika::ConfigError, "soak --verify needs --envelope PATH (the frozen envelope the run was declared with)" if envelope_path.nil?
+
+        envelope = Envelope.load(envelope_path)
+        records = read_records(path)
+        result = Report.fold(records, envelope: envelope)
+        stdout.puts result.to_s
+        result.pass? ? 0 : 1
+      rescue Insika::ConfigError => e
+        stderr.puts "insika soak: #{e.message}"
+        2
+      end
+
+      # Lazy line reader: .jsonl while running, .jsonl.gz once archived. Lines
+      # that fail to parse travel through RAW so the fold can count them
+      # (a truncated file must not read as a clean one).
+      def self.read_records(path)
+        lines = if path.end_with?(".gz")
+                  Zlib::GzipReader.open(path) { |gz| gz.each_line.to_a }
+                else
+                  File.foreach(path).to_a
+                end
+        lines.map do |line|
+          JSON.parse(line)
+        rescue JSON::ParserError
+          line
+        end
+      end
+
+      attr_reader :envelope
+
+      def initialize(envelope:, out: "soak-out", agent: nil, env: ENV, http: nil,
+                     seed: nil, clock: nil, sleeper: nil, stdout: $stdout, stderr: $stderr)
+        @envelope = envelope
+        @out = out
+        @agent = agent || envelope[:agent]
+        @env = env
+        @http = http || Http.new(token: resolve_token(env))
+        @seed = seed || Time.now.to_i
+        @clock = clock || -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+        @sleeper = sleeper || ->(s) { sleep s }
+        @stdout = stdout
+        @stderr = stderr
+        @stop_reason = nil
+        @lanes = []
+        @in_flight = 0
+        @mutex = Mutex.new
+        @write_mutex = Mutex.new
+        @cond = ConditionVariable.new
+        @vitals_failures = 0
+        @vitals_degraded_noted = false
+      end
+
+      def target_url
+        (@env["INSIKA_URL"] || @env["HARNESS_URL"] || "http://localhost:9292").sub(%r{/$}, "")
+      end
+
+      def corpus
+        path = @envelope[:corpus]
+        raise Insika::ConfigError, "soak envelope declares no corpus" if path.to_s.empty?
+
+        lines = File.readlines(path, chomp: true).map(&:strip).reject(&:empty?)
+        raise Insika::ConfigError, "soak corpus #{path} has no usable lines" if lines.empty?
+
+        lines
+      rescue Errno::ENOENT
+        raise Insika::ConfigError, "soak corpus not found: #{path}"
+      end
+
+      # The five preconditions (techspec §7.2). Each is a REFUSAL TO START, not
+      # a runtime behaviour: a soak must not measure its own limiter, a wrong
+      # deploy, or a box that hides what it runs on.
+      def preflight
+        failures = []
+        vitals = @http.get_vitals(target_url)
+
+        if vitals[:status] != 200 || !vitals.dig(:body, "rss_bytes") || vitals.dig(:body, "boot_id").to_s.empty?
+          failures << Failure.new("P1", "GET /v1/vitals must return 200 with a non-null rss_bytes and a non-empty boot_id")
+        end
+
+        probe = @http.post_turn(target_url, @agent, user: "soak-preflight", message: "ok",
+                                timeout: (@envelope[:request_timeout_s] || 120))
+        unless probe.dig(:timing).is_a?(Hash) && probe[:timing].any?
+          failures << Failure.new("P2", "the probe turn carries no timing block (INSIKA_TURN_TIMING off on the target)")
+        end
+        unless probe.dig(:usage, "total_tokens").to_i.positive?
+          failures << Failure.new("P3", "the probe turn called no model (no usage) — the run would measure the edge limiter")
+        end
+
+        pids = [vitals.dig(:body, "pid")]
+        2.times do
+          @sleeper.call(5)
+          pids << @http.get_vitals(target_url).dig(:body, "pid")
+        end
+        if pids.compact.uniq.length != 1
+          failures << Failure.new("P4", "vitals.pid is not stable across three polls — the RSS series would be a random worker per hour")
+        end
+        if @envelope[:web_concurrency] != 1
+          failures << Failure.new("P4", "the envelope declares web_concurrency #{@envelope[:web_concurrency].inspect}, not 1")
+        end
+        unless URI(target_url).host == @envelope[:target_url_host]
+          failures << Failure.new("P5", "target host #{URI(target_url).host.inspect} does not match the envelope's #{@envelope[:target_url_host].inspect}")
+        end
+        if @envelope[:agent] && @agent != @envelope[:agent]
+          failures << Failure.new("P5", "agent #{@agent.inspect} does not match the envelope's #{@envelope[:agent].inspect}")
+        end
+        failures
+      end
+
+      def dry_run_plan
+        lines = [
+          "soak dry-run — no requests sent",
+          "  envelope: #{@envelope[:target]} (sha #{@envelope.sha})",
+          "  target:   #{target_url}",
+          "  agent:    #{@agent}",
+          "  shape:    #{@envelope[:turns_per_hour]} turns/h poisson, #{@envelope[:session_turns]}-turn sessions, " \
+          "cap #{@envelope[:concurrency_cap]}, #{@envelope[:duration_hours]}h (#{@envelope[:warmup_hours]}h warmup)",
+          "  sample:   POST #{URI.join(target_url + '/', 'v1/responses')} model=openclaw:#{@agent} user=soak-1",
+          "  out:      #{@out}/"
+        ]
+        unless @envelope.calibrated?
+          lines << "  NOTE: not calibrated — a #{@envelope[:duration_hours]}h run will refuse to start (E1 first)"
+        end
+        lines.join("\n")
+      end
+
+      # Fires the soak. -> :complete | :interrupted | :aborted.
+      def run(resume: nil, traps: false)
+        unless @envelope.calibrated? || @envelope.dry_run?
+          raise Insika::ConfigError, "the #{@envelope[:duration_hours]}h run refuses to start: " \
+                                     "the envelope is not calibrated (run E1 first, then write the three ceilings)"
+        end
+
+        failures = preflight
+        raise PreflightError, failures unless failures.empty?
+
+        install_traps if traps
+
+        header, lane_id = resume ? resume_state(resume) : [new_header, 0]
+        path = resume || File.join(@out, "#{header['run_id']}.jsonl")
+        FileUtils.mkdir_p(File.dirname(path)) unless resume
+        @file = File.open(path, "a")
+        if resume
+          append_gap_record(resume)
+        else
+          append(header)
+        end
+
+        run_id = header["run_id"]
+        @stdout.puts "soak -> target=#{target_url} agent=#{@agent} duration=#{@envelope[:duration_hours]}h " \
+                     "turns=#{@envelope[:turns_per_hour]}/h seed=#{@seed} out=#{path}"
+        @stdout.puts "deploys are frozen for the window: any restart (boot_id or pid change) fails the run"
+
+        duration_hours = @envelope[:duration_hours]
+        offset_hours = resume ? elapsed_hours(header["started_at"]) : 0
+        start = @clock.call
+        deadline = start + (duration_hours - offset_hours) * 3600.0
+        # The envelope declares TURNS per hour; each arrival is a SESSION of
+        # session_turns turns, so arrivals arrive at turns_per_hour/session_turns
+        # per hour — otherwise a 60/h x 7-turn envelope fires 420 turns/h.
+        sessions_per_hour = @envelope[:turns_per_hour].to_f / @envelope[:session_turns]
+        arrivals = self.class.arrivals(seed: @seed, rate_per_hour: sessions_per_hour,
+                                       count: (sessions_per_hour * duration_hours).ceil)
+        messages = corpus
+        next_turn = start
+        snapshot_index = 1
+        turn_index = 0
+
+        loop do
+          break if @stop_reason
+
+          now = @clock.call
+          # Hour 1 is due at start+3600 — the LAST snapshot (hour 72) is due
+          # exactly at the deadline, so the snapshot fires before the loop
+          # ends. Freshly computed from the index, never accumulated (float
+          # drift must not eat the final hour).
+          snapshot_due = start + snapshot_index * 3600.0
+          if now >= snapshot_due - 1e-9 && snapshot_due <= deadline + 1e-9
+            append_snapshot(offset_hours + snapshot_index)
+            snapshot_index += 1
+            next
+          end
+          break if now >= deadline
+
+          # All scheduled arrivals consumed: nothing turn-shaped is ever due
+          # again, so neither the spawn branch nor the wait math may keep
+          # waking on next_turn.
+          next_turn = Float::INFINITY if turn_index >= arrivals.length
+
+          if now >= next_turn && next_turn <= deadline
+            spawn_lane(lane_id, turn_index, messages)
+            @lanes.reject! { |t| !t.alive? }
+            lane_id += 1
+            next_turn += arrivals[turn_index]
+            turn_index += 1
+            next
+          end
+
+          wait = [[snapshot_due, next_turn].min, deadline].min - now
+          break if wait <= 0
+
+          @sleeper.call(wait)
+        end
+
+        @lanes.each(&:join)
+        reason = @stop_reason || "complete"
+        append({ "t" => "end", "at" => Time.now.utc.iso8601, "reason" => reason })
+        @file.close
+        archive_path = gzip!(path)
+
+        result = Report.fold(self.class.read_records(archive_path), envelope: @envelope)
+        @stdout.puts result.to_s
+        reason == "complete" ? :complete : :interrupted
+      end
+
+      private
+
+      def resolve_token(env) = env["OPENCLAW_GATEWAY_TOKEN"] || env["ADMIN_TOKEN"] || "local-demo"
+
+      def install_traps
+        %w[INT TERM].each { |sig| Signal.trap(sig) { @stop_reason = "interrupted" } }
+      end
+
+      def new_header
+        started = Time.now.utc.iso8601
+        {
+          "t" => "header", "run_id" => "#{@envelope[:target]}-#{started.tr(':', '-')}",
+          "envelope_sha" => @envelope.sha, "envelope" => @envelope.values,
+          "target_url" => target_url, "agent" => @agent,
+          "seed" => @seed, "runner_version" => "insika #{Insika::VERSION}",
+          "started_at" => started
+        }
+      end
+
+      # The header plus the next free lane id: lane ids are per-user session
+      # ids on the target, so a resume MUST NOT reuse them — a lane 0 that
+      # existed before the gap would continue a conversation, not start one.
+      def resume_state(path)
+        header = nil
+        last_lane = 0
+        File.foreach(path) do |line|
+          record = JSON.parse(line)
+          if record["t"] == "header"
+            header ||= record
+          elsif record["t"] == "turn" && record["lane"].is_a?(Integer)
+            last_lane = record["lane"] if record["lane"] >= last_lane
+          end
+        rescue JSON::ParserError
+          next
+        end
+        raise Insika::ConfigError, "#{path} has no header record" unless header
+
+        [header, last_lane + 1]
+      end
+
+      def elapsed_hours(started_iso)
+        [(Time.now.utc - Time.parse(started_iso)) / 3600, 0].max.floor
+      end
+
+      def append_gap_record(path)
+        last_at = self.class.read_records(path).filter_map { |r| r.is_a?(Hash) ? r["at"] : nil }.compact.last
+        to = Time.now.utc
+        from = Time.parse(last_at) if last_at
+        append({ "t" => "gap", "from" => (from || to).iso8601, "to" => to.iso8601,
+                 "seconds" => (to - (from || to)).round, "reason" => "resume" })
+      end
+
+      def append(record)
+        @write_mutex.synchronize do
+          @file.puts(JSON.generate(record))
+          @file.fsync
+        end
+      end
+
+      def append_snapshot(hour)
+        vitals = @http.get_vitals(target_url)
+        if vitals[:status] == 200 && vitals[:body].is_a?(Hash)
+          @vitals_failures = 0
+          append({ "t" => "snapshot", "at" => Time.now.utc.iso8601, "hour" => hour,
+                   "envelope_sha" => @envelope.sha, "vitals" => vitals[:body], "error" => nil })
+        else
+          @vitals_failures += 1
+          append({ "t" => "snapshot", "at" => Time.now.utc.iso8601, "hour" => hour,
+                   "envelope_sha" => @envelope.sha, "vitals" => nil, "error" => "vitals poll failed" })
+          if @vitals_failures >= 3 && !@vitals_degraded_noted
+            @vitals_degraded_noted = true
+            append({ "t" => "note", "at" => Time.now.utc.iso8601, "note" => "vitals_degraded" })
+          end
+        end
+      end
+
+      def spawn_lane(lane_id, turn_index, messages)
+        @lanes << Thread.new do
+          queued_at = @clock.call
+          @mutex.synchronize do
+            @cond.wait(@mutex, 0.2) while @in_flight >= @envelope[:concurrency_cap]
+            @in_flight += 1
+          end
+          queued_ms = ((@clock.call - queued_at) * 1000).round
+          begin
+            @envelope[:session_turns].times do |step|
+              # step advances the corpus read: turn 7 of a session must not
+              # repeat turn 1's line.
+              line = messages[(turn_index + step) % messages.length]
+              result = @http.post_turn(target_url, @agent, user: "soak-#{lane_id}", message: line,
+                                       timeout: (@envelope[:request_timeout_s] || 120))
+              append({
+                       "t" => "turn", "at" => Time.now.utc.iso8601, "lane" => lane_id, "step" => step + 1,
+                       "corpus_line" => ((turn_index + step) % messages.length) + 1,
+                       "ok" => result[:ok] == true, "status" => result[:status],
+                       "queued_ms" => queued_ms, "ttfb_ms" => result[:ttfb_ms],
+                       "total_ms" => result[:total_ms], "timing" => result[:timing],
+                       "usage" => result[:usage], "error" => result[:error]
+                     })
+            end
+          ensure
+            @mutex.synchronize do
+              @in_flight -= 1
+              @cond.signal
+            end
+          end
+        end
+      end
+
+      def gzip!(path)
+        gz_path = "#{path}.gz"
+        Zlib::GzipWriter.open(gz_path) { |gz| File.open(path, "rb") { |f| IO.copy_stream(f, gz) } }
+        File.delete(path)
+        gz_path
+      end
+
+      # stdlib HTTP transport, deliberately Net::HTTP — the same choice
+      # loadtest.rb made, and the runner measures the reactor from outside it.
+      class Http
+        def initialize(token:)
+          @token = token
+        end
+
+        def get_vitals(base_url)
+          uri = URI.join(base_url + "/", "v1/vitals")
+          req = Net::HTTP::Get.new(uri)
+          req["Authorization"] = "Bearer #{@token}"
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = uri.scheme == "https"
+          http.open_timeout = 10
+          http.read_timeout = 30
+          res = http.request(req)
+          { status: res.code.to_i, body: safe_json(res.body) }
+        rescue StandardError => e
+          { status: nil, body: nil, error: e.class.to_s }
+        end
+
+        # One turn: streaming POST /v1/responses; measures TTFB/total and
+        # extracts the last usage + timing frames. No retry — a failed turn is
+        # evidence.
+        def post_turn(base_url, agent, user:, message:, timeout:)
+          uri = URI.join(base_url + "/", "v1/responses")
+          req = Net::HTTP::Post.new(uri)
+          req["Authorization"] = "Bearer #{@token}"
+          req["Content-Type"] = "application/json"
+          req["Accept"] = "text/event-stream"
+          req.body = JSON.generate(model: "openclaw:#{agent}", user: user, stream: true, input: message)
+
+          t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          ttfb = nil
+          usage = nil
+          timing = nil
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = uri.scheme == "https"
+          http.read_timeout = timeout
+          http.open_timeout = 10
+
+          status = nil
+          http.start do
+            http.request(req) do |res|
+              status = res.code.to_i
+              return { ok: false, status: status, error: "http #{status}" } unless status.between?(200, 299)
+
+              buffer = +""
+              res.read_body do |chunk|
+                ttfb ||= Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0
+                buffer << chunk
+                while (i = buffer.index("\n\n"))
+                  frame = buffer.slice!(0..i + 1)
+                  frame.each_line do |line|
+                    next unless line.start_with?("data:")
+
+                    payload = line.sub(/^data:\s*/, "").strip
+                    next if payload.empty? || payload == "[DONE]"
+
+                    begin
+                      obj = JSON.parse(payload)
+                      u = obj.dig("response", "usage") || obj["usage"]
+                      usage = u if u
+                      tm = obj.dig("response", "timing")
+                      timing = tm if tm
+                    rescue JSON::ParserError
+                      nil
+                    end
+                  end
+                end
+              end
+            end
+          end
+          { ok: true, status: status, ttfb_ms: (ttfb || 0) * 1000.0,
+            total_ms: (Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0) * 1000.0,
+            usage: usage, timing: timing, error: nil }
+        rescue ::Timeout::Error
+          { ok: false, status: status, error: "timeout" }
+        rescue StandardError => e
+          { ok: false, status: status, error: e.class.to_s }
+        end
+
+        private
+
+        def safe_json(body)
+          JSON.parse(body)
+        rescue JSON::ParserError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/insika/steer_injector.rb

@@ -69,14 +69,32 @@ module Insika
       inject! if @seen >= @expected
     end
 
+    # Tail-appends whatever is in the mailbox right now and reports how many. Called
+    # at a batch boundary (#inject!) and ONCE MORE by the Executor when the run ended
+    # with a message no boundary ever arrived for (a text-only turn closes no batch) —
+    # the append, the running count and the `:turn_steered` event belong in one place
+    # either way.
+    def absorb_pending!
+      texts = @actor.take_user_messages!
+      return 0 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 })
+      texts.size
+    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).
+      # pending message where it is. The turn is about to end, and the Executor
+      # absorbs it there in ONE extra round (#absorb_pending!) — a text-only turn
+      # closes no batch, and answering it half-way is not an option.
       return @expected = nil if size.zero?
 
       @expected = size
@@ -88,14 +106,7 @@ module Insika
       @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 })
+      absorb_pending!
     end
 
     def halt?(result) = defined?(RubyLLM::Tool::Halt) && result.is_a?(RubyLLM::Tool::Halt)

data/lib/insika/store.rb

@@ -17,10 +17,13 @@ module Insika
   #   normalizes at the boundary)
   # - list(scope) returns only keys of the scope, ordered lexicographically;
   #   prefix filters by start_with?
+  # - scopes(prefix) returns the scope NAMES that start with the prefix,
+  #   ordered lexicographically (an additive enumeration, for domain stores
+  #   that name cells hierarchically — "memory:acme", "memory:acme:123")
   # - 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
+  # Backends `include Store` and override the six methods; any forgotten
   # method raises NotImplementedError (fail-fast, better than a distant
   # NoMethodError).
   module Store
@@ -44,6 +47,12 @@ module Insika
       raise NotImplementedError, "#{self.class}#list"
     end
 
+    # -> [String] scope names ordered lexicographically, filtered by prefix
+    # (start_with?). Added for domain stores with hierarchical scope names.
+    def scopes(prefix = nil)
+      raise NotImplementedError, "#{self.class}#scopes"
+    end
+
     # -> the block's result; atomic if the backend supports it
     def transaction(&blk)
       raise NotImplementedError, "#{self.class}#transaction"

data/lib/insika/stores/memory.rb

@@ -39,6 +39,12 @@ module Insika
         prefix ? keys.select { |k| k.start_with?(prefix) } : keys
       end
 
+      def scopes(prefix = nil)
+        names = @data.keys
+        names = names.select { |s| s.start_with?(prefix) } if prefix
+        names.sort
+      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).

data/lib/insika/stores/sqlite.rb

@@ -128,6 +128,14 @@ module Insika
         raise Insika::StoreError, e.message
       end
 
+      def scopes(prefix = nil)
+        names = @db.execute("SELECT DISTINCT scope FROM kv ORDER BY scope").map(&:first)
+        names = names.select { |s| s.start_with?(prefix) } if prefix
+        names
+      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)