insika 0.2.0 → 0.3.0

data/lib/insika/commands/run_harvest.rb

@@ -0,0 +1,393 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # the ONLY path that writes candidates. Mines ONE window end
+    # to end: resolve the sessions, read the transcripts + evidence, ask the
+    # miner, schema-drop, apply the negative list and the grounding filter,
+    # dedup against the ledger, write the run + candidates, stamp the markers.
+    #
+    # Synchronous (it runs on the engine's worker fiber, C12, or the CLI, C15)
+    # — it creates no task and no turn. It writes NOTHING to sessions or
+    # skills: D2's fork discipline is this command's contract — a customer
+    # turn's prefix is untouched by construction, and the only harvest-side
+    # spend is the run's cost (E1).
+    #
+    # Payload: { agent:, last_sessions?, since?, full?, session_ids?,
+    #            max_proposals?, exclude_sessions? }
+    class RunHarvest
+      DEFAULT_LAST_SESSIONS = 200 # the EvidenceCollector's window default
+      DEFAULT_MIN_MESSAGES = 3
+      DEFAULT_MAX_PROPOSALS = 10
+      DEFAULT_IDLE_HOURS = 24
+
+      def initialize(profiles:, harvest_store:, session_store:, task_store:,
+                     skill_store: nil, tool_trace_store: nil, settings_store: nil,
+                     negative_list: nil, miner_factory: nil, event_stream:)
+        @profiles = ProfileSource.coerce(profiles)
+        @harvest_store = harvest_store
+        @session_store = session_store
+        @task_store = task_store
+        @skill_store = skill_store
+        @tool_trace_store = tool_trace_store
+        @settings_store = settings_store
+        @negative_list = negative_list
+        @miner_factory = miner_factory ||
+                         ->(config) { Harvest::MinerFactory.build(config, utility_model: utility_model) }
+        @event_stream = event_stream
+      end
+
+      # -> { mined: true, run_id:, candidates: N,
+      #      rejected: { "<rule-id>" => N, "ungrounded" => N, "dedup" => N,
+      #                  "schema" => N, ... }, cost: {...} | nil }
+      #  | { mined: false, skipped: "disabled|no_model|no_grounding_matcher" }
+      def call(command)
+        p = AgentPayload.symbolize(command.payload)
+        agent = AgentPayload.presence(p[:agent])
+        raise Insika::ValidationError, "agent is required" if agent.nil?
+
+        profile = @profiles[agent] ||
+                  (raise Insika::NotFoundError, "agent '#{agent}' not configured")
+        config = Coercion.deep_stringify(profile.harvest)
+        return skip("disabled") if config.nil? || !Coercion.truthy?(config["enabled"])
+
+        # D4: the OPERATIVE negative list lives on the profile (hot-editable,
+        # seeded by `insika harvest:negative import`); the injected list is
+        # the deployment's fallback. The engine applies data, never authors it.
+        @list = negative_list_for(config)
+
+        # D3: product claims cannot be verified without a matcher, so NOTHING
+        # mines — refused, not warned (D12's "by refusal, not by prompt").
+        grounding = Grounding.parse(profile.grounding)
+        return skip("no_grounding_matcher") if grounding.nil? || !grounding.matcher.sku?
+
+        miner = @miner_factory.call(config)
+        return skip("no_model") if miner.nil?
+
+        run = @harvest_store.create_run(agent_id: agent, window: window_record(p),
+                                        budget: budget_cap(config))
+        sessions = resolve_sessions(agent, p, config)
+
+        begin
+          # No eligible sessions: a run that says "we looked and it was clean"
+          # without paying a bill; markers untouched (re-scan, D10).
+          if sessions.empty?
+            @harvest_store.complete_run(run.id, candidates: 0)
+            return { mined: true, run_id: run.id, candidates: 0,
+                     rejected: empty_rejected, cost: nil }
+          end
+
+          prompt = build_prompt(config, sessions, agent)
+          result = miner.mine(prompt: prompt,
+                              message_counts: sessions.map { |s| s[:messages].size },
+                              max_proposals: max_proposals(p, config))
+
+          # The mining budget is a REAL cap (the review fix): a pass that
+          # spent more than the pack declared is failed with the numbers and
+          # proposes NOTHING — the docs' "the budget cap bounds it" is
+          # enforced here, post-hoc for the one model call, pre-hoc for every
+          # downstream write and gate.
+          if budget_exceeded?(budget_cap(config), result[:cost])
+            @harvest_store.fail_run(run.id, error: "mining budget exceeded: " \
+                                                 "spent #{result[:cost]['spent']} > " \
+                                                 "#{budget_cap(config)['tokens']}")
+            emit(:harvest_mined, agent: agent, run_id: run.id, candidates: 0,
+                                 rejected: empty_rejected, cost: result[:cost])
+            return { mined: true, run_id: run.id, candidates: 0,
+                     rejected: empty_rejected, cost: result[:cost] }
+          end
+
+          survivors, rejected = filter_skills(result[:skills], sessions, agent, grounding.matcher)
+
+          survivors.each do |skill|
+            @harvest_store.create_candidate(
+              run_id: run.id, agent: agent, name: skill["name"],
+              description: skill["description"], body: skill_md(skill),
+              triggers: skill["triggers"] || [], rationale: skill["rationale"].to_s,
+              origin: sessions.map { |s| s[:id] }, evidence_turns: skill["evidence_turns"] || [],
+              proposer: miner.model
+            )
+          end
+
+          final_rejected = merge_rejected(result[:dropped], rejected)
+          @harvest_store.complete_run(run.id, candidates: survivors.size,
+                                              cost: result[:cost],
+                                              rejected: final_rejected)
+          # Markers AFTER the pass completes (D10's crash-safe re-scan).
+          sessions.each { |s| @harvest_store.mark_mined(s[:id], candidates: survivors.size) }
+
+          emit(:harvest_mined, agent: agent, run_id: run.id, candidates: survivors.size,
+                               rejected: final_rejected, cost: result[:cost])
+          { mined: true, run_id: run.id, candidates: survivors.size,
+            rejected: final_rejected, cost: result[:cost] }
+        rescue StandardError => e
+          # The run is failed; the markers are NOT written (re-scan, D10);
+          # the exception propagates to the caller's fiber or the CLI.
+          begin
+            @harvest_store.fail_run(run.id, error: e.message)
+          rescue StandardError
+            nil
+          end
+          raise
+        end
+      end
+
+      private
+
+      def skip(reason)
+        { mined: false, skipped: reason }
+      end
+
+      # The pack's harvest.miner.budget as { "tokens" => N } — nil when
+      # absent/not positive (no cap, the refinement discipline).
+      def budget_cap(config)
+        raw = config && config.dig("miner", "budget")
+        raw.is_a?(Hash) && raw["tokens"].to_i.positive? ? { "tokens" => raw["tokens"].to_i } : nil
+      end
+
+      def budget_exceeded?(cap, cost)
+        cap && cost && cost["spent"].to_i > cap["tokens"].to_i
+      end
+
+      # The candidate's body is a full SKILL.md by construction: the model
+      # writes the procedure, the engine wraps the frontmatter (name /
+      # description / triggers — the miner's own fields), so a candidate is
+      # servable the moment a human promotes it (WriteSkill validates the
+      # frontmatter, and the gate's clone serves it the same way).
+      def skill_md(skill)
+        fm = { "name" => skill["name"], "description" => skill["description"] }
+        fm["triggers"] = Array(skill["triggers"]).join(", ") if Array(skill["triggers"]).any?
+        "---\n#{fm.map { |k, v| "#{k}: #{v}" }.join("\n")}\n---\n#{skill['body']}"
+      end
+
+      # The profile's own rules win over the injected seed (D4). A malformed
+      # profile list parses to nil — the injected list stays the fallback,
+      # never a silent empty.
+      def negative_list_for(config)
+        return @negative_list unless config && config["negative_list"]
+
+        Harvest::NegativeList.parse(config["negative_list"]) || @negative_list
+      end
+
+      def empty_rejected = { "schema" => 0, "unknown_key" => 0, "oversized" => 0,
+                             "bad_turns" => 0, "duplicate" => 0, "capped" => 0 }
+
+      def window_record(p)
+        return { "session_ids" => Array(p[:session_ids]).map(&:to_s) } if p[:session_ids]
+        return { "since" => p[:since].to_s } if AgentPayload.presence(p[:since])
+        return { "last_sessions" => Integer(p[:last_sessions]) } if p[:last_sessions]
+
+        {}
+      end
+
+      # The EvidenceCollector window discipline, applied to session ids: the
+      # agent's turns (by the task's command payload), distinct session ids,
+      # newest first, capped at the "last N conversations". Marker suppression
+      # unless `full` (a re-mine is explicit). A session's evidence ledger
+      #  is the grounding filter's input.
+      def resolve_sessions(agent, p, config)
+        ids = window_session_ids(agent, p, config)
+        ids = ids.reject { |sid| @harvest_store.mined?(sid) } unless EnvSchema.truthy?(p[:full])
+        ids = ids.first(Harvest::Miner::MAX_SESSIONS)
+
+        min_messages = (config["min_messages"] || DEFAULT_MIN_MESSAGES).to_i
+        idle_hours = (config["idle_hours"] || DEFAULT_IDLE_HOURS).to_i
+        ids.filter_map do |sid|
+          session = @session_store.find(sid)
+          next unless session
+
+          messages = session.messages.to_a
+          next if messages.size < min_messages # a 2-message session mines noise
+          # D10: the per-agent maturity bound is re-checked here — the engine
+          # scan's default is only the LOWER bound (a pack that wants 12 h is
+          # never mined at 6, and a manual CLI run over fresh traffic mines
+          # nothing).
+          next unless idle?(session.updated_at, idle_hours)
+
+          evidence = (session.evidence || {})["ids"] || []
+          { id: sid.to_s, messages: messages, evidence: Array(evidence).map(&:to_s) }
+        end
+      end
+
+      def window_session_ids(agent, p, config)
+        explicit = Array(p[:session_ids]).map(&:to_s)
+        return explicit unless explicit.empty?
+
+        since = AgentPayload.presence(p[:since])
+        tasks = @task_store.each_id
+                           .filter_map { |id| @task_store.find(id) }
+                           .select { |t| task_agent(t) == agent }
+                           .sort_by { |t| [t.created_at.to_s, t.id] }.reverse
+
+        tasks = tasks.select { |t| t.created_at.to_s >= since.to_s } if since
+
+        distinct = []
+        seen = {}
+        tasks.each do |t|
+          sid = presence(t.session_id)
+          next if sid.nil? || seen[sid]
+
+          seen[sid] = true
+          distinct << sid
+        end
+        return distinct if since
+
+        last = AgentPayload.presence(p[:last_sessions])
+        count = last ? Integer(last) : config_window(config)
+        distinct.first(count)
+      end
+
+      # The config's miner.window last_sessions, or the collector default.
+      def config_window(config)
+        configured = config.dig("miner", "window", "last_sessions")
+        configured ? Integer(configured) : DEFAULT_LAST_SESSIONS
+      end
+
+      def task_agent(task)
+        task.command.is_a?(Hash) ? task.command.dig("payload", "agent").to_s : ""
+      end
+
+      def idle?(updated_at, idle_hours)
+        return false if Coercion.blank?(updated_at)
+
+        Time.iso8601(updated_at.to_s) <= Time.now.utc - idle_hours * 3600
+      rescue ArgumentError
+        false
+      end
+
+      def presence(value)
+        Insika::Coercion.presence(value)
+      end
+
+      def max_proposals(p, config)
+        raw = p[:max_proposals] || config.dig("miner", "max_proposals")
+        raw ? Integer(raw) : DEFAULT_MAX_PROPOSALS
+      end
+
+      # The prompt: the transcript slices (masked through the   output
+      # filter — the   redaction rule), the evidence ids per
+      # session, the agent's CURRENT skill names (the model should not
+      # re-propose them), and the answer rules. The pack prompt replaces
+      # DEFAULT_PROMPT whole (the forge's half).
+      def build_prompt(config, sessions, agent)
+        base = Coercion.presence(config["prompt"]) || Harvest::DEFAULT_PROMPT
+        current_skills = current_skill_names(agent)
+        blocks = sessions.map do |s|
+          evidence = s[:evidence].join(", ")
+          lines = ["## Session #{s[:id]} (#{s[:messages].size} messages; " \
+                   "evidence ids: #{evidence.empty? ? '(none)' : evidence})"]
+          lines << render_transcript(s[:messages])
+          lines.join("\n")
+        end
+        <<~PROMPT
+          #{base.rstrip}
+
+          ## Conversations to mine
+
+          #{blocks.join("\n")}
+
+          ## Skills this agent already has (do not re-propose them)
+
+          #{current_skills.empty? ? "(none)" : current_skills.join(", ")}
+        PROMPT
+      end
+
+      def current_skill_names(agent)
+        return [] unless @skill_store
+
+        (@skill_store.names | @skill_store.names(agent: agent)).sort
+      end
+
+      def render_transcript(messages)
+        redacted, = Insika::Safety::Detectors.redact(
+          messages.each_with_index.map { |m, i| "[#{i}] #{m['role']}: #{m['content']}" }.join("\n")
+        )
+        redacted
+      end
+
+      # The safety order: negative list (D4) -> grounding (D3) -> dedup. A
+      # drop is COUNTED and NEVER written. `rejected` keys: the matched RULE
+      # ids for negative hits (each named — E2), "ungrounded"/"dedup" for the
+      # other two filters.
+      # -> [[raw skill], { key => count }]
+      def filter_skills(skills, sessions, agent, matcher)
+        rejected = Hash.new(0)
+        survivors = skills.select do |skill|
+          hits = negative_hits(skill)
+          if hits.any?
+            hits.each { |r| rejected[r.rule] += 1 }
+            false
+          elsif !grounded?(skill, sessions, matcher)
+            rejected["ungrounded"] += 1
+            false
+          elsif deduped?(skill, agent)
+            rejected["dedup"] += 1
+            false
+          else
+            true
+          end
+        end
+        [survivors, rejected.to_h]
+      end
+
+      # D4: every rejected-by-list candidate is logged with the matching rule
+      # id. The BODY is part of the match (the review fix): it is exactly what
+      # enters the model's context when the skill loads, so a banned phrase
+      # hidden there is the Hermes failure the design cites — the same text
+      # the grounding filter already reads (name+description+body). The name
+      # uses the stricter substring reading, the prose the word-boundary one.
+      def negative_hits(skill)
+        return [] unless @list
+
+        text = [skill["name"], skill["description"], skill["body"]].join(" ")
+        hits = @list.matches_name(skill["name"].to_s)
+        hits | @list.matches(text)
+      end
+
+      # D3: every reference must be in the union of the origin sessions'
+      # persisted evidence ids. The empty-ledger conservative reading (the
+      # enforcer's rule): a candidate whose origin sessions hold NO evidence
+      # ids and that carries a reference is dropped too. A skill with no
+      # references is not a grounding casualty. -> bool
+      def grounded?(skill, sessions, matcher)
+        text = [skill["name"], skill["description"], skill["body"]].join(" ")
+        refs = matcher.references(text)
+        return true if refs.empty?
+
+        union = sessions.flat_map { |s| s[:evidence] }.uniq
+        return false if union.empty?
+
+        missing = refs.reject { |r| union.include?(r) }
+        missing.empty?
+      end
+
+      # The dedup ledger: the same name already in the store's SkillStore
+      # (shared or agent scope) or an open (agent, name) tuple.
+      def deduped?(skill, agent)
+        name = skill["name"].to_s
+        store_has = @skill_store && (@skill_store.get(name) || @skill_store.get(name, agent: agent))
+        store_has || @harvest_store.open_pending?(agent: agent, name: name)
+      end
+
+      # The miner's schema drops + the filters' — one record; the keys never
+      # collide (the filters own rule ids and their own names).
+      def merge_rejected(dropped, filters)
+        dropped.merge(filters) { |_k, left, right| left + right }
+      end
+
+      def utility_model
+        return nil unless @settings_store
+
+        @settings_store.get["utility_model"]
+      end
+
+      def emit(type, **data)
+        @event_stream.emit(Insika::Event.new(
+                             type: type, data: data, meta: { at: Time.now.utc.iso8601 }
+                           ))
+      end
+    end
+  end
+end

