insika 0.9.0 → 1.0.1

data/lib/insika/evals/report.rb

@@ -12,7 +12,15 @@ module Insika
       module_function
 
       # -> Hash ready for JSON. `at` is an ISO-8601 string stamped by the caller.
-      def to_h(results, at:)
+      #
+      # `perf` is what each case COST, keyed by case id: `{"ms" =>, "turns" =>,
+      # "tokens" =>, "cached" =>}`. Optional, because the answer to "did it pass" must
+      # not depend on anyone having measured the clock — but a cross-harness table
+      # without it is a table about correctness only, and a merchant asks how long the
+      # customer waited before asking anything else. Wall clock is measured by the
+      # RUNNER around the turn, never self-reported: it is the one column every
+      # entrant can be held to.
+      def to_h(results, at:, perf: nil)
         passed = results.count(&:pass?)
         skipped = results.count(&:skipped?)
         {
@@ -27,17 +35,22 @@ module Insika
           # Absent (not an empty tally) when nothing was compared — a run with no
           # pairwise is the normal one, and a zeroed block reads like every case tied.
           "pairwise" => pairwise_summary(results),
+          "perf" => perf_summary(perf),
           "cases" => results.map do |r|
             {
               "id" => r.id, "agent" => r.agent, "pass" => r.pass?,
               "skipped" => r.skipped,
               "judge_pending" => r.judge_pending?, "error" => r.error,
-              "checks" => r.checks.map { |c| { "name" => c.name, "pass" => c.pass, "detail" => c.detail } },
+              "checks" => r.checks.map do |c|
+                { "name" => c.name, "pass" => c.pass, "detail" => c.detail,
+                  "skipped" => (true if c.skipped?) }.compact
+              end,
               "judge" => (r.judge && { "score" => r.judge.score, "pass" => r.judge.pass, "reason" => r.judge.reason }),
               "pairwise" => (r.pairwise && { "outcome" => r.pairwise.outcome, "vs" => r.pairwise.vs,
                                              "reason" => r.pairwise.reason, "judges" => r.pairwise.judges,
-                                             "order_dependent" => r.pairwise.order_dependent })
-            }
+                                             "order_dependent" => r.pairwise.order_dependent }),
+              "perf" => perf&.[](r.id)
+            }.compact
           end
         }.compact
       end
@@ -57,8 +70,36 @@ module Insika
           "outcomes" => counts }
       end
 
