insika 0.2.0 → 0.3.0

data/lib/insika/channels/relay.rb

@@ -3,6 +3,7 @@
 require "digest"
 require "json"
 require "openssl"
+require "time"
 require "uri"
 
 module Insika
@@ -33,12 +34,25 @@ module Insika
       DEFAULT_ID = "relay"
       DEFAULT_TIMEOUT = 10
 
+      # how the outbox flushes for THIS channel. `:at_end` (the
+      # default) is one POST with the whole answer, byte-identical to today;
+      # `:progressive` lets ChannelDelivery split the answer into balloons and
+      # POST them in order (the channel still only translates — it does not know
+      # what a balloon is).
+      POLICIES = %i[at_end progressive].freeze
+
       attr_reader :id
 
       # The bundled relay as an operator configures it: three env vars, of which the
       # token is the SWITCH — no token, no channel, so there is no way to end up with
       # this route mounted and open. -> Relay | nil.
       #
+      # `INSIKA_RELAY_SHADOW` (truthy) is the shadow switch: the turn
+      # runs end to end and the reply is recorded, never delivered.
+      #
+      # `INSIKA_RELAY_DELIVERY` ("progressive" | "at_end") is how the outbox
+      # flushes. Unset = :at_end.
+      #
       # Shared by every composition root on purpose: the DSL front door has to reach
       # the same feature as `config.ru`, or the docs are true of only one of them.
       def self.from_env(env = ENV, http: nil, allow_http: false, allow_private: false)
@@ -48,6 +62,8 @@ module Insika
         new(inbound_token: token,
             deliver_url: Insika::EnvSchema.read("INSIKA_RELAY_DELIVER_URL", env),
             deliver_token: Insika::EnvSchema.read("INSIKA_RELAY_DELIVER_TOKEN", env),
+            shadow: Insika::EnvSchema.truthy?(Insika::EnvSchema.read("INSIKA_RELAY_SHADOW", env)),
+            delivery: policy!(Insika::EnvSchema.read("INSIKA_RELAY_DELIVERY", env)),
             http: http, allow_http: allow_http, allow_private: allow_private)
       end
 
@@ -59,9 +75,14 @@ module Insika
       #                 reply and the delivery fails loudly instead of silently).
       # deliver_token:  Bearer we send THEM. Optional: a consumer on a private
       #                 network may authenticate us another way.
+      # shadow: The turn runs, the reply is recorded and never
+      #                 sent. Fail-closed by construction: everything downstream
+      #                 duck-types `shadow?`, so a channel that does not answer it
+      #                 is a normal channel.
+      # delivery: How the outbox flushes (:at_end | :progressive).
       def initialize(inbound_token:, deliver_url:, deliver_token: nil, http: nil,
                      id: DEFAULT_ID, allow_http: false, allow_private: false,
-                     timeout: DEFAULT_TIMEOUT)
+                     timeout: DEFAULT_TIMEOUT, shadow: false, delivery: :at_end)
         @id = id.to_s
         @inbound_token = inbound_token.to_s
         @deliver_url = deliver_url.to_s
@@ -70,10 +91,30 @@ module Insika
         @allow_http = allow_http
         @allow_private = allow_private
         @timeout = timeout
+        @shadow = shadow
+        @delivery = self.class.policy!(delivery)
+      end
+
+      def shadow? = @shadow
+
+      def delivery = @delivery
+      def progressive? = @delivery == :progressive
+
+      # "progressive" | "at_end" | blank/unset (= :at_end). An unknown value is
+      # a config error at BOOT — the consumer would silently miss every
+      # progressive turn, so it is refused where the operator is.
+      def self.policy!(value)
+        return :at_end if Insika::Coercion.blank?(value)
+
+        name = value.to_s.strip.downcase.to_sym
+        return name if POLICIES.include?(name)
+
+        raise Insika::ConfigError,
+              "unknown relay delivery: #{value.inspect} (expected #{POLICIES.join(', ')})"
       end
 
       # -> :ok | :unauthorized | :disabled. A SYMBOL and not a Rack triple (the
-      # RFC sketched one): a status code is the transport's vocabulary, and keeping
+      # the design sketched one): a status code is the transport's vocabulary, and keeping
       # it out of here is what lets this class be tested without Rack and read
       # without knowing HTTP.
       def authenticate(req)
@@ -91,19 +132,25 @@ module Insika
       #   { "agent": "support", "external_id": "5511999998888",
       #     "event_id": "wamid.HBg…", "message": "queria saber do pedido",
       #     "vars": { … } }
