insika 0.2.0 → 0.7.0

data/lib/insika/schedule_store.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "time"
+
+module Insika
+  # the per-agent schedule rows of the recurring feature — one
+  # row per declared schedule, keyed `tenant:agent:id`, holding BOTH the
+  # declaration (a copy of the profile's `schedules` entry — the engine reads
+  # the store, never the profile, on the fire path) and the runtime state
+  # (`next_fire_at`, `last_run_at`, `last_task_id`, `last_skip`).
+  #
+  # The row is a DERIVED record: the profile declaration is the config (the
+  # DSL, the API, the Studio all edit the profile); the ScheduleEngine
+  # reconciles rows with declarations at each pass. The engine OWNS the
+  # runtime writes — `transition_fire`/`mark_skip` are called only inside the
+  # engine's transaction (the D5 discipline), never by a consumer. A row that
+  # is no longer declared is deleted (no zombie schedules); a row whose
+  # declaration is malformed is deleted too — a broken schedule must not keep
+  # firing with stale text (the doctor names it).
+  #
+  # Multi-worker at-most-once rides Store#transaction: the pass re-reads the
+  # row inside the transaction, so two workers serialize on the backend lock
+  # and only one advances `next_fire_at`.
+  class ScheduleStore
+    SCOPE = "schedules"
+
+    Record = Data.define(:id, :tenant, :agent, :every, :cron, :tz, :message,
+                         :session_mode, :session_id, :overrides, :enabled,
+                         :next_fire_at, :last_run_at, :last_task_id, :last_skip,
+                         :created_at, :updated_at)
+
+    def initialize(store:)
+      @store = store
+    end
+
+    # Reconcile: upsert the declaration's row, or delete it when the
+    # declaration is gone/malformed. Called by the engine inside its pass
+    # transaction. A NEW or CHANGED declaration recomputes `next_fire_at`
+    # (the trigger lattice starts fresh); an unchanged row keeps its.
+    def sync_declared(tenant:, agent:, schedules: nil, now: Time.now.utc)
+      kept = []
+      Array(schedules).each do |declaration|
+        schedule = Insika::Schedule.parse(declaration)
+        next if schedule.nil? # malformed — dropped, the doctor names it
+
+        keep = upsert(tenant: tenant, agent: agent, schedule: schedule, now: now)
+        kept << schedule.id if keep
+      end
+
+      # drop rows the agent no longer declares
+      prefix = "#{tenant_id(tenant)}:#{agent}:"
+      @store.list(SCOPE).each do |k|
+        next unless k.start_with?(prefix)
+        next if kept.include?(k.split(":").last)
+
+        @store.delete(SCOPE, k)
+      end
+      kept
+    end
+
+    # -> Record | nil
+    def find(tenant:, agent:, id:)
+      record = @store.get(SCOPE, key(tenant, agent, id))
+      record && to_record(record)
+    end
+
+    # -> [Record] — one agent's rows (the Studio's read), lexicographic.
+    def for_agent(tenant:, agent:)
+      prefix = "#{tenant_id(tenant)}:#{agent}:"
+      @store.list(SCOPE).filter_map do |k|
+        next unless k.start_with?(prefix)
+
+        to_record(@store.get(SCOPE, k))
+      end
+    end
+
+    # -> [Record] — every row (the Studio grid, the engine pass).
+    def all
+      @store.list(SCOPE).filter_map { |k| to_record(@store.get(SCOPE, k)) }
+    end
+
+    # -> [Record] — enabled AND due, oldest first (determinism). A row whose
+    # next_fire_at is nil (a cron that can never fire) is never due.
+    def due(now: Time.now.utc)
+      cutoff = now.iso8601
+      all.select { |r| r.enabled && !r.next_fire_at.to_s.empty? && r.next_fire_at.to_s <= cutoff }
+         .sort_by { |r| [r.next_fire_at.to_s, r.id] }
+    end
+
+    # The engine's atomic fire claim — the LAST step of the fire's
+    # transaction: advance the lattice, stamp the run, clear the skip.
+    # Callers pass `id` and the engine's OWN transaction encloses this.
+    def transition_fire(id:, tenant:, agent:, task_id:, next_fire_at:, now: Time.now.utc)
+      mutate(tenant, agent, id, now) do |record|
+        record["last_run_at"] = now.utc.iso8601
+        record["last_task_id"] = task_id.to_s
+        record["next_fire_at"] = next_fire_at.iso8601
+        record["last_skip"] = nil
+      end
+    end
+
+    # The visible skip — recorded, never silent: `next_fire_at` advances
+    # (the window is skipped, not queued) and `last_skip` names why.
+    def mark_skip(id:, tenant:, agent:, reason:, next_fire_at:, now: Time.now.utc)
+      mutate(tenant, agent, id, now) do |record|
+        record["last_skip"] = { "at" => now.utc.iso8601, "reason" => reason.to_s }
+        record["next_fire_at"] = next_fire_at.iso8601
+      end
+    end
+
+    def delete(tenant:, agent:, id:)
+      @store.delete(SCOPE, key(tenant, agent, id))
+    end
+
+    # -> count removed. The LGPD sweep (a tenant's schedules die with it).
+    def purge(tenant:)
+      prefix = "#{tenant_id(tenant)}:"
+      keys = @store.list(SCOPE).select { |k| k.start_with?(prefix) }
+      keys.each { |k| @store.delete(SCOPE, k) }
+      keys.size
+    end
+
+    private
+
+    # Create or update ONE row from the declaration, recomputing next_fire_at
+    # on create and on any trigger/definition change. -> the schedule id.
+    def upsert(tenant:, agent:, schedule:, now:)
+      k = key(tenant, agent, schedule.id)
+      record = @store.get(SCOPE, k)
+      return schedule.id if record && !changed?(record, schedule)
+
+      next_fire_at = initial_next_fire(schedule, now)
+      row = {
+        "id" => schedule.id, "tenant" => tenant_id(tenant), "agent" => agent.to_s,
+        "every" => schedule.every, "cron" => schedule.cron, "tz" => schedule.tz,
+        "message" => schedule.message, "session_mode" => schedule.session_mode,
+        "session_id" => schedule.session_id, "overrides" => schedule.overrides,
+        "enabled" => schedule.enabled,
+        "next_fire_at" => next_fire_at&.iso8601,
+        "last_run_at" => record&.dig("last_run_at"),
+        "last_task_id" => record&.dig("last_task_id"),
+        "last_skip" => record&.dig("last_skip"),
+        "created_at" => record ? record["created_at"] : now.iso8601,
+        "updated_at" => now.iso8601
+      }
+      @store.set(SCOPE, k, row)
+      schedule.id
+    end
+
+    # Does the row's DECLARATION differ from the schedule? (runtime state is
+    # never part of the comparison.)
+    def changed?(record, schedule)
+      record["cron"] != schedule.cron || record["every"] != schedule.every ||
+        record["tz"] != schedule.tz || record["message"] != schedule.message ||
+        record["session_mode"] != schedule.session_mode ||
+        record["session_id"] != schedule.session_id ||
+        record["overrides"] != schedule.overrides ||
+        record["enabled"] != schedule.enabled
+    end
+
+    # The first fire after `now` for a schedule that has none yet: for `every`,
+    # one interval out; for cron, the next expression match. nil (a cron that
+    # can never fire) makes the row never due — `due` ignores a nil.
+    def initial_next_fire(schedule, now)
+      if schedule.every
+        now + schedule.every
+      else
+        Insika::Cron.new(schedule.cron).next_after(now, tz: schedule.tz)
+      end
+    end
+
+    def mutate(tenant, agent, id, now)
+      @store.transaction do
+        record = @store.get(SCOPE, key(tenant, agent, id))
+        raise Insika::NotFoundError, "schedule not found: #{tenant}:#{agent}:#{id}" if record.nil?
+
+        yield record
+        record["updated_at"] = now.utc.iso8601
+        @store.set(SCOPE, key(tenant, agent, id), record)
+        to_record(record)
+      end
+    end
+
+    def key(tenant, agent, id)
+      "#{tenant_id(tenant)}:#{agent.to_s}:#{id.to_s}"
+    end
+
+    def tenant_id(tenant)
+      t = tenant.to_s
+      t.empty? ? "platform" : t
+    end
+
+    def to_record(rec)
+      return nil if rec.nil?
+
+      Record.new(id: rec["id"], tenant: rec["tenant"], agent: rec["agent"],
+                 every: rec["every"], cron: rec["cron"], tz: rec["tz"],
+                 message: rec["message"], session_mode: rec["session_mode"],
+                 session_id: rec["session_id"], overrides: rec["overrides"],
+                 enabled: rec["enabled"] != false,
+                 next_fire_at: rec["next_fire_at"],
+                 last_run_at: rec["last_run_at"],
+                 last_task_id: rec["last_task_id"], last_skip: rec["last_skip"],
+                 created_at: rec["created_at"], updated_at: rec["updated_at"])
+    end
+  end
+end