data/lib/insika/commands/send_message.rb

@@ -20,12 +20,22 @@ module Insika
       # nil = no dedup (every surface that does not send an `event_id`, which is all
       # of them today), and a caller that cannot supply a stable id gets
       # at-least-once turns rather than a content hash pretending to be dedup.
-      def initialize(profiles:, session_store:, task_store:, executor:, inbound_log: nil)
+      #
+      # `contact_store`/`followup_store` : the contact-state hook —
+      # a customer message reopens the contact cell and a cancellation keyword
+      # revokes it + falls the pending records. nil = the hook is off (parity).
+      # `store` is the SHARED backend the two stores ride — the keyword revoke
+      # commits in ONE transaction (D2). nil = best-effort separate writes.
+      def initialize(profiles:, session_store:, task_store:, executor:, inbound_log: nil,
+                     contact_store: nil, followup_store: nil, store: nil)
         @profiles = ProfileSource.coerce(profiles)
         @session_store = session_store
         @task_store = task_store
         @executor = executor
         @inbound_log = inbound_log
+        @contact_store = contact_store
+        @followup_store = followup_store
+        @store = store
       end
 
       def call(command)
@@ -37,8 +47,15 @@ module Insika
         profile = @profiles[agent] ||
                   (raise Insika::NotFoundError, "agent '#{agent}' not configured")
 