+      #
+      # In SHADOW mode `event_id` is REQUIRED: it is the correlation key both
+      # halves of the pair are built from, and a mirror that cannot supply a
+      # stable id cannot be paired.
       def parse(_req, body:)
         body = body.is_a?(Hash) ? body : {}
         agent = string(body["agent"])
         external_id = string(body["external_id"])
         message = string(body["message"])
+        event_id = presence(body["event_id"])
 
         raise Insika::ValidationError, "agent is required" if agent.empty?
         raise Insika::ValidationError, "external_id is required" if external_id.empty?
         raise Insika::ValidationError, "message is required" if message.strip.empty?
+        raise Insika::ValidationError, "event_id is required in shadow mode" if @shadow && event_id.nil?
 
         vars = body["vars"].is_a?(Hash) ? body["vars"] : {}
         { agent: agent, external_id: external_id, message: message,
-          event_id: presence(body["event_id"]), vars: vars }
+          event_id: event_id, vars: vars, incumbent_reply: presence(body["incumbent_reply"]) }
       end
 
       # the engine namespaces the platform's conversation key, so a
@@ -127,6 +174,8 @@ module Insika
       # consumer that receives the same delivery twice (we retried after a timeout
       # that actually landed) can drop the second one.
       def deliver(payload, to:, delivery_id: nil)
+        raise Insika::DeliveryError, "relay '#{@id}' is in shadow mode and must never deliver" if @shadow
+
         raise Insika::DeliveryError, "relay deliver_url is not configured" if @deliver_url.empty?
 
         if (reason = egress_violation)
@@ -143,8 +192,33 @@ module Insika
         raise Insika::DeliveryError, "#{e.class}: #{e.message}"
       end
 
+      # The reply, as recorded by the mirror. Follows the
+      # same strictness as `parse`; `at` is optional (nil = now).
+      def parse_shadow_reply(_req, body:)
+        body = body.is_a?(Hash) ? body : {}
+        external_id = string(body["external_id"])
+        event_id = presence(body["event_id"])
+        reply = string(body["reply"])
+
+        raise Insika::ValidationError, "external_id is required" if external_id.empty?
+        raise Insika::ValidationError, "event_id is required" if event_id.nil?
+        raise Insika::ValidationError, "reply is required" if reply.strip.empty?
+
+        at = presence(body["at"])
+        raise Insika::ValidationError, "at must be an ISO8601 timestamp" if at && !parseable_time?(at)
+
+        { external_id: external_id, event_id: event_id, reply: reply, at: at }
+      end
+
       private
 
+      def parseable_time?(value)
+        Time.iso8601(value)
+        true
+      rescue ArgumentError
+        false
+      end
+
       # Resolved on EVERY call, not once at boot: a hostname that answered a public
       # address yesterday can answer 169.254.169.254 today, and this POST carries
       # the customer's conversation.

data/lib/insika/channels/web.rb

@@ -7,7 +7,7 @@ require "securerandom"
 module Insika
   module Channels
     # The web widget — the FIRST Shape A channel, and the adoption
-    # claim behind the whole RFC: an adopter pastes one tag into their site and has
+    # claim behind the whole design: an adopter pastes one tag into their site and has
     # a working agent, with no backend of their own and no build step.
     #
     #   <script src="https://agents.example.com/channels/web/asset/widget.js"
@@ -50,7 +50,7 @@ module Insika
       # never reach a browser that already has it. Short max-age + an ETag instead:
       # the common case is a 304 with no body, and an upgrade lands within minutes.
       # (A deliberate narrowing of's "long-cache versioned URL": the install
-      # snippet in the RFC has no version in it, so there is nothing to bust.)
+      # snippet has no version in it, so there is nothing to bust.)
       ASSET_CACHE_CONTROL = "public, max-age=300"
 
       attr_reader :id

data/lib/insika/chat_builder.rb

@@ -14,7 +14,8 @@ module Insika
   class ChatBuilder
     def initialize(tool_registry:, skill_catalog:, checkpoint_store:, event_stream:,
                    hooks:, tool_catalog: nil, memory_store: nil, subagent_runner: nil,
-                   tool_trace_store: nil)
+                   tool_trace_store: nil, media_runner: nil, session_store: nil,
+                   contact_store: nil, followup_store: nil)
       @tool_registry = tool_registry
       @skill_catalog = skill_catalog
       @checkpoint_store = checkpoint_store