data/lib/insika/schema_guard.rb

@@ -131,6 +131,41 @@ module Insika
       end
     end
 
+    # Walks a dotted path on a plain object: nil when a segment
+    # is absent or the intermediate is not a Hash. Shared by the evidence output
+    # check and the Processor's extraction.
+    def dig(obj, path)
+      path.to_s.split(".").reduce(obj) do |cur, seg|
+        return nil unless cur.is_a?(Hash) && cur.key?(seg)
+
+        cur[seg]
+      end
+    end
+
+    # The evidence RESULT contract: {items: [{id, line}]} .
+    # -> nil | String. Same idiom as `violation`: nil = fine, one message = what
+    # is wrong. A malformed evidence result is a correctable TOOL answer — the
+    # envelope returns it to the model as `{error:}`, exactly like a malformed
+    # call is today. A raw body that is NOT an object (a bare JSON array from a
+    # search, a string, nil) is a violation — never a silent `{items: []}` that
+    # the model reads as "no products".
+    def violation_output(spec, raw)
+      return nil if spec.nil?
+      return "evidence: result must be an object" unless raw.is_a?(Hash)
+
+      items = dig(raw, spec.items_path)
+      return "evidence: items is missing" if items.nil?
+      return "evidence: items must be a list" unless items.is_a?(Array)
+
+      items.each_with_index do |item, i|
+        ok = item.is_a?(Hash) &&
+             Coercion.present?(item["id"] || item[:id]) &&
+             (item["line"] || item[:line]).is_a?(String)
+        return "evidence: items[#{i}] must be {id, line}" unless ok
+      end
+      nil
+    end
+
     # Name the shape the way a model reads it, not the way Ruby does.
     def kind(value)
       case value