+        # A turn is text OR media. The media half (WS9) is what a voice note
+        # with no caption looks like on the wire — `{ parts: [{type: "audio",
+        # url: …}] }` and nothing else — and demanding a message here made the
+        # anchor use case unreachable end to end: the audio becomes the message
+        # at the :media stage, one step later.
         message = p[:message]
-        raise Insika::ValidationError, "message is required and non-empty" if message.to_s.strip.empty?
+        if message.to_s.strip.empty? && !media?(p[:parts])
+          raise Insika::ValidationError, "message is required and non-empty (or a media part)"
+        end
 
         # session_id XOR history (both -> error; neither -> one-shot).
         if p[:session_id] && p[:history]
@@ -50,7 +67,14 @@ module Insika
         # is what a turn has always meant. Refused here rather than downstream: a
         # typo'd origin would read as absent, and a marker that silently means
         # "unmarked" is worse than none — it looks like the filtering is on.
-        Insika::MessageOrigin.parse!(p[:origin])
+        origin = Insika::MessageOrigin.parse!(p[:origin])
+        # `scheduled` is ENGINE-RESERVED — the FollowupEngine's
+        # synthetic turn stamps it, and the edge must not let a consumer
+        # impersonate the engine's kick (a spoofed follow-up is the spam bug).
+        if origin == Insika::MessageOrigin::SCHEDULED
+          raise Insika::ValidationError,
+                "origin 'scheduled' is engine-reserved: it is stamped by the follow-up engine only"
+        end
         if p[:session_id]
           @session_store.find(p[:session_id]) ||
             (raise Insika::NotFoundError, "session '#{p[:session_id]}' not found")