@@ -28,6 +29,19 @@ module Insika
       # spawn_subagent system tool is never wired (parity for a builder used
       # without delegation, e.g. some unit stubs).
       @subagent_runner = subagent_runner
+      # the Executor as the generate_image/tts runner (seams + usage
+      # accounting). nil = the media tools are never wired (parity for stubs).
+      @media_runner = media_runner
+      # update_briefing / set_next_step are the briefing-write system
+      # tools — wired only with @session_store present AND profile.briefing_fields
+      # non-empty (double gate, like remember). nil = never wired (parity for a
+      # builder used without session persistence, e.g. some unit stubs).
+      @session_store = session_store
+      # the schedule/cancel_followup system tools — wired only
+      # with BOTH stores present AND a parsed follow-up policy on the profile
+      # (double gate, like remember). nil = never wired (parity).
+      @contact_store = contact_store
+      @followup_store = followup_store
     end
 
     # Configures an already-created chat with the context (stage 2) and the
@@ -90,6 +104,22 @@ module Insika
                                      event_stream: @event_stream, state: state)
       end
 
+      # update_briefing / set_next_step are the briefing-write system tools
+      #  — wired only with @session_store present AND
+      # profile.briefing_fields non-empty (double gate, like remember). Never
+      # enveloped: deterministic in-process writes.
+      fields = if state.profile.respond_to?(:briefing_fields)
+                 Array(state.profile.briefing_fields).map(&:to_s)
+               else
+                 []
+               end
+      if @session_store && !fields.empty?
+        tools << Tools::UpdateBriefing.new(session_store: @session_store, fields: fields,
+                                           event_stream: @event_stream, state: state)
+        tools << Tools::UpdateBriefing::SetNextStep.new(session_store: @session_store,
+                                                        event_stream: @event_stream, state: state)
+      end
+
       # signal_stuck is the "I cannot proceed" system tool (WS5) — wired only
       # when the agent opted in (`profile.stuck_signal`), never enveloped. It is a
       # deterministic signal; the consumer decides what "stuck" means. Defensive
@@ -98,6 +128,33 @@ module Insika
         tools << Tools::StuckSignal.new(state: state)
       end
 
+      # schedule/cancel_followup are the follow-up system tools  —
+      # wired only with BOTH stores present AND a parsed follow-up policy on
+      # the profile (double gate, like remember). Never enveloped: the store
+      # writes are deterministic. The tools stay OUT of the allowlist — they
+      # are data-driven per agent, not admittable (prompts/memory/stuck_signal
+      # are the precedent).
+      if @contact_store && @followup_store && followup_policy(state)
+        tools << Tools::ScheduleFollowup.new(contact_store: @contact_store,
+                                             followup_store: @followup_store,
+                                             state: state,
+                                             event_stream: @event_stream)
+        tools << Tools::CancelFollowup.new(followup_store: @followup_store,
+                                           state: state,
+                                           event_stream: @event_stream)
+      end
+
+      # generate_image / tts are the generated-media system tools (WS9, saída)
+      # — wired only when BOTH gates pass, never enveloped: the AGENT opted in
+      # (`profile.outputs` — the per-kind generator config) AND the CHANNEL
+      # declared it can receive the media (state.channel_capabilities, from the
+      # request's `channel.capabilities`). The "abstraction admits only what
+      # leaks" rule, C4: a channel that never declared image_output cannot get
+      # a generated image; a profile without `outputs` never generates. The
+      # runner is the Executor (seams + usage accounting); nil = no media
+      # output at all (parity for a stub builder).
+      output_media_tools(state).each { |tool| tools << tool } if @media_runner
+
       # spawn_subagent is the delegation system tool — wired only with a
       # runner present AND profile.subagents non-empty (a double gate, like
       # remember). Never enveloped: in the synchronous mode the child lives in the
@@ -139,6 +196,32 @@ module Insika
       names - eager
     end
 
