insika 0.0.1 → 0.1.0

data/lib/insika/agent_profile.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+require_relative "coercion"
+
+module Insika
+  # Single point of per-agent policy.
+  # ONE allowlist semantics for tools, skills, providers and workflows
+  # (nil = all [+ opt-in for optional tools]; [] = none for skills/allow;
+  # [names] = the final set; deny always wins) — a single rule, tested once.
+  #
+  # Deliberate EXCEPTION: `capabilities` does NOT follow the
+  # `nil = all` rule. nil/absent = NO capability (explicit opt-in — exposing
+  # every registered capability by mistake would couple the agent to plugins it
+  # didn't ask for). Do NOT "fix" it to be consistent with tools_allow.
+  AgentProfile = Data.define(
+    :id, :model, :provider,
+    :base_prompt, :prompt_files,
+    :tools_allow, :tools_deny,
+    :tools_allow_groups,              # per-GROUP allowlist (Phase 7/D4/F5, Stage C):
+    #                                   union with tools_allow; deny wins; both
+    #                                   nil = all (parity). Expands to the group's
+    #                                   tools in the ToolAllowlist policy.
+    :skills,
+    :context_providers,               # provider allowlist
+    :workflows_allow,                 # applied by WorkflowAllowlist
+    :policies,                        # names in the Policy Registry
+    :prompt_refs,                     # names in the Prompt Catalog
+    :limits,                          # timeouts/budgets
+    :approvals_required,              # tools that require approval (ApprovalRequired)
+    :capabilities,                    # intents the agent can trigger.
+    #                                   nil = NONE (opt-in, see above).
+    :subagents,                       # allowlist of child agent ids this agent MAY spawn
+    #                                   (RFC-0010, item 21). CAPACITY field — NEVER inherits;
+    #                                   opt-in like `capabilities`: nil/absent = NONE (do NOT
+    #                                   "fix" to nil = all). Present => the `spawn_subagent`
+    #                                   system tool is wired (ChatBuilder), gated by this set.
+    :tools_deferred,                  # searchable-not-wired tools (Tool Search).
+    #                                   nil = no deferred (all eager — parity);
+    #                                   [names] ⊆ allowed_tools, exposed via tool_search.
+    :memory,                          # cross-session memory.
+    #                                   nil/false = OFF (parity: provider []; the `remember`
+    #                                   tool not wired); true = ON. Same opt-in as capabilities.
+    :prompt_caching,                  # Anthropic prompt caching (§11 R3): nil/false = OFF
+    #                                   (parity); true = ON. Same opt-in as `memory`. When ON
+    #                                   AND the resolved provider is Anthropic, ChatBuilder sets
+    #                                   ONE cache breakpoint at the end of the system block
+    #                                   (caches tools+system by the tools->system->messages
+    #                                   prefix order; immune to history eviction). PRE-AUDIT:
+    #                                   the system prompt MUST be byte-stable between turns —
+    #                                   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.
+    :params,                          # LLM generation params (v2, §10): a Hash with
+    #                                   temperature/max_tokens/thinking, applied to the chat at
+    #                                   stage 5. {} = provider defaults (parity).
+    :model_policy,                    # governance of WHICH models the agent may use (v2, §10):
+    #                                   { "allow" => [refs] }. nil = NO fence (all models —
+    #                                   parity). Enforced on the RESOLVED model (ModelResolver).
+    :guardrails,                      # content-safety config (RFC-0009 §3.3): { input:, output:,
+    #                                   moderator:, strictness: }. OPT-IN like capabilities —
+    #                                   nil/absent = the conservative default (Safety::Config:
+    #                                   deterministic on, moderator off). Parsed, never a policy.
+    :sandbox,                         # confined-execution config (item 35, §4.6):
+    #                                   { provider: "local"|"docker", root:, timeout:, ...+provider
+    #                                   keys }. Declarative provider selection (config-over-code) —
+    #                                   consumed by Insika::Sandbox.build. {} = absent (a
+    #                                   deployment builds a `local` sandbox by default). It is
+    #                                   CONFIG, never a policy — it does not decide security by
+    #                                   itself; the FS boundary + approvals do.
+    :refinement,                      # self-improvement config (RFC-0013 §3.8):
+    #                                   { mode: "report"|"propose"|"auto_apply", window: {…},
+    #                                   files: [allowlist], proposers: [refs], budget: {tokens:},
+    #                                   auto_apply_max_edits:, max_findings:, … }. nil/absent =
+    #                                   REPORT-ONLY (phase A writes nothing to the agent, so
+    #                                   reading your own traces needs no opt-in); `propose`
+    #                                   and above must be enabled explicitly. It is CONFIG,
+    #                                   never a policy — the write allowlist it carries is
+    #                                   enforced by the applier, not by this field.
+    :capabilities_declared,           # FACTS ABOUT THIS DEPLOYMENT that are not tools
+    #                                   (RFC-0014 §3.5): %w[promotions human_handoff
+    #                                   b2b_pricing]. An eval case declares what it
+    #                                   `requires` and is SKIPPED — never failed — where
+    #                                   the deployment lacks it, which is what makes one
+    #                                   corpus usable across stores. A flat list the
+    #                                   OPERATOR writes: inferring "this store has
+    #                                   promotions" from data is how a suite starts lying.
+    #                                   nil/[] = declares nothing.
+    #                                   NOT `capabilities` above — that one is the
+    #                                   capability-resolution intents the agent may
+    #                                   trigger, a runtime allowlist. This one decides
+    #                                   nothing at runtime and is read only by the evals.
+    :edge_stream,                     # WHICH INTERNAL CHANNELS MAY CROSS TO THE CUSTOMER:
+    #                                   { "thinking" => bool, "intermediate" => bool }.
+    #                                   {} / absent = NEITHER, which is the safe default and
+    #                                   the reason the engine holds them back at all: the
+    #                                   answer is `:content`, and a turn's other text (the
+    #                                   provider's reasoning, the model narrating its tool
+    #                                   loop) is for the Studio and the trace. A product that
+    #                                   WANTS to show reasoning — a chat UI with a "thinking"
+    #                                   panel — opts in per agent, and each channel then gets
+    #                                   its OWN frame type at `/v1/responses`, never the
+    #                                   answer's. Turning it on for a channel where the
+    #                                   consumer concatenates every delta into one message
+    #                                   (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, Phase 6/D2).
+    #                                   It is NOT a policy — never decides security. {} = absent.
+  )
+
+  # Reopened class (not a Data.define block): a constant assigned inside
+  # the block would leak into the lexical scope (Insika::DEFAULT_LIMITS).
+  class AgentProfile
+    DEFAULT_LIMITS = {
+      turn_timeout: 300, tool_timeout: 60, provider_timeout: 5,
+      context_budget: 8_000, max_tool_calls: 50,
+      approval_timeout: 3_600, # cap on the wait for human approval (~1h)
+      # Item 30: parallel tool calls. ONE number is both the switch and the cap
+      # (nil/0/1 = serial, the default; N > 1 = at most N tool calls in flight).
+      # It sits next to tool_timeout/max_tool_calls because it is the third bound
+      # on tool execution. Read through TurnState#tool_concurrency, which also
+      # applies the approval gate (D3).
+      tool_concurrency: 1
+    }.freeze
+
+    # `model` is OPTIONAL as of v2 (§10): an agent without one resolves the
+    # platform `default_model` (Settings) at turn start via the ModelResolver.
+    def self.build(id:, model: nil, provider: nil, base_prompt: "", prompt_files: [],
+                   tools_allow: nil, tools_deny: [], tools_allow_groups: nil, skills: 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,
+                   params: {}, model_policy: nil, guardrails: nil, sandbox: nil,
+                   refinement: nil, capabilities_declared: nil, edge_stream: nil, metadata: {})
+      new(
+        id: id, model: model, provider: provider, base_prompt: base_prompt,
+        prompt_files: Array(prompt_files), tools_allow: tools_allow,
+        tools_deny: Array(tools_deny), tools_allow_groups: tools_allow_groups, skills: skills,
+        context_providers: context_providers, workflows_allow: workflows_allow,
+        policies: Array(policies), prompt_refs: Array(prompt_refs),
+        limits: DEFAULT_LIMITS.merge(limits), approvals_required: approvals_required,
+        capabilities: capabilities,
+        # opt-in like capabilities: nil => NONE. Array-normalize a present value so
+        # 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,
+        # 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
+        # downstream has to defend against both (store_id, model_policy, Studio forms).
+        params: Coercion.deep_stringify(params || {}),
+        model_policy: Coercion.deep_stringify(model_policy),
+        guardrails: Coercion.deep_stringify(guardrails),
+        sandbox: Coercion.deep_stringify(sandbox),
+        refinement: Coercion.deep_stringify(refinement),
+        # Flat [String] — the evals compare it against a case's `requires`, and a
+        # symbol/string mix there would be a silent miss.
+        capabilities_declared: Array(capabilities_declared).map(&:to_s),
+        edge_stream: Coercion.deep_stringify(edge_stream || {}),
+        metadata: Coercion.deep_stringify(metadata || {})
+      )
+    end
+
+    # opt-in for an optional tool = being in the agent's allow list.
+    def tool_opted_in?(name)
+      Array(tools_allow).include?(name)
+    end
+
+    # store_id of the turn context (ctx.store_id): lives in `metadata` (stable
+    # per store, comes from the pack). `build` string-keys metadata, so a plain
+    # string lookup is enough. nil = absent (the data-tool emits an empty header).
+    # It is NOT achei-specific: `store_id` is a field of the turn-context contract
+    # (§5), generic per project.
+    def store_id = (metadata || {})["store_id"]
+
+    # May this channel (:thinking / :intermediate) cross to the customer? Tolerant
+    # of the string values a form or a pack round-trip produces ("1"/"true"), and
+    # of anything else being absent: the safe reading is the default one.
+    def stream_public?(channel)
+      v = (edge_stream || {})[channel.to_s]
+      [true, "true", "1", "yes", "on"].include?(v)
+    end
+  end
+end

