insika 0.1.0 → 0.3.0

data/lib/insika/server/app.rb

@@ -3,8 +3,9 @@
 require "json"
 require "rack"
 require "async"
+require "securerandom"
 require_relative "sse_body"
-require_relative "admin_auth" # Bearer checker shared by the gateway edge (fail-closed)
+require_relative "tenant_auth" # WS1: Bearer -> { role:, tenant_id: } (single/multi-tenant)
 require_relative "a2a/app" # A2A edge adapter (pulls protocol/errors/message/projection/card)
 require_relative "responses" # OpenAI Responses adapter (/v1/responses) — drop-in for the OpenClaw gateway
 
@@ -32,7 +33,7 @@ module Insika
       TERMINAL_EVENTS = %i[task_completed task_failed task_cancelled].freeze
       private_constant :TERMINAL_EVENTS
 
-      # RFC-0016 A5: the `/v1` contract, versioned by date. A caller PINS behaviour
+      # the `/v1` contract, versioned by date. A caller PINS behaviour
       # with `Insika-Version: YYYY-MM-DD` so a future breaking change does not move
       # silently underneath it; absent header = today's (only) version. Only one
       # entry exists so far — the day a second one is added, the routes that
@@ -41,13 +42,21 @@ module Insika
       KNOWN_VERSIONS = ["2026-08-08"].freeze
       private_constant :KNOWN_VERSIONS
 
-      # The operator control UI now lives in the Studio (§12 G5); server/ is a
+      # the 500 envelope. A 500 is by definition unexpected — the client
+      # cannot fix the request, so the contract is "you may retry, wait this
+      # long, and quote this ref when you report it". The ref only means
+      # anything because the same line goes to the server log (see #internal_error_response).
+      RETRY_AFTER_SECONDS = 1
+      private_constant :RETRY_AFTER_SECONDS
+
+      # The operator control UI now lives in the Studio; server/ is a
       # pure transport surface (/v1, /a2a). The constitutional rule holds: server/
       # only READS stores and never imports the Executor, store writes, or RubyLLM.
       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)
+                     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
@@ -56,26 +65,45 @@ module Insika
         @pending_action_store = pending_action_store # read for GET /v1/tasks/:id
         @a2a = a2a # A2A edge. nil = server does not expose A2A (parity).
         @provisioner = provisioner # PackImporter. nil = provisioning not exposed.
-        # Item 22 / §4.4: READ-ONLY registry, injected only where workflows are
+        # WS1 multi-tenant credentials. nil = single_tenant mode (the classic
+        # single operator credential, gateway_token). Present = tokens resolve
+        # from the store (per-tenant + operator), gateway_token still resolves
+        # as operator (an existing deployment switching modes keeps its token).
+        @token_store = token_store
+        # "single_tenant" (default, parity) | "multi_tenant".
+        @tenancy = config.fetch(:tenancy, "single_tenant")
+        # READ-ONLY registry, injected only where workflows are
         # exposed (the minimal wiring). nil = no /v1/workflows routes (parity — the
         # deployment does not expose workflows). Reading a catalog is a READ, like a
         # store read: the constitutional rule (no Executor/store-writes/RubyLLM) holds.
         @workflow_registry = workflow_registry
-        # Item 20 / §5.6: LLM-first onboarding surface (start.md + models.json +
+        # LLM-first onboarding surface (start.md + models.json +
         # docs). PUBLIC (no auth — the whole point of the "read <base>/start.md" trick
         # is that the developer's coding agent can fetch it), and READ-ONLY, so the
         # constitutional rule holds. nil = routes not exposed (parity — the production
         # deployment opts in). Reading files/masked stores is a READ, like a store read.
         @onboarding = onboarding
-        # RFC-0014 §3.2: READ-ONLY ProfileSource, so `GET /v1/agents/:id` can answer
+        # READ-ONLY ProfileSource, so `GET /v1/agents/:id` can answer
         # what an agent has — the eval is a client and cannot read a store. Same
         # constitutional footing as the workflow registry: reading a catalog is a
         # READ. nil = the route 404s (parity).
         @profiles = profiles