+    # the follow-up tools' gate — a PARSED policy on the profile.
+    # A malformed declaration reads as "no policy" (the firer blocks it, the
+    # doctor reports it; the tools are simply not offered).
+    def followup_policy(state)
+      followup = state.profile.respond_to?(:followup) ? state.profile.followup : nil
+      followup && Insika::FollowupPolicy.parse(followup)
+    end
+
+    # WS9 (saída): the media-output tools this turn may carry, per the double
+    # gate (profile outputs ∩ channel capabilities). [] = none. Defensive reads
+    # throughout — a minimal profile/state stub is "off", which is the safe
+    # parity reading.
+    def output_media_tools(state)
+      outputs = state.profile.respond_to?(:outputs) ? state.profile.outputs : nil
+      return [] unless outputs.is_a?(Hash)
+      return [] unless state.respond_to?(:channel_capabilities)
+
+      caps = Array(state.channel_capabilities).map(&:to_s)
+      image_cfg = outputs["image"]
+      tts_cfg = outputs["tts"]
+      [
+        (Tools::GenerateImage.new(runner: @media_runner, config: image_cfg, state: state) if image_cfg.is_a?(Hash) && caps.include?("image_output")),
+        (Tools::Tts.new(runner: @media_runner, config: tts_cfg, state: state) if tts_cfg.is_a?(Hash) && caps.include?("audio_output"))
+      ].compact
+    end
+
     # The turn's effective tool concurrency (nil = serial), plus the ONE thing the
     # gate owes the operator: when the profile asked for parallel tool calls and
     # this turn silently cannot have them (an approval-required tool would

data/lib/insika/checkpoint_store.rb

@@ -109,6 +109,22 @@ module Insika
       nil
     end
 
+    # Deletes EVERY checkpoint + side-effect record of the task (WS8 retention:
+    # a purged task's durability trail goes with it — no orphaned keys).
+    # -> count of records removed.
+    def purge(task_id)
+      removed = 0
+      checkpoint_turns(task_id).each do |n|
+        @store.delete(SCOPE, checkpoint_key(task_id, n))
+        removed += 1
+      end
+      sideeffect_turns(task_id).each do |n|
+        @store.delete(SCOPE, sideeffects_key(task_id, n))
+        removed += 1
+      end
+      removed
+    end
+
     private
 
     def checkpoint_key(task_id, turn)

data/lib/insika/commands/agent_payload.rb

@@ -12,10 +12,10 @@ module Insika
       FIELDS = %i[id model provider base_prompt prompt_files tools_allow tools_deny
                   tools_allow_groups skills skills_eager context_providers workflows_allow policies
                   prompt_refs limits approvals_required capabilities subagents tools_deferred
-                  memory prompt_caching tool_output_compression budget reliability alerts
-                  stuck_signal
+                  memory prompt_caching tool_persistence tool_output_compression budget reliability alerts
+                  routes stuck_signal outputs briefing_fields grounding funnel followup
                   params model_policy guardrails refinement capabilities_declared
-                  edge_stream metadata].freeze
+                  edge_stream metadata distill harvest].freeze
 
       module_function
 

data/lib/insika/commands/cancel_followup.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # the operator cancels ONE pending follow-up record (the
+    # Studio's Cancel button dispatches this). Synchronous control command (no
+    # task, like RecordOutcome); idempotent — an already-cancelled record
+    # returns as-is (a repeat of the same call is not an error). Tenant-scoped
+    # (WS1): a tenant principal can only cancel its own tenant's records.
+    class CancelFollowup
+      def initialize(followup_store:, event_stream:)
+        @followup_store = followup_store
+        @event_stream = event_stream
+      end
+
+      # -> Record. Emits :followup_cancelled { id:, cancelled_by: }.
+      def call(command)
+        id = Coercion.presence(command.payload[:followup_id] || command.payload["followup_id"])
+        raise ValidationError, "followup_id is required" if id.nil?
+
+        record = @followup_store.find(id)
+        raise NotFoundError, "follow-up not found: #{id}" if record.nil?
+
+        # WS1: the principal's tenant is the scope — a tenant token cannot
+        # cancel another tenant's record by id.
+        tenant = command.meta[:tenant]
+        unless record.tenant == (tenant.to_s.empty? ? "platform" : tenant.to_s)
+          raise ValidationError, "follow-up #{id} belongs to another tenant"
+        end
+
+        # A non-pending record (the tick fired it between the render and the
+        # click) is a domain error the Studio can flash — never a 500.
+        cancelled = begin
+          @followup_store.cancel(id: id)
+        rescue ArgumentError => e
+          raise ValidationError, e.message
+        end
+        @event_stream.emit(Insika::Event.new(
+                             type: :followup_cancelled,
+                             data: { id: cancelled.id, cancelled_by: "operator" },
+                             meta: { tenant: command.meta[:tenant], at: Time.now.utc.iso8601 }
+                           ))
+        cancelled
+      end
+    end
+  end
+end

data/lib/insika/commands/delete_tenant_data.rb

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

data/lib/insika/commands/export_customer_memory.rb

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

data/lib/insika/commands/forget_customer.rb

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