data/lib/insika/allowlist.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Insika
+  # Profile allowlist semantics, defined once: nil = all; [] = none;
+  # [names] = subset. It used to be copied in the Builder, the SkillCatalog and the
+  # policies — the rule must live in a single place.
+  module Allowlist
+    module_function
+
+    # Filters a collection by the allowlist, comparing `key.call(candidate)` (or the
+    # candidate itself) against the allowed names.
+    def filter(candidates, allow, &key)
+      return candidates if allow.nil?
+      return [] if allow.empty?
+
+      names = Array(allow).map(&:to_s)
+      candidates.select { |c| names.include?((key ? key.call(c) : c).to_s) }
+    end
+
+    # Per-item boolean variant (to compose with other filters in a select).
+    def allows?(allow, value)
+      return true if allow.nil?
+      return false if allow.empty?
+
+      Array(allow).map(&:to_s).include?(value.to_s)
+    end
+  end
+end

data/lib/insika/baseline_store.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  # The ACCEPTED state of an agent's golden set (RFC-0008 §3.4, promoted to a store
+  # by RFC-0013 §3.7.3). One record per agent in the ConfigStore (scope "baselines"):
+  #
+  #   { "at" => iso8601, "cases" => { "<case id>" => { "pass" => bool, "score" => n } } }
+  #
+  # Exactly the shape `Evals::Baseline.snapshot` already produces, so the file and
+  # the record are the same document in two places — no converter to keep honest,
+  # the same discipline `GoldenStore` applies to the corpus.
+  #
+  # **Why it had to leave the file.** `evals/baseline.json` works fine for the CLI,
+  # which runs from a checkout. The refinement gate does not: it runs inside a
+  # Railway deployment, scores a throwaway clone against the accepted state, and
+  # there is no checkout there to read. A gate that fell back to "no baseline found,
+  # nothing regressed" would be the most dangerous default in the system — so the
+  # baseline became a per-agent record, and the gate refuses when it is missing.
+  #
+  # The file stays the export format and the seed for a fresh deploy
+  # (`insika evals:baseline import|export`), for the same reason the goldens' YAML
+  # does. It is also still what `evals/run.rb --gate` reads for the pre-merge check,
+  # which is a checkout-side job and should stay one.
+  #
+  # Per AGENT and not one blob, unlike the file: a deployment serves many agents, a
+  # refinement run is about exactly one, and re-baselining the store after fixing
+  # agent A must not silently accept agent B's current state.
+  class BaselineStore
+    SCOPE = "baselines"
+
+    def initialize(config_store:)
+      @cs = config_store
+    end
+
+    # -> { "at" =>, "cases" => {…} } | nil. nil means NOT RECORDED, which every
+    # caller must treat as "cannot gate", never as "nothing regressed".
+    def get(agent_id)
+      @cs.get(SCOPE, agent_id.to_s)
+    end
+
+    # -> the stored record. `snapshot` is `Evals::Baseline.snapshot` output (or the
+    # equivalent hash); `at` is stamped here when the snapshot carries none.
+    def put(agent_id, snapshot, at: nil)
+      raw = Coercion.deep_stringify(snapshot || {})
+      cases = raw["cases"]
+      raise Insika::ValidationError, "baseline needs a 'cases' mapping" unless cases.is_a?(Hash)
+
+      record = { "at" => Coercion.presence(raw["at"]) || at || timestamp, "cases" => cases }
+      @cs.put(SCOPE, agent_id.to_s, record)
+      record
+    end
+
+    # -> bool (did it exist?). Removing a baseline disables the gate for that agent,
+    # which is the honest consequence and not a side effect worth hiding.
+    def delete(agent_id) = !!@cs.delete(SCOPE, agent_id.to_s)
+
+    # -> [String] agents with a recorded baseline.
+    def agents = @cs.keys(SCOPE)
+
+    # How many cases the accepted state covers. `0` and `nil` are different answers:
+    # nil = never recorded, 0 = recorded and empty (every case was skipped), and only
+    # the first is a configuration mistake.
+    def size(agent_id)
+      record = get(agent_id)
+      record && (record["cases"] || {}).size
+    end
+
+    private
+
+    def timestamp = Time.now.utc.iso8601
+  end
+end

