insika 0.8.0 → 1.0.1

data/lib/insika/server/app.rb

@@ -56,8 +56,13 @@ module Insika
                      config:, pending_action_store: nil, a2a: nil, provisioner: nil,
                      workflow_registry: nil, onboarding: nil, profiles: nil,
                      channels: nil, logger: nil, token_store: nil, outcome_store: nil,
-                     executor: nil, db_path: nil, tool_registry: nil, mcp_store: nil)
+                     executor: nil, db_path: nil, tool_registry: nil, mcp_store: nil,
+                     settings_store: nil)
         @command_bus = command_bus
+        # READ for one gate: `POST /v1/conversations/:id/seed` answers only while
+        # the platform setting `evals.seeding` is on. nil = no settings = seeding
+        # off (fail-closed — the base wiring has no SettingsStore and cannot seed).
+        @settings_store = settings_store
         @event_stream = event_stream
         @session_store = session_store
         @task_store = task_store
@@ -132,6 +137,8 @@ module Insika
         error_response(422, e)
       rescue Insika::NotFoundError => e
         error_response(404, e)
+      rescue Insika::ConflictError => e
+        error_response(409, e) # the write contradicts existing state (a seed on a used conversation)
       rescue Async::TimeoutError => e
         error_response(504, e) # synchronous control request exceeded the ceiling
       rescue StandardError => e
@@ -186,6 +193,8 @@ module Insika
           handle_trigger_workflow(req, name)
         in ["POST", ["v1", "responses"]]
           handle_responses(req)
+        in ["POST", ["v1", "conversations", id, "seed"]]
+          handle_seed(req, id)
         in ["POST", ["v1", "outcomes"]] if @outcome_store
           handle_record_outcome(req)
         in ["GET", ["v1", "outcomes"]] if @outcome_store
@@ -418,8 +427,11 @@ module Insika
         tenant = req_tenant(req)
         ensure_session(parsed[:user], tenant: tenant)
         payload = { agent: parsed[:agent], session_id: parsed[:user], message: parsed[:message] }
+        payload.merge!(parsed.slice(:shared_conversation, :user_text))
         payload[:origin] = parsed[:origin] if parsed[:origin] # declared, else absent
+        payload[:context] = parsed[:context] if parsed[:context]
         payload[:customer] = parsed[:customer] if parsed[:customer] # WS8: the memory scope handle
+        payload.merge!(parsed.slice(*Insika::SessionStore::CUSTOMER_LABELS.map(&:to_sym)))
         payload[:parts] = parsed[:parts] if parsed[:parts] # WS9: multimodal content parts
         payload[:source] = parsed[:source] if parsed[:source] # WS9: voice-marked text
         payload[:channel] = parsed[:channel] if parsed[:channel] # WS9 (saída): the channel's output capabilities
@@ -427,6 +439,40 @@ module Insika
                               tenant: tenant)
       end
 
+      # POST /v1/conversations/:id/seed — loads the snapshot an eval case starts from
+      # (its `state:` — evidence ids, memory facts/notes, history, briefing fields)
+      # into the conversation BEFORE its first turn. Body = the state mapping, plus an
+      # optional `customer` (the memory scope the turns will carry) and `agent` (the
+      # agent the Studio lists the conversation under). Same Bearer as
+      # /v1/responses and the same id namespacing for a tenant, so the seeded session
+      # IS the one the turn continues. 200 {session}; 409 when the conversation
+      # already has messages (seeding a used one is a test bug, not a merge).
+      #
+      # Refused (auth error) unless the platform setting `evals.seeding` is on. A seeded
+      # conversation is a fabricated precondition written under the tenant token:
+      # right on the machine running snapshot evals, wrong in production — so the
+      # default is off and the doctor warns while it is on.
+      def handle_seed(req, id)
+        return auth_error(403, "seeding is off (settings evals.seeding)") unless seeding_enabled?
+
+        body = parse_body(req)
+        tenant = req_tenant(req)
+        # the conversation id as the TURN will send it in `user` — the path
+        # segment arrives percent-encoded (the eval transport encodes "loja:c1").
+        conv = URI.decode_www_form_component(id)
+        payload = { id: scoped_session_id(tenant, conv), state: body.except(:customer, :agent) }
+        (customer = Insika::Coercion.presence(body[:customer])) && (payload[:customer] = customer)
+        (agent = Insika::Coercion.presence(body[:agent])) && (payload[:agent] = agent)
+        command = Insika::Command.build(:seed_session, payload, transport: :http, tenant: tenant)
+        session = dispatch_with_timeout(command)
+        json_response(200, { session: session.to_h })
+      end
+
+      def seeding_enabled?
+        settings = @settings_store&.get
+        settings.is_a?(Hash) && (settings["evals"] || {})["seeding"] == true
+      end
+
       # POST /v1/agents — provisions (upserts) an agent from a standardized
       # PACK. Same Bearer as /v1/responses (gateway_token,
       # fail-closed). The consumer (GatewayClient/ProvisionStore) sends the pack as