-      def to_json(results, at:)
-        JSON.pretty_generate(to_h(results, at: at))
+      # nil when nothing was timed — an absent block, never a zeroed one: "nobody
+      # measured" and "it took no time" are different facts, and a table that confuses
+      # them publishes a harness as instant.
+      def perf_summary(perf)
+        measured = Array(perf&.values).select { |v| v["ms"] }
+        return nil if measured.empty?
+
+        case_ms = measured.map { |v| v["ms"].to_f }.sort
+        turn_ms = measured.flat_map { |v| Array(v["turn_ms"]) }.compact.sort
+        tokens = measured.filter_map { |v| v["tokens"] }
+        { "cases_measured" => measured.size,
+          "case_ms_p50" => percentile(case_ms, 50), "case_ms_p95" => percentile(case_ms, 95),
+          "turn_ms_p50" => percentile(turn_ms, 50), "turn_ms_p95" => percentile(turn_ms, 95),
+          # Absent rather than zero when no provider reported usage — most rival
+          # harnesses will not, and a zero there reads as free.
+          "tokens_total" => (tokens.sum unless tokens.empty?),
+          "tokens_measured" => tokens.size }.compact
+      end
+
+      def percentile(sorted, p)
+        return nil if sorted.empty?
+
+        r = (p / 100.0) * (sorted.length - 1)
+        lo = sorted[r.floor]
+        hi = sorted[r.ceil]
+        (lo + ((hi - lo) * (r - r.floor))).round
+      end
+
+      def to_json(results, at:, perf: nil)
+        JSON.pretty_generate(to_h(results, at: at, perf: perf))
       end
 
       PAIRWISE_MARK = { "better" => "🟢", "comparable" => "🟡", "worse" => "🔴",
@@ -85,8 +126,8 @@ module Insika
       end
 
       # Human summary. One line per case; failing checks nested underneath.
-      def to_markdown(results, at:)
-        h = to_h(results, at: at)
+      def to_markdown(results, at:, perf: nil)
+        h = to_h(results, at: at, perf: perf)
         lines = ["# Eval report — #{at}", "",
                  "**#{h['passed']}/#{h['total'] - h['skipped']} passed** · #{h['failed']} failed" \
                  "#{" · #{h['skipped']} skipped" if h['skipped'].positive?}" \
@@ -99,14 +140,25 @@ module Insika
             next
           end
 
-          lines << "- #{r.pass? ? '✅' : '❌'} `#{r.id}` (#{r.agent})#{'  ⏳ judge pending' if r.judge_pending?}"
+          took = perf&.dig(r.id, "ms")
+          lines << "- #{r.pass? ? '✅' : '❌'} `#{r.id}` (#{r.agent})" \
+                   "#{" · #{(took / 1000.0).round(1)}s" if took}" \
+                   "#{'  ⏳ judge pending' if r.judge_pending?}"
           r.failures.each { |c| lines << "    - ❌ #{c.name}: #{c.detail}" }
+          # A grader the transport could not feed. Printed even on a passing case:
+          # "passed" over checks nobody could run is the claim this line prevents.
+          r.skipped_checks.each { |c| lines << "    - ⏭️ #{c.name}: #{c.detail}" }
           if r.judge
             v = r.judge
             lines << "    - #{v.pass ? '✅' : '❌'} judge: #{v.score} — #{v.reason}"
           end
           lines << "    - #{pairwise_line(r.pairwise)}" if r.pairwise
         end
+        if (summary = h["perf"])
+          lines << "" << "**time** (#{summary['cases_measured']} case(s)): " \
+                   "case p50/p95 #{summary['case_ms_p50']} / #{summary['case_ms_p95']} ms · " \
+                   "turn p50/p95 #{summary['turn_ms_p50']} / #{summary['turn_ms_p95']} ms"
+        end
         lines.concat(pairwise_block(h["pairwise"])) if h["pairwise"]
         "#{lines.join("\n")}\n"
       end

data/lib/insika/evals/runner.rb

@@ -19,7 +19,11 @@ module Insika
       # cache, carried separately because it is the number that explains a total.
       # Only the refinement gate reads them (records a run's cost); the
       # report and the exit code are untouched.
-      RunCase = Struct.new(:result, :timings, :tokens, :cached, keyword_init: true)
+      # `turns` and `store` are what the case actually SAW: every turn's reply and
+      # tool calls, and the store as it stood afterwards. The verdict alone says a
+      # cell failed; only these say what the harness answered, and a cross-harness
+      # table is unreadable without being able to go and look.
+      RunCase = Struct.new(:result, :timings, :tokens, :cached, :turns, :store, keyword_init: true)
 
       # judge: an Evals::Judge (optional). When set, a case with a rubric whose turn
       # ran cleanly gets a subjective verdict attached on top of the deterministic pass.
@@ -35,12 +39,18 @@ module Insika
       # pairwise: an Evals::Pairwise (optional). Only cases carrying a
       # `reference:` are compared, and the verdict never touches pass/fail — it is the
       # answer to "can we replace it", reported beside the suite's own verdict.
-      def initialize(transport:, judge: nil, conv_map: {}, capabilities: nil, pairwise: nil)
+      #
+      # store_reader: how a case's `store_state:` is graded — anything answering
+      # `#read(collection)` with the collection's rows. Only the cases that declare a
+      # `store_state:` ask for it; a case that declares one with no reader configured
+      # is SKIPPED with the reason, never run and passed on its reply alone.
+      def initialize(transport:, judge: nil, conv_map: {}, capabilities: nil, pairwise: nil, store_reader: nil)
         @transport = transport
         @judge = judge
         @conv_map = conv_map || {}
         @capabilities = capabilities
         @pairwise = pairwise
+        @store_reader = store_reader
       end
 
       # [Golden] -> [RunCase]. Each RunCase carries the CaseResult (for the report) +
@@ -62,9 +72,16 @@ module Insika
         skip = skip_reason(golden)
         return RunCase.new(result: Assertions.skip(golden, skip), timings: []) if skip
 
+        if golden.store_state? && @store_reader.nil?
+          return RunCase.new(result: Assertions.skip(golden, "no store reader configured for `store_state`"),
+                             timings: [])
+        end
+
         # A backend that resolves state from a pre-existing conversation (e.g. a
         # consumer needing a real Chat UUID as X-Chat-Id) supplies it via conv_map; otherwise the
         # synthetic "eval-<id>" keeps the adapter's own multi-turn continuation.
+        # A reader that caches its snapshot is opening a new case now.
+        @store_reader.forget if @store_reader.respond_to?(:forget)
         conv = @conv_map[golden.id] || "eval-#{golden.id}"
         if golden.seeded?
           # The snapshot goes in BEFORE turn 1 — on the same conversation id the turns
@@ -101,7 +118,10 @@ module Insika
         last = turns.last
         # Tool/content assertions read the last turn (unchanged); the policy checks
         # read every turn — "one question per reply" is a rule about each of them.
-        result = Assertions.evaluate(golden, last, turns: turns)
+        # The store is read AFTER the last turn: what the conversation left behind.
+        store, store_error = read_store(golden) if golden.store_state? && last.error.nil?
+        result = Assertions.evaluate(golden, last, turns: turns, store: store, store_error: store_error,
+                                     tools_reported: tools_reported?)
         # Subjective layer: only when a judge is configured, the case has a rubric, and
         # the turn ran cleanly (nothing to judge on an errored turn).
         result.judge = @judge.score(golden: golden, result: last) if @judge && result.rubric && result.error.nil?
@@ -110,11 +130,31 @@ module Insika
         # comparison for a reason that has nothing to do with the agent.
         result.pairwise = @pairwise.compare(golden: golden, turns: turns) if @pairwise && result.error.nil?
         RunCase.new(result: result, timings: timings, tokens: sum_tokens(spent),
-                    cached: sum_tokens(cached))
+                    cached: sum_tokens(cached), turns: turns, store: store)
       end
 
       private
 
+      # Does the transport see tool calls at all? Only a benched harness answers no
+      # (an adapter that can report the text and nothing else). Anything that does
+      # not answer the question is assumed to report them, which is what every
+      # transport in the engine does.
+      def tools_reported?
+        return true unless @transport.respond_to?(:reports_tool_calls?)
+
+        @transport.reports_tool_calls?
+      end
+
+      # -> [{ collection => [rows] }, nil] or [nil, why]. A reader that raises fails
+      # the store graders WITH the reason rather than killing the run: one unreadable
+      # cell of a bench table must not throw away the other thirty-nine, and a store
+      # nobody could read is never a store that matched.
+      def read_store(golden)
+        [golden.store_collections.to_h { |c| [c, Array(@store_reader.read(c))] }, nil]
+      rescue StandardError => e
+        [nil, "#{e.class}: #{e.message}"]
+      end
+
       # nil when NO turn reported usage; otherwise the sum of the ones that did. A
       # partially-metered case is reported as what was actually measured, low rather
       # than absent — a budget under-counting is a smaller lie than a budget that

data/lib/insika/evals/simulator.rb

@@ -166,12 +166,21 @@ module Insika
       # [tool names] the agent can reach that are marked side-effect, sorted.
       def side_effect_tools(profile, registry)
         allowed = if profile.tools_allow.nil? then Array(registry.names)
-                  else Array(profile.tools_allow).map(&:to_s)
+                  else Array(profile.tools_allow).map(&:to_s) | group_tools(profile, registry)
                   end
         denied = Array(profile.tools_deny).map(&:to_s)
         (allowed - denied).select { |name| registry.side_effect?(name) }.sort
       end
 
+      # Tools reachable through tools_allow_groups (an MCP server, a kit's groups):
+      # the registry entries whose metadata group the agent allows.
+      def group_tools(profile, registry)
+        groups = Array(profile.tools_allow_groups).map(&:to_s)
+        return [] if groups.empty? || !registry.respond_to?(:entries)
+
+        registry.entries.select { |e| groups.include?(e.metadata[:group].to_s) }.map { |e| e.name.to_s }
+      end
+
       # -> bool: can a simulated run touch this agent without a staging
       # declaration (no reachable side-effect tool)?
       def safe?(profile, registry)

data/lib/insika/evals/transport.rb

@@ -3,6 +3,7 @@
 require "net/http"
 require "json"
 require "uri"
+require "open3"
 require_relative "assertions"
 
 module Insika
@@ -329,6 +330,205 @@ module Insika
       end
     end
 
+    # Drives a turn through an EXTERNAL agent runtime — a rival harness in a
+    # container — so the same corpus can be replayed against something that is not
+    # Insika and the answers land in the same TurnResult the graders already read.
+    #
+    # The protocol is one JSON object each way, per turn:
+    #
+    #   in  (stdin):  {"agent": "...", "conv": "...", "message": "..."}
+    #   out (stdout): {"output_text": "...", "tool_calls": [...], "error": null,
+    #                  "usage": {...}}
+    #
+    # `command` is an argv array, never a shell string: the message is customer text
+    # and must not be able to reach a shell. The adapter that speaks this protocol
+    # lives with the harness under test, not here — every rival has its own idea of
+    # what a turn is, and that translation is exactly what a bench entry costs.
+    #
+    # A harness whose adapter cannot report which tools were called says so ONCE, at
+    # construction (`reports_tool_calls: false`), and the Runner skips its tool-shaped
+    # graders with the reason. Otherwise a missing `tool_calls` is read as "this turn
+    # called nothing", which is a claim, not an absence.
+    #
+    # Timeout kills the child process; a container it started keeps running, which is
+    # the compose file's business (`--rm` and a per-run project name) rather than
+    # something to reimplement here.
+    class DriverTransport
+      def initialize(command:, timeout: 300, reports_tool_calls: true, env: {})
+        raise ArgumentError, "command must be an argv array" unless command.is_a?(Array) && !command.empty?
+
+        @command = command.map(&:to_s)
+        @timeout = timeout
+        @reports_tool_calls = reports_tool_calls
+        @env = env.transform_keys(&:to_s).transform_values(&:to_s)
+      end
+
+      def reports_tool_calls? = @reports_tool_calls
+
+      def mono = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      def turn(agent:, conv:, message:)
+        t0 = mono
+        out, err, status = run_driver(JSON.generate(agent: agent, conv: conv, message: message))
+        return failure(err, t0) if status.nil? || !status.success?
+
+        answer = last_json_object(out)
+        return failure("driver wrote no JSON object#{" (stderr: #{tail(err)})" if err}", t0) if answer.nil?
+
+        TurnOutcome.new(
+          result: TurnResult.new(output_text: answer["output_text"].to_s,
+                                 tool_calls: normalize_tool_calls(answer["tool_calls"]),
+                                 ui: [], error: presence(answer["error"])),
+          ttfb: nil, total: (mono - t0) * 1000.0, usage: answer["usage"]
+        )
+      rescue StandardError => e
+        failure("#{e.class}: #{e.message}", t0)
+      end
+
+      private
+
+      # -> [stdout, stderr-or-reason, status]. status nil = it never finished.
+      def run_driver(input)
+        Open3.popen3(@env, *@command) do |stdin, stdout, stderr, wait_thr|
+          stdin.write(input)
+          stdin.close
+          out = +""
+          err = +""
+          readers = [Thread.new { out << stdout.read }, Thread.new { err << stderr.read }]
+
+          if wait_thr.join(@timeout).nil?
+            kill(wait_thr.pid)
+            readers.each(&:kill)
+            return [out, "driver timed out after #{@timeout}s", nil]
+          end
+
+          readers.each(&:join)
+          status = wait_thr.value
+          [out, status.success? ? err : "exit #{status.exitstatus}#{" — #{tail(err)}" if presence(err)}", status]
+        end
+      end
+
+      def kill(pid)
+        Process.kill("KILL", pid)
+      rescue Errno::ESRCH, Errno::EPERM
+        nil
+      end
+
+      # The driver's answer is the LAST JSON object it printed: an adapter that logs
+      # to stdout is the normal case, and refusing to read past its chatter would
+      # turn every such harness into an entry-gate failure it does not deserve.
+      def last_json_object(out)
+        out.to_s.each_line.reverse_each do |line|
+          parsed = begin
+            JSON.parse(line)
+          rescue JSON::ParserError
+            nil
+          end
+          return parsed if parsed.is_a?(Hash)
+        end
+        nil
+      end
+
+      # Adapters report tool calls in whichever shape their harness has: a bare name,
+      # or an object. Both become the shape the graders read.
+      def normalize_tool_calls(raw)
+        Array(raw).filter_map do |call|
+          case call
+          when String then { "name" => call, "status" => nil }
+          when Hash
+            name = (call["name"] || call[:name]).to_s
+            next if name.empty?
+
+            entry = { "name" => name, "status" => presence(call["status"]) }
+            (args = call["arguments"]) && (entry["arguments"] = args)
+            (gate = presence(call["gate"])) && (entry["gate"] = gate)
+            entry
+          end
+        end
+      end
+
+      def presence(value)
+        s = value.to_s.strip
+        s.empty? ? nil : s
+      end
+
+      def tail(text) = text.to_s.strip.lines.last(3).join.strip
+
+      def failure(msg, t0)
+        TurnOutcome.new(result: TurnResult.new(output_text: "", tool_calls: [], ui: [], error: msg.to_s),
+                        ttfb: nil, total: (mono - t0) * 1000.0, usage: nil)
+      end
+    end
+
+    # WHAT THE STORE HOLDS, for the `store_state:` graders. The bench dumps the
+    # store to one JSON file ({ collection => [rows] }) after the turn and points
+    # the runner at it; the file is re-read on every call, so the same reader serves
+    # a whole run as the dump is rewritten between tasks.
+    #
+    # Deliberately a file and not an MCP client: the harnesses under test reach the
+    # store over MCP and nothing else, but the GRADER is not a harness — reading the
+    # dumped truth is stricter than asking the same surface the agent could have
+    # confused, and it costs no per-store tool mapping.
+    class JsonStoreReader
+      def initialize(path)
+        @path = path
+      end
+
+      def read(collection)
+        snapshot = JSON.parse(File.read(@path))
+        raise Insika::Error, "#{@path}: expected a mapping of collection -> rows" unless snapshot.is_a?(Hash)
+
+        Array(snapshot[collection.to_s])
+      rescue Errno::ENOENT
+        raise Insika::Error, "#{@path}: no store snapshot on disk"
+      rescue JSON::ParserError => e
+        raise Insika::Error, "#{@path}: #{e.message}"
+      end
+    end
+
+    # The store, asked for its own state by running a command — `docker compose exec
+    # store dump-state`, or whatever a given store answers with. Preferred over the
+    # file reader for a benched harness: the dump then happens AFTER the turn, outside
+    # the window the runner is timing, so the store's own latency never lands in the
+    # harness's column.
+    #
+    # The dump is read ONCE per case and cached, because a case asks for several
+    # collections and dumping twice would report two different stores. `forget` is how
+    # the Runner opens a new case; a reader nobody resets would grade every case
+    # against the first one.
+    class CommandStoreReader
+      def initialize(command:, timeout: 60)
+        raise ArgumentError, "command must be an argv array" unless command.is_a?(Array) && !command.empty?
+
+        @command = command.map(&:to_s)
+        @timeout = timeout
+        @snapshot = nil
+      end
+
+      def forget = @snapshot = nil
+
+      def read(collection)
+        @snapshot ||= dump
+        Array(@snapshot[collection.to_s])
+      end
+
+      private
+
+      def dump
+        out, err, status = Open3.capture3(*@command)
+        raise Insika::Error, "store dump exited #{status.exitstatus}: #{err.to_s.strip.lines.last}" unless status.success?
+
+        parsed = JSON.parse(out)
+        raise Insika::Error, "store dump is not a mapping of collection -> rows" unless parsed.is_a?(Hash)
+
+        parsed
+      rescue JSON::ParserError => e
+        raise Insika::Error, "store dump is not JSON: #{e.message}"
+      rescue SystemCallError => e
+        raise Insika::Error, "store dump could not run: #{e.message}"
+      end
+    end
+
     # Thin A2A transport: drives a REMOTE A2A agent (an agent that only speaks
     # A2A) through the same `turn` seam the Simulator uses. The outbound A2A
     # client already does the send+poll; this is the wrapper that makes it a

data/lib/insika/event_stream.rb

@@ -9,6 +9,7 @@ module Insika
   # has its own queue and `emit` only enqueues. No mutex: one reactor, cooperative
   # fibers — a plain Array is enough.
   class EventStream
+    EMPTY = [].freeze
     # One subscription = one queue. The consumer blocks on `each` (its own fiber),
     # never the emitter.
     class Subscription
@@ -20,6 +21,8 @@ module Insika
       # local :error event — the turn never waits on transport.
       MAX_QUEUED = 1000
 
+      attr_reader :session_id
+
       def initialize(task_id: nil, session_id: nil, tenant: nil, types: nil, on_close: nil)
         @task_id = task_id
         @session_id = session_id
@@ -106,19 +109,26 @@ module Insika
       end
     end
 
+    # Subscriptions by the session they filter on (nil = any session). A session
+    # filter never changes after subscribe, so an event only needs the any-session
+    # list plus its own session's: emit does not walk every open conversation.
     def initialize
-      @subscriptions = []
+      @subscriptions = {}
+      @running = {} # session_id -> { task_id -> [Event] } of the turns still running
     end
 
     # NEVER raises: an observer's exception is isolated — a
     # broken observer does not bring down the turn. Synchronous and cheap.
     #
-    # Iterates over a SNAPSHOT (`dup`): a subscription's cap may close it
+    # Iterates over a SNAPSHOT (a new array): a subscription's cap may close it
     # DURING the push (overflow -> close -> on_close removes from the array);
     # mutating the array in the middle of a plain Array#each would skip the next
     # subscriber.
     def emit(event)
-      @subscriptions.dup.each do |sub|
+      session_id = event.meta&.[](:session_id)
+      candidates = @subscriptions.fetch(nil, EMPTY) + (session_id.nil? ? EMPTY : @subscriptions.fetch(session_id, EMPTY))
+      remember(event, session_id)
+      candidates.each do |sub|
         sub.push(event) if sub.matches?(event)
       rescue StandardError
         # a broken observer does not bring down the turn; nothing to propagate
@@ -130,13 +140,59 @@ module Insika
     # `#each` on its own fiber). `tenant:` scopes the stream to one tenant's
     # events (WS1) — fail-closed, see Subscription#matches?. `types:` (nil =
     # any) filters by event type so a subscriber's queue only ever holds what
-    # its consumer answers (WS6).
-    def subscribe(task_id: nil, session_id: nil, tenant: nil, types: nil)
+    # its consumer answers (WS6). `replay: true` first hands over what the
+    # session's running turns already emitted: the transcript is only saved when
+    # a turn ends, so a viewer who arrives mid-turn would otherwise miss it.
+    def subscribe(task_id: nil, session_id: nil, tenant: nil, types: nil, replay: false)
       sub = Subscription.new(task_id: task_id, session_id: session_id, tenant: tenant,
                              types: types,
-                             on_close: ->(s) { @subscriptions.delete(s) })
-      @subscriptions << sub
+                             on_close: ->(s) { unsubscribe(s) })
+      running_events(session_id).each { |event| sub.push(event) if sub.matches?(event) } if replay && session_id
+      (@subscriptions[session_id] ||= []) << sub
       sub
     end
+
+    private
+
+    TERMINAL = %i[task_completed task_failed task_cancelled].freeze
+    DELTAS = %i[intermediate thinking].freeze
+    # Sessions whose running turn is kept. A turn that never reaches a terminal
+    # (a crash) would stay forever; past this, the oldest is dropped.
+    # ponytail: count cap, not a TTL — add one if stuck turns pile up.
+    MAX_RUNNING = 200
+
+    # Keeps the running turn of each session; consecutive deltas are merged into
+    # one event (carrying the newest meta/seq) so a long turn stays a short list.
+    def remember(event, session_id)
+      task_id = event.meta&.[](:task_id)
+      return if session_id.nil? || task_id.nil?
+
+      if TERMINAL.include?(event.type)
+        turns = @running[session_id] or return
+        turns.delete(task_id)
+        @running.delete(session_id) if turns.empty?
+        return
+      end
+
+      events = ((@running[session_id] ||= {})[task_id] ||= [])
+      last = events.last
+      if last && DELTAS.include?(event.type) && last.type == event.type
+        events[-1] = event.with(data: last.data.merge(delta: last.data[:delta].to_s + event.data[:delta].to_s))
+      else
+        events << event
+      end
+      @running.delete(@running.keys.first) if @running.size > MAX_RUNNING
+    end
+
+    def running_events(session_id)
+      @running.fetch(session_id, {}).values.flatten
+    end
+
+
+    def unsubscribe(sub)
+      list = @subscriptions[sub.session_id] or return
+      list.delete(sub)
+      @subscriptions.delete(sub.session_id) if list.empty?
+    end
   end
 end

data/lib/insika/evidence.rb

@@ -26,7 +26,11 @@ module Insika
     #
     # `kind` is the PILOT PACK's value, never a gem constant (the
     # engine owns nothing about product shape).
-    Spec = Data.define(:kind, :items_path, :attachments_path) do
+    # `id`/`line` name the FIELDS inside an item, because a store's own payload
+    # calls them what it calls them (`product_id`, `name`) and a server nobody
+    # controls — an MCP server in particular — will not rename them for us.
+    # Defaults keep every existing spec byte-identical.
+    Spec = Data.define(:kind, :items_path, :attachments_path, :id_field, :line_field) do
       PATH_RE = /\A[a-zA-Z0-9_]+(?:\.[a-zA-Z0-9_]+)*\z/
 
       # String | Hash | Spec | nil -> Spec | nil. Raises ValidationError on a blank kind
@@ -43,13 +47,28 @@ module Insika
 
         items = presence_path(h["items"], "items")
         attachments = presence_path(h["attachments"], "attachments")
-        new(kind: kind, items_path: items, attachments_path: attachments)
+        new(kind: kind, items_path: items, attachments_path: attachments,
+            id_field: presence_field(h["id"], "id"), line_field: presence_field(h["line"], "line"))
       end
 
+      # A default field is left OUT: a spec that names nothing new serializes
+      # exactly as it did before this existed.
       def to_h
-        { "kind" => kind, "items" => items_path, "attachments" => attachments_path }.compact
+        { "kind" => kind, "items" => items_path, "attachments" => attachments_path,
+          "id" => (id_field unless id_field == "id"),
+          "line" => (line_field unless line_field == "line") }.compact
       end
 
+      # A field name, not a path: the item is one flat object and a dotted dig
+      # inside it would be a different feature.
+      def self.presence_field(value, default)
+        s = Coercion.presence(value) || default
+        raise Insika::ValidationError, "evidence.#{default}: not a field name" unless /\A[a-zA-Z0-9_]+\z/.match?(s)
+
+        s
+      end
+      private_class_method :presence_field
+
       def self.presence_path(value, default)
         s = Coercion.presence(value)
         s = default if s.nil?
@@ -119,14 +138,15 @@ module Insika
         # model must never see a null where the contract says items.
         def build(spec, raw)
           items = SchemaGuard.dig(raw, spec.items_path) || []
+          id_of = ->(item) { item[spec.id_field] || item[spec.id_field.to_sym] }
           lean_items = items.first(MAX_ITEMS).map do |item|
-            { "id" => (item["id"] || item[:id]).to_s,
+            { "id" => id_of.call(item).to_s,
               # the line is what the model reads: truncated here; sanitized by the
               # envelope's fence when the agent has `fencing` on (bytes as-is when off).
-              "line" => Coercion.utf8((item["line"] || item[:line]).to_s)[0, LINE_MAX] }
+              "line" => Coercion.utf8((item[spec.line_field] || item[spec.line_field.to_sym]).to_s)[0, LINE_MAX] }
           end
           lean = { "items" => lean_items }
-          cards = stamp_ids(items, SchemaGuard.dig(raw, spec.attachments_path))
+          cards = stamp_ids(items, SchemaGuard.dig(raw, spec.attachments_path), id_of)
           [lean, Insika::Evidence.valid_attachments(cards)]
         end
 
@@ -135,12 +155,12 @@ module Insika
         # its position. That id is what a presentation tool later joins on. Stamped
         # on the RAW list, before malformed cards are dropped: pairing after the
         # drop would shift every later card onto the wrong product.
-        def stamp_ids(items, cards)
+        def stamp_ids(items, cards, id_of = ->(item) { item["id"] || item[:id] })
           Array(cards).each_with_index.map do |card, i|
             next card unless card.is_a?(Hash) && (card["id"] || card[:id]).nil?
 
             item = items[i]
-            id = item.is_a?(Hash) ? (item["id"] || item[:id]).to_s : ""
+            id = item.is_a?(Hash) ? id_of.call(item).to_s : ""
             id.empty? ? card : card.merge("id" => id)
           end
         end
@@ -217,6 +237,7 @@ module Insika
     # "nothing to append", never an explosion).
     def flush!
       return self unless @store && @session_id
+      return self if @ids.empty? && @cards.empty? && @ungrounded.zero? # nothing new: no session rewrite
 
       @store.append_evidence(@session_id, ids: @ids, ungrounded: @ungrounded, cards: @cards)
       @ids = []