-        # RFC-0011 §4.4: ONE generic route family for every channel, opt-in by
+        # ONE generic route family for every channel, opt-in by
         # 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
@@ -96,7 +124,7 @@ module Insika
       rescue Async::TimeoutError => e
         error_response(504, e) # synchronous control request exceeded the ceiling
       rescue StandardError => e
-        error_response(500, e)
+        internal_error_response(e)
       end
 
       private
@@ -114,8 +142,15 @@ module Insika
           return version_error if version_error
         end
 
-        gate = public_route?(req.request_method, segments) ? nil : gateway_gate(req)
+                gate = public_route?(req.request_method, segments) ? nil : gateway_gate(req)
         return gate if gate
+        # WS1: a TENANT principal is confined to its own runtime surfaces (chat
+        # + its own reads). Every authoring/provisioning surface stays
+        # operator-only — a tenant can never mint tokens, author tools or
+        # change platform config. single_tenant (no principal) is untouched.
+        if tenant_principal?(req) && !tenant_surface?(req.request_method, segments)
+          return auth_error(403, "operator surface")
+        end
 
         case [req.request_method, segments]
         in ["GET", ["up"]]
@@ -140,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"]]
@@ -151,13 +190,17 @@ module Insika
         in ["GET", ["v1", "agents", id]] if @profiles
           handle_read_agent(id)
         in ["GET", ["v1", "sessions", id]]
-          handle_read_session(id)
+          handle_read_session(req, id)
         in ["GET", ["v1", "tasks", id]]
-          handle_read_task(id)
+          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
@@ -215,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
@@ -233,16 +276,62 @@ 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)
-        command = Insika::Command.build(:create_session, { vars: body[:vars] || {} },
-                                         transport: :http)
+        tenant = req_tenant(req)
+        # WS1: a tenant's session must be born under its OWN "<tenant>:" namespace
+        # — the read path (GET /v1/sessions/:id) refuses anything else. Scope the
+        # caller's id the same way message_flow scopes a session_id; a tenant that
+        # passed none gets a namespaced uuid instead of an unprefixed one it could
+        # never read back.
+        if tenant
+          id = body[:id] || body["id"]
+          id = Insika::Coercion.blank?(id) ? scoped_session_id(tenant, SecureRandom.uuid)
+                                           : scoped_session_id(tenant, id)
+          body = body.merge(id: id)
+        end
+        command = Insika::Command.build(:create_session,
+                                         { vars: body[:vars] || {}, id: body[:id] }.compact,
+                                         transport: :http, tenant: tenant)
         session = dispatch_with_timeout(command)
         json_response(201, { session: session.to_h })
       end
@@ -251,13 +340,14 @@ module Insika
       # "false" -> 200 JSON aggregated at the terminal event.
       def handle_send_message(req)
         stream = req.GET["stream"] != "false"
-        # RFC-0015 §5.5: only the aggregated-JSON form has room for the `merged`/`steered`
+        # only the aggregated-JSON form has room for the `merged`/`steered`
         # verdict, so only it may join a message to another turn. Once the stream is open
         # there is no way to tell the caller it does not own the reply.
-        message_flow(parse_body(req), stream: stream, transport: stream ? :http : :"http:json")
+        message_flow(parse_body(req), stream: stream, transport: stream ? :http : :"http:json",
+                                      tenant: req_tenant(req))
       end
 
-      # GET /docs/:name.md — one public doc as raw markdown (item 20 / §5.6). The
+      # GET /docs/:name.md — one public doc as raw markdown. The
       # slug is a KEY of the onboarding allowlist, so no filesystem traversal is
       # possible; an unknown slug -> 404. `file` still carries the ".md" suffix.
       def handle_doc(file)
@@ -274,7 +364,7 @@ module Insika
         Insika::Coercion.presence(@config[:public_url]) || req.base_url
       end
 
-      # GET /v1/workflows — discovery (item 22 / §4.4). Direct read of the
+      # GET /v1/workflows — discovery. Direct read of the
       # registry catalog (name + description + the I/O schema contract). Not a
       # Command; opt-in via the injected registry.
       def handle_list_workflows
