insika 0.2.0 → 0.3.0

data/lib/insika/agent_profile.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "coercion"
+require_relative "tool_definition"
 
 module Insika
   # Single point of per-agent policy.
@@ -63,6 +64,14 @@ module Insika
     #                                   a context provider injecting volatile content into
     #                                   :system turns every turn into a paid cache WRITE with
     #                                   no read hit. Enable only for stable-system agents.
+    :tool_persistence,                # the engine's "Tool discipline" block in the system
+    #                                   prompt (retry weak/empty tool results with a different
+    #                                   approach before giving up). THE ONE OPT-OUT FIELD:
+    #                                   nil/true = ON (the proven default — every reference
+    #                                   harness ships it), false = OFF. Deliberately inverted
+    #                                   from the opt-in fields above: the exception here is
+    #                                   turning the good behavior OFF, so that is what an
+    #                                   operator declares. Read by Context::Providers::Prompt.
     :tool_output_compression,          # MECHANICAL tool-result dedupe in the replayed
     #                                   history (A3/C3): nil/false = OFF (parity); true = ON.
     #                                   Same opt-in as `memory`. When ON, the history the
@@ -103,6 +112,14 @@ module Insika
     #                                   breaker_open / delivery_failed events are POSTed to
     #                                   the URL as JSON (outbox + claim, at-most-once).
     #                                   nil/absent = no webhook (parity).
+    :routes,                          # intent routing (WS4): { "route" => "description" or a
+    #                                   Hash with description/delegate/stuck/message,
+    #                                   "default" => route, "model" => cheap classifier }.
+    #                                   When present, the message is classified BEFORE the
+    #                                   ask with the cheap model; the route lands on the
+    #                                   turn (state.route + :route_classified) and may
+    #                                   delegate to an existing agent or end the turn :stuck
+    #                                   (WS5). nil/absent = no routing (parity).
     :stuck_signal,                    # the agent may signal it cannot proceed (WS5):
     #                                   nil/false = OFF (parity — the signal_stuck system
     #                                   tool is not wired); true = ON (the model may call
@@ -111,6 +128,19 @@ module Insika
     #                                   event the consumer acts on). Same opt-in as
     #                                   `memory`. What "stuck" MEANS is the consumer's call
     #                                   (escalation via CRM/operator), never the engine's.
+    :outputs,                         # generated-media output policy (WS9, saída):
+    #                                   { "image" => { "model" => …, "size" => "1024x1024" },
+    #                                   "tts" => { "model" => "tts-1", "voice" => "alloy",
+    #                                   "format" => "mp3" } }. THE AGENT'S HALF of the
+    #                                   media-output gate — nil/absent = the agent never
+    #                                   generates media (opt-in like `capabilities`, do NOT
+    #                                   "fix" to nil = all). The other half is the CHANNEL'S:
+    #                                   the request must declare it can receive the media
+    #                                   (`channel.capabilities` — "image_output" /
+    #                                   "audio_output"); only with BOTH does the model see
+    #                                   the generate_image/tts tools (the abstraction admits
+    #                                   only what leaks). Generated media rides the turn's
+    #                                   `output_parts` in the envelope, never the answer text.
     :model_policy,                    # governance of WHICH models the agent may use:
     #                                   { "allow" => [refs] }. nil = NO fence (all models —
     #                                   parity). Enforced on the RESOLVED model (ModelResolver).
@@ -162,10 +192,72 @@ module Insika
     #                                   (WhatsApp) puts the deliberation in front of a
     #                                   customer; that is the operator's call to make, not a
     #                                   default to inherit.