data/lib/insika/server/app.rb

@@ -55,7 +55,8 @@ module Insika
       def initialize(command_bus:, event_stream:, session_store:, task_store:,
                      config:, pending_action_store: nil, a2a: nil, provisioner: nil,
                      workflow_registry: nil, onboarding: nil, profiles: nil,
-                     channels: nil, logger: nil, token_store: nil)
+                     channels: nil, logger: nil, token_store: nil, outcome_store: nil,
+                     executor: nil, db_path: nil, tool_registry: nil, mcp_store: nil)
         @command_bus = command_bus
         @event_stream = event_stream
         @session_store = session_store
@@ -91,10 +92,29 @@ module Insika
         # injecting the registry (nil ⇒ the routes do not exist, parity with @a2a).
         # The channel does the translating; this class keeps doing only transport.
         @channels = channels
+        # WS7: business outcomes per conversation (POST /v1/outcomes — a Control
+        # command on the bus — and the tenant-scoped GET /v1/outcomes read).
+        # nil = the routes 404 (parity).
+        @outcome_store = outcome_store
         # where a 500's error_ref goes to be FOUND. nil = silent (parity for
         # embedders); the serving wirings pass $stdout. Class+message+backtrace
         # only — the ref never travels with request payloads (secrets stay out).
         @logger = logger
+        #   GET /v1/vitals: process readings, operator-only, no store.
+        # Both optional — nil means the body simply omits those readings.
+        @executor = executor
+        @db_path = db_path
+        # The deployment's EFFECTIVE tool registry, so the capability view can
+        # answer what the agent can reach that can WRITE (the derived
+        # eval-profile swap list). Read-only use (names/side_effect?) — same
+        # constitutional footing as the profile source. nil = the view omits it.
+        @tool_registry = tool_registry
+        # The durable MCP instance CRUD (GET/PUT/DELETE
+        # /v1/mcp[/:name]) — a direct store read/Command surface, same footing
+        # as @profiles/@outcome_store. nil = the routes 404 (parity — a
+        # deployment that never wires an McpStore never exposes MCP config
+        # over HTTP, same as one that skips provisioning).
+        @mcp_store = mcp_store
         @heartbeat = config.fetch(:heartbeat, 15)
         @sync_timeout = config.fetch(:sync_timeout, 10) # synchronous control
       end