@@ -293,7 +383,8 @@ module Insika
         body = parse_body(req)
         payload = { workflow: name, agent: body[:agent],
                     input: body[:input], session_id: body[:session_id] }.compact
-        workflow_flow(payload, stream: req.GET["stream"] == "true")
+        workflow_flow(payload, stream: req.GET["stream"] == "true",
+                               tenant: req_tenant(req))
       end
 
       # POST /v1/responses — OpenAI Responses adapter (drop-in for the OpenClaw
@@ -305,14 +396,20 @@ module Insika
         return gate if gate
 
         parsed = Responses.parse_request(parse_body(req), req) # ValidationError -> 422
-        ensure_session(parsed[:user])
+        tenant = req_tenant(req)
+        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
-        message_flow(payload, stream: true, serialize: Responses.method(:frame_for))
+        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
 
       # POST /v1/agents — provisions (upserts) an agent from a standardized
-      # PACK (Phase 6/D4/F7). Same Bearer as /v1/responses (gateway_token,
+      # PACK. Same Bearer as /v1/responses (gateway_token,
       # fail-closed). The consumer (GatewayClient/ProvisionStore) sends the pack as
       # JSON; the PackImporter emits the authoring Commands. -> 200 { summary }.
       # Raw body (string keys): the pack's file/skill names are data keys,
@@ -326,7 +423,7 @@ module Insika
       end
 
       # POST /v1/tools/manifest — BATCH ingestion of data-tools via manifest
-      # (Phase 7, Step B). Same Bearer as provisioning (gateway_token, fail-
+      # Same Bearer as provisioning (gateway_token, fail-
       # closed): it's an authoring/provisioning surface and resolves the
       # deployment's secrets. RAW body (string keys): the JSON Schema property names and
       # the headers are DATA, not symbols. Dispatches :import_tools -> 200 { per-tool
@@ -341,7 +438,7 @@ module Insika
         json_response(200, dispatch_with_timeout(command))
       end
 
-      # POST /v1/mcp/:name/import — LIVE MCP ingestion (Phase 7, Step E). Same
+      # POST /v1/mcp/:name/import — LIVE MCP ingestion. 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:
@@ -367,7 +464,7 @@ module Insika
 
       # GET /v1/agents/:id — what this deployment HAS for that agent, so an eval
       # (a client: it never reads a store) can tell "this case cannot run here" from
-      # "this case failed" (RFC-0014 §3.2). Deliberately NOT the profile: the prompt,
+      # "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.
       #
@@ -400,26 +497,85 @@ module Insika
       end
 
       # Gateway Bearer (fail-closed). -> error response (503/401) OR nil when
-      # ok (the handler proceeds).
+      # ok (the handler proceeds). In multi_tenant mode the resolved principal
+      # is stashed on the request env: `tenant_principal?`/`req_tenant` read it
+      # back for the surface gate and the command stamping.
       def gateway_gate(req)
-        case Insika::Server::AdminAuth.check(@config[:gateway_token], req.get_header("HTTP_AUTHORIZATION"))
+        result = Insika::Server::TenantAuth.check(@config[:gateway_token], @token_store,
+                                                  req.get_header("HTTP_AUTHORIZATION"))
+        case result
         when :disabled then auth_error(503, "gateway disabled")
         when :unauthorized then auth_error(401, "unauthorized", "www-authenticate" => "Bearer")
+        else
+          req.set_header("insika.principal", result)
+          nil
         end
       end
 