-    :metadata                         # free-form agent metadata, stable per agent
-    #                                   (from the pack `agent.config.json`). Home of the `store_id`
-    #                                   that becomes turn context (ctx.store_id).
-    #                                   It is NOT a policy — never decides security. {} = absent.
+    :grounding,                     # the pack's grounding policy —
+    #                                   { "mode" => "flag"|"enforce"|"off",
+    #                                   "matcher" => { "sku" => …,
+    #                                   "name_keys" => [...] } }. OPT-IN:
+    #                                   nil/absent = OFF (parity, zero allocations).
+    #                                   Deep-stringified like the other hashes.
+    :metadata,                      # free-form agent metadata, stable per agent
+                                   # (from the pack `agent.config.json`). Home of the `store_id`
+                                   # that becomes turn context (ctx.store_id).
+                                   # It is NOT a policy — never decides security. {} = absent.
+    :briefing_fields,                # the per-session working-state schema this agent
+                                   # keeps and asks for: a flat [String] of
+                                   # field names the pack declares. []/nil/absent = the
+                                   # feature is OFF (no provider output, no tools — visibly
+                                   # removable). Names are engine-owned store keys
+                                   # and tool text, so they are validated against NAME_RE at
+                                   # build time. Data, never a policy: the engine owns the
+                                   # briefing object, the pack owns the fields.
+    :funnel,                         # the outcome funnel declaration — pack
+                                   # data, exactly like budget/reliability:
+                                   # { "stages" => ["greeted", "qualified", "cart", "paid"],
+                                   #   "advance_on" => { "pix_paid" => "paid", … },
+                                   #   "primary" => "paid", "attribution_window" => "72h" }.
+                                   # The ENGINE never hard-codes a stage name: the fold,
+                                   # the doctor and the Studio read this declaration (D1).
+                                   # nil/absent = no funnel (parity — nothing folds).
+                                   # Deep-stringified like the other free-form hashes;
+                                   # shape-validated by FunnelDeclaration, never here (D8).
+    :followup,                       # the follow-up declaration — pack data,
+                                   # exactly like budget/funnel:
+                                   # { "arm" => "schedule",
+                                   #   "policy" => { "quiet_hours" => { "timezone" => "…",
+                                   #       "start" => "21:30", "end" => "09:00" },
+                                   #     "max_frequency" => "2/24h",
+                                   #     "cancel_keywords" => ["não quero mais contato"],
+                                   #     "silence_after_sends" => 3 } }.
+                                   # The engine OWNS the firing, never a policy value (D1);
+                                   # shape-validated by FollowupPolicy, never here (D9).
+                                   # nil/absent = the feature is off (parity).
+                                   # Deep-stringified like the other free-form hashes.
+    :distill,                        # the session-distillation declaration — pack
+                                   # data, exactly like refinement/followup:
+                                   # { "enabled" => bool, "prompt" => "<pack-authored markdown
+                                   #   — what counts as a fact for this store>",
+                                   #   "model" => "<ref — absent = the platform utility_model>",
+                                   #   "idle_hours" => 6, "min_messages" => 3,
+                                   #   "max_proposals" => 10 }.
+                                   # The ENGINE assembles the scope from the session; the
+                                   # model only names facts (D1). nil/absent = the feature is
+                                   # off (parity, byte-identical engine). Shape-validated by
+                                   # the command/engine, never here (the refinement precedent).
+                                   # Deep-stringified like the other free-form hashes.
+    :harvest                         # the gated-harvest declaration — pack data,
+                                   # exactly like refinement/distill:
+                                   # { "enabled" => bool,
+                                   #   "negative_list" => [ { "rule" => "…", "pattern" => "…",
+                                   #                          "note" => "…" } ],
+                                   #   "miner" => { "model" => "<ref — absent = the platform
+                                   #       utility_model>", "window" => { "last_sessions" => N },
+                                   #       "max_proposals" => N, "budget" => { "tokens" => N } },
+                                   #   "idle_hours" => 24, "min_messages" => 3 }.
+                                   # The ENGINE mines (reads sessions, asks the miner, filters
+                                   # through the negative list + grounding), never authors a
+                                   # rule (D4). nil/absent = the loop is off (parity).
+                                   # Shape-validated by the command/engine/doctor, never here.
+                                   # Deep-stringified like the other free-form hashes.
   )
 
   # Reopened class (not a Data.define block): a constant assigned inside
@@ -193,10 +285,12 @@ module Insika
                    skills_eager: nil, context_providers: nil, workflows_allow: nil,
                    policies: [], prompt_refs: [], limits: {}, approvals_required: nil,
                    capabilities: nil, subagents: nil, tools_deferred: nil, memory: nil,