@@ -166,8 +186,20 @@ module Insika
           handle_trigger_workflow(req, name)
         in ["POST", ["v1", "responses"]]
           handle_responses(req)
+        in ["POST", ["v1", "outcomes"]] if @outcome_store
+          handle_record_outcome(req)
+        in ["GET", ["v1", "outcomes"]] if @outcome_store
+          handle_list_outcomes(req)
         in ["POST", ["v1", "tools", "manifest"]]
           handle_import_tools(req)
+        in ["GET", ["v1", "mcp"]] if @mcp_store
+          handle_list_mcp
+        in ["GET", ["v1", "mcp", name]] if @mcp_store
+          handle_read_mcp(name)
+        in ["PUT", ["v1", "mcp"]] if @mcp_store
+          handle_upsert_mcp(req)
+        in ["DELETE", ["v1", "mcp", name]] if @mcp_store
+          handle_delete_mcp(req, name)
         in ["POST", ["v1", "mcp", name, "import"]]
           handle_import_mcp_tools(req, name)
         in ["POST", ["v1", "agents"]] if @provisioner
@@ -182,8 +214,12 @@ module Insika
           handle_read_task(req, id)
         in ["GET", ["v1", "events"]]
           handle_events(req)
+        in ["GET", ["v1", "vitals"]]
+          handle_vitals
         in ["POST", ["channels", id, "events"]] if @channels
           handle_channel_event(req, id)
+        in ["POST", ["channels", id, "shadow-reply"]] if @channels
+          handle_channel_shadow_reply(req, id)
         in ["POST", ["channels", id, "sessions"]] if @channels
           handle_channel_session(req, id)
         in ["POST", ["channels", id, "messages"]] if @channels
@@ -241,7 +277,7 @@ module Insika
       # tomorrow is gated by default and publishing it is a deliberate edit here.
       def channel_route?(method, segments)
         case [method, segments]
-        in ["POST", ["channels", _, "events" | "sessions" | "messages"]] then true
+        in ["POST", ["channels", _, "events" | "sessions" | "messages" | "shadow-reply"]] then true
         in ["GET", ["channels", _, "asset", _]] then true
         in ["OPTIONS", ["channels", _, *]] then true # CORS preflight carries no credential, by spec
         else false
@@ -259,11 +295,44 @@ module Insika
       # POST /v1/commands/:type — generic: every new Command is born with a
       # transport. The control vs turn distinction is BY THE SHAPE of the result (the
       # transport knows no semantics).
+      #
+      # The principal's tenant is stamped like on every other surface. It is
+      # nil for an operator (this route is operator-only — see TENANT_SURFACES),
+      # which is exactly why a tenant-scoped command such as `forget_customer`
+      # ALSO reads a `tenant` from its payload: over HTTP the operator names the
+      # tenant, because the credential does not carry one.
       def handle_command(req, type)
-        command = Insika::Command.build(type.to_sym, parse_body(req), transport: :http)
+        command = Insika::Command.build(type.to_sym, parse_body(req), transport: :http,
+                                                                      tenant: req_tenant(req))
         command_response(dispatch_with_timeout(command))
       end
 
+      # POST /v1/outcomes — the operator or the integration records a business
+      # outcome for a conversation (WS7). A Control command on the bus, tenant
+      # stamped from the principal (WS1) — additive, outside the response
+      # contract: the engine transports the outcome, never interprets it.
+      # 201 { outcome: { agent, outcome, value, session_id, at } }.
+      def handle_record_outcome(req)
+        command = Insika::Command.build(:record_outcome, parse_body(req), transport: :http,
+                                         tenant: req_tenant(req))
+        record = dispatch_with_timeout(command)
+        json_response(201, { outcome: { agent: record.agent, outcome: record.outcome,
+                                        value: record.value, session_id: record.session_id,
+                                        at: record.at } })
+      end
+
+      # GET /v1/outcomes[?agent=] — the Studio scorecard's data: the LAST
+      # outcome per agent (state cards) + the per-day series. Tenant-scoped
+      # (WS1): a tenant principal reads only its own outcomes.
+      def handle_list_outcomes(req)
+        tenant = req_tenant(req)
+        agent = req.GET["agent"]
+        latest = @outcome_store.latest_per_agent(tenant: tenant)
+        latest = { agent => latest[agent] }.compact if agent && !agent.empty?
+        series = @outcome_store.series(tenant: tenant, agent: agent)
+        json_response(200, { latest: latest, series: series })
+      end
+
       # POST /v1/sessions — sugar for create_session; 201 {session}.
       def handle_create_session(req)
         body = parse_body(req)