-      # POST /channels/:id/events — the Shape B inbound webhook (RFC-0011 §4.4).
+      # -> bool: is the requester a TENANT principal (multi_tenant mode only)?
+      # The surface gate and the session/task read gates consume it; an operator
+      # principal is NOT a tenant (it has the run of the deployment, exactly as
+      # in single_tenant mode).
+      def tenant_principal?(req)
+        p = req.get_header("insika.principal")
+        p && p[:role] == "tenant"
+      end
+
+      # The tenant the request operates AS: nil for an operator/classic request.
+      def req_tenant(req)
+        p = req.get_header("insika.principal")
+        p && p[:role] == "tenant" ? p[:tenant_id] : nil
+      end
+
+      # A tenant may reach ONLY its own runtime surfaces. Everything else
+      # (commands, provisioning, authoring, config) is the operator's. An
+      # unknown route is NOT here -> a tenant is refused (the surface exists —
+      # just not for them), not told it is missing.
+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]],
+        ["GET", ["v1", "tasks", nil]],
+        ["GET", ["v1", "events"]]
+      ].freeze
+      private_constant :TENANT_SURFACES
+
+      def tenant_surface?(method, segments)
+        TENANT_SURFACES.any? do |m, s|
+          m == method && s.zip(segments).all? { |pattern, got| pattern.nil? || pattern == got }
+        end
+      end
+
+      # Session id namespacing (WS1): a tenant's session lives under
+      # "<tenant>:<id>", so two tenants using the SAME chat id never share a
+      # session — the key itself is the isolation, not a convention. ":"
+      # (never "/") so the id stays one URL path segment; the same delimiter
+      # convention as the channels' "<channel>:<external_id>". Idempotent (a
+      # caller passing its own namespaced id back is not double-prefixed).
+      def scoped_session_id(tenant, id)
+        return id if tenant.nil? || id.nil? || id.to_s.empty?
+        return id if id.to_s.start_with?("#{tenant}:")
+
+        "#{tenant}:#{id}"
+      end
+
+      # POST /channels/:id/events — the Shape B inbound webhook.
       # ACK FAST and never the reply: the platform (or the relay consumer) is holding
       # a connection open with a retry timer on it, so this dispatches the turn and
       # answers with its id. The answer itself leaves later, out of band, through the
-      # channel's own `deliver` (§6.5).
+      # channel's own `deliver`.
       #
       # The channel does ALL the translating — auth, envelope, session correlation —
       # and this handler stays what `server/` is allowed to be: a route that turns a
       # request into a Command. Four answers, and each one is a different fact:
       #   202 {task_id}            a turn is running; its reply will be delivered
-      #   200 {task_id, duplicate} we already ran this event id (§6.4)
-      #   200 {task_id, merged}    it joined a turn at the door (RFC-0015 §5.5)
+      #   200 {task_id, duplicate} we already ran this event id
+      #   200 {task_id, merged}    it joined a turn at the door
       #   200 {task_id, steered}   it was appended to a turn already running
       # A consumer that treats the last three as 202 delivers the same answer twice.
       def handle_channel_event(req, id)
@@ -435,11 +591,56 @@ module Insika
 
         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
-      # channel (RFC-0011 §4.3). The engine issues the id and the client never
+      # channel. The engine issues the id and the client never
       # proposes one: an endpoint that created a session from a caller-supplied id
       # would let anyone read someone else's conversation by guessing.
       #
@@ -523,7 +724,7 @@ module Insika
       end
 
       # Does this session exist AND belong to this channel? `vars["channel"]` is
-      # written when the session is minted (§4.3).
+      # written when the session is minted.
       def channel_session?(id, session_id)
         session = session_id && @session_store.find(session_id)
         return false if session.nil?
@@ -569,7 +770,7 @@ module Insika
         json_response(202, { task_id: result[:task_id] })
       end
 
-      # RFC-0011 §4.3: `channel` + `external_id` on the session are how a later turn
+      # `channel` + `external_id` on the session are how a later turn
       # (and the outbox) know where a reply goes. The consumer's own `vars` ride along
       # on first contact, but never over those two — a caller must not be able to
       # rewrite its own conversation's address.
@@ -582,19 +783,29 @@ module Insika
       # namespaced `<channel>:<external_id>` for a channel): creates if new, continues
       # if it exists (multi-turn). Via Command (server/ does not write to a store).
       # Benign race (two near-simultaneous turns creating) -> ArgumentError from the