-                   prompt_caching: nil, tool_output_compression: nil,
-                   params: {}, model_policy: nil, guardrails: nil, sandbox: nil,
-                   refinement: nil, capabilities_declared: nil, edge_stream: nil, metadata: {},
-                   budget: nil, reliability: nil, alerts: nil, stuck_signal: nil)
+                   prompt_caching: nil, tool_persistence: nil, tool_output_compression: nil,
+                    params: {}, model_policy: nil, guardrails: nil, sandbox: nil,
+                    refinement: nil, capabilities_declared: nil, edge_stream: nil, metadata: {},
+                     budget: nil, reliability: nil, alerts: nil, routes: nil, stuck_signal: nil,
+                     outputs: nil, briefing_fields: nil, grounding: nil, funnel: nil,
+                     followup: nil, distill: nil, harvest: nil)
       new(
         id: id, model: model, provider: provider, base_prompt: base_prompt,
         prompt_files: Array(prompt_files), tools_allow: tools_allow,
@@ -210,7 +304,8 @@ module Insika
         # readers get a clean [] and the ChatBuilder gate (present? => wire) is stable.
         subagents: subagents.nil? ? nil : Array(subagents).map(&:to_s),
         tools_deferred: tools_deferred, memory: memory,
-        prompt_caching: prompt_caching, tool_output_compression: tool_output_compression,
+        prompt_caching: prompt_caching, tool_persistence: tool_persistence,
+        tool_output_compression: tool_output_compression,
         # The free-form hashes arrive with symbol keys (internal build) OR string
         # keys (StoredProfileSource JSON round-trip). Normalize to string keys ONCE
         # here — the single front door every profile passes through — so no reader
@@ -228,10 +323,50 @@ module Insika
         budget: Coercion.deep_stringify(budget),
         reliability: Coercion.deep_stringify(reliability),
         alerts: Coercion.deep_stringify(alerts),
-        stuck_signal: stuck_signal
+        routes: Coercion.deep_stringify(routes),
+        stuck_signal: stuck_signal,
+        outputs: Coercion.deep_stringify(outputs),
+        # Flat [String] — same discipline as capabilities_declared: a
+        # symbol/string mix would be a silent miss in the provider's known-set.
+        briefing_fields: normalize_briefing_fields(briefing_fields),
+        # grounding is profile DATA, deep-stringified like the other
+        # free-form hashes; parsed into a Grounding per turn by the validator/
+        # enforcer. nil = off (parity).
+        grounding: Coercion.deep_stringify(grounding),
+        # funnel is profile DATA, deep-stringified like the other
+        # free-form hashes; parsed into a FunnelDeclaration by the fold/doctor/
+        # Studio (shape-validated THERE, never here — D8). nil = no funnel (parity).
+        funnel: Coercion.deep_stringify(funnel),
+        # followup is profile DATA, deep-stringified like the other
+        # free-form hashes; parsed into a FollowupPolicy by the tool/engine/
+        # doctor/Studio (shape-validated THERE, never here — D9). nil = off (parity).
+        followup: Coercion.deep_stringify(followup),
+        # distill is profile DATA, deep-stringified like the other
+        # free-form hashes; shape-validated by the command/engine/doctor
+        # (never here — the refinement precedent). nil = off (parity).
+        distill: Coercion.deep_stringify(distill),
+        # harvest is profile DATA, deep-stringified like the other
+        # free-form hashes; shape-validated by the command/engine/doctor
+        # (never here — the refinement precedent). nil = off (parity).
+        harvest: Coercion.deep_stringify(harvest)
       )
     end
 
+    # nil -> []; strings; trim + drop empties + uniq (stable order); every name
+    # must match ToolDefinition::NAME_RE (\A[a-z][a-z0-9_]*\z) or it is a
+    # ValidationError at build time — the names become tool-description text,
+    # store keys and context-block lines, so "size ok" or "tamanho do cliente"
+    # is refused here, not corrupted later.
+    def self.normalize_briefing_fields(list)
+      names = Array(list).map { |f| f.to_s.strip }.reject(&:empty?).uniq
+      bad = names.reject { |n| ToolDefinition::NAME_RE.match?(n) }
+      unless bad.empty?
+        raise Insika::ValidationError,
+              "briefing_fields must match #{ToolDefinition::NAME_RE.inspect}: #{bad.join(', ')}"
+      end
+      names
+    end
+
     # opt-in for an optional tool = being in the agent's allow list.
     def tool_opted_in?(name)
       Array(tools_allow).include?(name)

