insika 0.2.0 → 0.7.0

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

data/lib/insika/commands/record_shadow_reply.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # C4 — the incumbent's half of a shadow pair, recorded on the mirror's
+    # word. One command, two doors: Shape 1 (the reply rides the mirror call
+    # itself) and Shape 2 (the follow-up route, for a consumer that mirrors
+    # before answering) both dispatch HERE, so there is one behaviour and one
+    # store method behind both.
+    #
+    # Idempotency is first-write-wins: the customer received ONE reply, and
+    # letting a retry overwrite it would silently rewrite evidence. The
+    # guarantee lives in ShadowPairStore#record_incumbent (inside its
+    # transaction); the find below is only the cheap fast path for the common
+    # retry. A reply for a pair that does not exist yet creates it :open — the
+    # mirror may legitimately arrive before our turn finishes.
+    class RecordShadowReply
+      def initialize(shadow_pairs:, event_stream: nil)
+        @shadow_pairs = shadow_pairs
+        @event_stream = event_stream
+      end
+
+      # payload: { channel:, external_id:, event_id:, reply:, at: }
+      # -> { pair_id:, status: }
+      def call(command)
+        payload = command.payload
+        channel = Coercion.presence(payload[:channel] || payload["channel"])
+        external_id = Coercion.presence(payload[:external_id] || payload["external_id"])
+        event_id = Coercion.presence(payload[:event_id] || payload["event_id"])
+        reply = payload[:reply] || payload["reply"]
+
+        raise ValidationError, "channel is required" if channel.nil?
+        raise ValidationError, "external_id is required" if external_id.nil?
+        raise ValidationError, "event_id is required" if event_id.nil?
+        raise ValidationError, "reply is required" if reply.to_s.strip.empty?
+
+        id = ShadowPairStore.key_for(channel: channel, external_id: external_id,
+                                     event_id: event_id)
+        existing = @shadow_pairs.find(id)
+        if existing && !existing.incumbent_reply.nil?
+          emit(id, "already_recorded")
+          return { pair_id: id, status: "already_recorded" }
+        end
+
+        pair = @shadow_pairs.record_incumbent(id: id, channel: channel, event_id: event_id,
+                                              external_id: external_id, reply: reply.to_s,
+                                              at: payload[:at] || payload["at"])
+        emit(id, pair.status.to_s)
+        { pair_id: id, status: pair.status.to_s }
+      end
+
+      private
+
+      # Metadata only: the pair id and its status, never the reply's text.
+      def emit(pair_id, status)
+        return unless @event_stream
+
+        @event_stream.emit(Insika::Event.new(
+                             type: :shadow_reply_recorded,
+                             data: { pair_id: pair_id, status: status },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+      end
+    end
+  end
+end

data/lib/insika/commands/refresh_mcp_tools.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command: LIVE re-discovery of an MCP instance's tools.
+    # Delegates to McpToolRegistry#refresh (connect +
+    # tools/list + write McpStore#tools_cache) — TOOL EXECUTION never reads
+    # that cache; this command only refreshes what `entries`/Studio/doctor
+    # display. The CLI verb / API route / Studio button that call it are
+    # later work (PR3/PR4) — the command itself is the seam they'll share.
+    # -> { instance:, tools: [{name,description,inputSchema}, ...] }.
+    class RefreshMcpTools
+      def initialize(mcp_registry:, event_stream:)
+        @mcp_registry = mcp_registry
+        @event_stream = event_stream
+      end
+
+      def call(command)
+        p = symbolize(command.payload)
+        name = Insika::Coercion.presence(p[:name]) ||
+               (raise Insika::ValidationError, "refresh_mcp_tools: 'name' (MCP instance) is required")
+
+        tools = @mcp_registry.refresh(name)
+        emit(name, tools)
+        { instance: name, tools: tools }
+      end
+
+      private
+
+      # Emits only the COUNT + the instance name (never a tool's schema, in
+      # case a schema description ever carries something sensitive): 0 leakage.
+      def emit(name, tools)
+        @event_stream.emit(Insika::Event.new(
+                             type: :mcp_tools_refreshed,
+                             data: { instance: name, tools: tools.size },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+      end
+
+      def symbolize(payload)
+        (payload || {}).each_with_object({}) { |(k, v), acc| acc[k.to_sym] = v }
+      end
+    end
+  end
+end

data/lib/insika/commands/reject_harvest.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    #   — the operator's dismissal: a candidate that is NOT yet
+    # gated can be rejected by a human directly (a human may always outvote
+    # the miner). The thin wrapper over `mark_rejected`.
+    class RejectHarvest
+      def initialize(harvest_store:, event_stream:)
+        @harvest_store = harvest_store
+        @event_stream = event_stream
+      end
+
+      # payload: { candidate_id:, operator?, note? }
+      # -> Candidate (rejected)
+      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
+        rejected = @harvest_store.mark_rejected(candidate.id, operator: operator, note: p[:note])
+
+        @event_stream.emit(Insika::Event.new(
+                             type: :harvest_rejected,
+                             data: { candidate_id: candidate.id, agent: candidate.agent,
+                                     operator: operator },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+        rejected
+      end
+    end
+  end
+end

data/lib/insika/commands/resolve_proposal.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Insika
+  module Commands
+    # the human's answer : approve (→ the
+    # store, CAS, provenance `distilled:<session_ref>`), reject (with an
+    # optional reason), dismiss (latches the tuple). Approval never silently
+    # overwrites an operator edit (D5/E3): the CAS baseline captured at distill
+    # time guards the write, and a lost race flips the proposal to `:stale`
+    # carrying the fact's CURRENT value — both values visible on the wiki.
+    # Synchronous control command — the Studio dispatches it; no task, no actor.
+    class ResolveProposal
+      DECISIONS = %w[approved rejected dismissed].freeze
+
+      def initialize(proposal_store:, memory_store:, event_stream:)
+        @proposal_store = proposal_store
+        @memory_store = memory_store
+        @event_stream = event_stream
+      end
+
+      # payload: { proposal_id:, decision: "approved"|"rejected"|"dismissed",
+      #            operator?, note? }
+      # operator from payload || command.meta[:operator] || "operator"
+      # -> Proposal (the resolved record; a :stale one carries current_value)
+      def call(command)
+        proposal_id = Coercion.presence(command.payload[:proposal_id] || command.payload["proposal_id"])
+        raise ValidationError, "proposal_id is required" if proposal_id.nil?
+
+        decision = Coercion.presence(command.payload[:decision] || command.payload["decision"])
+        raise ValidationError, "decision is required" unless DECISIONS.include?(decision)
+
+        proposal = @proposal_store.find(proposal_id)
+        raise Insika::NotFoundError, "proposal not found: #{proposal_id}" if proposal.nil?
+
+        operator = operator_for(command)
+        note = Coercion.presence(command.payload[:note] || command.payload["note"])
+
+        case decision
+        when "approved" then approve(command, proposal, operator, note)
+        when "rejected"
+          resolved = @proposal_store.reject(id: proposal.id, operator: operator, note: note)
+          emit(:proposal_rejected, resolved)
+          resolved
+        else # "dismissed"
+          resolved = @proposal_store.dismiss(id: proposal.id, operator: operator, note: note)
+          emit(:proposal_dismissed, resolved)
+          resolved
+        end
+      end
+
+      private
+
+      # The whole safety argument (D5/E3). The read-check-write CAS rides the
+      # store's transaction — a lost race is a re-present, never a silent
+      # overwrite.
+      def approve(command, proposal, operator, note)
+        fact = @memory_store.get_fact(tenant: proposal.tenant, customer: proposal.customer,
+                                      key: proposal.key)
+        if proposal.expected_existed
+          if fact && fact.updated_at == proposal.expected_revision
+            written = @memory_store.replace_if_revision(
+              tenant: proposal.tenant, customer: proposal.customer,
+              key: proposal.key, value: proposal.value,
+              expected_revision: proposal.expected_revision,
+              origin: "distilled:#{proposal.session_ref}")
+            return stale(proposal, fact, operator) unless written
+          else
+            return stale(proposal, fact, operator) # the operator's edit stands
+          end
+        elsif fact
+          return stale(proposal, fact, operator) # the operator created it first
+        else
+          @memory_store.put_fact(tenant: proposal.tenant, customer: proposal.customer,
+                                 key: proposal.key, value: proposal.value,
+                                 origin: "distilled:#{proposal.session_ref}")
+        end
+        resolved = @proposal_store.approve(id: proposal.id, operator: operator, note: note)
+        emit(:proposal_approved, resolved)
+        resolved
+      end
+
+      # The re-present (E3): the proposal carries the fact's CURRENT value next
+      # to the proposed one; both are visible on the wiki page.
+      def stale(proposal, fact, operator)
+        resolved = @proposal_store.mark_stale(id: proposal.id, current_value: fact&.value,
+                                              operator: operator)
+        emit(:proposal_stale, resolved)
+        resolved
+      end
+
+      # ids and statuses only (D7) — a fact value never enters the stream.
+      def emit(type, proposal)
+        @event_stream.emit(Insika::Event.new(
+                             type: type,
+                             data: { proposal_id: proposal.id, status: proposal.status,
+                                     operator: proposal.operator },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+      end
+
+      def operator_for(command)
+        Coercion.presence(command.payload[:operator] || command.payload["operator"]) ||
+          Coercion.presence(command.meta[:operator]) ||
+          "operator"
+      end
+    end
+  end
+end

data/lib/insika/commands/restore_concept.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command: restores an old version of a concept as the current
+    # content (a new write — linear history, like `RestoreSystemFile`).
+    # -> { name, agent, tenant, updated_at }.
+    class RestoreConcept
+      def initialize(knowledge_store:, event_stream:)
+        @knowledge_store = knowledge_store
+        @event_stream = event_stream
+      end
+
+      def call(command)
+        p = AgentPayload.symbolize(command.payload)
+        name = AgentPayload.presence(p[:name])
+        agent = AgentPayload.presence(p[:agent])
+        tenant = AgentPayload.presence(p[:tenant])
+        raise Insika::ValidationError, "name is required" if name.nil?
+        raise Insika::ValidationError, "agent is required" if agent.nil?
+        raise Insika::ValidationError, "version is required" if p[:version].nil?
+
+        rec = @knowledge_store.restore(agent, name, p[:version], tenant: tenant)
+        @event_stream.emit(Insika::Event.new(
+                             type: :knowledge_learned, data: { name: name, agent: agent },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+        { name: name, agent: agent, tenant: tenant, updated_at: rec["updated_at"] }
+      end
+    end
+  end
+end

data/lib/insika/commands/revoke_contact.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # a channel opt-out event (mapped by the integration)— or
+    # the operator force-revoking a contact whose opt-out never arrived.
+    # Revokes the contact cell AND cancels every pending record of that
+    # customer in ONE transaction on the shared backend (D2: a half-cancelled
+    # opt-out is the spam bug — a crash mid-revoke must leave the old state,
+    # never the cell revoked with pending records alive). Blocked/fired
+    # records are never touched. Tenant-scoped (WS1).
+    class RevokeContact
+      def initialize(contact_store:, followup_store:, store:, event_stream:)
+        @contact_store = contact_store
+        @followup_store = followup_store
+        @store = store
+        @event_stream = event_stream
+      end
+
+      # -> { customer:, tenant:, cancelled: }.
+      def call(command)
+        customer = Coercion.presence(command.payload[:customer] || command.payload["customer"])
+        raise ValidationError, "customer is required" if customer.nil?
+
+        tenant = command.meta[:tenant]
+        # ONE transaction on the shared backend: both stores' writes (each
+        # wrapped in their own nested transaction) join the outer one.
+        cancelled = @store.transaction do
+          @contact_store.set_revoked(tenant: tenant, customer: customer)
+          @followup_store.cancel_pending_for(tenant: tenant, customer: customer)
+        end
+
+        @event_stream.emit(Insika::Event.new(
+                             type: :contact_revoked,
+                             data: { customer: customer, tenant: tenant },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+        @event_stream.emit(Insika::Event.new(
+                             type: :followups_cancelled,
+                             data: { customer: customer, count: cancelled },
+                             meta: { tenant: tenant, at: Time.now.utc.iso8601 }
+                           ))
+        { customer: customer, tenant: tenant, cancelled: cancelled }
+      end
+    end
+  end
+end