data/lib/insika/capability/resolved_tool.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "delegate"
+
+module Insika
+  module Capability
+    # Thin decorator: swaps only the `name` exposed to the model for the
+    # STABLE capability name (e.g. "browse"), regardless of which concrete impl
+    # (`impl_name`, e.g. "puppeteer_browser") resolution chose.
+    # `execute`/`parameters`/`description`/`call` keep delegating to the impl via
+    # SimpleDelegator — nothing reimplemented, same spirit as `ToolEnvelope`.
+    #
+    # Wrapping order in run_pipeline: impl -> ResolvedTool ->
+    # ToolEnvelope. The Envelope, from the outside, sees the already-renamed call (the
+    # model calls `browse`); for side_effect?/approval it needs the REAL `impl_name`
+    # (it's the tool_registry that knows whether "puppeteer_browser" is a side-effect, not
+    # "browse") — that's why `impl_name` is exposed here. This is consumed by the
+    # Executor (ToolEnvelope).
+    class ResolvedTool < SimpleDelegator
+      def initialize(impl, capability_name:, impl_name:)
+        super(impl)
+        @capability_name = capability_name.to_s
+        @impl_name = impl_name.to_s
+      end
+
+      # STABLE name exposed to the model — shadows the impl's `name`.
+      def name = @capability_name
+
+      # Concrete name behind resolution — for side_effect?/approval in the
+      # ToolEnvelope, NEVER exposed to the model.
+      def impl_name = @impl_name
+    end
+  end
+end

