insika 0.2.0 → 0.3.0

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).
+    # (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

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

data/lib/insika/commands/record_outcome.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command (WS7): the operator or the integration records a business
+    # OUTCOME for a conversation — `{ outcome: "conversion", value: R$ }` — via
+    # `POST /v1/outcomes`. The engine transports it and never interprets it; the
+    # Studio's scorecard card aggregates the store. The record is tenant-stamped
+    # (WS1): a tenant principal's outcomes land under its own tenant, invisible
+    # to every other tenant and to nothing the tenant can read.
+    class RecordOutcome
+      def initialize(outcome_store:, event_stream:)
+        @outcome_store = outcome_store
+        @event_stream = event_stream
+      end
+
+      def call(command)
+        payload = command.payload
+        agent = Coercion.presence(payload[:agent] || payload["agent"])
+        outcome = Coercion.presence(payload[:outcome] || payload["outcome"])
+        raise ValidationError, "agent is required" if agent.nil?
+        raise ValidationError, "outcome is required" if outcome.nil?
+
+        value = payload[:value] || payload["value"]
+        unless value.nil? || value.is_a?(Numeric)
+          raise ValidationError, "value must be a number"
+        end
+
+        session_id = payload[:session_id] || payload["session_id"]
+        record = @outcome_store.create(
+          tenant: command.meta[:tenant], agent: agent, session_id: session_id,
+          outcome: outcome, value: value
+        )
+        @event_stream.emit(Insika::Event.new(
+                             type: :outcome_recorded,
+                             data: { agent: agent, outcome: outcome, value: record.value,
+                                     session_id: record.session_id },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+        record
+      end
+    end
+  end
+end