insika 0.1.0 → 0.2.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,20 @@ 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)
         @command_bus = command_bus
         @event_stream = event_stream
         @session_store = session_store
@@ -56,26 +64,37 @@ 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
+        # 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
         @heartbeat = config.fetch(:heartbeat, 15)
         @sync_timeout = config.fetch(:sync_timeout, 10) # synchronous control
       end
@@ -96,7 +115,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 +133,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"]]
@@ -151,9 +177,9 @@ 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 ["POST", ["channels", id, "events"]] if @channels
@@ -241,8 +267,21 @@ module Insika
       # 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 +290,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 +314,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 +333,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 +346,16 @@ 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))
+        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 +369,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 +384,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 +410,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 +443,83 @@ 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
+
+      # -> 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", "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
 
-      # POST /channels/:id/events — the Shape B inbound webhook (RFC-0011 §4.4).
+      # 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)
@@ -439,7 +539,7 @@ module Insika
       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 +623,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 +669,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 +682,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 +713,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 +734,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 +779,15 @@ 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)
+        # 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 +797,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 +818,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 +866,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,12 +958,38 @@ 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" })
 

data/lib/insika/server/boot.rb

@@ -52,12 +52,12 @@ module Insika
         Sync { do_recovery }
       end
 
-      # Task recovery THEN delegation recovery (RFC-0010 Fase 2): the delegation
+      # Task recovery THEN delegation recovery: the delegation
       # sweep re-delivers completed-but-undelivered async delegations, and depends
       # on the task sweep having re-dispatched any in-flight children first. Both
       # create task fibers, so both must run inside the reactor scope of run_recovery.
       #
-      # The TASK sweep is additionally gated per boot generation (RFC-0016 E2):
+      # The TASK sweep is additionally gated per boot generation:
       # its "orphaned :running" test cannot see a sibling worker's live fiber, so
       # only the worker that claims the generation sweeps — the others would steal
       # in-flight turns. The delegation and channel sweeps stay ungated: each of
@@ -89,7 +89,7 @@ module Insika
         log("boot: delegations re-delivered — #{Array(result && result[:delivered]).size}")
       end
 
-      # RFC-0011 §6.5: replies a previous process committed but never handed to the
+      # replies a previous process committed but never handed to the
       # channel. Runs AFTER the task recovery for the same reason the delegation
       # sweep does — a resumed turn writes its own outbox record at its terminal, and
       # sweeping first would miss it.
@@ -108,7 +108,7 @@ module Insika
         return if @wiring.durable?
 
         log("boot: WARNING — EPHEMERAL backend (no INSIKA_DB): recovery will " \
-            "not resume anything after a restart (doc 02 §6).")
+            "not resume anything after a restart.")
       end
 
       def log(message)

data/lib/insika/server/rack_app.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# RFC-0017 A3 — the /v1 transport as a VALUE the host app mounts, instead of a
+# the /v1 transport as a VALUE the host app mounts, instead of a
 # server the engine starts.
 #
 #   mount Insika::Server.rack_app(INSIKA, token: ENV.fetch("INSIKA_TOKEN")), at: "/ai"
@@ -11,7 +11,7 @@
 # server boot now calls this instead of inlining it, which is what keeps the two
 # from drifting.
 #
-# The Studio is deliberately NOT part of this (the embed contract, item 4): it is
+# The Studio is deliberately NOT part of this (the embed contract): it is
 # a class-level singleton, so it is one per process, and a host that wants the
 # operator UI mounts `Studio::App` itself and accepts that limitation.
 
@@ -44,27 +44,35 @@ module Insika
       attr_reader :token
 
       def app
+        tenancy = @config[:tenancy] || ENV["INSIKA_TENANCY"] || "single_tenant"
+        # WS1: the token store is handed over ONLY in multi_tenant mode — in
+        # single_tenant the classic gateway token is the only credential
+        # (passing the store would silently widen the surface).
+        store = tenancy == "multi_tenant" ? @graph.token_store : nil
         @app ||= Insika::Server::App.new(
           command_bus: @graph.bus, event_stream: @graph.event_stream,
           session_store: @graph.session_store, task_store: @graph.task_store,
           pending_action_store: @graph.pending_action_store,
           provisioner: Insika::PackImporter.new(bus: @graph.bus, profiles: @graph.profiles),
           # GET /v1/agents/:id — the read-only capability view a case's `requires`
-          # resolves against (RFC-0014 §3.2).
+          # resolves against.
           profiles: @graph.profiles,
-          # Item 20 / §5.6: the OSS onboarding surface (start.md + models.json + docs).
+          # the OSS onboarding surface (start.md + models.json + docs).
           # This is the primary "build my first agent" target — models.json reports the
           # DSL's stores + the agents this process serves (each id IS the `model`).
           onboarding: build_onboarding,
-          # Item 22: GET /v1/workflows + POST /v1/workflows/:name, opt-in by
+          # GET /v1/workflows + POST /v1/workflows/:name, opt-in by
           # injection like every other edge — nil when the system declares none,
           # so the routes simply do not exist (404, parity).
           workflow_registry: (@graph.workflow_registry if workflows?),
-          # RFC-0011: the bundled relay, when the env turns it on. Same rule as the
+          # the bundled relay, when the env turns it on. Same rule as the
           # OTEL bridge — a feature only `config.ru` can reach is a feature the
           # docs are half-true about.
           channels: (@graph.channel_registry if channels?),
-          config: { gateway_token: @token }.merge(@config)
+          config: { gateway_token: @token, tenancy: tenancy }.merge(@config),
+          token_store: store,
+          # a 500's error_ref must be findable in the process log.
+          logger: $stdout
         )
       end