-      # store, treated as "already exists".
-      def ensure_session(id, vars: { channel: "responses" })
+      # store, treated as "already exists". A TENANT's id is namespaced (WS1), so
+      # two tenants with the same chat id get two isolated sessions.
+      def ensure_session(id, vars: { channel: "responses" }, tenant: nil)
+        id = scoped_session_id(tenant, id)
         return if @session_store.find(id)
 
         @command_bus.dispatch(
-          Insika::Command.build(:create_session, { id: id, vars: vars }, transport: :http)
+          Insika::Command.build(:create_session, { id: id, vars: vars }, transport: :http,
+                                tenant: tenant)
         )
       rescue ArgumentError
         nil
       end
 
-      # GET /v1/sessions/:id — direct read (not a Command).
-      def handle_read_session(id)
+      # GET /v1/sessions/:id — direct read (not a Command). A tenant may only
+      # read its OWN sessions: the ownership is the id namespace itself (its
+      # sessions live under "<tenant>:…"), anything else reads as a 404.
+      def handle_read_session(req, id)
+        tenant = req_tenant(req)
+        if tenant && !id.to_s.start_with?("#{tenant}:")
+          raise Insika::NotFoundError, "session not found: #{id}"
+        end
+
         session = @session_store.find(id)
         raise Insika::NotFoundError, "session not found: #{id}" if session.nil?
 
@@ -603,11 +814,18 @@ module Insika
 
       # GET /v1/tasks/:id — direct read. This is where the consumer observes
       # PolicyDenied/post-202 failures: the terminal state lives in the Task
-      # Store; nothing is lost if the client disconnected.
-      def handle_read_task(id)
+      # Store; nothing is lost if the client disconnected. A tenant may only
+      # read a task its own command stamped (the task record carries the
+      # command with its meta.tenant) — someone else's reads as a 404.
+      def handle_read_task(req, id)
         task = @task_store.find(id)
         raise Insika::NotFoundError, "task not found: #{id}" if task.nil?
 
+        tenant = req_tenant(req)
+        if tenant && task_tenant(task) != tenant
+          raise Insika::NotFoundError, "task not found: #{id}"
+        end
+
         body = { task: task_to_h(task) }
         # pending approvals: this is where the consumer/operator sees
         # what needs approval after an :approval_requested.
@@ -617,12 +835,24 @@ module Insika
         json_response(200, body)
       end
 
+      # The tenant stamped on the task's persisted command (WS1): string or
+      # symbol keys, whichever the store round-trip produced.
+      def task_tenant(task)
+        command = task.respond_to?(:command) ? task.command : nil
+        return nil unless command.is_a?(Hash)
+
+        meta = command["meta"] || command[:meta] || {}
+        meta["tenant"] || meta[:tenant]
+      end
+
       # GET /v1/events?task_id=&session_id= — here the filters ARE known.
       # CONTINUOUS stream (post-crash reconnection route): does not close on a
-      # terminal event — ends on client disconnect or cap.
+      # terminal event — ends on client disconnect or cap. A tenant's stream is
+      # scoped to its own events (fail-closed on the event's meta.tenant).
       def handle_events(req)
         subscription = @event_stream.subscribe(task_id: req.GET["task_id"],
-                                                session_id: req.GET["session_id"])
+                                                session_id: req.GET["session_id"],
+                                                tenant: req_tenant(req))
         sse_response(subscription)
       end
 
@@ -650,8 +880,45 @@ module Insika
       # transport (TaskFilter). A SYNCHRONOUS handler error (Validation/NotFound)
       # 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)
-        command = Insika::Command.build(:send_message, payload, transport: transport)
+      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.
+        if tenant
+          payload = payload.dup
+          payload[:session_id] = scoped_session_id(tenant, payload[:session_id]) if payload[:session_id]
+        end
+        command = Insika::Command.build(:send_message, payload, transport: transport, tenant: tenant)
         subscription = @event_stream.subscribe
         result =
           begin
@@ -661,7 +928,7 @@ module Insika
             raise
           end
 
