insika 0.2.0 → 0.3.0

data/lib/insika/safety/factory.rb

@@ -6,6 +6,10 @@ require_relative "moderator"
 require_relative "output_filter"
 require_relative "input_guardrail"
 require_relative "output_validator"
+# the grounding validator (flagged as the OutputValidator's first
+# step) and the enforcer (the executor's stage-8 boundary call). Pure Ruby.
+require_relative "grounding_validator"
+require_relative "grounding_enforcer"
 
 module Insika
   module Safety
@@ -36,15 +40,24 @@ module Insika
       end
 
       # The after_task hook (register with hooks.register(:task, after: ...)).
+      # the grounding validator is the OutputValidator's FIRST step —
+      # it runs before the output gate (D9), so grounding is independent of the
+      # guardrails opt-in.
       def output_validator
-        OutputValidator.new(ask_factory: ->(config) { ask_for(config) })
+        OutputValidator.new(ask_factory: ->(config) { ask_for(config) },
+                            grounding: GroundingValidator.new)
       end
 
+      # the `:enforce` boundary step the Executor calls between
+      # stages 6 and 8. Inert unless the profile's grounding.mode is :enforce.
+      def grounding_enforcer = GroundingEnforcer.new
+
       # Injected into the Executor. ->(state) { OutputFilter | nil }: a fresh stateful
       # filter per turn when the agent has output guardrails on; nil = off (parity).
       def content_filter_factory
         lambda do |state|
-          Config.from_profile(state.profile).output ? OutputFilter.new : nil
+          config = Config.from_profile(state.profile)
+          config.output ? OutputFilter.new(corpus: config.corpus) : nil
         end
       end
 

data/lib/insika/safety/grounding_enforcer.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Insika
+  module Safety
+    #   — the `:enforce` half of grounding: the claim's SENTENCE is
+    # cut from the content the turn persists and delivers. A NEW stage-8 boundary
+    # step (a plain executor call, NOT an after_task hook — after_task fires too
+    # late to change what is persisted).
+    #
+    # The cut removes the SENTENCE that contains an ungrounded claim (never a
+    # surgical span — removing half a sentence produces broken prose). What the
+    # cut CANNOT do is unsay a streamed delta — for a streaming surface `:enforce`
+    # still delivers the cut text via channel delivery and flags the turn; that
+    # honesty is why the own default is `:flag` (ship `:enforce` only after
+    # the matcher audit). Runs ONLY in :enforce mode — inert otherwise.
+    class GroundingEnforcer
+      # -> [new_content, state]. The stage-8 boundary call. Fail-open: grounding
+      # must never break a completed turn.
+      def call(task, state, content)
+        grounding = grounding_of(state)
+        return [content, state] unless grounding&.enforce?
+
+        ledger = state.respond_to?(:evidence_ledger) ? state.evidence_ledger : nil
+        return [content, state] unless ledger
+
+        text = content.to_s
+        refs = grounding.matcher.references(text)
+        claims = grounding.matcher.ungrounded(refs, evidence_ids: ledger.ids)
+        return [content, state] if claims.empty?
+
+        cut = cut_sentences(text, claims)
+        claims.each { |c| ledger.ungrounded_count(c) }
+        state.guardrail_flags = Array(state.guardrail_flags) + [{
+          category: "ungrounded", source: "evidence", action: "cut",
+          detail: "cut claim(s): #{claims.join(', ')}" }]
+        [cut, state]
+      rescue StandardError
+        [content, state] # fail-open: grounding must never break a completed turn
+      end
+
+      private
+
+      def grounding_of(state)
+        raw = state.profile.respond_to?(:grounding) ? state.profile.grounding : nil
+        raw && Insika::Grounding.parse(raw)
+      end
+
+      # The smallest self-contained unit: split on sentence boundaries and drop
+      # every sentence containing an ungrounded reference. Conservative on
+      # purpose — a sentence with TWO claims, one grounded and one not, is cut
+      # whole (documented behavior).
+      def cut_sentences(text, claims)
+        sentences = text.split(/(?<=[.!?])\s+/)
+        kept = sentences.reject { |sentence| claims.any? { |claim| sentence.include?(claim) } }
+        kept.join(" ").strip
+      end
+    end
+  end
+end

