insika 0.2.0 → 0.7.0

data/lib/insika/commands/delete_tenant_data.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command (WS8, phase 2 — LGPD): purges everything the engine holds
+    # about ONE TENANT — its sessions (the "<tenant>:" namespace) and everything
+    # those sessions left behind (traces, tasks, checkpoints, outbox deliveries
+    # — see SessionPurge), every memory cell under the tenant (its own + the
+    # customer cells), its outcome records (WS7) and its API CREDENTIALS (every
+    # active token of the tenant is revoked first — an offboarded tenant must
+    # not authenticate). The tenant string IS the
+    # isolation boundary, so zeroing it cannot touch another tenant's data.
+    # Operator-only BY CONSTRUCTION: the generic command ingress is
+    # operator-grade (a tenant principal never reaches it).
+    class DeleteTenantData
+      include SessionPurge
+
+      def initialize(memory_store:, session_store:, tool_trace_store: nil,
+                     context_trace_store: nil, model_visible_trace_store: nil,
+                     outcome_store: nil, task_store: nil,
+                     checkpoint_store: nil, outbox_store: nil, shadow_pairs: nil,
+                      token_store: nil, funnel_store: nil, event_stream:,
+                     followup_store: nil, contact_store: nil, proposal_store: nil,
+                     harvest_store: nil, schedule_store: nil, artifact_store: nil)
+        @memory_store = memory_store
+        @token_store = token_store
+        @session_store = session_store
+        @tool_trace_store = tool_trace_store
+        @context_trace_store = context_trace_store
+        @model_visible_trace_store = model_visible_trace_store #  ; nil = parity
+        @outcome_store = outcome_store
+        @task_store = task_store
+        @checkpoint_store = checkpoint_store
+        @outbox_store = outbox_store
+        @shadow_pairs = shadow_pairs
+        @funnel_store = funnel_store #  ; nil = nothing to sweep
+        @followup_store = followup_store #  ; nil = nothing to sweep
+        @contact_store = contact_store   #  ; nil = nothing to sweep
+        @proposal_store = proposal_store #  ; nil = nothing to sweep
+        @harvest_store = harvest_store   #  ; nil = nothing to sweep
+        @schedule_store = schedule_store #  ; nil = nothing to sweep
+        @artifact_store = artifact_store #  ; nil = nothing to sweep
+        @event_stream = event_stream
+      end
+
+      # -> { tenant:, sessions:, memory_records:, outcomes:, tokens_revoked:,
+      #      tasks:, checkpoints:, deliveries:, followups:, contacts: }.
+      def call(command)
+        tenant = Coercion.presence(command.payload[:tenant] || command.payload["tenant"])
+        raise ValidationError, "tenant is required" if tenant.nil?
+
+        # CREDENTIALS FIRST (WS1+WS8): erasing the data while the tenant's
+        # tokens still resolve leaves an offboarded tenant authenticating and
+        # opening a NEW session — the purge would report success over a live
+        # customer. Revoking before the sweep closes the door, so nothing the
+        # tenant does mid-purge survives it. nil store = single_tenant mode
+        # (no per-tenant credential exists).
+        tokens_revoked = @token_store ? @token_store.revoke_all(tenant_id: tenant) : 0
+
+        sessions = @session_store.each_id.select { |id| id.to_s.start_with?("#{tenant}:") }
+        purged = purge_sessions(sessions)
+
+        memory_records = @memory_store.purge_tenant(tenant)
+        outcomes = @outcome_store ? @outcome_store.purge(tenant: tenant) : 0
+        funnel = @funnel_store ? @funnel_store.purge(tenant: tenant) : 0
+        # the follow-up footprint dies with the tenant — records
+        # and contact cells under the same tenant prefix.
+        followups = @followup_store ? @followup_store.purge(tenant: tenant) : 0
+        contacts = @contact_store ? @contact_store.purge(tenant: tenant) : 0
+        # the distilled proposals die with the tenant.
+        proposals = @proposal_store ? @proposal_store.purge(tenant: tenant) : 0
+        # candidates reference sessions, and sessions carry the
+        # tenant prefix — the harvest rows die with the tenant (D11).
+        harvest = @harvest_store ? @harvest_store.purge(tenant: tenant) : 0
+        # recurring-schedule rows die with the tenant too (their
+        # message text is content, never kept behind an offboarded tenant).
+        schedules = @schedule_store ? @schedule_store.purge(tenant: tenant) : 0
+        # artifacts die with the tenant — a report is content, and the
+        # tenant binding is the isolation boundary (never a model-typed id).
+        artifacts = @artifact_store ? @artifact_store.purge(tenant: tenant) : 0
+
+        @event_stream.emit(Insika::Event.new(
+                             type: :tenant_data_deleted,
+                             data: { tenant: tenant, sessions: sessions,
+                                     memory_records: memory_records,
+                                     outcomes: outcomes,
+                                     funnel: funnel,
+                                     followups: followups,
+                                     contacts: contacts,
+                                     proposals: proposals,
+                                     harvest: harvest,
+                                     schedules: schedules,
+                                     artifacts: artifacts,
+                                     tokens_revoked: tokens_revoked }.merge(purged),
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+        { tenant: tenant, sessions: sessions, memory_records: memory_records,
+          outcomes: outcomes, funnel: funnel, followups: followups, contacts: contacts,
+          proposals: proposals, harvest: harvest, schedules: schedules,
+          artifacts: artifacts,
+          tokens_revoked: tokens_revoked }.merge(purged)
+      end
+    end
+  end
+end

data/lib/insika/commands/export_customer_memory.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command  the LGPD access right): exports what the
+    # engine holds about ONE customer — their memory cell's facts + notes,
+    # expired facts excluded. The FULL content is the RETURN VALUE (the Studio
+    # turns it into a JSON download); the emitted event carries counts only, so
+    # the event stream, the audit store and every log stay content-free (D7).
+    # The return value never enters a store, an event or a log.
+    class ExportCustomerMemory
+      def initialize(memory_store:, event_stream:)
+        @memory_store = memory_store
+        @event_stream = event_stream
+      end
+
+      # payload: { customer: (REQUIRED), tenant: } — customer from the payload
+      # (an operator names the person); tenant from the payload || meta.
+      # -> { "customer" =>, "tenant" =>, "exported_at" =>, "facts" => [Fact#to_h],
+      #      "notes" => [Note#to_h], "counts" => { "facts" =>, "notes" => } }
+      def call(command)
+        p = AgentPayload.symbolize(command.payload)
+        customer = AgentPayload.presence(p[:customer])
+        raise Insika::ValidationError, "customer is required" if customer.nil?
+
+        tenant = AgentPayload.presence(p[:tenant]) || command.meta[:tenant]
+        facts = @memory_store.facts(tenant: tenant, customer: customer)
+        notes = @memory_store.notes(tenant: tenant, customer: customer)
+        exported_at = Time.now.utc.iso8601
+
+        @event_stream.emit(Insika::Event.new(
+                             type: :customer_memory_exported,
+                             data: { customer: customer, tenant: tenant,
+                                     counts: { facts: facts.size, notes: notes.size } },
+                             meta: { at: exported_at }
+                           ))
+        {
+          "customer" => customer, "tenant" => tenant, "exported_at" => exported_at,
+          "facts" => facts.map { |f| Coercion.deep_stringify(f.to_h) },
+          "notes" => notes.map { |n| Coercion.deep_stringify(n.to_h) },
+          "counts" => { "facts" => facts.size, "notes" => notes.size }
+        }
+      end
+    end
+  end
+end

data/lib/insika/commands/forget_customer.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command (WS8, phase 2 — LGPD): purges what the engine holds about
+    # ONE customer — the customer's memory cell, their sessions (found through
+    # the `customer` var the Executor stamps on a tagged conversation) and
+    # everything those sessions left behind (traces, tasks, checkpoints, outbox
+    # deliveries — see SessionPurge). The scope string IS the isolation
+    # boundary, so zeroing it cannot touch another customer's or another
+    # tenant's data. Operator-only BY CONSTRUCTION: the generic command ingress
+    # is operator-grade (a tenant principal never reaches it).
+    #
+    # WHICH TENANT is the whole correctness of the purge: the memory cell is
+    # "memory:<tenant>:<customer>" and the sessions are the "<tenant>:" ones. It
+    # is read from the command meta (an internal caller acting AS a tenant) or
+    # from the payload (`{ customer:, tenant: }` — the operator naming it over
+    # HTTP, where the principal has no tenant of its own). Absent from both, the
+    # purge is deployment-wide: the untagged memory cell plus that customer's
+    # sessions in EVERY tenant — right for a single-tenant deployment, and never
+    # what a multi-tenant operator means, so they must name the tenant.
+    class ForgetCustomer
+      include SessionPurge
+
+      def initialize(memory_store:, session_store:, tool_trace_store: nil,
+                     context_trace_store: nil, model_visible_trace_store: nil,
+                     task_store: nil, checkpoint_store: nil,
+                     outbox_store: nil, shadow_pairs: nil, audit_store: nil, event_stream:,
+                     followup_store: nil, contact_store: nil, proposal_store: nil)
+        @memory_store = memory_store
+        @session_store = session_store
+        @tool_trace_store = tool_trace_store
+        @context_trace_store = context_trace_store
+        @model_visible_trace_store = model_visible_trace_store #  ; nil = parity
+        @task_store = task_store
+        @checkpoint_store = checkpoint_store
+        @outbox_store = outbox_store
+        @shadow_pairs = shadow_pairs
+        @audit_store = audit_store
+        @event_stream = event_stream
+        @followup_store = followup_store #  ; nil = nothing to sweep
+        @contact_store = contact_store   #  ; nil = nothing to sweep
+        @proposal_store = proposal_store #  ; nil = nothing to sweep
+      end
+
+      # -> { customer:, tenant:, memory_records:, sessions: [], tasks:,
+      #      checkpoints:, deliveries:, followups:, contacts: }.
+      def call(command)
+        customer = Coercion.presence(command.payload[:customer] || command.payload["customer"])
+        raise ValidationError, "customer is required" if customer.nil?
+
+        tenant = command.meta[:tenant] ||
+                 Coercion.presence(command.payload[:tenant] || command.payload["tenant"])
+        memory_scope = [tenant, customer].compact.join(":")
+        memory_records = @memory_store.purge(tenant: memory_scope)
+
+        # the follow-up footprint dies with the person — the
+        # schedule records and the contact cell (LGPD).
+        followups = @followup_store&.purge_customer(tenant: tenant, customer: customer) || 0
+        contacts = @contact_store&.delete(tenant: tenant, customer: customer) ? 1 : 0
+
+        # the distilled PROPOSALS die with the person — a proposal
+        # is born inside a customer cell (D6), so forget_customer reaches it.
+        proposals = @proposal_store&.purge_customer(tenant: tenant, customer: customer) || 0
+
+        sessions = session_ids_for(customer, tenant)
+        purged = purge_sessions(sessions)
+
+        # the audit records the thing that happened, content-free —
+        # a digest-free line with the counts (the deleted VALUES never enter
+        # the audit store). Written AFTER the purge, so the line describes a
+        # deletion that actually happened. nil audit_store = no-op.
+        @audit_store&.record(
+          cell: @memory_store.cell_for(tenant, customer),
+          action: "purge", actor: operator(command), tenant: tenant, customer: customer,
+          note: "memory_records: #{memory_records}, sessions: #{sessions.size}"
+        )
+
+        @event_stream.emit(Insika::Event.new(
+                             type: :customer_forgotten,
+                             data: { customer: customer, tenant: tenant,
+                                     memory_records: memory_records,
+                                     sessions: sessions,
+                                     followups: followups,
+                                     contacts: contacts,
+                                     proposals: proposals }.merge(purged),
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+        { customer: customer, tenant: tenant, memory_records: memory_records,
+          sessions: sessions, followups: followups, contacts: contacts,
+          proposals: proposals }.merge(purged)
+      end
+
+      private
+
+      def operator(command)
+        Coercion.presence(command.payload[:operator] || command.payload["operator"]) || "operator"
+      end
+
+      # The customer's sessions: the ones the Executor stamped with this
+      # customer var — plus, in multi_tenant, only ids inside the tenant's
+      # "<tenant>:" namespace (single_tenant sessions carry no prefix).
+      def session_ids_for(customer, tenant)
+        @session_store.each_id.each_with_object([]) do |id, acc|
+          session = @session_store.find(id)
+          next unless session
+          next unless Coercion.presence(session.vars["customer"]).to_s == customer.to_s
+          next if tenant && !id.to_s.start_with?("#{tenant}:")
+
+          acc << id.to_s
+        end
+      end
+    end
+  end
+end

data/lib/insika/commands/freeze_funnel_baseline.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "time"
+require "date"
+
+module Insika
+  module Commands
+    # the operator's FREEZE — turn the folded counts over a
+    # declared span into the baseline snapshot (A/B follow-up) and
+    # (promotion gate) read. One command, dispatched from the Studio
+    # and available to any operator-grade caller. Synchronous control command —
+    # no task, no actor, same discipline as RecordOutcome (WS7).
+    #
+    # The ≥ 4-week rule ("no 1.0 target before a remeasure") is
+    # enforced HERE, not by convention: a frozen span shorter than 28 days is a
+    # ValidationError. `frozen_at` stamps when; the baseline OVERWRITES (D5) —
+    # the freeze event is the audit surface.
+    class FreezeFunnelBaseline
+      MIN_SPAN_DAYS = 28
+
+      def initialize(funnel_store:, profiles:, event_stream:)
+        @funnel_store = funnel_store
+        @profiles = profiles
+        @event_stream = event_stream
+      end
+
+      # payload: { agent:, tenant:, from: "YYYY-MM-DD", to: "YYYY-MM-DD", operator: }
+      #   agent REQUIRED (ValidationError); tenant from payload || meta[:tenant].
+      #   from/to optional — default to the pair's folded span (first/last day
+      #   cell); explicit from/to are inclusive bounds.
+      # -> the baseline record.
+      def call(command)
+        payload = command.payload
+        agent = Coercion.presence(payload[:agent] || payload["agent"])
+        raise ValidationError, "agent is required" if agent.nil?
+
+        declaration = declaration_for(agent)
+        tenant = payload[:tenant] || payload["tenant"] || command.meta[:tenant]
+
+        from, to = bounds(payload, tenant, agent)
+        validate_span!(from, to)
+
+        stages = @funnel_store.days(tenant: tenant, agent: agent, from: from, to: to)
+                              .each_with_object(Hash.new(0)) do |(_, counts), acc|
+          counts.each { |stage, n| acc[stage] += n }
+        end
+        primary = declaration.primary
+        primary_count = stages[primary].to_i
+        first_count = stages[declaration.first_stage].to_i
+        conversion = first_count.zero? ? nil : primary_count.to_f / first_count
+
+        baseline = {
+          "from" => from, "to" => to, "stages" => stages,
+          "primary" => primary, "primary_count" => primary_count,
+          "conversion" => conversion, "window" => declaration.attribution_window,
+          "frozen_at" => Time.now.utc.iso8601
+        }
+        @funnel_store.set_baseline(tenant: tenant, agent: agent, record: baseline)
+
+        @event_stream.emit(Insika::Event.new(
+                             type: :funnel_baseline_frozen,
+                             data: { agent: agent, from: from, to: to,
+                                     primary: primary, primary_count: primary_count,
+                                     conversion: conversion },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+        baseline
+      end
+
+      private
+
+      # -> FunnelDeclaration | raise — the freeze needs the parsed declaration,
+      # so a malformed/absent one is a hard ValidationError (D8: the FOLD skips
+      # malformed declarations, but freezing without one is an operator error).
+      def declaration_for(agent)
+        profile = @profiles.fetch(agent)
+        decl = profile && Insika::FunnelDeclaration.parse(profile.funnel)
+        return decl if decl
+
+        raise ValidationError, "agent '#{agent}' has no valid funnel declaration"
+      end
+
+      # Explicit from/to (inclusive) or the pair's folded span (first/last day
+      # cell). -> [String, String].
+      def bounds(payload, tenant, agent)
+        from = Coercion.presence(payload[:from] || payload["from"])
+        to = Coercion.presence(payload[:to] || payload["to"])
+        # both given -> no scan at all (a pair with no cells still freezes,
+        # over a zero-count span, when the operator names the dates)
+        return [from, to] if from && to
+
+        days = @funnel_store.days(tenant: tenant, agent: agent)
+        days_keys = days.keys
+        raise ValidationError, "no folded days for agent '#{agent}'" if days_keys.empty?
+
+        [from || days_keys.first, to || days_keys.last]
+      end
+
+      def validate_span!(from, to)
+        raise ValidationError, "from must be before to" if from >= to
+
+        span = (Date.iso8601(to) - Date.iso8601(from)).to_i
+        if span < MIN_SPAN_DAYS
+          raise ValidationError,
+                "baseline span must cover at least #{MIN_SPAN_DAYS} days " \
+                "(the number needs a remeasured baseline)"
+        end
+      rescue Date::Error
+        raise ValidationError, "from/to must be ISO dates (YYYY-MM-DD)"
+      end
+    end
+  end
+end

data/lib/insika/commands/gate_harvest.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    #   — the double gate on ONE candidate, in order:
+    # eval first (expensive — a full golden replay), conversion second (cheap
+    # — a fold read). Synchronous control command (the Studio dispatches it;
+    # the gate is minutes of real replay, exactly like `gate_refinement`).
+    # It records both reports on the candidate and moves it: both passed ->
+    # awaiting_approval; either failed -> rejected with the reason (a failed
+    # candidate is terminal — the same finding must re-surface with new
+    # evidence, no silent retry).
+    class GateHarvest
+      def initialize(harvest_store:, gate:, conversion_gate:, criterion: nil, event_stream:)
+        @harvest_store = harvest_store
+        @gate = gate
+        @conversion_gate = conversion_gate
+        @criterion = criterion
+        @event_stream = event_stream
+      end
+
+      # payload: { candidate_id: } (tenant from command.meta — WS1)
+      # -> Candidate (awaiting_approval | rejected | gated-parked; both
+      #    reports attached)
+      def call(command)
+        p = AgentPayload.symbolize(command.payload)
+        candidate_id = AgentPayload.presence(p[:candidate_id])
+        raise Insika::ValidationError, "candidate_id is required" if candidate_id.nil?
+
+        candidate = @harvest_store.find_candidate(candidate_id) ||
+                    (raise Insika::NotFoundError, "harvest candidate not found: #{candidate_id}")
+
+        # The base graph wires NO gates (the deployment owns the eval surface):
+        # the candidate parks at gated with the named reason — refuse-with-a-
+        # named-reason, never pass, never crash.
+        if @gate.nil? || @conversion_gate.nil?
+          parked = @harvest_store.attach_gate(
+            candidate.id,
+            eval_gate: { "passed" => false, "reason" => "no_eval_gate_wired" },
+            conversion_gate: { "passed" => false, "reason" => "no_conversion_gate_wired" },
+            criterion_sha: nil
+          )
+          return parked
+        end
+
+        # The mining budget is read HERE too (the review fix): once the mining
+        # pass spent the pack's cap, the expensive golden replay is refused
+        # with the named reason — the Refinement::Budget discipline ("not
+        # gated — the budget was spent"), applied before the provider bill.
+        run = @harvest_store.find_run(candidate.run_id)
+        cap = run && run.budget && run.budget["tokens"].to_i
+        spent = run && run.cost && run.cost["spent"].to_i
+        if cap&.positive? && spent.to_i >= cap
+          parked = @harvest_store.attach_gate(
+            candidate.id,
+            eval_gate: { "passed" => false, "reason" => "budget_exceeded",
+                         "spent" => spent, "tokens" => cap },
+            conversion_gate: { "passed" => false, "reason" => "budget_exceeded" },
+            criterion_sha: nil
+          )
+          return parked
+        end
+
+        skill = { "name" => candidate.name, "description" => candidate.description,
+                  "body" => candidate.body, "triggers" => candidate.triggers }
+        eval_report = @gate.score(agent_id: candidate.agent, skill: skill,
+                                  run_id: candidate.run_id)
+        conversion_report = @conversion_gate.call(tenant: command.meta[:tenant],
+                                                  agent: candidate.agent)
+        criterion_sha = @criterion ? @criterion.sha : nil
+
+        # A conversion REFUSAL (missing data — :no_frozen_baseline etc.) is NOT
+        # a candidate failure: it parks the candidate at gated with both
+        # reports and the named reason — the page shows the ruler's hole.
+        # Only a conversion FAILURE (current worse than baseline) rejects.
+        if refused?(conversion_report)
+          gated = @harvest_store.attach_gate(candidate.id,
+                                             eval_gate: eval_report.to_h,
+                                             conversion_gate: conversion_report.to_h,
+                                             criterion_sha: criterion_sha)
+          emit(:harvest_gated, candidate, gated, eval_report, conversion_report)
+          return gated
+        end
+
+        passed = eval_report.passed && conversion_report.passed
+        @harvest_store.attach_gate(candidate.id,
+                                   eval_gate: eval_report.to_h,
+                                   conversion_gate: conversion_report.to_h,
+                                   criterion_sha: criterion_sha)
+        result = if passed
+                   @harvest_store.mark_awaiting(candidate.id)
+                 else
+                   reason = eval_report.passed ? conversion_report.reason : eval_report.reason
+                   @harvest_store.mark_rejected(candidate.id, operator: "gate", note: reason)
+                 end
+        emit(:harvest_gated, candidate, result, eval_report, conversion_report)
+        result
+      end
+
+      private
+
+      # The D6 refusals: the ruler is MISSING, not moving — the candidate
+      # parks. Anything else with passed: false is a real failure.
+      def refused?(report)
+        !report.passed && REFUSAL_REASONS.include?(report.reason)
+      end
+
+      REFUSAL_REASONS = %i[no_criterion no_funnel no_frozen_baseline metric_mismatch no_fold
+                       baseline_span_short no_baseline_rate budget_exceeded].freeze
+
+      def emit(type, candidate, result, eval_report, conversion_report)
+        @event_stream.emit(Insika::Event.new(
+                             type: type,
+                             # ids and verdicts, never the skill body
+                             data: { run_id: candidate.run_id, candidate_id: candidate.id,
+                                     agent: candidate.agent,
+                                     eval_passed: eval_report.passed,
+                                     conversion_passed: conversion_report.passed,
+                                     reason: verdict_reason(result, eval_report, conversion_report) },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+      end
+
+      # The refusal/failure reason as an id the operator stream can act on —
+      # the symbol, not the human note.
+      def verdict_reason(result, eval_report, conversion_report)
+        return nil if result.status == "awaiting_approval"
+
+        return eval_report.reason unless eval_report.passed
+        return conversion_report.reason if conversion_report.reason
+
+        result.decision && result.decision["note"]
+      end
+    end
+  end
+end

data/lib/insika/commands/gate_refinement.rb

@@ -12,7 +12,7 @@ module Insika
     # Synchronous like `run_refinement`, and for the same reason: it is operator-paced
     # work with a human waiting on the answer. It is NOT cheap — the replay is a real
     # conversation per golden case — so it is fired deliberately, never on a timer
-    # (the engine has no scheduler and this RFC does not add one).
+    # (a recurring timer may schedule OTHER turns; this gate stays human-paced).
     #
     # Payload:
     #   run_id     (required) a run in :completed — the evidence the candidate answers

data/lib/insika/commands/judge_shadow_pairs.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # C7 — turn complete shadow pairs into judged pairs, using the judges the
+    # operator ALREADY configured (settings["evals"], through JudgePanel — the
+    # one builder the eval CLI and the refinement gate use too). Never automatic:
+    # a Studio button or the CLI dispatches it, and it states its cost
+    # (2 provider calls per judge per pair, both orders —   position-bias
+    # rule) before it runs.
+    #
+    # Refusals are visible, a fake judge is not: no configured judges, or fewer
+    # models than the criterion demands, is a ValidationError — an unjudged
+    # window reads :invalid, where a window judged by judges nobody chose reads
+    # as evidence.
+    class JudgeShadowPairs
+      DEFAULT_LIMIT = 50
+      DEFAULT_EXPIRE_HOURS = 24
+
+      def initialize(shadow_pairs:, settings_store:, criterion:, llm: nil, event_stream: nil)
+        @shadow_pairs = shadow_pairs
+        @settings_store = settings_store
+        @criterion = criterion
+        @llm = llm
+        @event_stream = event_stream
+      end
+
+      # payload: { limit: Integer = 50, agent: String|nil, expire_after_hours: Integer|nil }
+      # -> { judged:, skipped:, expired:, failed:, models: [..] }
+      def call(command)
+        payload = command.payload
+        limit = begin
+          Integer(payload[:limit] || payload["limit"] || DEFAULT_LIMIT)
+        rescue ArgumentError
+          raise ValidationError, "limit must be an integer"
+        end
+        agent = Coercion.presence(payload[:agent] || payload["agent"])
+        expire_hours = begin
+          Integer(payload[:expire_after_hours] || payload["expire_after_hours"] || DEFAULT_EXPIRE_HOURS)
+        rescue ArgumentError
+          raise ValidationError, "expire_after_hours must be an integer"
+        end
+
+        # Judges BEFORE the expire: a refusal (no judges, too few models) must
+        # leave every pair untouched — expiring first would stamp :incomplete on
+        # pairs and that is terminal evidence against a click that judged nothing.
+        panel = Insika::Evals::JudgePanel.pairwise(settings, llm: @llm)
+        raise ValidationError, "no judges configured in settings['evals'] — refusing to judge without judges" if panel.nil?
+
+        pairwise, models = panel
+        minimum = @criterion.rule.min_judge_models
+        distinct = models.uniq
+        if distinct.length < minimum
+          raise ValidationError, "the criterion requires at least #{minimum} distinct judge models; " \
+                                 "#{distinct.length} configured (#{distinct.join(', ')})"
+        end
+
+        # A mirror that dropped a half stops looking like pending work.
+        expired = @shadow_pairs.expire(older_than: Time.now.utc - (expire_hours * 3600))
+
+        judged = 0
+        failed = 0
+        @shadow_pairs.unjudged(limit: limit, agent: agent).each do |pair|
+          if judge_pair(pair, pairwise, models)
+            judged += 1
+          else
+            failed += 1
+          end
+        end
+        skipped = @shadow_pairs.unjudged(agent: agent).length
+
+        emit_summary(judged: judged, skipped: skipped, expired: expired, failed: failed, models: models)
+        { judged: judged, skipped: skipped, expired: expired, failed: failed, models: models }
+      end
+
+      private
+
+      def settings
+        (@settings_store.get || {})["evals"] || {}
+      end
+
+      # -> true when the pair was judged. A raising judge leaves the pair
+      # :complete (retryable on the next press) and never aborts the batch; an
+      # empty side is recorded :unknown — visible, never a preference. The rescue
+      # is broad on purpose: a provider outage raises the transport's own error
+      # class (RubyLLM::Error, an HTTP status as StandardError), NOT an
+      # Insika::Error — and one broken provider must not sink the rest of the
+      # batch against this method's own contract.
+      def judge_pair(pair, pairwise, models)
+        verdict = pairwise.compare_texts(
+          ours: Insika::Parity.transcript(pair.inbound, pair.insika_reply),
+          theirs: Insika::Parity.transcript(pair.inbound, pair.incumbent_reply)
+        )
+        verdict ||= Insika::Evals::Pairwise::Verdict.new(
+          outcome: "unknown", reason: "a side of the pair was empty", vs: "agent",
+          judges: [], order_dependent: false
+        )
+        blob = verdict.to_h.merge("judged_at" => Time.now.utc.iso8601, "models" => models)
+        @shadow_pairs.record_verdict(pair.id, verdict: blob)
+        @event_stream&.emit(Insika::Event.new(
+                              type: :shadow_judged,
+                              data: { pair_id: pair.id, agent: pair.agent, outcome: blob[:outcome] },
+                              meta: { at: Time.now.utc.iso8601 }
+                            ))
+        true
+      rescue StandardError
+        false
+      end
+
+      def emit_summary(judged:, skipped:, expired:, failed:, models:)
+        return unless @event_stream
+
+        @event_stream.emit(Insika::Event.new(
+                             type: :shadow_judge_batch,
+                             data: { judged: judged, skipped: skipped, expired: expired,
+                                     failed: failed, models: models },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+      end
+    end
+  end
+end