data/lib/insika/capability_registry.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Insika
+  # Intent→implementation resolution. Pure INDIRECTION: does NOT inherit
+  # from `Registry` (which holds executables) — it holds `Provider`s (resolution
+  # metadata) and returns the `impl_name` that ANOTHER registry instantiates.
+  # Immutable post-boot by construction (only boot/loader registers), like `Registry`.
+  class CapabilityRegistry
+    Provider = Data.define(:capability, :impl_name, :kind, :plugin, :priority, :available)
+    #   kind:      :tool | :workflow
+    #   priority:  Integer | nil (nil = lowest; inherits plugin precedence)
+    #   available: callable -> bool (default -> { true }; never nil in a registered Provider)
+
+    def initialize
+      # capability(Symbol) -> [Provider], na ordem de registro (proxy de announce)
+      @providers = Hash.new { |h, k| h[k] = [] }
+    end
+
+    # Unlike `Registry#register`, there is NO "first wins": registering the
+    # same capability more than once is the normal case (providers competing) —
+    # dedup/tie-breaking happens in `resolve`, not here.
+    def register(capability, impl_name:, kind:, plugin: nil, priority: nil, available: nil)
+      unless %i[tool workflow].include?(kind)
+        raise ArgumentError, "invalid kind: #{kind.inspect} (use :tool or :workflow)"
+      end
+
+      if kind == :workflow
+        warn "[capability_registry] '#{capability}' registered with kind: :workflow — " \
+             "exposure to the agent deferred (L5)"
+      end
+
+      @providers[capability.to_sym] << Provider.new(
+        capability: capability.to_sym, impl_name: impl_name.to_s, kind: kind,
+        plugin: plugin&.to_s, priority: priority, available: available || -> { true }
+      )
+      self
+    end
+
+    def providers(capability) = @providers[capability.to_sym].dup
+
+    def capabilities = @providers.keys
+
+    # Loader rollback, symmetric to `Registry#deregister_plugin`. Removes
+    # only the plugin's Providers; capabilities with no remaining provider drop
+    # from `capabilities` (clears the key so the Hash.new-with-block won't recreate it empty).
+    def deregister_plugin(plugin_id)
+      @providers.each_value { |list| list.delete_if { |p| p.plugin == plugin_id.to_s } }
+      @providers.delete_if { |_cap, list| list.empty? }
+      nil
+    end
+
+    # -> chosen Provider | raise CapabilityUnavailable | raise CapabilityAmbiguous.
+    # PURE and deterministic: same input → same choice or same error. No
+    # IO beyond the Provider's own `available.call`. Emits `:capability_resolved`
+    # when `event_stream:` is present (audit).
+    def resolve(capability, profile:, context: {}, event_stream: nil)
+      candidates = providers(capability)
+      candidates = candidates.select { |p| p.available.call }
+      candidates = apply_deny(candidates, profile)
+
+      raise CapabilityUnavailable.new(capability: capability) if candidates.empty?
+
+      chosen = pick_top(candidates, capability)
+      event_stream&.emit(Insika::Event.new(
+                           type: :capability_resolved,
+                           data: {
+                             capability: capability.to_sym,
+                             chosen: chosen.impl_name,
+                             candidates: candidates.map do |p|
+                               { impl_name: p.impl_name, plugin: p.plugin, priority: p.priority }
+                             end
+                           }
+                         ))
+      chosen
+    end
+
+    private
+
+    # Resolution applies ONLY `tools_deny` over `impl_name` (deny ALWAYS wins) — it does
+    # NOT apply `tools_allow`: the grant to use the capability is
+    # listing it in `profile.capabilities`, checked by the Executor BEFORE
+    # calling `resolve`. Reusing `tools_allow` would filter out a provider for
+    # an agent that lists only the capability (not the raw impl). Per-agent provider
+    # pinning (`capability_providers`) is future work.
+    def apply_deny(candidates, profile)
+      deny = Array(profile.tools_deny).map(&:to_s)
+      candidates.reject { |p| deny.include?(p.impl_name) }
+    end
+
+    # `priority` desc primary, `nil` as the LOWEST possible (below
+    # any Integer, including negative — do not normalize to 0, which would collide
+    # with an explicit `priority: 0`). Tie-break by plugin precedence (registration
+    # order, announce proxy): different plugins always
+    # break the tie; same plugin (nil included) tied = CapabilityAmbiguous.
+    def pick_top(candidates, capability)
+      indexed = providers(capability).each_with_index.to_h { |p, i| [p, i] }
+
+      rank = ->(p) { p.priority.nil? ? [0, 0] : [1, p.priority] }
+      top_rank = candidates.map(&rank).max
+      top = candidates.select { |p| rank.call(p) == top_rank }
+
+      return top.first if top.size == 1
+
+      groups = top.group_by(&:plugin).values
+      if groups.any? { |g| g.size > 1 }
+        raise CapabilityAmbiguous.new(capability: capability, candidates: top)
+      end
+
+      groups.min_by { |g| indexed[g.first] }.first
+    end
+  end
+end