@@ -66,6 +90,14 @@ module Insika
           return { task_id: prior, duplicate: true }
         end
 
+        # the contact-state hook — the ONLY path that sees every
+        # customer message. A real customer message reopens the contact cell; a
+        # cancellation keyword revokes it and falls the pending records in ONE
+        # transaction. Runs AFTER validation and dedup: a refused or duplicated
+        # message must not touch contact state. Nil-safe and policy-gated: no
+        # profile declaration = the hook is off (parity).
+        touch_contact(p, profile, command, origin)
+
         result = start_turn(command, p, profile)
         @inbound_log.record(key, result[:task_id]) if key
         result
@@ -73,6 +105,41 @@ module Insika
 
       private
 
+      # the contact bookkeeping of a customer message. The
+      # keyword cast IS a revocation: the customer just said the shut-off
+      # words — the pending records must fall with the state (D2, ONE
+      # transaction). The reset-on-origin list: only an origin that is
+      # nil/customer acts — an engine/operator-composed line (even one QUOTING
+      # the customer's words) never touches contact state. Nil collaborators
+      # or no profile declaration = the hook is a no-op (byte-parity).
+      def touch_contact(p, profile, command, origin)
+        return unless @contact_store
+        return unless origin.nil? || origin == Insika::MessageOrigin::CUSTOMER
+
+        policy = Insika::FollowupPolicy.parse(profile.followup)
+        return unless policy
+
+        customer = p[:customer]
+        return if customer.to_s.empty?
+
+        keyword = policy.match_keyword(p[:message].to_s)
+        if keyword
+          # one transaction on the shared backend: the revoke and the pending
+          # fall commit together — a half-cancelled opt-out is the spam bug.
+          if @store
+            @store.transaction do
+              @contact_store.set_revoked(tenant: command.meta[:tenant], customer: customer)
+              @followup_store&.cancel_pending_for(tenant: command.meta[:tenant], customer: customer)
+            end
+          else
+            @contact_store.set_revoked(tenant: command.meta[:tenant], customer: customer)
+            @followup_store&.cancel_pending_for(tenant: command.meta[:tenant], customer: customer)
+          end
+        else
+          @contact_store.set_granted(tenant: command.meta[:tenant], customer: customer)
+        end
+      end
+
       # The turn (or the verdict that this message joined someone else's).
       def start_turn(command, p, profile)
         message = p[:message]
