insika 0.1.0 → 0.3.0

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

@@ -4,21 +4,21 @@ require "time"
 
 module Insika
   module Commands
-    # Control command (RFC-0013 phase C): takes a CANDIDATE for a completed
+    # Control command: takes a CANDIDATE for a completed
     # refinement run, validates it against the agent's write allowlist, and scores it
     # by actually running it — clone the agent, apply the edits to the clone, replay
-    # the golden set, compare to the accepted baseline (§3.5).
+    # the golden set, compare to the accepted baseline.
     #
     # 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
-    # (D8: the engine has no scheduler and this RFC does not add one).
+    # (the engine has no scheduler and this design does not add one).
     #
     # Payload:
     #   run_id     (required) a run in :completed — the evidence the candidate answers
     #   candidate  { proposer?, rationale?, edits: [ {file, op, anchor?, before, after,
     #              addresses?} ] } — or omit it and pass `propose: true` to have the
-    #              configured model(s) write one from the run's findings (§3.4).
+    #              configured model(s) write one from the run's findings.
     #   propose    truthy — write the candidate with the agent's proposer PANEL.
     #   tolerance  Float — overrides the configured judge-score tolerance for this gate
     #
@@ -30,14 +30,14 @@ module Insika
     # forgot the candidate should get an error, not a bill.
     #
     # Two refusals happen BEFORE anything is cloned, because both mean the operator
-    # has not actually enabled this: an agent still in `mode: report` (§3.8 — writing
+    # has not actually enabled this: an agent still in `mode: report` (writing
     # is opt-in and an absent config is report-only), and a candidate whose every edit
     # was dropped (stale, off-allowlist, over budget). Neither is worth a provider bill.
     #
-    # Phase D (§3.9) makes the proposal a PANEL and the run's spend a BUDGET. The
+    # makes the proposal a PANEL and the run's spend a BUDGET. The
     # command's shape does not change: N models write N candidates, the gate scores
     # each, and the best survivor is the one proposal a human is shown. A deployment
-    # with one proposer and no budget behaves exactly as phase C did.
+    # with one proposer and no budget behaves exactly as did.
     class GateRefinement
       WRITE_MODES = %w[propose auto_apply].freeze
 
@@ -49,7 +49,7 @@ module Insika
 
       # proposer_factory: ->(refinement_config) { [Refinement::Proposer] | Proposer | nil }.
       # Optional — a deployment with none can still gate a candidate that arrives from
-      # the API, which is exactly what phase C shipped before the proposer existed.
+      # the API, which is exactly what shipped before the proposer existed.
       # resolver: the :resolve_refinement handler, used ONLY for `mode: auto_apply`.
       # Reusing it rather than writing files here is what keeps auto-apply honest: it
       # goes through the same staleness re-check, the same versioned write and the
@@ -125,7 +125,7 @@ module Insika
       end
 
       # Editing an agent's instructions is opt-in, explicitly, per agent — the whole
-      # point of §3.1 is that the reachable surface is small and declared. An absent
+      # point of is that the reachable surface is small and declared. An absent
       # or `report` config is not "not configured yet", it is a NO.
       def require_write_mode!(config, agent_id)
         mode = Coercion.presence(config["mode"]) || "report"
@@ -148,7 +148,7 @@ module Insika
         raise ArgumentError, "run #{run.id} is #{run.status}, expected completed"
       end
 
-      # The model(s) write the candidates (§3.4/§3.9). Each is shown the run's findings
+      # The model(s) write the candidates. Each is shown the run's findings
       # and the CURRENT content of the allowlisted files only — the same allowlist the
       # builder then enforces, so a proposal cannot even name a file it may not touch.
       #
@@ -194,7 +194,7 @@ module Insika
         allow
       end
 
-      # `mode: auto_apply` (§3.6, D2) — the ONE path where a prompt changes with no
+      # `mode: auto_apply` — the ONE path where a prompt changes with no
       # human in the loop. Off by default and deliberately narrow: it needs the mode,
       # a gate PASS with zero regressions, and a diff under `auto_apply_max_edits`.
       # Everything else parks at :awaiting_approval, which is the product.
@@ -232,7 +232,7 @@ module Insika
       end
 
       # Counts and ids only, never file content: these events reach the operator