data/lib/insika/channel_delivery.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  # Hands a finished turn's answer to a Shape B channel (RFC-0011 §6.5). The turn
+  # ended; the recipient is not on any connection; the reply has to travel out of
+  # band and survive a crash on the way. Three moves, in this order, and the order
+  # is the whole design:
+  #
+  #   1. RECORD at the turn's terminal (durable, `pending`).
+  #   2. CLAIM before the HTTP call (`pending -> delivering`, atomic). A crash
+  #      between the claim and the POST loses that delivery; it does not duplicate
+  #      it. At-most-once, stated rather than papered over — the same honest scope
+  #      the async-delegation path already has.
+  #   3. RETRY, bounded and explicit. Unlike a delegation, the recipient is a third
+  #      party with outages, so "keep trying" is a real requirement and "keep trying
+  #      forever" is a real outage of ours.
+  #
+  # It is NOT a job queue: no scheduler, no priorities, no fan-out. The moment it
+  # grows one, the thing to do is take a real queue, not to finish building this.
+  class ChannelDelivery
+    MAX_ATTEMPTS = 3
+    # Waits BETWEEN attempts, so attempt 1 is immediate. Short on purpose: a
+    # customer waiting on WhatsApp is the deadline, not the consumer's SLA.
+    BACKOFF_SECONDS = [1, 5].freeze
+
+    def initialize(channels:, outbox:, session_store:, event_stream: nil,
+                   max_attempts: MAX_ATTEMPTS, backoff: BACKOFF_SECONDS, sleeper: nil)
+      @channels = channels
+      @outbox = outbox
+      @session_store = session_store
+      @event_stream = event_stream
+      @max_attempts = max_attempts
+      @backoff = Array(backoff)
+      @sleeper = sleeper || method(:default_sleep)
+    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 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 — P19),
+    #   · or we do not know who to send it to.
+    def record(task:, channel_id:, content:)
+      return nil if content.to_s.strip.empty?
+
+      channel = @channels&.find(channel_id)
+      return nil unless channel.respond_to?(:deliver)
+
+      to = recipient(channel, task.session_id)
+      return nil if to.nil? || to.empty?
+
+      @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 }
+      )
+    end
+
+    # Claim + POST + bounded retry. Safe to call twice: the second caller loses the
+    # claim and returns without touching the recipient.
+    def deliver(id)
+      return false unless @outbox.claim(id)
+
+      delivery = @outbox.find(id)
+      channel = @channels&.find(delivery&.channel)
+      # The channel vanished between the record and the dispatch (a plugin was
+      # disabled, the deployment was reconfigured). Nothing can send this; leave it
+      # terminal so the boot sweep does not spin on it forever.
+      if channel.nil? || !channel.respond_to?(:deliver)
+        return finish(@outbox.mark_failed(id, error: "channel '#{delivery&.channel}' is not registered"))
+      end
+
+      attempt(delivery, channel)
+    end
+
+    # Boot: re-drive what a previous process recorded and never claimed. Records
+    # left `delivering` are deliberately NOT swept — that process may have POSTed
+    # before it died, and replaying is the duplicate the claim exists to prevent.
+    # -> { dispatched: [ids] }
+    def sweep
+      dispatched = @outbox.pending.map do |delivery|
+        deliver(delivery.id)
+        delivery.id
+      end
+      { dispatched: dispatched }
+    end
+
+    private
+
+    def attempt(delivery, channel)
+      last_error = nil
+
+      @max_attempts.times do |i|
+        @sleeper.call(@backoff[i - 1]) if i.positive? && @backoff[i - 1]
+
+        begin
+          status = channel.deliver(delivery.payload, to: delivery.to, delivery_id: delivery.id)
+          return finish(@outbox.mark_delivered(delivery.id)) if (200..299).cover?(status.to_i)
+
+          last_error = "HTTP #{status}"
+        rescue Insika::DeliveryError => e
+          last_error = e.message
+        end
+        @outbox.record_attempt(delivery.id, error: last_error)
+      end
+
+      finish(@outbox.mark_failed(delivery.id, error: last_error))
+    end
+
+    # The consumer's own key for this conversation. Written into the session's vars
+    # when the channel minted it (§4.3); the channel's own id parser is the fallback
+    # for a session created before those vars existed.
+    def recipient(channel, session_id)
+      session = session_id && @session_store.find(session_id)
+      vars = session&.vars || {}
+      from_vars = vars["external_id"] || vars[:external_id]
+      return from_vars.to_s if Insika::Coercion.presence(from_vars)
+
+      channel.respond_to?(:external_id_from) ? channel.external_id_from(session_id) : nil
+    end
+
+    def finish(delivery)
+      emit(delivery)
+      delivery.status == :delivered
+    end
+
+    def emit(delivery)
+      return unless @event_stream
+
+      @event_stream.emit(Insika::Event.new(
+                           type: :channel_delivered,
+                           data: { channel: delivery.channel, outbox_id: delivery.id,
+                                   status: delivery.status.to_s, attempts: delivery.attempts,
+                                   error: delivery.last_error },
+                           meta: { task_id: delivery.task_id, session_id: delivery.session_id,
+                                   at: Time.now.utc.iso8601 }
+                         ))
+    end
+
+    # Async when there is a reactor (production: the retry must not block the
+    # worker), plain sleep otherwise (boot sweep before the reactor, specs).
+    def default_sleep(seconds)
+      task = defined?(Async::Task) ? Async::Task.current? : nil
+      task ? task.sleep(seconds) : sleep(seconds)
+    end
+  end
+end

data/lib/insika/channel_registry.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Insika
+  # The channels this deployment speaks, by id (RFC-0011 §4.2). A `Registry` like
+  # tools and workflows — same plugin bookkeeping, so `deregister_plugin` rolls a
+  # half-registered plugin back exactly as it does for a tool.
+  #
+  # The id is the URL segment (`/channels/relay/events`), which is why lookup here
+  # is a `find` and not a `resolve`: an unknown segment is a 404, not an exception
+  # the transport has to rescue.
+  class ChannelRegistry < Registry
+    # -> the channel instance | nil (unknown id). A blank id never matches.
+    def find(id)
+      name = id.to_s
+      return nil if name.empty?
+
+      resolve(name)
+    rescue Insika::NotFoundError
+      nil
+    end
+
+    # Does this channel deliver out of band (Shape B)? A Shape A channel answers on
+    # the request's own stream and has no `deliver`, so nothing is ever written to
+    # the outbox for it. Duck-typed, like every other seam in the engine.
+    def deliverable?(id)
+      channel = find(id)
+      !channel.nil? && channel.respond_to?(:deliver)
+    end
+  end
+end