@@ -546,6 +592,10 @@ module Insika
         profile = @profiles.fetch(id)
         raise Insika::NotFoundError, "agent not found: #{id}" if profile.nil?
 
+        # The agent as its turns see it: a kit's tools are reachable for real, so
+        # the capability view and the eval swap list must count them.
+        profile = Insika::Kits.apply(profile, @settings_store.kits) if @settings_store.respond_to?(:kits)
+
         allow = profile.tools_allow
         deny = Array(profile.tools_deny).map(&:to_s)
         payload = {
@@ -567,11 +617,7 @@ module Insika
       def side_effect_tools(profile)
         return nil unless @tool_registry
 
-        allowed = if profile.tools_allow.nil? then Array(@tool_registry.names)
-                  else Array(profile.tools_allow).map(&:to_s)
-                  end
-        denied = Array(profile.tools_deny).map(&:to_s)
-        (allowed - denied).select { |name| @tool_registry.side_effect?(name) }.sort
+        Insika::Evals::EvalProfile.side_effect_tools(profile, @tool_registry)
       end
 
       # `/v1` only — `/a2a` is versioned by its own JSON-RPC spec and a channel's
@@ -625,6 +671,7 @@ TENANT_SURFACES = [
         ["POST", ["v1", "sessions"]],
         ["POST", ["v1", "messages"]],
         ["POST", ["v1", "responses"]],
+        ["POST", ["v1", "conversations", nil, "seed"]],
         ["POST", ["v1", "outcomes"]],
         ["GET", ["v1", "outcomes"]],
         ["POST", ["v1", "workflows", nil]],
@@ -1009,7 +1056,11 @@ TENANT_SURFACES = [
           payload[:session_id] = scoped_session_id(tenant, payload[:session_id]) if payload[:session_id]
         end
         command = Insika::Command.build(:send_message, payload, transport: transport, tenant: tenant)
-        subscription = @event_stream.subscribe
+        # Filtered by session from the start: until `bind` below, an unfiltered
+        # subscription takes EVERY turn's events, and under load the other
+        # sessions' deltas fill its 1000-event cap during the dispatch — the
+        # stream then ends with no terminal event. nil session = unfiltered, as before.
+        subscription = @event_stream.subscribe(session_id: payload[:session_id])
         result =
           begin
             @command_bus.dispatch(command)

data/lib/insika/server/rack_app.rb

@@ -80,6 +80,8 @@ module Insika
           outcome_store: @graph.outcome_store,
           # GET/PUT/DELETE /v1/mcp[/:name] — the config surface.
           mcp_store: @rt.component(:mcp_store),
+          # POST /v1/conversations/:id/seed answers only while `evals.seeding` is on.
+          settings_store: @rt.component(:settings_store),
           # a 500's error_ref must be findable in the process log.
           logger: $stdout
         )

data/lib/insika/server/responses.rb

@@ -42,9 +42,23 @@ module Insika
         message = extract_input(body[:input])
 
         out = { agent: agent.strip, user: user, message: message }
+        if body.key?(:shared_conversation)
+          raise Insika::ValidationError, 'shared_conversation must be an object and user_text a string' unless body[:shared_conversation].is_a?(Hash) && body[:user_text].is_a?(String)
+          out[:shared_conversation] = body[:shared_conversation]
+          out[:user_text] = body[:user_text]
+        end
         (origin = Insika::MessageOrigin.parse!(body[:origin])) && (out[:origin] = origin)
+        # the caller's text that rides ahead of `input` to the model; guardrails read `input` alone
+        unless body[:context].nil? || body[:context].is_a?(String)
+          raise Insika::ValidationError, "context must be a string"
+        end
+        out[:context] = body[:context] if body[:context]
         # WS8: the optional customer_key — per-customer memory scope + purge handle
         (customer = Insika::Coercion.presence(body[:customer])) && (out[:customer] = customer)
+        # the optional labels the Studio shows and searches the conversation by
+        Insika::SessionStore::CUSTOMER_LABELS.each do |key|
+          out[key.to_sym] = body[key.to_sym] if body[key.to_sym].is_a?(String)
+        end
         # WS9: the multimodal OPENAI shape — `input` as an array of content parts
         # ({type: text/image/audio}) is preserved additively alongside the
         # joined text; a string input stays byte-identical to before. The
@@ -95,7 +109,7 @@ module Insika
       end
 
       # Turn Event -> OpenAI Responses SSE frame | nil (event with no
-      # counterpart: :task_started, :tool_result, :skill_activated, ...).
+      # counterpart: :task_started, :skill_activated, ...).
       # Terminal events emit the final frame + `[DONE]` (close the stream).
       def frame_for(event)
         case event.type
@@ -103,9 +117,27 @@ module Insika
           sse("response.output_text.delta",
               { type: "response.output_text.delta", delta: event.data[:delta].to_s })
         when :tool_call
-          sse("response.output_item.added",
-              { type: "response.output_item.added",
-                item: { type: "function_call", name: event.data[:name].to_s } })
+          item = { type: "function_call", name: event.data[:name].to_s }
+          # The provider's call id, as the OpenAI item carries it: `added` and `done`
+          # are TWO frames of ONE call, and a consumer pairs them by this. Absent when
+          # the emitter had none.
+          (id = event.data[:call_id]) && (item[:call_id] = id.to_s)
+          # The call's arguments, as the OpenAI item carries them (a JSON string).
+          # Absent when the emitter had none to report.
+          (args = event.data[:arguments]) && (item[:arguments] = args.is_a?(String) ? args : JSON.generate(args))
+          sse("response.output_item.added", { type: "response.output_item.added", item: item })
+        when :tool_result
+          # How the call ENDED — ok / error / blocked (+ the gate that held it). Until
+          # this frame the stream carried tool NAMES only, so nothing outside the
+          # process could tell "the tool ran" from "a gate refused it" or "it errored".
+          # The result body itself stays inside: it is the model's input, not the
+          # consumer's answer. Same `call_id` as the `added` frame — a consumer that
+          # counts calls counts `added`, not both.
+          item = { type: "function_call", name: event.data[:name].to_s,
+                   status: (event.data[:status] || "ok").to_s }
+          (id = event.data[:call_id]) && (item[:call_id] = id.to_s)
+          (gate = event.data[:gate]) && (item[:gate] = gate.to_s)
+          sse("response.output_item.done", { type: "response.output_item.done", item: item })
         when :task_completed
           completed(event) + done
         when :task_failed
@@ -149,6 +181,15 @@ module Insika
           # Studio + the trace. Explicit (not a fall-through) to keep the closed
           # catalog honest.
           nil
+        when :ui
+          # A presentation tool's selection: what the customer should SEE alongside
+          # the answer. Namespaced like `insika.intermediate` — no OpenAI Responses
+          # counterpart, unknown to strict clients, safely ignored. `items` are the
+          # cards the engine validated and joined (id/url/caption); `dropped` is what
+          # the model asked for and could not be shown, with the reason.
+          sse("insika.ui", { type: "insika.ui", component: event.data[:component].to_s,
+                             title: event.data[:title], items: Array(event.data[:items]),
+                             count: event.data[:count].to_i, dropped: Array(event.data[:dropped]) })
         when :ttft
           # the live TTFB signal (WS6, INSIKA_TURN_TIMING opt-in): the provider's
           # ms-to-first-token, emitted when the first content chunk arrives.
@@ -170,7 +211,11 @@ module Insika
           # `model` travels alongside usage in the event; in the OpenAI shape it is a sibling of
           # usage (pure tokens in usage).
           model = usage[:model] || usage["model"]
-          response[:usage] = usage.reject { |k, _| k.to_s == "model" }
+          projected = usage.transform_keys(&:to_sym).reject { |k, _| k == :model }
+          cache = projected[:cached_tokens].to_i + projected[:cache_creation_tokens].to_i
+          projected[:input_tokens] += cache if projected[:input_tokens]
+          projected[:total_tokens] += cache if projected[:total_tokens]
+          response[:usage] = projected
           response[:model] = model if model
         end
         # Opt-in per-turn latency breakdown (INSIKA_TURN_TIMING). Absent

data/lib/insika/session_actor.rb

@@ -23,28 +23,47 @@ module Insika
   # 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)
+    # `on_idle` is called with the actor once its queue drains and the loop ends, so
+    # the owner can drop it: an idle session holds no fiber.
+    def initialize(session_id:, executor:, parent: Async::Task.current, on_idle: nil)
       @session_id = session_id
       @executor = executor
+      @on_idle = on_idle
       @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
+      # The turns sitting at the door: created and :queued, but not yet released to
+      # run — whether waiting out a debounce window or simply queued behind the turn
+      # in flight. `collect` merges into the LAST one (the turn that has not
+      # answered yet; appending to an older one would put a newer fragment in an
+      # older message). Keyed by task so a turn released from the FIFO still finds
+      # its OWN count — with a single slot, a second turn enqueued behind the first
+      # would take the first's fragments with it. Empty is the common case and the
+      # safe default: a policy that does not merge never opens one.
+      @doors = {}
       @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.
+    # `policy` (a QueuePolicy) decides the door: a merging mode (`collect`/`steer`)
+    # opens it here, and a `debounce_ms` on top of that also holds the turn once it
+    # reaches the front. A nil policy or `followup` behaves exactly as before —
+    # nothing to merge into, dequeued and run at once.
     #
     # `timing`  is the channel clock a channel turn allocated at 202
     # acceptance and already stamped `:inbound`; it rides the queue so the debounce
     # window and the FIFO wait land INSIDE first_balloon_ms.
     def enqueue(task, profile:, resume_from: nil, policy: nil, timing: nil)
+      # The door opens HERE, not when the turn is dequeued. "Created and not yet
+      # started" lasts as long as the turn IN FRONT takes, and that whole wait is
+      # mergeable: the turn has not spoken, so a fragment appended to it costs
+      # nothing and saves an answer. Opening the door only for a debounce window
+      # (where it used to live) left every message that arrived while a turn sat in
+      # the FIFO with nothing to join — it became a turn of its own behind two
+      # others, and a `stream=false` caller then waited for BOTH to run before it
+      # heard anything. A window is now what EXTENDS the door, never what creates it.
+      @doors[task.id] = open_door(task) if policy&.collect?
       @queue.enqueue([task, profile, resume_from, policy, timing])
       task.id
     end
@@ -58,7 +77,7 @@ module Insika
     # 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
+      pending = @doors.values.last
       return nil if pending.nil?
 
       @executor.task_store.append_message(pending[:task_id], text)
@@ -88,15 +107,15 @@ module Insika
     # 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 there a turn at the door that `collect` could still merge into? True from
+    # the moment a merging policy enqueues one until it starts running.
+    def collecting? = !@doors.empty?
 
     # 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).
+    # Shuts down the loop (server shutdown / tests).
     def stop = @loop&.stop
 
     private
@@ -118,45 +137,56 @@ module Insika
           @running = false
           @current_task = nil
         end
+        # Ends with the last queued turn. A parked fiber per session ever seen grew a
+        # worker without bound; the next message starts a fresh actor. No yield sits
+        # between this check and the loop's end, so an enqueue cannot slip in.
+        break if @queue.empty?
       end
+      @on_idle&.call(self)
+      nil # the finished task must not hold the actor (see TaskActor#run)
     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).
+    # Closes the turn's door and reports what it caught. The debounce
+    # window (when the policy has one) is the EXTRA wait held here, on the LOOP's
+    # fiber and 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 = @doors[task.id]
+      return task if pending.nil?
 
-      @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]
+        wait_for_quiet(policy, pending) if policy&.debounce?
+        merged = pending[:count]
       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