data/lib/insika/safety/grounding_validator.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Insika
+  module Safety
+    #   — the `:flag` half of grounding. A reply claiming a product
+    # whose reference is not in the evidence ledger is FLAGGED (audit via the
+    # existing `:guardrail_flagged` channel) — the text is already out, so
+    # flagging is audit, exactly like every other output flag.
+    #
+    # Runs as the FIRST step of the OutputValidator's after_task chain, BEFORE
+    # the `config.output` gate (D9): grounding is evidence integrity, independent
+    # of the guardrails opt-in — an agent with guardrails off and
+    # `grounding.mode: :flag` still gets the check. Fail-open on any error
+    # (grounding must never break a completed turn).
+    class GroundingValidator
+      # -> state (the after_task contract). Appends `:ungrounded` flags.
+      def call(state)
+        grounding = grounding_of(state)
+        # :flag only — :enforce is the enforcer's job, :off / absent is nothing.
+        return state if grounding.nil? || grounding.off? || grounding.enforce?
+
+        ledger = state.respond_to?(:evidence_ledger) ? state.evidence_ledger : nil
+        return state unless ledger
+
+        text = state.response_content.to_s
+        return state if text.empty?
+
+        refs = grounding.matcher.references(text)
+        claims = grounding.matcher.ungrounded(refs, evidence_ids: ledger.ids)
+        claims.each { |c| ledger.ungrounded_count(c) }
+        unless claims.empty?
+          state.guardrail_flags = Array(state.guardrail_flags) + [{
+            category: "ungrounded", source: "evidence",
+            detail: "product claim without tool evidence: #{claims.join(', ')}" }]
+        end
+        state
+      rescue StandardError
+        state # fail-open
+      end
+
+      private
+
+      def grounding_of(state)
+        raw = state.profile.respond_to?(:grounding) ? state.profile.grounding : nil
+        raw && Insika::Grounding.parse(raw)
+      end
+    end
+  end
+end

data/lib/insika/safety/input_guardrail.rb

@@ -33,7 +33,7 @@ module Insika
         config = Config.from_profile(state.profile)
         return nxt.call(state) unless config.input
 
-        hit = Detectors.scan_input(state.message.to_s, categories: config.input_categories)
+        hit = Detectors.scan_input(state.message.to_s, categories: config.input_categories, corpus: config.corpus)
         return block(state, config, category: hit[:category], source: :deterministic, detail: hit[:matched]) if hit
 
         if config.moderator? && (mod = build_moderator(config))

data/lib/insika/safety/moderator.rb

@@ -13,7 +13,7 @@ module Insika
     #
     # FAIL-OPEN by construction: the deterministic layer already ran and caught the
     # gross cases, so an unparseable/failed moderator reply must NOT block a
-    # legitimate customer. Blocking is the high-stakes direction (RFC: a false
+    # legitimate customer. Blocking is the high-stakes direction (a false
     # positive turns away a real buyer). But fail-open is not a fake negative
     # a moderator that could not answer returns the third state
     # `unavailable` — it does not block, and it is NOT recorded as a clean `allow`,

data/lib/insika/safety/output_filter.rb

@@ -9,7 +9,7 @@ module Insika
     # sits between the provider chunks and the `:content` event and only ever emits
     # text it has PROVEN clean.
     #
-    # The hard part (RFC, "fronteira de chunk"): a CPF/secret can arrive split
+    # The hard part ("fronteira de chunk"): a CPF/secret can arrive split
     # across two chunks and neither half matches on its own. A naive delta-by-delta
     # regex leaks "by construction". So the filter keeps a SLIDING BUFFER: it retains
     # the tail that might still be growing into a match (Detectors::OPEN_TAIL, which
@@ -21,7 +21,11 @@ module Insika
     class OutputFilter
       attr_reader :redaction_counts
 
-      def initialize
+      # `corpus` : the compiled corpus for the turn — the
+      # language-filtered PII set and its open-tail pattern. Default = the
+      # full shipped corpus (parity).
+      def initialize(corpus: Corpus.compile)
+        @corpus = corpus
         @buf = +""
         @emitted = +"" # full redacted text emitted so far (for the persisted content)
         @redaction_counts = Hash.new(0)
@@ -51,11 +55,11 @@ module Insika
       def safe_cut
         cut = @buf.length
 
-        if (m = @buf.match(Detectors::OPEN_TAIL))
+        if (m = @buf.match(@corpus.open_tail))
           cut = [cut, m.begin(0)].min
         end
 
-        Detectors.match_ranges(@buf).each do |b, e|
+        @corpus.match_ranges(@buf).each do |b, e|
           cut = b if b < cut && cut < e
         end
 
@@ -69,7 +73,7 @@ module Insika
 
         chunk = @buf[0...cut]
         @buf = @buf[cut..] || +""