@@ -350,6 +419,10 @@ module Insika
         ensure_session(parsed[:user], tenant: tenant)
         payload = { agent: parsed[:agent], session_id: parsed[:user], message: parsed[:message] }
         payload[:origin] = parsed[:origin] if parsed[:origin] # declared, else absent
+        payload[:customer] = parsed[:customer] if parsed[:customer] # WS8: the memory scope handle
+        payload[:parts] = parsed[:parts] if parsed[:parts] # WS9: multimodal content parts
+        payload[:source] = parsed[:source] if parsed[:source] # WS9: voice-marked text
+        payload[:channel] = parsed[:channel] if parsed[:channel] # WS9 (saída): the channel's output capabilities
         message_flow(payload, stream: true, serialize: Responses.method(:frame_for),
                               tenant: tenant)
       end
@@ -384,18 +457,61 @@ module Insika
         json_response(200, dispatch_with_timeout(command))
       end
 
-      # POST /v1/mcp/:name/import — LIVE MCP ingestion. Same
+      # GET /v1/mcp — every configured MCP instance, MASKED (@mcp_store.all
+      # already masks — never plaintext over the wire). A direct store read,
+      # not a Command (constitutional rule at the top of this file); the
+      # generic route gate already confined this to the operator (not a
+      # TENANT_SURFACES entry), same footing as GET /v1/agents/:id.
+      def handle_list_mcp
+        json_response(200, { instances: @mcp_store.all })
+      end
+
+      # GET /v1/mcp/:name — one instance, MASKED. Missing -> 404.
+      def handle_read_mcp(name)
+        record = @mcp_store.get(name)
+        raise Insika::NotFoundError, "MCP instance '#{name}' not found" if record.nil?
+
+        json_response(200, record)
+      end
+
+      # PUT /v1/mcp — create/edit an instance (the CLI/DSL/Studio
+      # config surfaces share this ONE seam: the `:upsert_mcp` Command already
+      # registered on the bus). Per-key secret reconciliation (the `__OCULTO__`
+      # sentinel round-trips: preserves; a new string replaces; "" clears) —
+      # same contract as `Insika::McpJson`. 200 { the MASKED upserted record }.
+      def handle_upsert_mcp(req)
+        gate = gateway_gate(req)
+        return gate if gate
+
+        command = Insika::Command.build(:upsert_mcp, parse_body(req), transport: :http)
+        json_response(200, dispatch_with_timeout(command))
+      end
+
+      # DELETE /v1/mcp/:name — removes an instance (`:delete_mcp`). Idempotent
+      # (200 { existed: false } on a name that was never there — never a 404;
+      # deleting a thing that is already gone is not an error). The name comes
+      # from the ROUTE (data), not the body.
+      def handle_delete_mcp(req, name)
+        gate = gateway_gate(req)
+        return gate if gate
+
+        command = Insika::Command.build(:delete_mcp, { name: name }, transport: :http)
+        json_response(200, dispatch_with_timeout(command))
+      end
+
+      # POST /v1/mcp/:name/import — kept as the alias for the
+      # "Refresh tools" action (the route predates the live registry; the name
+      # stuck). Dispatches :refresh_mcp_tools — LIVE connect + tools/list +
+      # write McpStore#tools_cache, never the retired ingestor snapshot. Same
       # Bearer as provisioning (gateway_token, fail-closed): it's an authoring
-      # surface. Discovers the tools of the MCP instance `:name` (via a client injectable
-      # at the composition root) and ingests them as data-tools (reuses :import_tools:
-      # upsert + hot reload). Dispatches :import_mcp_tools -> 200 { per-tool report
-      # + instance }. Missing instance -> 404; disabled/no-url -> 422; per-tool
-      # failure isolated in `errors[]` (R4). The name comes from the ROUTE (data), not the body.
+      # surface. Missing instance -> 404; disabled -> 422; a transport failure
+      # surfaces as whatever #call's rescue maps it to. The name comes from the
+      # ROUTE (data), not the body.
       def handle_import_mcp_tools(req, name)
         gate = gateway_gate(req)
         return gate if gate
 