data/lib/insika/balloon_splitter.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Insika
+  #   — pure: confirmed answer text -> the balloons a progressive
+  # channel should POST. Paragraphs are the unit (`\n\n` is the seam E1 cares
+  # about); the sentence split fires only as a SOFT cap for one paragraph that
+  # grew past `SENTENCE_AFTER`. It never splits inside a fenced code block.
+  #
+  # No events, no outbox, no `:intermediate` — if it is handed loop narration
+  # that is a caller bug; the splitter has no way to tell.
+  module BalloonSplitter
+    # Soft cap after which a single paragraph is split on sentences. WhatsApp's
+    # hard cap is ~4096; this is a readability cap, not a platform one.
+    SENTENCE_AFTER = 600
+
+    module_function
+
+    # -> [String], at least one when `text` is non-blank, else [].
+    def split(text)
+      raw = Insika::Coercion.presence(text)
+      return [] if raw.nil?
+
+      paragraphs = raw.split(PARAGRAPH_BREAK)
+      balloons = group_fenced(paragraphs)
+      balloons.flat_map { |balloon| split_long(balloon) }
+    end
+
+    # A fenced code block (` ``` ` … ` ``` `) spans paragraphs and stays ONE
+    # balloon — newlines inside it are code, not a seam. A fence that never
+    # closes still ends as one balloon (garbage in, one balloon out).
+    def group_fenced(paragraphs)
+      balloons = []
+      fence = nil
+      paragraphs.each do |para|
+        piece = para.strip
+        next if piece.empty?
+
+        if fence
+          fence << piece
+          # a line starting with ``` closes the block, wherever it lands — the
+          # close fence of ordinary markdown shares a paragraph with its code.
+          if closes_fence?(piece)
+            balloons << fence.join("\n\n")
+            fence = nil
+          end
+        elsif piece.lines.first.to_s.start_with?(FENCE)
+          fence = [piece]
+          # one paragraph may open AND close the block (```ruby\nx = 1\n```) —
+          # the closer is a later line of the same piece.
+          if closes_fence?(piece, opener: true)
+            balloons << fence.join("\n\n")
+            fence = nil
+          end
+        else
+          balloons << piece
+        end
+      end
+      balloons << fence.join("\n\n") if fence
+      balloons
+    end
+
+    # Does this paragraph close an open fence? Any line starting with the fence
+    # marker counts. `opener: true` skips the FIRST line — the line that opened
+    # the block, which cannot be its own closer.
+    def closes_fence?(piece, opener: false)
+      lines = piece.lines
+      lines[(opener ? 1 : 0)..].any? { |line| line.start_with?(FENCE) }
+    end
+
+    # The soft cap: a paragraph longer than SENTENCE_AFTER splits after sentence
+    # closers followed by whitespace — which is why `3.9s` and `www.` survive
+    # (their period is not followed by whitespace) and a decimal does too. A
+    # leftover without a closer stays one balloon.
+    #
+    # Sentences are then RE-GROUPED into ~SENTENCE_AFTER blocks (
+    # the split is a cap, not a mandate). Without the regroup, a 680-char
+    # paragraph of short sentences would atomize into one balloon per sentence —
+    # a paragraph that was ONE bubble becomes 40 WhatsApp messages for no
+    # latency win.
+    def split_long(balloon)
+      return [balloon] if balloon.length <= SENTENCE_AFTER
+
+      parts = balloon.split(SENTENCE_BOUNDARY).map(&:strip).reject(&:empty?)
+      return [balloon] if parts.empty?
+
+      parts.each_with_object([+""]) do |sentence, balloons|
+        if balloons.last.empty?
+          balloons.last << sentence
+        elsif balloons.last.length + sentence.length + 1 <= SENTENCE_AFTER
+          balloons.last << " #{sentence}"
+        else
+          balloons << +sentence
+        end
+      end
+    end
+
+    PARAGRAPH_BREAK = /\n\s*\n+/
+    FENCE = "```"
+    SENTENCE_BOUNDARY = /(?<=[.!?…])\s+(?=\S)/
+    private_constant :PARAGRAPH_BREAK, :FENCE, :SENTENCE_BOUNDARY
+  end
+end

data/lib/insika/budget_ledger.rb