-        redacted, counts = Detectors.redact(chunk)
+        redacted, counts = @corpus.redact(chunk)
         counts.each { |name, n| @redaction_counts[name] += n }
         @emitted << redacted
         redacted

data/lib/insika/safety/output_validator.rb

@@ -27,13 +27,19 @@ module Insika
     class OutputValidator
       # `ask_factory` (optional): ->(config) { ->(prompt){text} | nil }, built by the
       # Safety::Factory from the utility_model. nil = deterministic only.
-      def initialize(ask_factory: nil)
+      # `grounding` (optional): a GroundingValidator — its step runs
+      # FIRST in #call, before the `config.output` gate (D9: grounding is
+      # evidence integrity, independent of the guardrails opt-in).
+      def initialize(ask_factory: nil, grounding: nil)
         @ask_factory = ask_factory
+        @grounding = grounding
       end
 
       # after_task hook body. Idempotent and defensive: never raises out (a hook
-      # error must not fail a committed turn).
+      # error must not fail a committed turn). Grounding runs BEFORE the output
+      # gate so an agent with guardrails off and grounding on still gets the check.
       def call(state)
+        state = @grounding&.call(state) || state
         config = Config.from_profile(state.profile)
         return state unless config.output
 
@@ -41,7 +47,7 @@ module Insika
         return state if text.empty?
 
         flags = []
-        flags.concat(deterministic_flags(text))
+        flags.concat(deterministic_flags(text, config.corpus))
         flags.concat(llm_flags(text, config)) if config.moderator?
 
         state.guardrail_flags = Array(state.guardrail_flags) + flags unless flags.empty?
@@ -55,8 +61,8 @@ module Insika
       # Residual PII/secret that somehow reached the final text (the stream filter
       # should have caught it — this is defense in depth, and the flag itself
       # carries category counts, never the raw value).
-      def deterministic_flags(text)
-        _redacted, counts = Detectors.redact(text)
+      def deterministic_flags(text, corpus)
+        _redacted, counts = Detectors.redact(text, corpus: corpus)
         return [] if counts.empty?
 
         [{ category: "pii_residual", source: "deterministic", detail: counts.map { |k, v| "#{k}:#{v}" }.join(",") }]

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)
         @command_bus = command_bus
         @event_stream = event_stream
         @session_store = session_store
@@ -91,10 +92,18 @@ 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
         @heartbeat = config.fetch(:heartbeat, 15)
         @sync_timeout = config.fetch(:sync_timeout, 10) # synchronous control
       end
@@ -166,6 +175,10 @@ 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 ["POST", ["v1", "mcp", name, "import"]]
@@ -182,8 +195,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 +258,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 +276,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 +400,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
@@ -481,6 +535,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 +591,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 +881,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} 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 +1124,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

data/lib/insika/server/rack_app.rb

@@ -42,6 +42,10 @@ module Insika
       end
 
       attr_reader :token
+      attr_reader :graph
+      # the frozen criterion, memoized when the relay runs in shadow —
+      # nil otherwise. Loaded ONCE at boot (the refusal below), then shared.
+      attr_reader :criterion
 
       def app
         tenancy = @config[:tenancy] || ENV["INSIKA_TENANCY"] || "single_tenant"
@@ -71,6 +75,7 @@ module Insika
           channels: (@graph.channel_registry if channels?),
           config: { gateway_token: @token, tenancy: tenancy }.merge(@config),
           token_store: store,
+          outcome_store: @graph.outcome_store,
           # a 500's error_ref must be findable in the process log.
           logger: $stdout
         )
@@ -87,6 +92,17 @@ module Insika
             allow_http: Insika::EnvSchema.truthy?(ENV["INSIKA_EGRESS_ALLOW_HTTP"]),
             allow_private: Insika::EnvSchema.truthy?(ENV["INSIKA_EGRESS_ALLOW_PRIVATE"])
           )