@@ -83,7 +150,10 @@ module Insika
         # boot). Only offered on a surface that can report the verdict back —
         # coalescing a caller that cannot hear `merged` makes it deliver the
         # same answer twice.
-        if coalescable?(command)
+        # A message carrying MEDIA never joins another turn: `collect`/`steer`
+        # move TEXT into a task that is already at the door, and its parts would
+        # be left behind — the customer's photo would silently not exist.
+        if coalescable?(command) && !media?(p[:parts])
           if (joined = @executor.collect_into_pending(p[:session_id], message, profile: profile))
             return { task_id: joined, merged: true }
           end
@@ -101,16 +171,41 @@ module Insika
         # command.to_h persists the entire Command in the Task;
         # ResumeTask re-reads payload.message from there.
         task = @task_store.create(command: command.to_h, session_id: p[:session_id])
+        # the channel clock starts HERE — the 202-owning request
+        # is accepted, before the SessionActor FIFO and the debounce window.
+        # `first_balloon_ms` is the wait the customer feels, so t0 is not the
+        # moment the turn finally runs; the same object travels with the turn
+        # and `:first_balloon` closes the window at the outbox flush.
         # `interrupt` mode: the turn in flight is now answering the wrong
         # question, so it is abandoned at its next boundary. This message keeps its OWN
         # task and its own reply (that is why it needs no verdict and no surface gate), and
         # the cancel is posted after `create` so the event can name what replaced what.
         # No-op in every other mode.
         @executor.interrupt_running(p[:session_id], profile: profile, replaced_by: task.id)