+        # The door closes BEFORE the turn runs, under every exit path: a `collect`
+        # that slipped in here would append to a task about to be read.
+        @doors.delete(task.id)
       end
 
       return task if merged == 1
 
-      @executor.emit_coalesced(task, merged: merged, arrivals: arrivals)
+      @executor.emit_coalesced(task, merged: merged, arrivals: pending[:arrivals])
       @executor.task_store.find(task.id) || task
     end
 
+    def open_door(task)
+      { task_id: task.id, count: 1, version: 0, arrivals: [Time.now.utc.iso8601] }
+    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)
+    def wait_for_quiet(policy, pending)
       quiet = policy.debounce_ms / 1000.0
       deadline = monotonic + (policy.debounce_max_ms / 1000.0)
 
       loop do
-        mark = @pending[:version]
+        mark = pending[:version]
         Async::Task.current.sleep(quiet)
-        break if @pending[:version] == mark # a full slice of silence
+        break if pending[:version] == mark # a full slice of silence
         break if monotonic >= deadline
       end
     end

data/lib/insika/session_store.rb

@@ -20,7 +20,20 @@ module Insika
     include Coercion
 
     SCOPE = "sessions"
+    STATS_SCOPE = "session_stats" # one small record per session, see #write
+    # Optional Strings a caller sends to label a conversation in the Studio
+    # (shown and searched there; no effect on memory scope).
+    CUSTOMER_LABELS = %w[customer_name customer_phone].freeze
     KEY_PREFIX = "session:"