+          # NO criterion, no shadow — enforced at boot, not per
+          # turn. Raises ConfigError when the file is missing, unparseable, or
+          # incomplete; the criterion is memoized here and injected into
+          # ChannelDelivery (its sha stamps every pair our half records).
+          if relay&.shadow?
+            criterion_path = Insika::EnvSchema.read("INSIKA_PARITY_CRITERION")
+            raise Insika::ConfigError, "shadow mode requires INSIKA_PARITY_CRITERION (the frozen criterion)" if criterion_path.nil?
+
+            @criterion = Insika::Parity::Criterion.load(criterion_path)
+            @graph.channel_delivery&.criterion_sha = @criterion.sha
+          end
           @graph.channel_registry.register(relay.id, relay) if relay
 
           widget = Insika::Channels::Web.from_env(

data/lib/insika/server/responses.rb

@@ -40,10 +40,45 @@ module Insika
         raise Insika::ValidationError, "user missing" if user.strip.empty?
 
         message = extract_input(body[:input])
-        raise Insika::ValidationError, "input empty" if message.strip.empty?
 
         out = { agent: agent.strip, user: user, message: message }
         (origin = Insika::MessageOrigin.parse!(body[:origin])) && (out[:origin] = origin)
+        # WS8: the optional customer_key — per-customer memory scope + purge handle
+        (customer = Insika::Coercion.presence(body[:customer])) && (out[:customer] = customer)
+        # WS9: the multimodal OPENAI shape — `input` as an array of content parts
+        # ({type: text/image/audio}) is preserved additively alongside the
+        # joined text; a string input stays byte-identical to before. The
+        # CONTRACT is enforced here (422) — the engine stays lenient.
+        raw = body[:input]
+        if raw.is_a?(Array)
+          unless Insika::Media.well_formed?(raw)
+            raise Insika::ValidationError,
+                  "malformed content part — each part must be {type: text|image|audio} with text/url"
+          end
+
+          normalized = Insika::Media.parts(raw).map do |p|
+            { "type" => p.type, "text" => p.text, "url" => p.url }.compact
+          end
+          out[:parts] = normalized unless normalized.empty?
+        end
+        # The turn needs SOMETHING to be about — text, or media the engine will
+        # turn into text (a voice note) or show the model (a photo). Checked
+        # after the parts are known, because the anchor use case (a WhatsApp
+        # voice note, no caption) carries no text at all and joining only the
+        # text parts made it a 422 at the door.
+        if message.strip.empty? && Array(out[:parts]).none? { |p| p["type"] != "text" }
+          raise Insika::ValidationError, "input empty"
+        end
+        # WS9: `source` marks pre-transcribed voice text; anything else is refused.
+        unless body[:source].nil? || body[:source].to_s == "voice"
+          raise Insika::ValidationError, 'source must be "voice"'
+        end
+        out[:source] = body[:source].to_s if Insika::Coercion.presence(body[:source])
+        # WS9 (saída): the channel declares which generated media it can
+        # RECEIVE ({ capabilities: ["image_output", "audio_output"] }). Additive
+        # + additive sibling on the completed frame; the exact capabilities are
+        # validated at the boundary (message_flow), not here.
+        (channel = body[:channel]) && (out[:channel] = channel)
         out
       end
 
@@ -146,6 +181,10 @@ module Insika
         # the OpenAI-shaped response.use it to run their escalation ("stuck" means
         # what they decide it means, never the engine's business).
         (outcome = event.data[:outcome]) && (response[:outcome] = outcome.to_s)
+        # WS9 (saída): generated media parts (image/audio clips) ride the
+        # completed frame additively next to the text — absent when none were
+        # generated. The base64 bytes are the consumer's to render/upload.
+        (parts = event.data[:output_parts]) && (response[:output_parts] = parts)
         sse("response.completed", { type: "response.completed", response: response })
       end
 

data/lib/insika/session_actor.rb

@@ -40,8 +40,12 @@ module Insika
     #
     # `policy` (a QueuePolicy) opens the debounce window for this turn; nil or a
     # policy without a window behaves exactly as before — dequeued and run at once.
-    def enqueue(task, profile:, resume_from: nil, policy: nil)
-      @queue.enqueue([task, profile, resume_from, policy])
+    #
+    # `timing`  is the channel clock a channel turn allocated at 202
+    # acceptance and already stamped `:inbound`; it rides the queue so the debounce
+    # window and the FIFO wait land INSIDE first_balloon_ms.
+    def enqueue(task, profile:, resume_from: nil, policy: nil, timing: nil)
+      @queue.enqueue([task, profile, resume_from, policy, timing])
       task.id
     end
 
@@ -99,12 +103,12 @@ module Insika
 
     def run_loop
       loop do
-        task, profile, resume_from, policy = @queue.dequeue # blocks when empty
+        task, profile, resume_from, policy, timing = @queue.dequeue # blocks when empty
         task = hold_at_the_door(task, policy)
         @running = true
         @current_task = task
         begin
-          @executor.run_serial(task, profile: profile, resume_from: resume_from)
+          @executor.run_serial(task, profile: profile, resume_from: resume_from, timing: timing)
         rescue StandardError
           # run_serial already maps turn errors; this rescue is defense: an
           # unexpected error must NEVER bring down the session loop (Async::Stop <