-        # RFC-0015 §5.5: the message joined another turn — one still waiting at the
+        # the message joined another turn — one still waiting at the
         # door (`merged`) or one already running (`steered`). Either way this call
         # owns no reply; the one holding `task_id` does. Say exactly that and open no
         # stream: a caller that delivered this response's (empty) output would
@@ -682,14 +949,20 @@ module Insika
         stream ? sse_response(filtered, serialize: serialize) : aggregate_response(filtered, task_id)
       end
 
-      # Workflow trigger flow (item 22). Async by default (the honest workflow
+      # Workflow trigger flow. Async by default (the honest workflow
       # contract: fire the run, return the runId); ?stream=true streams the run's
       # events like a turn. Same subscribe-before-dispatch discipline as
       # message_flow so no eager event is lost when streaming. A synchronous handler
       # error (bad input / unknown workflow) closes the subscription and propagates
       # to #call (HTTP status).
-      def workflow_flow(payload, stream:)
-        command = Insika::Command.build(:trigger_workflow, payload, transport: :http)
+      def workflow_flow(payload, stream:, tenant: nil)
+        # WS1: same session-id namespacing as message_flow — the workflow's run
+        # session is the tenant's own.
+        if tenant
+          payload = payload.dup
+          payload[:session_id] = scoped_session_id(tenant, payload[:session_id]) if payload[:session_id]
+        end
+        command = Insika::Command.build(:trigger_workflow, payload, transport: :http, tenant: tenant)
 
         unless stream
           result = dispatch_with_timeout(command)
@@ -724,7 +997,11 @@ module Insika
           events << event.to_h
           case event.type
           when :content        then content << event.data[:delta].to_s
-          when :task_failed    then error = { class: event.data[:error], message: event.data[:message] }
+          when :task_failed
+            error = { class: event.data[:error], message: event.data[:message] }
+            # A8: the classification rides through when the executor wrapped
+            # the failure (ProviderError) — additive for every other terminal.
+            error = error.merge(event.data.slice(:kind, :retryable, :retry_after))
           when :task_cancelled then error = { class: "Insika::CancelledError", message: "task cancelled" }
           when :error          then error ||= { class: nil, message: event.data[:message] }
           end
@@ -812,15 +1089,50 @@ module Insika
         json_response(status, { error: { class: error.class.name, message: error.message } })
       end
 
+      # the 500 is the ONE status whose body carries the retry envelope —
+      # retryable/retry_after tell the client what to do, error_ref is what it
+      # quotes when the retry keeps failing. The SAME ref is logged here, or the
+      # field is decoration. 4xx stay bare: a client error is fixed by editing
+      # the request, not by waiting.
+      def internal_error_response(error)
+        ref = "err_#{SecureRandom.hex(8)}"
+        # Observability only (shutdown.rb's rule): a logger failure must never
+        # mask the 500 the client is owed.
+        begin
+          @logger&.puts("[server] #{ref} #{error.class}: #{error.message}\n" \
+                        "#{Array(error.backtrace).first(5).join("\n")}")
+        rescue StandardError
+          nil
+        end
+        # B9/A8: a classified ProviderError quotes its own retry guidance;
+        # everything else keeps the blanket retry (the caller may have died mid
+        # request — a bounded wait is the safe default).
+        retryable = error.respond_to?(:retryable) && !error.retryable.nil? ? error.retryable : true
+        retry_after = error.respond_to?(:retry_after) && error.retry_after ? error.retry_after : RETRY_AFTER_SECONDS
+        body = { error: { class: error.class.name, message: error.message,
+                           retryable: retryable, retry_after: retry_after, error_ref: ref } }
+        body[:error][:kind] = error.kind if error.respond_to?(:kind) && error.kind
+        json_response(500, body)
+      end
+
       def not_found
         [404, { "content-type" => "text/plain" }, ["not found"]]
       end
 
       # Liveness/readiness. Fixed 200: if the process accepts the connection and recovery
-      # has already run (Boot only returns the app afterward — doc 07 §4), it's ready. Does NOT
+      # has already run (Boot only returns the app afterward), it's ready. Does NOT
       # 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