-        @executor.spawn_in_session(task, profile: profile)
+        @executor.spawn_in_session(task, profile: profile,
+                                          timing: channel_inbound_timing(command))
         { task_id: task.id }
       end
 
+      # allocate the channel clock at 202 acceptance and stamp
+      # `:inbound` — the window's start. `breakdown: false` when INSIKA_TURN_TIMING
+      # is off, so a channel turn measures ONLY first_balloon_ms (H-latência never
+      # depends on the flag). nil for every non-channel transport: no clock to start.
+      def channel_inbound_timing(command)
+        return nil unless command.meta[:transport].to_s.start_with?("channel:")
+
+        timing = Insika::TurnTiming.new(breakdown: Insika::TurnTiming.enabled?)
+        timing.mark(:inbound)
+        timing
+      end
+
+      # Does the payload carry a part the engine will turn into the turn's
+      # substance — audio (transcribed into the message) or an image (attached
+      # to the ask)? A text part is not media: it is the message, spelled long.
+      def media?(parts)
+        Insika::Media.parts(parts).any? { |p| p.audio? || p.image? }
+      end
+
       def coalescable?(command)
         transport = command.meta[:transport]
         COALESCABLE_TRANSPORTS.include?(transport) || transport.to_s.start_with?("channel:")
@@ -133,7 +228,9 @@ module Insika
           session_id: payload[:session_id] || payload["session_id"],
           history: payload[:history] || payload["history"],
           origin: payload[:origin] || payload["origin"],