+    # Simulator (`sim-<chat>`) and eval (`eval-<id>`) sessions are synthetic
+    # traffic: nothing learns from them
+    # (knowledge extraction, harvest). A tenant-scoped id ("<tenant>:sim-…")
+    # is judged by its last segment.
+    SYNTHETIC_PREFIXES = %w[sim- eval-].freeze
+
+    def self.synthetic?(session_id)
+      session_id.to_s.split(":").last.to_s.start_with?(*SYNTHETIC_PREFIXES)
+    end
 
     Session = Data.define(:id, :messages, :vars, :memory_refs,
                           :created_at, :updated_at, :briefing, :evidence, :compaction) do
@@ -56,7 +69,7 @@ module Insika
         "created_at" => now,
         "updated_at" => now
       }
-      @store.set(SCOPE, key, record)
+      write(record)
       to_session(record)
     end
 
@@ -78,13 +91,18 @@ module Insika
     # 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)
+    # `agent:` names the session's agent when it has none yet (a turn with no
+    # customer never stamped one), riding this write instead of one of its own.
+    def append_messages(id, messages, agent: nil)
       record = fetch!(id)
       incoming = (messages.is_a?(Hash) ? [messages] : Array(messages))
                  .map { |msg| stamp(deep_stringify(msg)) }
       record["messages"] += incoming