-        command = Insika::Command.build(:import_mcp_tools, { name: name }, transport: :http)
+        command = Insika::Command.build(:refresh_mcp_tools, { name: name }, transport: :http)
         json_response(200, dispatch_with_timeout(command))
       end
 
@@ -412,22 +528,50 @@ module Insika
       # (a client: it never reads a store) can tell "this case cannot run here" from
       # "this case failed". Deliberately NOT the profile: the prompt,
       # the model and the guardrail config are none of the caller's business. Just the
-      # two facts a case declares `requires` against.
+      # three facts a case declares `requires` against — plus the side-effect set,
+      # which is what an eval profile must swap.
       #
       # `tools` is the DECLARED allowlist, and `null` means the agent has an open one
       # (every registered tool) — the client reads that as "cannot rule anything out"
       # and runs the case rather than skipping it.
+      #
+      # `side_effect_tools` is DERIVED here from the deployment's own registry (the
+      # effective one the Executor uses): the agent's reachable tools the registry
+      # marks `side_effect` (a data-tool's non-GET method, the MCP ingestor's
+      # `tools/call`). It is the list a simulated run's eval profile must cover —
+      # and it is a fact of the deployment, never a hand-maintained client list.
+      # Absent (no registry wired) -> the key is omitted, and the view behaves as
+      # before.
       def handle_read_agent(id)
         profile = @profiles.fetch(id)
         raise Insika::NotFoundError, "agent not found: #{id}" if profile.nil?
 
         allow = profile.tools_allow
         deny = Array(profile.tools_deny).map(&:to_s)
-        json_response(200, {
-                        id: profile.id,
-                        tools: allow.nil? ? nil : (Array(allow).map(&:to_s) - deny),
-                        capabilities: Array(profile.capabilities_declared).map(&:to_s)
-                      })
+        payload = {
+          id: profile.id,
+          # `tools: null` is MEANINGFUL (an open allowlist — the client reads it
+          # as "cannot rule anything out"), so it must survive, unlike the new
+          # field below.
+          tools: allow.nil? ? nil : (Array(allow).map(&:to_s) - deny),
+          capabilities: Array(profile.capabilities_declared).map(&:to_s)
+        }
+        derived = side_effect_tools(profile)
+        payload[:side_effect_tools] = derived unless derived.nil?
+        json_response(200, payload)
+      end
+
+      # The derived side-effect set for an agent: its reachable tools (the same
+      # allowlist − deny resolution the `tools` field uses) that the registry marks
+      # `side_effect`, sorted for a stable answer. -> [names] | nil (no registry).
+      def side_effect_tools(profile)
+        return nil unless @tool_registry
+
+        allowed = if profile.tools_allow.nil? then Array(@tool_registry.names)
+                  else Array(profile.tools_allow).map(&:to_s)
+                  end
+        denied = Array(profile.tools_deny).map(&:to_s)
+        (allowed - denied).select { |name| @tool_registry.side_effect?(name) }.sort
       end
 
       # `/v1` only — `/a2a` is versioned by its own JSON-RPC spec and a channel's