@@ -18,9 +18,11 @@ module Insika
   # BEGIN IMMEDIATE: no lost update. No enforcement here — the middleware is
   # WS2; this file is only correct accounting.
   #
-  # Growth is bounded like UsageLedger: each `add` deletes the (id)'s previous
-  # day AND previous month cell, so an active scope holds at most 4 keys and an
-  # idle one converges to 2.
+  # Growth is bounded on the hot path AND swept: each `add` deletes the (id)'s
+  # previous day and previous month cell (an ACTIVE scope holds at most 4 keys),
+  # and `prune` — the daily sweep on the tick — drops everything else: the cells
+  # of an id that went idle for more than one window and the alert flags, which
+  # the hot path never collects.
   class BudgetLedger
     SCOPE = "budget_counters"
     ALERT_SCOPE = "budget_alerts"
@@ -87,6 +89,25 @@ module Insika
       !@store.get(ALERT_SCOPE, alert_key(cell_id(tenant, agent), window, now, level)).nil?
     end
 
+    # The GC of both scopes: drops every cell whose window is not the CURRENT
+    # one. `add`'s two deletes only reach the IMMEDIATELY previous day/month, so
+    # a scope that goes idle for two days leaves its counter behind forever, and
+    # the alert flags were never collected at all — unbounded row growth the WS8
+    # retention sweep does not reach (that one is age-based over CONTENT; these
+    # are counters with no timestamp). Every key of both scopes ENDS in its
+    # bucket, so one rule sweeps both. -> count of cells removed.
+    def prune(now: Time.now)
+      day = daily_bucket(now)
+      month = month_bucket(now)
+      @store.transaction do
+        [SCOPE, ALERT_SCOPE].sum do |scope|
+          stale = @store.list(scope).select { |k| past?(k.rpartition(":").last.to_i, day, month) }
+          stale.each { |k| @store.delete(scope, k) }
+          stale.size
+        end
+      end
+    end
+
     private
 
     # No tenant (single_tenant default) is a LITERAL "platform" cell, never a
@@ -95,6 +116,16 @@ module Insika
       [tenant || "platform", agent].join(":")
     end
 
+    # Is that bucket a window STRICTLY BEHIND the live one? The two kinds of
+    # bucket cannot collide — an epoch-day is a multiple of 86_400 (~1.7e9), a
+    # calendar month is year*12+month (~24e3) — so the magnitude tells them
+    # apart. STRICTLY behind, never "not the current one": a host whose clock
+    # runs minutes ahead writes tomorrow's cell around midnight, and a sweeper
+    # that deleted it would hand that tenant a fresh day of budget.
+    def past?(bucket, day, month)
+      bucket >= DAY ? bucket < day : bucket.positive? && bucket < month
+    end
+
     def bump(id, bucket, by)
       total = @store.get(SCOPE, key(id, bucket)).to_i + by
       @store.set(SCOPE, key(id, bucket), total)

data/lib/insika/cache_series_store.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Insika
+  #   — per-AGENT cache-hit series (scope "cache_series"), for the
+  # Studio agent-detail plot. Sessions do not stamp their agent, so the
+  # per-session context trace cannot answer "cache-hit over time for THIS
+  # agent"; this capped list can. Entries are counts and a category name only —
+  # PII-free by construction. No retention hook: the cap bounds growth.
+  class CacheSeriesStore
+    SCOPE = "cache_series"
+    MAX_PER_AGENT = 200 # oldest dropped; one entry per turn, so 200 is a
+    # rolling window, not a leak path
+
+    def initialize(store:)
+      @store = store
+    end
+
+    # Appends a sanitized entry for the agent; caps. Rescues everything — the
+    # series never breaks the turn.
+    def record(agent:, entry:)
+      return if agent.to_s.empty?
+
+      list = (@store.get(SCOPE, agent.to_s) || []) + [sanitize(entry)]
+      @store.set(SCOPE, agent.to_s, list.last(MAX_PER_AGENT))
+    rescue StandardError
+      nil
+    end
+
+    # -> [Hash] the agent's series, chronological. [] if none.
+    def for_agent(agent) = @store.get(SCOPE, agent.to_s) || []
+
+    private
+
+    def sanitize(entry)
+      e = entry.is_a?(Hash) ? entry : {}
+      {
+        "at" => (e[:at] || e["at"])&.to_s,
+        "turn" => int(e[:turn] || e["turn"]),
+        "hit_pct" => int_or_nil(e[:hit_pct] || e["hit_pct"]),
+        "cached_tokens" => int(e[:cached_tokens] || e["cached_tokens"]),
+        "prompt_tokens" => int(e[:prompt_tokens] || e["prompt_tokens"]),
+        "invalidation_reason" => (e[:invalidation_reason] || e["invalidation_reason"])&.to_s
+      }
+    end
+
+    def int(value) = Integer(value || 0)
+    def int_or_nil(value) = value.nil? ? nil : Integer(value)
+  end
+end