+      if agent && Coercion.presence((record["vars"] ||= {})["agent"]).nil?
+        record["vars"]["agent"] = agent.to_s
+      end
       record["updated_at"] = timestamp
-      @store.set(SCOPE, key_for(id), record)
+      write(record)
       to_session(record)
     end
 
@@ -94,21 +112,24 @@ module Insika
       record = fetch!(id)
       record["vars"] = record["vars"].merge(deep_stringify(vars))
       record["updated_at"] = timestamp
-      @store.set(SCOPE, key_for(id), record)
+      write(record)
       to_session(record)
     end
 
     # appends this turn's evidence (ids + ungrounded delta) to the
     # session record. RMW like append_messages — the SessionActor serializes
     # same-session turns; the copy is in the method comment.
-    def append_evidence(id, ids:, ungrounded:)
+    def append_evidence(id, ids:, ungrounded:, cards: [])
       record = fetch!(id)
       ev = record["evidence"] ||= { "ids" => [], "ungrounded" => 0 }
       fresh = (ev["ids"] + Array(ids).map(&:to_s).reject(&:empty?)).uniq.last(EvidenceLedger::MAX_IDS)
       ev["ids"] = fresh
       ev["ungrounded"] = ev["ungrounded"].to_i + ungrounded.to_i
+      # the cards those ids came with (one per id, newest wins) — what a
+      # presentation tool joins on in a LATER turn. Absent until a card arrives.
+      ev["cards"] = EvidenceLedger.merge_cards(ev["cards"], cards) unless Array(cards).empty?
       record["updated_at"] = timestamp
-      @store.set(SCOPE, key_for(id), record)
+      write(record)
       to_session(record)
     end
 
@@ -135,7 +156,7 @@ module Insika
       value = Coercion.presence(Coercion.utf8(value.to_s))
       value ? briefing["fields"][field.to_s] = value : briefing["fields"].delete(field.to_s)
       record["updated_at"] = timestamp
-      @store.set(SCOPE, key_for(id), record)
+      write(record)
       to_session(record)
     end
 