-          event_id: payload[:event_id] || payload["event_id"]
+          event_id: payload[:event_id] || payload["event_id"],
+          parts: payload[:parts] || payload["parts"],
+          customer: payload[:customer] || payload["customer"]
         }
       end
 

data/lib/insika/commands/session_purge.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Insika
+  module Commands
+    # The CONVERSATION footprint of a session, purged (WS8/LGPD). Shared by
+    # `forget_customer` and `delete_tenant_data` because "erase this person"
+    # and "erase this tenant" differ only in WHICH sessions they name — what a
+    # session leaves behind is the same list, and a second copy of that list is
+    # a second thing to forget to update.
+    #
+    # Deleting the session record alone is NOT erasure: the customer's own text
+    # lives in the task's persisted command payload, the whole transcript lives
+    # in the turn's checkpoints, and the answer as it was handed to the channel
+    # lives in the outbox record's payload. All four go together or none of them
+    # counts.
+    #
+    # A task is deleted whatever its status — this is a deletion order, not the
+    # retention sweep (which spares live tasks on purpose). The stores it needs
+    # beyond the session are optional (deployment components): a graph without
+    # them purges what it has and reports zero for the rest.
+    module SessionPurge
+      # ids: the session ids to erase. -> { tasks:, checkpoints:, deliveries:, pairs: }
+      def purge_sessions(ids)
+        ids = Array(ids).map(&:to_s)
+        return { tasks: 0, checkpoints: 0, deliveries: 0, pairs: 0 } if ids.empty?
+
+        tasks, checkpoints, model_visible = purge_tasks_of(ids)
+        deliveries = @outbox_store ? @outbox_store.purge_sessions(ids) : 0
+        pairs = @shadow_pairs ? @shadow_pairs.purge_sessions(ids) : 0
+        ids.each do |id|
+          @tool_trace_store&.clear(id)
+          @context_trace_store&.clear(id)
+          @session_store.delete(id)
+        end
+        { tasks: tasks, checkpoints: checkpoints, model_visible: model_visible,
+          deliveries: deliveries, pairs: pairs }
+      end
+
+      private
+
+      # -> [tasks removed, checkpoint records removed, model-visible records removed].
+      # the model-visible traces are transcripts — they die next to
+      # their checkpoints (the same single list, so "erase this person" cannot
+      # forget one half). The id list is SNAPSHOTTED (`to_a`) before the deletes:
+      # `each_id` enumerates the backend's keys lazily, and deleting under it
+      # would skip records.
+      def purge_tasks_of(ids)
+        return [0, 0, 0] unless @task_store
+
+        wanted = ids.each_with_object({}) { |id, acc| acc[id] = true }
+        tasks = 0
+        checkpoints = 0
+        model_visible = 0
+        @task_store.each_id.to_a.each do |task_id|
+          task = @task_store.find(task_id)
+          next unless task && wanted[task.session_id.to_s]
+
+          checkpoints += @checkpoint_store ? @checkpoint_store.purge(task_id) : 0
+          model_visible += @model_visible_trace_store ? @model_visible_trace_store.purge(task_id) : 0
+          @task_store.delete(task_id)
+          tasks += 1
+        end
+        [tasks, checkpoints, model_visible]
+      end
+    end
+  end
+end