data/lib/insika/channel_delivery.rb

@@ -26,7 +26,8 @@ module Insika
     BACKOFF_SECONDS = [1, 5].freeze
 
     def initialize(channels:, outbox:, session_store:, event_stream: nil,
-                   max_attempts: MAX_ATTEMPTS, backoff: BACKOFF_SECONDS, sleeper: nil)
+                   max_attempts: MAX_ATTEMPTS, backoff: BACKOFF_SECONDS, sleeper: nil,
+                   shadow_pairs: nil, criterion_sha: nil)
       @channels = channels
       @outbox = outbox
       @session_store = session_store
@@ -34,29 +35,66 @@ module Insika
       @max_attempts = max_attempts
       @backoff = Array(backoff)
       @sleeper = sleeper || method(:default_sleep)
+      @shadow_pairs = shadow_pairs
+      @criterion_sha = criterion_sha
     end
 
-    # The turn committed an answer. -> the Delivery to dispatch, or nil when there
-    # is nothing to deliver, which is the common case and must stay cheap:
+    # the pair store and the frozen criterion's sha. Both default to
+    # nil (parity — a graph without them behaves exactly as today); the server
+    # root sets them at boot, after the criterion file has been loaded and
+    # refused-or-accepted (the graph itself reads no env and no file).
+    attr_writer :shadow_pairs, :criterion_sha
+
+    # Confirmed answer -> 0..N pending Deliveries, in order .
+    # A progressive channel splits on paragraphs (BalloonSplitter); everything
+    # else is the single whole-answer row.
+    # -> [] when there is nothing to send (the cheap exits):
     #   · the turn did not come in through a channel,
     #   · the channel is Shape A (answers on its own stream — no `deliver`),
     #   · the answer is empty (a turn that died mid-message published nothing, and
     #     half a sentence was never an answer),
+    #   · the channel is in SHADOW mode: the answer is recorded as a
+    #     pair and nothing is dispatched — zero outbox writes, ever (E1),
     #   · or we do not know who to send it to.
-    def record(task:, channel_id:, content:)
-      return nil if content.to_s.strip.empty?
-
+    #
+    # `attachments` (evidence cards) ride the outbox payload as an
+    # ADDITIVE key on the LAST balloon — a Shape B channel that reads `payload`
+    # ignores it (JSON contract, additive); one that renders cards consumes it.
+    def record_balloons(task:, channel_id:, content:, progressive:, attachments: nil)
       channel = @channels&.find(channel_id)
-      return nil unless channel.respond_to?(:deliver)
+      return [] unless channel.respond_to?(:deliver)
+      # Shadow records ONE pair for the whole answer — a balloon per paragraph
+      # would mint N pairs for one turn.
+      if shadow?(channel)
+        record_shadow(task, channel_id, content)
+        return []
+      end
+
+      return [] if content.to_s.strip.empty?
 
       to = recipient(channel, task.session_id)
-      return nil if to.nil? || to.empty?
+      return [] if to.nil? || to.empty?
+
+      parts = progressive ? Insika::BalloonSplitter.split(content) : [content.to_s]
+      parts = parts.reject { |p| p.to_s.strip.empty? }
+      return [] if parts.empty?
+
+      multi = parts.size > 1
+      parts.each_with_index.map do |part, i|
+        last = i == parts.size - 1
+        create_pending(task, channel_id, part, to,
+                       index: multi ? i : nil, final: multi ? last : nil,
+                       attachments: last ? attachments : nil)
+      end
+    end
+
+    def shadow?(channel) = channel.respond_to?(:shadow?) && channel.shadow?
 