@@ -146,7 +167,7 @@ module Insika
       briefing = record["briefing"] ||= { "fields" => {}, "next_step" => nil }
       briefing["next_step"] = Coercion.presence(Coercion.utf8(text.to_s))
       record["updated_at"] = timestamp
-      @store.set(SCOPE, key_for(id), record)
+      write(record)
       to_session(record)
     end
 
@@ -161,31 +182,130 @@ module Insika
     # read/mutate/set path suspends, so no other writer can interleave
     # mid-RMW. The LLM call that produced the summary happened BEFORE this
     # method; only the plain write lives here.
-    def set_compaction(id, summary:, upto:, model: nil)
+    def set_compaction(id, summary: nil, upto:, model: nil, native: nil)
       record = fetch!(id)
       current = record["compaction"]
       upto = Integer(upto)
       return to_session(record) if current && upto <= current["upto"].to_i
 
       record["compaction"] = {
-        "summary" => Coercion.utf8(summary.to_s),
+        "summary" => native ? nil : Coercion.utf8(summary.to_s),
+        "native" => native && Coercion.deep_stringify(native),
         "upto" => upto,
         "runs" => (current ? current["runs"].to_i : 0) + 1,
         "model" => Coercion.presence(model.to_s),
         "at" => timestamp
       }.compact
       record["updated_at"] = timestamp
-      @store.set(SCOPE, key_for(id), record)
+      write(record)
+      to_session(record)
+    end
+
+    # -> Session. A person's verdict on one guardrail flag:
+    # messages[message]["guardrail_flags"][flag]["review"] = { status, at }.
+    # status "reported" (a false positive to fix in the corpus) or "resolved";
+    # nil clears it. updated_at is left alone — a review is not conversation
+    # activity. NotFoundError for an unknown session, message or flag.
+    REVIEW_STATUSES = %w[reported resolved].freeze
+
+    def review_guardrail_flag(id, message:, flag:, status:)
+      record = fetch!(id)
+      message = Integer(message)
+      flag = Integer(flag)
+      # a negative index would count from the end: a different flag
+      target = Array(record["messages"])[message] unless message.negative?
+      flags = target.is_a?(Hash) ? Array(target["guardrail_flags"]) : []
+      entry = flags[flag] unless flag.negative?
+      raise Insika::NotFoundError, "guardrail flag not found: #{id} #{message}/#{flag}" unless entry.is_a?(Hash)
+
+      if status.nil?
+        entry.delete("review")
+      else
+        raise Insika::ValidationError, "unknown review status: #{status}" unless REVIEW_STATUSES.include?(status.to_s)
+
+        entry["review"] = { "status" => status.to_s, "at" => timestamp }
+      end
+      write(record, amend: true)
       to_session(record)
     end
 
     # -> bool (delegates to the backend: false for a nonexistent id)
     def delete(id)
+      @store.delete(STATS_SCOPE, key_for(id))
       @store.delete(SCOPE, key_for(id))
     end
 
     # -> enumerates ids without the "session:" prefix. Without a block,
     # returns an Enumerator.