@@ -481,6 +625,8 @@ TENANT_SURFACES = [
         ["POST", ["v1", "sessions"]],
         ["POST", ["v1", "messages"]],
         ["POST", ["v1", "responses"]],
+        ["POST", ["v1", "outcomes"]],
+        ["GET", ["v1", "outcomes"]],
         ["POST", ["v1", "workflows", nil]],
         ["GET", ["v1", "workflows"]],
         ["GET", ["v1", "sessions", nil]],
@@ -535,7 +681,52 @@ TENANT_SURFACES = [
 
         payload = { agent: parsed[:agent], session_id: session_id,
                     message: parsed[:message], event_id: parsed[:event_id] }.compact
-        channel_ack(payload, transport: :"channel:#{id}")
+        ack = channel_ack(payload, transport: :"channel:#{id}")
+        # in shadow the mirror's own reply may ride the SAME call
+        # (Shape 1) — recorded before we answer, through the one command.
+        if channel.respond_to?(:shadow?) && channel.shadow?
+          dispatch_shadow_reply(id, parsed) if parsed[:incumbent_reply]
+          return shadow_ack(ack)
+        end
+        ack
+      end
+
+      # POST /channels/:id/shadow-reply — the mirror contract's fallback (Shape 2),
+      # for a consumer that mirrors the exchange BEFORE it answers the customer.
+      # Same channel_gate (auth is the channel's, not the route's); 404 unless the
+      # channel is in shadow — the same parity every other optional surface has.
+      def handle_channel_shadow_reply(req, id)
+        channel = @channels.find(id)
+        return not_found if channel.nil? || !(channel.respond_to?(:shadow?) && channel.shadow?)
+
+        gate = channel_gate(channel, req)
+        return gate if gate
+
+        parsed = channel.parse_shadow_reply(req, body: parse_raw_body(req)) # ValidationError -> 422
+        result = dispatch_shadow_reply(id, parsed)
+        json_response(202, { pair_id: result[:pair_id], status: result[:status] })
+      end
+
+      # The incumbent half rides ONE command whatever shape it arrived in, so
+      # server/ never writes to a store and both doors share one behaviour.
+      def dispatch_shadow_reply(id, parsed)
+        @command_bus.dispatch(
+          Insika::Command.build(:record_shadow_reply,
+                                { channel: id.to_s, external_id: parsed[:external_id],
+                                  event_id: parsed[:event_id], reply: parsed[:incumbent_reply] || parsed[:reply],
+                                  at: parsed[:at] }.compact,
+                                transport: :"channel:#{id}")
+        )
+      end
+
+      # 202 -> 200 {task_id, shadow: true}: a consumer wired to "202 means a
+      # reply is coming" must not be silently misled. The duplicate/merged/
+      # steered verdicts pass through untouched (they already say 200).
+      def shadow_ack(ack)
+        status, _headers, body = ack
+        return ack unless status == 202
+
+        json_response(200, JSON.parse(body.join).merge("shadow" => true))
       end
 
       # POST /channels/:id/sessions — mint a conversation for a PUBLIC Shape A
@@ -780,6 +971,36 @@ TENANT_SURFACES = [
       # happens here, BEFORE the SSE opens -> closes the subscription and propagates to the
       # #call rescue (becomes an HTTP status).
       def message_flow(payload, stream:, serialize: nil, transport: :http, tenant: nil)
+        # WS9: content parts are CONTRACT at the edge — the closed shape is
+        # validated here (422) before the command is built; the engine stays
+        # lenient for transports that bypass this surface.
+        parts = payload[:parts] || payload["parts"]
+        if parts && !Insika::Media.well_formed?(parts)
+          raise Insika::ValidationError,
+                "malformed content part — each part must be {type: text|image|audio|document} with text/url"
+        end
+        # WS9: the only declared message source is "voice" (pre-transcribed
+        # audio) — a consumer that writes prose here is told so, not silently.
+        source = payload[:source] || payload["source"]
+        if source && source.to_s != "voice"
+          raise Insika::ValidationError, 'source must be "voice"'
+        end
+        # WS9 (saída): the channel's declared OUTPUT media capabilities. The
+        # closed list IS the "abstraction admits only what leaks" rule: an
+        # unknown value is refused here (422), never silently ignored; a
+        # declared value is what the executor may wire (generate_image/tts).
+        channel = payload[:channel] || payload["channel"]
+        if channel.is_a?(Hash)
+          caps = Insika::Media.channel_capabilities(channel)
+          unknown = caps - Insika::Media::OUTPUT_CAPABILITIES
+          unless unknown.empty?
+            raise Insika::ValidationError,
+                  "unknown channel capability: #{unknown.join(', ')}"
+          end
+
+          payload = payload.dup
+          payload[:channel] = { capabilities: caps }
+        end
         # WS1: a tenant's session_id is NAMESPACED before the command is built,
         # so the turn lands on the tenant's OWN session even when another tenant
         # uses the same chat id. The payload the caller sent is untouched.
@@ -993,6 +1214,15 @@ TENANT_SURFACES = [
       # touch a store (health cannot fail on IO nor require auth).
       def health = json_response(200, { status: "ok" })
 
+      #   process vitals. Operator-only by construction: not in
+      # PUBLIC_ROUTES (no bearer -> unauthorized) and not in TENANT_SURFACES
+      # (a tenant principal hits the operator-surface gate), so only an
+      # operator reads process internals. Reads no store — pure OS/VM
+      # readings, safe at any rate.
+      def handle_vitals
+        json_response(200, Insika::Vitals.snapshot(executor: @executor, db_path: @db_path))
+      end
+
       # Thin Subscription decorator: discards
       # events from OTHER tasks and CLOSES the subscription after forwarding the task's
       # terminal event. Solves the subscribe-before-task_id gap without touching