-      @outbox.create(
-        channel: channel_id, to: to, task_id: task.id, session_id: task.session_id,
-        payload: { "session_id" => task.session_id.to_s, "task_id" => task.id.to_s,
-                   "content" => content.to_s }
-      )
+    # does this channel flush progressively? Duck-typed — a channel
+    # that does not answer `progressive?` is `:at_end`.
+    def progressive?(channel_id)
+      channel = @channels&.find(channel_id)
+      channel.respond_to?(:progressive?) && channel.progressive?
     end
 
     # Claim + POST + bounded retry. Safe to call twice: the second caller loses the
@@ -90,6 +128,73 @@ module Insika
 
     private
 
+    # One outbox row for a confirmed balloon. `index`/`final` ride the payload
+    # only when non-nil — a single-balloon progressive turn is indistinguishable
+    # from an `:at_end` one on the wire. `index` also lands on the RECORD, which
+    # is what the boot sweep orders by. `attachments` :
+    # validated for the outbox — malformed entries dropped, never a turn failure.
+    def create_pending(task, channel_id, content, to, index: nil, final: nil, attachments: nil)
+      payload = { "session_id" => task.session_id.to_s, "task_id" => task.id.to_s,
+                  "content" => content.to_s }
+      payload["index"] = index if index
+      payload["final"] = final unless final.nil?
+      atts = Insika::Evidence.valid_attachments(attachments)
+      payload["attachments"] = atts unless atts.empty?
+      @outbox.create(channel: channel_id, to: to, task_id: task.id, session_id: task.session_id,
+                     payload: payload, index: index.to_i)
+    end
+
+    # Our half of the shadow pair (C3). One store upsert on the turn's terminal,
+    # then nil — `Executor#finalize_channel_delivery` returns without dispatching.
+    # The ordering rules: no event_id -> :shadow_unpairable (C1 makes this
+    # unreachable through the relay; a plugin channel could still get it wrong);
+    # no pair store wired -> the same event (fail-closed, nothing delivered);
+    # no recipient -> the same event (a pair keyed on an empty external_id can
+    # never meet the mirror's half).
+    def record_shadow(task, channel_id, content)
+      command = task.respond_to?(:command) ? task.command : nil
+      payload = command.is_a?(Hash) ? (command["payload"] || command[:payload] || {}) : {}
+      agent = payload["agent"] || payload[:agent]
+      message = payload["message"] || payload[:message]
+      event_id = Insika::Coercion.presence(payload["event_id"] || payload[:event_id])
+      if event_id.nil? || @shadow_pairs.nil?
+        emit_shadow(:shadow_unpairable, channel_id, agent, nil, silent: nil)
+        return nil
+      end
+
+      channel = @channels&.find(channel_id)
+      external_id = recipient(channel, task.session_id)
+      # The same empty-recipient guard the delivery path has: a pair keyed on an
+      # empty external_id can never meet the mirror's half (its digest differs),
+      # so the pair would sit :open forever. C1 makes this unreachable through
+      # the relay; a plugin channel could still get it wrong.
+      if Insika::Coercion.presence(external_id).nil?
+        emit_shadow(:shadow_unpairable, channel_id, agent, nil, silent: nil)
+        return nil
+      end
+
+      silent = content.to_s.strip.empty?
+      id = Insika::ShadowPairStore.key_for(channel: channel_id, external_id: external_id,
+                                           event_id: event_id)
+      @shadow_pairs.record_ours(id: id, channel: channel_id, agent: agent,
+                                session_id: task.session_id, task_id: task.id,
+                                event_id: event_id, inbound: message.to_s,
+                                reply: content.to_s, criterion_sha: @criterion_sha)
+      emit_shadow(:shadow_recorded, channel_id, agent, id, silent: silent)
+      nil
+    end
+
+    # Metadata only: the stream reaches every subscriber and stays free of
+    # customer content, per the Studio's own emit_operator_action rule.
+    def emit_shadow(type, channel, agent, pair_id, silent:)
+      return unless @event_stream
+
+      data = { channel: channel.to_s, agent: agent, pair_id: pair_id }.compact
+      data[:silent] = silent unless silent.nil?
+      @event_stream.emit(Insika::Event.new(type: type, data: data,
+                                           meta: { at: Time.now.utc.iso8601 }))
+    end
+
     def attempt(delivery, channel)
       last_error = nil