+    # -> [Session] every record, from ONE bulk read of the backend (see
+    # Store#entries) instead of a read per id.
+    def all
+      @store.entries(SCOPE, KEY_PREFIX).map { |_, record| to_session(record) }
+    end
+
+    # -> [Session] the `limit` most recently written sessions, newest first, from
+    # one read (Store#recent) instead of reading every session to sort them.
+    # `offset` skips that many of the newest (the next page).
+    def recent(limit, offset: 0)
+      # offset only when paging: a backend written for the 3-argument #recent keeps working
+      rows = offset.zero? ? @store.recent(SCOPE, KEY_PREFIX, limit) : @store.recent(SCOPE, KEY_PREFIX, limit, offset)
+      rows.map { |_, record| to_session(record) }
+    end
+
+    # -> Integer sessions stored, from the keys alone (no record is read).
+    def count = @store.list(SCOPE, KEY_PREFIX).size
+
+    # What a dashboard needs of a session without its messages: a few bytes per
+    # session, written with it, instead of the whole record (messages included).
+    # last_role: who spoke last ("user" = the customer is waiting); nil on stats
+    # written before it existed, until the session's next write.
+    # flagged: messages carrying a guardrail flag nobody resolved (a resolved
+    # flag stays on the message as history); reported: flags a person
+    # marked as a false positive and nobody resolved yet. Both 0 on stats
+    # written before they existed, until the session's next write.
+    # reported_at: the newest of those reports.
+    Stat = Data.define(:id, :updated_at, :message_count, :vars, :last_role, :flagged, :reported, :reported_at) do
+      def initialize(id:, updated_at:, message_count:, vars:, last_role: nil, flagged: 0, reported: 0, reported_at: nil) = super
+    end
+
+    # -> [Stat] every session's stats, in no particular order: small enough to read
+    # whole, so a reader never depends on the order they were written in.
+    def all_stats
+      @store.entries(STATS_SCOPE, KEY_PREFIX).map { |key, stat| to_stat(key, stat) }
+    end
+
+    # Bumped when stats gain a field (2: flagged/reported; 3: flagged skips
+    # resolved flags), so backfill_stats rewrites the older ones instead of
+    # only filling the missing.
+    STATS_VERSION = 3
+
+    # A guardrail flag still marks its conversation until a person resolves it.
+    def self.open_flag?(flag) = !(flag.is_a?(Hash) && flag.dig("review", "status") == "resolved")
+
+    # Writes the stats of every session that has none or older ones (sessions
+    # stored before a field existed) and deletes stats whose session is gone.
+    # Idempotent and safe with the app running: each batch re-reads inside a
+    # transaction, skipping a session that wrote its own stats meanwhile or was
+    # deleted. -> stats written.
+    def backfill_stats(batch: 500)
+      have = @store.entries(STATS_SCOPE, KEY_PREFIX).filter_map { |key, stat| key if current_stat?(stat) }.to_set
+      written = 0
+      @store.list(SCOPE, KEY_PREFIX).reject { |key| have.include?(key) }.each_slice(batch) do |keys|
+        @store.transaction do
+          keys.each do |key|
+            next if current_stat?(@store.get(STATS_SCOPE, key))
+
+            record = @store.get(SCOPE, key) or next
+            @store.set(STATS_SCOPE, key, stats_of(record))
+            written += 1
+          end
+        end
+      end
+      live = @store.list(SCOPE, KEY_PREFIX).to_set
+      @store.list(STATS_SCOPE, KEY_PREFIX).each { |key| @store.delete(STATS_SCOPE, key) unless live.include?(key) }
+      written
+    end
+
     def each_id
       return enum_for(:each_id) unless block_given?
 
@@ -196,6 +316,38 @@ module Insika
 
     private
 
+    # The one write of a session record: the record and its stats, side by side.
+    # amend: an edit that is not activity keeps the session's place in #recent.
+    def write(record, amend: false)
+      key = key_for(record["id"])
+      amend ? @store.amend(SCOPE, key, record) : @store.set(SCOPE, key, record)
+      @store.set(STATS_SCOPE, key, stats_of(record))
+    end
+
+    def current_stat?(stat) = stat.is_a?(Hash) && stat["v"].to_i >= STATS_VERSION
+
+    def stats_of(record)
+      messages = Array(record["messages"])
+      last = messages.last
+      vars = record["vars"] || {}
+      flags = messages.map { |m| m.is_a?(Hash) ? Array(m["guardrail_flags"]) : [] }
+      flagged = flags.count { |fs| fs.any? { self.class.open_flag?(_1) } }
+      reported = flags.flatten.select { |f| f.is_a?(Hash) && f.dig("review", "status") == "reported" }
+      { "v" => STATS_VERSION, "updated_at" => record["updated_at"], "message_count" => messages.size,
+        "agent" => vars["agent"], "customer" => vars["customer"],
+        "last_role" => last.is_a?(Hash) ? last["role"] : nil, "flagged" => (flagged if flagged.positive?),
+        "reported" => (reported.size if reported.any?), "reported_at" => reported.filter_map { |f| f.dig("review", "at") }.max,
+        **vars.slice(*CUSTOMER_LABELS) }.compact
+    end
+
+    def to_stat(key, stat)
+      Stat.new(id: key.delete_prefix(KEY_PREFIX), updated_at: stat["updated_at"],
+               message_count: stat["message_count"].to_i,
+               vars: stat.slice("agent", "customer", *CUSTOMER_LABELS),
+               last_role: stat["last_role"], flagged: stat["flagged"].to_i, reported: stat["reported"].to_i,
+               reported_at: stat["reported_at"])
+    end
+
     def key_for(id)
       "#{KEY_PREFIX}#{id}"
     end