-      # stream and the same rule the findings follow applies here (§5).
+      # stream and the same rule the findings follow applies here.
       def emit(type, run, **data)
         @event_stream.emit(Insika::Event.new(
                              type: type,

data/lib/insika/commands/import_mcp_tools.rb

@@ -4,7 +4,7 @@ require "time"
 
 module Insika
   module Commands
-    # Control command: LIVE MCP ingestion (Phase 7, Step E). Receives the NAME of
+    # Control command: LIVE MCP ingestion. Receives the NAME of
     # an MCP instance, delegates to McpToolIngestor (discovers via an injectable client
     # -> builds the manifest -> reuses :import_tools: batch upsert + hot reload)
     # and returns the per-tool report in the shape of :import_tools, plus

data/lib/insika/commands/import_tools.rb

@@ -4,18 +4,18 @@ require "time"
 
 module Insika
   module Commands
-    # BATCH ingestion of data-tools from a manifest (Phase 7, Step B).
+    # BATCH ingestion of data-tools from a manifest.
     # Normalizes each tool (defaults + envelope adapter + endpoint→url + secret/
     # env) via ToolManifest, UPSERTs it into the ToolStore, and RELOADS the overlay +
-    # catalog ONCE at the end — takes effect without a restart (NF3). Idempotent
+    # catalog ONCE at the end — takes effect without a restart. Idempotent
     # (re-importing reconciles). Injects the deployment's `{{secret.*}}`/`{{env.*}}`
-    # resolvers (D6/open-q2): the secret NEVER comes in the manifest.
+    # resolvers: the secret NEVER comes in the manifest.
     #
     # ISOLATED PARTIAL FAILURE (R4): a malformed tool (invalid envelope, missing
     # endpoint, unconfigured secret, collision with a code tool, invalid url)
     # does NOT bring down the batch — it becomes an entry in `errors[]`. Only a STRUCTURAL error in the
     # manifest (defaults/tools of the wrong type) raises (transport -> 422).
-    # Per-tool report in the shape of the Phase 6 pack importer.
+    # Per-tool report in the shape of the pack importer.
     #   -> { version, created: [names], updated: [names], errors: [{tool,error}] }
     class ImportTools
       def initialize(tool_store:, registry:, tool_catalog:, event_stream:, secrets: ENV, env: ENV)

data/lib/insika/commands/issue_tenant_token.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Insika
+  module Commands
+    # WS1: issues a PER-TENANT token (multi_tenant mode). Operator-only BY
+    # CONSTRUCTION: the edge refuses a tenant principal on POST /v1/commands
+    # (403), and an internal command stamped with a tenant is refused here —
+    # a tenant can never mint credentials. The plaintext token is the response
+    # and exists nowhere else; the store keeps only its hash. -> Issue.to_h.
+    class IssueTenantToken
+      def initialize(token_store:, event_stream:)
+        @token_store = token_store
+        @event_stream = event_stream
+      end
+
+      def call(command)
+        raise Insika::ValidationError, "token commands are operator-only" if command.meta[:tenant]
+
+        tenant_id = Insika::Coercion.presence(
+          command.payload[:tenant_id] || command.payload["tenant_id"]
+        )
+        raise Insika::ValidationError, "tenant_id is required" if tenant_id.nil?
+
+        label = command.payload[:label] || command.payload["label"] || "default"
+        issue = @token_store.issue(tenant_id: tenant_id, label: label)
+        emit(issue.id, tenant_id)
+        { token: issue.token, id: issue.id, tenant_id: tenant_id, label: label.to_s }
+      end
+
+      private
+
+      def emit(token_id, tenant_id)
+        @event_stream.emit(Insika::Event.new(
+                             type: :tenant_token_issued,
+                             data: { token_id: token_id, tenant_id: tenant_id },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+      end
+    end
+  end
+end

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

data/lib/insika/commands/memory_forget_fact.rb

@@ -7,10 +7,15 @@ module Insika
     # Control command: forgets (removes) a fact from the
     # agent's memory. Idempotent: forgetting something that doesn't exist is not an error
     # (`existed: false`). Scoped by `tenant`. -> { existed: bool }.
+    #
+    # with an `audit_store:` collaborator, appends a content-free
+    # audit line (old_hash only — the deleted value's digest, never the
+    # value). Optional: nil = no audit.
     class MemoryForgetFact
-      def initialize(memory_store:, event_stream:)
+      def initialize(memory_store:, event_stream:, audit_store: nil)
         @memory_store = memory_store
         @event_stream = event_stream
+        @audit_store = audit_store
       end
 
       def call(command)
@@ -19,14 +24,25 @@ module Insika
         raise Insika::ValidationError, "key is required" if key.nil?
 
         tenant = AgentPayload.presence(p[:tenant]) || command.meta[:tenant]
-        existed = @memory_store.forget_fact(tenant: tenant, key: key)
+        customer = AgentPayload.presence(p[:customer])
+        operator = AgentPayload.presence(p[:operator]) || command.meta[:operator] || "operator"
+
+        scope = @memory_store.cell_for(tenant, customer)
+        old = @memory_store.get_fact(tenant: tenant, key: key, customer: customer)
+        existed = @memory_store.forget_fact(tenant: tenant, key: key, customer: customer)
+        @audit_store&.record(
+          cell: scope, action: "forget", actor: operator, key: key,
+          tenant: tenant, customer: customer,
+          old_hash: old && MemoryAuditStore.digest(old.value)
+        )
         @event_stream.emit(Insika::Event.new(
                              type: :memory_fact_forgotten,
-                             data: { tenant: tenant, key: key, existed: existed },
+                             data: { tenant: tenant, key: key, customer: customer,
+                                     existed: existed }.compact,
                              meta: { at: Time.now.utc.iso8601 }
                            ))
         { existed: existed }
       end
     end
   end
-end
+end

data/lib/insika/commands/memory_put_fact.rb

@@ -9,10 +9,16 @@ module Insika
     # from WITHIN the turn (the `remember` tool); this Command is the HTTP surface the
     # Studio uses to edit facts directly. Scoped by `tenant` (nil = _default).
     # Synchronous; does not create a Task. -> Fact.
+    #
+    # the OPERATOR surface — every write stamps `origin: "operator"`
+    # (the `remember` tool keeps "engine") and, with an `audit_store:`
+    # collaborator, appends a content-free audit line (old/new digests). The
+    # audit is optional: nil = no audit (specs, minimal graphs).
     class MemoryPutFact
-      def initialize(memory_store:, event_stream:)
+      def initialize(memory_store:, event_stream:, audit_store: nil)
         @memory_store = memory_store
         @event_stream = event_stream
+        @audit_store = audit_store
       end
 
       def call(command)
@@ -22,14 +28,27 @@ module Insika
         raise Insika::ValidationError, "value is required" if p[:value].nil?
 
         tenant = AgentPayload.presence(p[:tenant]) || command.meta[:tenant]
-        fact = @memory_store.put_fact(tenant: tenant, key: key, value: p[:value])
+        customer = AgentPayload.presence(p[:customer])
+        operator = AgentPayload.presence(p[:operator]) || command.meta[:operator] || "operator"
+
+        scope = @memory_store.cell_for(tenant, customer)
+        old = @memory_store.get_fact(tenant: tenant, key: key, customer: customer)
+        fact = @memory_store.put_fact(tenant: tenant, key: key, value: p[:value],
+                                      customer: customer, origin: "operator",
+                                      expires_at: AgentPayload.presence(p[:expires_at]))
+        @audit_store&.record(
+          cell: scope, action: "put", actor: operator, key: key,
+          tenant: tenant, customer: customer,
+          old_hash: old && MemoryAuditStore.digest(old.value),
+          new_hash: MemoryAuditStore.digest(fact.value)
+        )
         @event_stream.emit(Insika::Event.new(
                              type: :memory_fact_put,
-                             data: { tenant: tenant, key: key },
+                             data: { tenant: tenant, key: key, customer: customer }.compact,
                              meta: { at: Time.now.utc.iso8601 }
                            ))
         fact
       end
     end
   end
-end
+end

data/lib/insika/commands/promote_harvest.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # — the human's answer, the ONLY path that lands a
+    # skill. Snapshot FIRST (the pre-promotion state), then the two existing
+    # write commands, then the append-only log row (D8). A promotion row's
+    # `rolled_back_at` makes the log the single ledger; re-promotion after a
+    # rollback is a NEW row with a NEW snapshot. The candidate flips to
+    # `promoted` ONLY after the writes land (record-after).
+    class PromoteHarvest
+      def initialize(harvest_store:, skill_store:, skill_catalog:, profile_source:,
+                     criterion:, conversion_gate:, event_stream:,
+                     write_skill: nil, set_skill_agents: nil)
+        @harvest_store = harvest_store
+        @skill_store = skill_store
+        @skill_catalog = skill_catalog
+        @profiles = ProfileSource.coerce(profile_source)
+        @criterion = criterion
+        @conversion_gate = conversion_gate
+        @event_stream = event_stream
+        @write_skill = write_skill ||
+                       Insika::Commands::WriteSkill.new(skill_store: skill_store,
+                                                        skill_catalog: skill_catalog,
+                                                        event_stream: event_stream)
+        @set_skill_agents = set_skill_agents ||
+                            Insika::Commands::SetSkillAgents.new(profile_source: @profiles,
+                                                                 event_stream: event_stream)
+      end
+
+      # payload: { candidate_id:, operator?, note? }
+      # operator from payload || command.meta[:operator] || "operator"
+      # -> Candidate (promoted | gated — the conversion re-check moved, D8-bis)
+      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}")
+        operator = (AgentPayload.presence(p[:operator]) || command.meta[:operator] || "operator").to_s
+
+        # D8-bis — the conversion ruler is RE-READ at the moment the skill
+        # lands (cheap: a fold read). A dip below the frozen baseline since
+        # gating PARKS the candidate at gated with the current numbers — the
+        # operator re-decides alertly. The eval gate is NOT re-run (expensive,
+        # and the skill body is not anchored to instruction files — nothing
+        # drifted to re-validate). A base graph without a conversion gate
+        # refuses with the named reason — never passes, never crashes.
+        current = if @conversion_gate
+                    @conversion_gate.call(tenant: command.meta[:tenant], agent: candidate.agent)
+                  else
+                    Insika::Harvest::ConversionGate::Result.new(
+                      passed: false, reason: :no_conversion_gate_wired, metric: nil, window: nil,
+                      current: nil, baseline: nil, threshold: nil, snapshot_ref: nil
+                    )
+                  end
+        return @harvest_store.recheck_conversion(candidate.id, conversion_gate: current.to_h) unless current.passed
+
+        # The criterion must STILL be the frozen one (D8-bis): a criterion that
+        # changed between boot and promotion is a criterion nobody froze.
+        unless @criterion && @criterion.sha == candidate.criterion_sha
+          raise Insika::ValidationError,
+                "the harvest criterion changed since boot (#{candidate.criterion_sha.inspect} -> " \
+                "#{@criterion&.sha.inspect}) — re-gate the candidate against the new frozen file"
+        end
+
+        # Snapshot first, then the writes, then the log row, then the flip.
+        existed = @skill_store.get(candidate.name, agent: candidate.agent)
+        # D8 + the review fix: the snapshot records EVERY agent the skill was
+        # enabled for BEFORE this promotion (SetSkillAgents' vocabulary). A
+        # homonymous skill allowed by B must stay allowed when A promotes —
+        # and the rollback restores exactly this set, B included.
+        enabled_for = agents_with_skill(candidate.name)
+        snapshot = @harvest_store.create_snapshot(
+          agent: candidate.agent, skill: candidate.name, content: existed,
+          existed: !existed.nil?,
+          enabled_for: enabled_for
+        )
+
+        @write_skill.call(Insika::Command.build(:write_skill,
+                                                { name: candidate.name, content: candidate.body,
+                                                  agent: candidate.agent }))
+        # ENABLE for the candidate's agent WITHOUT disabling anyone else who
+        # already had it: the wanted set is the pre-promotion holders plus the
+        # candidate.
+        @set_skill_agents.call(Insika::Command.build(:set_skill_agents,
+                                                     { name: candidate.name,
+                                                       agent_ids: enabled_for | [candidate.agent] }))
+
+        promotion = @harvest_store.append_promotion(
+          id: SecureRandom.uuid, agent: candidate.agent, skill: candidate.name,
+          origin: candidate.origin, eval_ref: "cand:#{candidate.id}",
+          conversion_ref: candidate.conversion_gate && candidate.conversion_gate["snapshot_ref"],
+          approver: operator, snapshot_ref: snapshot.id,
+          criterion_sha: candidate.criterion_sha
+        )
+        @harvest_store.mark_promoted(candidate.id, promotion_ref: promotion.id)
+
+        emit(:skill_promoted, agent: candidate.agent, skill: candidate.name,
+                              candidate_id: candidate.id, snapshot_ref: snapshot.id,
+                              promotion_ref: promotion.id, approver: operator)
+        @harvest_store.find_candidate(candidate.id)
+      end
+
+      private
+
+      def profile_of(agent_id)
+        @profiles.fetch(agent_id) ||
+          (raise Insika::NotFoundError, "agent '#{agent_id}' not configured")
+      end
+
+      # Every agent whose allowlist currently names the skill — the pre-
+      # promotion holder set (an agent with skills=nil has ALL, so it holds
+      # every name and is not "removable"; SetSkillAgents skips it).
+      def agents_with_skill(name)
+        @profiles.all.select { |p| Array(p.skills).include?(name) }.map(&:id)
+      end
+
+      def emit(type, **data)
+        # ids and refs only — the skill body never enters the stream (D7).
+        @event_stream.emit(Insika::Event.new(
+                             type: type, data: data, meta: { at: Time.now.utc.iso8601 }
+                           ))
+      end
+    end
+  end
+end