insika 0.1.0 → 0.3.0

data/lib/insika/edge_limiter.rb

@@ -4,7 +4,7 @@ require_relative "middleware"
 require_relative "coercion"
 
 module Insika
-  # The production edge (item 33 / §12 G7): THE named place where volume/cost
+  # The production edge: THE named place where volume/cost
   # abuse is cut. A Middleware with two independent limits, both OPT-IN
   # (nil/0 = off — a bare wiring behaves exactly as before):
   #
@@ -13,16 +13,29 @@ module Insika
   #   · agent token ceiling — total tokens per agent per window. Checked on entry
   #     against the accumulated ledger; the turn's own usage is recorded AFTER the
   #     terminal returns (the Middleware wraps stages 5-9, so state.usage is set).
+  #   · calendar budget    — WS2: `AgentProfile#budget` caps the spend per
+  #     (tenant, agent) over CALENDAR windows (daily/monthly), on the
+  #     BudgetLedger. Hard (default): crossing the cap raises the typed
+  #     Insika::BudgetExceeded (the envelope quotes budget_exceeded +
+  #     retry_after); soft: crossing warns instead — ONE budget_warning event
+  #     per window plus a note injected into the context. Crossing `alert_at`
+  #     (default 0.8 of the cap) warns the same way, before the wall. The turn's
+  #     billed spend (input+output+cached+cache_creation — the A4 rule) lands on
+  #     the windows after the terminal.
   #
   # Config resolution, per turn (configuration over convention):
   #   profile.limits[:chat_rate_limit / :agent_token_ceiling]  — per-agent override
   #   settings["edge"]                                          — platform default
   # A per-agent 0 explicitly disables a platform default for that agent.
   #
-  # On breach it uses the graceful-halt contract (RFC-0009 §3.1): halt_response
+  # On breach it uses the graceful-halt contract: halt_response
   # (the safe reply) + guardrail_block (audit -> :guardrail_blocked) and does NOT
   # call `nxt` — the turn completes with ZERO LLM calls. It sits BEFORE the
   # InputGuardrail in the stack so a flood can't spend the LLM moderator either.
+  # The BUDGET breach is the ONE deliberate exception: it is a typed failure
+  # (BudgetExceeded), not a customer-facing reply — the operator wants the
+  # envelope to say "budget" and quote when the window rolls, not to hand the
+  # customer a cost message.
   class EdgeLimiter < Middleware
     CHAT_KIND   = "chat"
     TOKENS_KIND = "tokens"
@@ -35,9 +48,13 @@ module Insika
     DEFAULT_RESPONSE = "Estou recebendo muitas mensagens agora. Aguarde um " \
                        "momento e tente novamente, por favor."
 
-    def initialize(ledger:, settings_store: nil)
+    def initialize(ledger:, settings_store: nil, budget_ledger: nil, event_stream: nil)
       @ledger = ledger
       @settings = settings_store
+      # WS2: the calendar-window ledger. nil = budget off (parity — the bare
+      # wiring is byte-identical to before).
+      @budget_ledger = budget_ledger
+      @event_stream = event_stream
     end
 
     def call(state, &nxt)
@@ -48,8 +65,14 @@ module Insika
       # the rate-limit reply exactly when the window is saturated. Entry checks
       # are skipped; the turn's usage still lands on the ledger below.
       resumed = state.resumed
+      # a SCHEDULED turn (the FollowupEngine's kick) skips the
+      # ENTRY checks exactly like a resume — a follow-up that trips the token
+      # ceiling must not receive the rate-limit REPLY (the customer agreed to
+      # this message; the volume control is the follow-up policy, not the flood
+      # rail). The turn still runs and its usage still lands on the ledger.
+      scheduled = scheduled_turn?(state)
 
-      if !resumed && (limit = positive(limits.key?(:chat_rate_limit) ? limits[:chat_rate_limit] : edge["chat_rate_limit"]))
+      if !resumed && !scheduled && (limit = positive(limits.key?(:chat_rate_limit) ? limits[:chat_rate_limit] : edge["chat_rate_limit"]))
         breach = check_chat_rate(state, limit, edge)
         return block(state, edge, **breach) if breach
       end
@@ -58,7 +81,7 @@ module Insika
       # `"chat_rate_limit": null`) reads as OFF for that agent, not "inherit".
       if (ceiling = positive(limits.key?(:agent_token_ceiling) ? limits[:agent_token_ceiling] : edge["agent_token_ceiling"]))
         token_window = positive(edge["agent_token_window"]) || DEFAULT_TOKEN_WINDOW
-        unless resumed
+        unless resumed || scheduled
           spent = @ledger.count(TOKENS_KIND, state.profile.id.to_s, window: token_window)
           if spent >= ceiling
             return block(state, edge, category: :token_ceiling,
@@ -69,13 +92,40 @@ module Insika
         record_after = token_window
       end
 
-      result = nxt.call(state)
-      record_usage(state, record_after) if record_after
+      # WS2: calendar budgets. Entry — a HARD budget at/over the cap raises the
+      # typed error (never a customer-facing reply); the alert_at warning and
+      # the SOFT over-cap both warn once per window + inject a context note.
+      # A resumed turn (crash/pause replay) was already admitted: it is never
+      # refused twice — its spend still lands on the ledger below. A scheduled
+      # turn  rides the same rule: the follow-up policy is the
+      # volume control, not the budget wall.
+      budget_on = budget_configured?(state)
+      budget_enforce(state) unless resumed || scheduled
+
+      result = begin
+        nxt.call(state)
+      ensure
+        # A turn that FAILED after burning tokens still SPENT them: record the
+        # usage the state captured before the error propagates. The ask's usage
+        # lands on state.usage before any later stage (guardrail block, tool
+        # error, workflow schema) can fail the turn — a failed turn must count
+        # against the budget like a completed one (WS2).
+        record_usage(state, record_after) if record_after
+        record_budget_usage(state) if budget_on
+      end
       result
     end
 
     private
 
+    # is this turn the FollowupEngine's synthetic kick? The
+    # command type is stamped by the engine only — a consumer cannot send it
+    # (the SendMessage edge refuses the spelling, C8).
+    def scheduled_turn?(state)
+      command = state.respond_to?(:task) && state.task&.command
+      command.is_a?(Hash) && command["type"].to_s == "scheduled_followup"
+    end
+
     # One KV get per turn (same order of cost as the guardrail's config read);
     # no SettingsStore in the wiring -> per-agent limits only.
     def platform_edge
@@ -101,7 +151,7 @@ module Insika
     # prefix (`Executor#usage_of` reports `cached_tokens`/`cache_creation_tokens`
     # alongside it) — on a cached identity that prefix is ~95% of what the
     # provider actually processed, so a ceiling reading only `total_tokens` is
-    # blind (RFC-0016 A4). Same billed-spend rule as `Evals::Runner#billed_tokens`.
+    # blind. Same billed-spend rule as `Evals::Runner#billed_tokens`.
     # nil usage (workflow turn / provider without counts) records nothing.
     def record_usage(state, window)
       usage = state.usage || {}
@@ -126,5 +176,114 @@ module Insika
       v = value.to_i
       v.positive? ? v : nil
     end
+
+    # --- WS2 calendar budgets ------------------------------------------
+
+    # -> truthy when a budget is configured AND the ledger is wired.
+    def budget_configured?(state)
+      budget = state.profile.respond_to?(:budget) ? state.profile.budget : nil
+      !budget.nil? && !@budget_ledger.nil?
+    end
+
+    # -> truthy (the budget hash) when budget checks ran. Raises BudgetExceeded
+    # on a HARD cap breach.
+    def budget_enforce(state, now: Time.now)
+      budget = state.profile.respond_to?(:budget) ? state.profile.budget : nil
+      return nil if budget.nil? || @budget_ledger.nil?
+
+      tenant = budget_tenant(state)
+      agent = state.profile.id.to_s
+      budget_windows(budget).each do |w|
+        spent = @budget_ledger.current(tenant: tenant, agent: agent, now: now)[w[:window]]
+        if spent >= w[:cap]
+          unless w[:soft]
+            raise Insika::BudgetExceeded.new(
+              window: w[:window],
+              retry_after: @budget_ledger.reset_in(w[:window], now: now)
+            )
+          end
+          warn_budget(state, tenant, agent, w, spent, now, level: "cap")
+        elsif spent >= w[:alert_at]
+          warn_budget(state, tenant, agent, w, spent, now, level: "alert_at")
+        end
+      end
+      budget
+    end
+
+    # The (tenant, agent) scope: the COMMAND's tenant (nil -> the BudgetLedger's
+    # "platform" cell) — never state.tenant, which falls back to the session id
+    # (a per-chat bucket is not a budget).
+    def budget_tenant(state)
+      command = state.respond_to?(:task) && state.task&.command
+      return nil unless command.is_a?(Hash)
+
+      meta = command["meta"] || command[:meta] || {}
+      meta["tenant"] || meta[:tenant]
+    end
+
+    # -> [{ window:, cap:, soft:, alert_at: }] — one entry per configured window
+    # (a 0/absent cap is off). absent `soft` = FALSE (hard): a limit that does
+    # not limit is decoration; the alert_at warning is the soft half.
+    def budget_windows(budget)
+      alert_at = budget["alert_at"].to_f
+      alert_at = 0.8 if alert_at <= 0 || alert_at >= 1
+      soft = budget["soft"] == true
+      %i[daily monthly].filter_map do |window|
+        cap = budget[window.to_s].to_i
+        cap.positive? ? { window: window, cap: cap, soft: soft,
+                          alert_at: (cap * alert_at).floor } : nil
+      end
+    end
+
+    # The warning: a note in the context (the model sees it, the customer's
+    # transcript does not) + the budget_warning event — each LEVEL once per
+    # (window) cell: the `alert_at` crossing and the real soft-cap crossing are
+    # separate markers, so the cap event is never swallowed by the 80% one that
+    # fired earlier (WS2).
+    def warn_budget(state, tenant, agent, w, spent, now, level:)
+      inject_budget_note(state,
+                         "[budget: agent '#{agent}' is at #{spent}/#{w[:cap]} tokens this " \
+                         "#{w[:window]} window — keep this turn cheap]")
+      return if @budget_ledger.mark_alert(tenant: tenant, agent: agent, window: w[:window],
+                                          level: level, now: now)
+
+      # `tenant` on the META too, not only in the payload: the tenant-scoped
+      # /v1/events subscription filters on meta[:tenant] and is fail-closed, so
+      # a warning about the tenant's OWN budget never reached the tenant.
+      meta = { task_id: state.task&.id, session_id: state.task&.session_id,
+               at: Time.now.utc.iso8601 }
+      meta[:tenant] = tenant unless tenant.nil?
+      @event_stream&.emit(Insika::Event.new(
+                            type: :budget_warning,
+                            data: { agent: agent, tenant: tenant, window: w[:window],
+                                    spent: spent, cap: w[:cap], level: level },
+                            meta: meta
+                          ))
+    end
+
+    # Appends the note to the assembled system prompt: the real Data package is
+    # immutable (with), the specs' minimal Struct is mutable — both duck-typed.
+    def inject_budget_note(state, note)
+      ctx = state.context
+      return if ctx.nil?
+
+      if ctx.respond_to?(:with)
+        state.context = ctx.with(system: "#{ctx.system}\n\n#{note}")
+      elsif ctx.respond_to?(:system=)
+        ctx.system = "#{ctx.system}\n\n#{note}"
+      end
+    end
+
+    # The turn's REAL billed spend (input + output + cached + cache_creation —
+    # the A4 rule) on the calendar windows.
+    def record_budget_usage(state, now: Time.now)
+      usage = state.usage || {}
+      tokens = usage[:total_tokens].to_i + usage[:cached_tokens].to_i +
+               usage[:cache_creation_tokens].to_i
+      return if tokens.zero?
+
+      @budget_ledger.add(tenant: budget_tenant(state), agent: state.profile.id.to_s,
+                         by: tokens, now: now)
+    end
   end
 end

data/lib/insika/egress_guard.rb

@@ -8,14 +8,14 @@ module Insika
   # EGRESS guard for data-tools (SSRF). A data-tool makes a server-side HTTP
   # request with a URL coming from UI-editable config — without a guard, it's an
   # SSRF vector (hitting cloud metadata, internal services, localhost). Rules
-  # (spec NF2):
+  # (spec):
   #   - https only by default (http requires explicit opt-in);
   #   - host required;
   #   - optional host allowlist (when present, only it passes);
   #   - resolves the host and BLOCKS if ANY address falls into a private/
   #     loopback/link-local/metadata network (defense against DNS rebinding);
   #   - `allow_private:` (opt-in) ALLOWS the private target — to reach a trusted
-  #     INTERNAL API (NF4: the consumer's /api/internal/* comes in via an
+  #     INTERNAL API (the consumer's /api/internal/* comes in via an
   #     allowlist). Dangerous without `host_allowlist`: PIN it to a known host.
   #     Default false = strict guard.
   #
@@ -48,7 +48,7 @@ module Insika
       addrs = resolve(host)
       return "host did not resolve" if addrs.empty?
       # allow_private skips the private-network block (trusted internal API,
-      # NF4). Without it, a private/loopback/metadata target is always blocked.
+      # Without it, a private/loopback/metadata target is always blocked.
       return "private-network destination blocked" if !allow_private && addrs.any? { |ip| blocked?(ip) }
 
       nil

data/lib/insika/env_schema.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Insika
-  # STRICT config, environment layer (item 23 / §8.1). OpenClaw's config discipline
+  # STRICT config, environment layer. OpenClaw's config discipline
   # — "recusa boot com chave desconhecida, no silent config compat" — applied to the
   # env vars the engine reads at boot. A declarative registry of the keys the engine
   # OWNS (config over convention: the schema IS data), used two ways:
@@ -12,7 +12,7 @@ module Insika
   #     silence), and a DEPRECATED legacy key still set under the old HARNESS_ prefix.
   #     Unknown-key detection is scoped to the OWNED prefixes only, so the platform's
   #     own vars (Railway's RAILWAY_*, PORT, PATH, the litestream sidecar's
-  #     LITESTREAM_*, the deployment's DEEPSEEK_*/ACHEI_*) are never flagged.
+  #     LITESTREAM_*, the deployment's DEEPSEEK_*/CONSUMER_*) are never flagged.
   #   · `enforce!(strict:)` — the boot gate. WARNS on every finding by default and
   #     lets the engine come up (last-known-good — a rotated key or a typo must never
   #     take the whole service down, same reasoning as the resilient DEEPSEEK boot);
@@ -92,7 +92,7 @@ module Insika
       Spec.new(name: name, type: type, secret: secret, required: required, enum: enum, description: description)
     end
 
-    # The engine's own keys. Deployment/app keys (DEEPSEEK_*, ACHEI_*, …) are NOT
+    # The engine's own keys. Deployment/app keys (DEEPSEEK_*, CONSUMER_*, …) are NOT
     # here — a root passes them as `extra:`.
     DEFAULT = [
       spec(name: "INSIKA_DB", type: :path, description: "SQLite path; durable config+state. Unset -> ephemeral memory."),
@@ -102,22 +102,32 @@ module Insika
       spec(name: "INSIKA_ENV", description: "Environment name shown in the Studio (falls back to RACK_ENV)."),
       spec(name: "INSIKA_A2A_AGENT", description: "Agent id to expose over inbound A2A (opt-in)."),
       spec(name: "INSIKA_A2A_REMOTES", type: :csv, description: "Comma-separated remote A2A endpoints."),
-      spec(name: "INSIKA_EGRESS_ALLOW_HTTP", type: :boolean, description: "Allow plain http egress from data-tools (default: https only)."),
+      spec(name: "INSIKA_EGRESS_ALLOW_HTTP", type: :boolean, description: "Allow plain http egress from data-tools, channel callbacks and media fetches (default: https only)."),
       spec(name: "INSIKA_EGRESS_ALLOW_PRIVATE", type: :boolean, description: "Allow egress to private/loopback ranges (SSRF guard off)."),
-      spec(name: "INSIKA_EGRESS_HOSTS", type: :csv, description: "Comma-separated host allowlist for data-tool egress."),
+      spec(name: "INSIKA_EGRESS_HOSTS", type: :csv, description: "Comma-separated host allowlist for data-tool egress (media fetches are NOT pinned by it)."),
       spec(name: "INSIKA_OTEL", type: :boolean, description: "Turn on OpenTelemetry export (opt-in)."),
       spec(name: "INSIKA_MODEL_PRICING", description: "JSON rates table (USD per million tokens) for the estimated-cost attribute; unset -> no cost reported."),
-      spec(name: "INSIKA_TURN_TIMING", type: :boolean, description: "Emit per-turn TTFB breakdown in responses (opt-in, item 34)."),
+      spec(name: "INSIKA_TURN_TIMING", type: :boolean, description: "Emit per-turn TTFB breakdown in responses (opt-in)."),
       spec(name: "INSIKA_SUBAGENT_DEPTH_CAP", type: :integer, description: "Max delegation depth in the subagent graph (default 5)."),
       spec(name: "INSIKA_SUBAGENT_FANOUT_CAP", type: :integer, description: "Max parallel children in spawn_subagents (default 8)."),
-      spec(name: "INSIKA_CONFIG_STRICT", type: :boolean, description: "Refuse boot on any config finding instead of warning (item 23)."),
-      spec(name: "INSIKA_BOOT_ID", description: "Boot generation id shared by all workers of one container start; the recovery task sweep runs once per id (RFC-0016). Unset -> every boot sweeps."),
-      spec(name: "INSIKA_DRAIN_TIMEOUT", type: :integer, description: "Seconds a stopping worker waits for in-flight turns before abandoning them to the next boot's recovery (default 20, RFC-0016 A3)."),
-      spec(name: "INSIKA_ONBOARDING", type: :boolean, description: "Expose the public onboarding surface (/start.md, /models.json, /docs) in production (opt-in, item 20)."),
-      spec(name: "INSIKA_RELAY_TOKEN", secret: true, description: "Bearer the relay consumer sends us. Unset -> the relay channel is not mounted (RFC-0011 §6)."),
+      spec(name: "INSIKA_CONFIG_STRICT", type: :boolean, description: "Refuse boot on any config finding instead of warning."),
+      spec(name: "INSIKA_BOOT_ID", description: "Boot generation id shared by all workers of one container start; the recovery task sweep runs once per id. Unset -> every boot sweeps."),
+      spec(name: "INSIKA_DRAIN_TIMEOUT", type: :integer, description: "Seconds a stopping worker waits for in-flight turns before abandoning them to the next boot's recovery (default 20)."),
+      spec(name: "INSIKA_TICK_INTERVAL", type: :integer, description: "Seconds between tick passes (outbox drain + stale recovery sweep). Default 60; 0 disables."),
+      spec(name: "INSIKA_TICK_STALE_AFTER", type: :integer, description: "Seconds a :queued/:running task must sit untouched before the tick sweeps it (default 900). Must exceed the largest turn_timeout of the deployment."),
+      spec(name: "INSIKA_STT_MODEL", description: "Model used to transcribe audio message parts (WS9). Unset -> RubyLLM's default transcription model."),
+      spec(name: "INSIKA_STT_LANGUAGE", description: "Language hint for the transcription of audio message parts (WS9)."),
+      spec(name: "INSIKA_TENANCY", enum: %w[single_tenant multi_tenant], description: "single_tenant (default: one operator credential) or multi_tenant (per-tenant + operator tokens resolved from the store)."),
+      spec(name: "INSIKA_ONBOARDING", type: :boolean, description: "Expose the public onboarding surface (/start.md, /models.json, /docs) in production (opt-in)."),
+      spec(name: "INSIKA_RELAY_TOKEN", secret: true, description: "Bearer the relay consumer sends us. Unset -> the relay channel is not mounted."),
       spec(name: "INSIKA_RELAY_DELIVER_URL", type: :url, description: "Consumer callback the relay POSTs each reply to."),
       spec(name: "INSIKA_RELAY_DELIVER_TOKEN", secret: true, description: "Bearer the relay sends TO the consumer's callback (optional)."),
-      spec(name: "INSIKA_WIDGET_ORIGINS", type: :csv, description: "Exact-match origins allowed to embed the web widget. Unset -> the widget channel is not mounted (RFC-0011 §5)."),
+      spec(name: "INSIKA_RELAY_SHADOW", type: :boolean, description: "Shadow mode: the relay records replies instead of delivering them."),
+      spec(name: "INSIKA_RELAY_DELIVERY", type: :enum, enum: %w[at_end progressive], description: "How the relay flushes the outbox: at_end (one POST) or progressive (one POST per balloon). Unset -> at_end."),
+      spec(name: "INSIKA_PARITY_CRITERION", type: :path, description: "The frozen parity criterion file (required in shadow mode)."),
+      spec(name: "INSIKA_HARVEST_CRITERION", type: :path, description: "The frozen harvest conversion criterion file (strict-loaded before any promotion)."),
+      spec(name: "INSIKA_HARVEST_NEGATIVE", type: :path, description: "The negative-list seed file the harvest CLI imports into agent profiles."),
+      spec(name: "INSIKA_WIDGET_ORIGINS", type: :csv, description: "Exact-match origins allowed to embed the web widget. Unset -> the widget channel is not mounted."),
       spec(name: "INSIKA_WIDGET_AGENTS", type: :csv, description: "Agent ids a widget visitor may address. Unset -> the widget channel is not mounted."),
       spec(name: "OPENCLAW_GATEWAY_TOKEN", secret: true, description: "Bearer for /v1 + /a2a (falls back to ADMIN_TOKEN)."),
       spec(name: "OPENCLAW_AGENTS_DIR", type: :path, description: "Directory of OpenClaw-style agent packs."),

data/lib/insika/errors.rb

@@ -30,7 +30,63 @@ module Insika
     end
   end
 
-  class ProviderError  < Error; end  # RubyLLM exhausted retries -> task :failed
+    # A provider/transport failure, wrapped by ProviderErrorClassifier with an
+  # ACTION classification (B9). The fields ride in the task's error record and
+  # the :task_failed event so the client envelope can tell fatal from
+  # retryable and quote the provider's own retry_after (A8). A bare
+  # `ProviderError.new("boom")` has an empty classification and adds nothing
+  # to the contract.
+  class ProviderError < Error
+    attr_reader :kind, :retryable, :retry_after
+
+    def initialize(message = nil, kind: nil, retryable: nil, retry_after: nil)
+      @kind = kind
+      @retryable = retryable
+      @retry_after = retry_after
+      super(message)
+    end
+
+    # the additive envelope fields, compacted — nil retry_after stays absent.
+    def classification
+      { kind: kind, retryable: retryable, retry_after: retry_after }.compact
+    end
+  end
+
+  # The hard budget refused the turn (WS2): the (tenant, agent) spend in the
+  # window already met its cap BEFORE the turn ran. A typed, retryable failure —
+  # the envelope reads `budget_exceeded` + `retry_after` (seconds until the
+  # window rolls) — never a silent drop. `window` is :daily | :monthly.
+  class BudgetExceeded < Error
+    attr_reader :window, :retry_after
+
+    def initialize(message = nil, window: nil, retry_after: nil)
+      @window = window
+      @retry_after = retry_after
+      super(message || "budget exceeded (#{window})")
+    end
+
+    def classification
+      { kind: :budget_exceeded, retryable: true, retry_after: retry_after }.compact
+    end
+  end
+
+  # The circuit breaker refused the turn WITHOUT touching the provider (WS3):
+  # the (tenant, provider/model) saw `after` failures within `within` seconds.
+  # Typed + retryable — the envelope reads `circuit_open` + `retry_after`
+  # (seconds until the cooldown lets a half-open trial through).
+  class CircuitOpenError < Error
+    attr_reader :ref, :retry_after
+
+    def initialize(message = nil, ref: nil, retry_after: nil)
+      @ref = ref
+      @retry_after = retry_after
+      super(message || "circuit open for #{ref}")
+    end
+
+    def classification
+      { kind: :circuit_open, retryable: true, retry_after: retry_after }.compact
+    end
+  end
   class StoreError     < Error; end  # persistence backend failed -> task :failed
   class CancelledError < Error; end  # cooperative cancellation -> task :cancelled
 
@@ -75,7 +131,7 @@ module Insika
     end
   end
 
-  # Subagent graph integrity (RFC-0010 §4.4). Raised at DEFINITION-time
+  # Subagent graph integrity. Raised at DEFINITION-time
   # (CreateAgent/UpdateAgent/boot) by SubagentGraph.validate! — a subagents
   # allowlist that forms a cycle or exceeds the depth cap is a configuration
   # error, never a runtime surprise. A ValidationError so the authoring Command
@@ -101,7 +157,7 @@ module Insika
     end
   end
 
-  # Workflow I/O contract violation (item 22 / §4.4). A workflow may declare an
+  # Workflow I/O contract violation. A workflow may declare an
   # `input_schema` / `output_schema`; a value that does not conform is rejected.
   # INPUT is validated SYNCHRONOUSLY (TriggerWorkflow) so it is a ValidationError
   # -> HTTP 422, no run created. OUTPUT is validated inside the fiber after the
@@ -119,14 +175,25 @@ module Insika
     end
   end
 
-  # A channel could not hand a reply to its recipient (RFC-0011 §6.5). NOT a turn
+  # A channel could not hand a reply to its recipient. NOT a turn
   # failure: the turn already completed and its answer is durable in the session —
   # what failed is the delivery, which lives in the OutboxStore with its own status
   # and its own bounded retry. Raised by a channel's `deliver` so the dispatcher can
   # tell "the recipient refused" from "the engine has a bug".
   class DeliveryError < Error; end
 
-  # Strict configuration violation (item 23 / §8.1 — OpenClaw's config discipline:
+  # WS4 routing failed: a route's delegate agent is not configured, or its turn
+  # failed. An operator/config error — the envelope names the :routing stage
+  # instead of swallowing it as :unknown.
+  class RoutingError < Error; end
+
+  # WS9 media failed: an audio part could not be fetched or transcribed, an
+  # image attachment could not be built, or a media URL was egress-blocked. A
+  # customer's voice message that never entered the turn must not be silently
+  # dropped — the :media stage names it.
+  class MediaError < Error; end
+
+  # Strict configuration violation (— OpenClaw's config discipline:
   # "recusa boot com chave desconhecida, no silent config compat"). Raised by
   # EnvSchema.enforce! at boot ONLY when strictness is on (INSIKA_CONFIG_STRICT) —
   # by default a bad key WARNS and the engine still boots (last-known-good: a rotated

data/lib/insika/evals/assertions.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# D4 (RFC-0009): the PII/secret patterns live in the RUNTIME (single source of
+# the PII/secret patterns live in the RUNTIME (single source of
 # truth) — the eval consumes them rather than keeping a divergent copy. Since the
 # module moved under `lib/`, `Safety::Detectors` is loaded by `insika.rb` before this
 # file; the explicit climb out of `evals/` that used to be here is gone.
@@ -33,12 +33,12 @@ module Insika
     # evaluated", never a silent pass. A case passes only if the deterministic checks
     # pass AND (there's no judge verdict OR it passed).
     #
-    # `skipped` (a reason, nil = it ran) is the THIRD outcome (RFC-0014 §3.2): the
+    # `skipped` (a reason, nil = it ran) is the THIRD outcome: the
     # deployment lacks something the case declared it needs, so there was nothing to
     # assert. It is never a pass and never a failure — a suite of 40 cases where 12
     # are skipped says something true, where 40 cases with 12 failures on capability
     # grounds says nothing and gets ignored.
-    # `pairwise` (a Pairwise::Verdict, RFC-0014 §3.4) is attached when the case
+    # `pairwise` (a Pairwise::Verdict) is attached when the case
     # carries a `reference:` and a panel is configured. It DELIBERATELY does not enter
     # `pass?`: "worse than the incumbent" is a judgement about a replacement decision,
     # not a regression in the suite, and letting it fail a case would put an opinion
@@ -53,25 +53,26 @@ module Insika
       def judge_pending? = !skipped? && !rubric.to_s.strip.empty? && judge.nil?
     end
 
-    # Deterministic (Fase A) evaluation — cheap, zero-token, zero-flakiness. It's the
+    # Deterministic evaluation — cheap, zero-token, zero-flakiness. It's the
     # layer that catches the gross regressions (a tool stopped being called, a secret
-    # leaked, the turn errored). Subjective scoring is the LLM-judge in Fase B.
+    # leaked, the turn errored). Subjective scoring is the LLM-judge in.
     module Assertions
-      # Named negative detectors for `must_not` now live in the runtime (D4). Kept as
+      # Named negative detectors for `must_not` now live in the runtime. Kept as
       # an alias so any external reference to Evals::Assertions::PII_DETECTORS still
-      # resolves; the values ARE the runtime's, never a fork.
-      PII_DETECTORS = Insika::Safety::Detectors::PII
+      # resolves; the values ARE the runtime's, never a fork. the
+      # pattern data moved to the corpus, still under the same Safety umbrella.
+      PII_DETECTORS = Insika::Safety::Corpus::PII
 
-      # HOW MUCH THE AGENT SHOULD ASK BEFORE ACTING (RFC-0014 §3.3). Declared per
+      # HOW MUCH THE AGENT SHOULD ASK BEFORE ACTING. Declared per
       # case because it is a per-STORE decision, not a universal rule: sometimes the
       # agent should establish the objective before searching ("energia, treino ou
-      # sono?" — Ocean Drop does this well), and sometimes asking again is the
+      # sono?" — a good store agent does this well), and sometimes asking again is the
       # failure and it should just search. A global assertion would be wrong half
       # the time; the judge is TOLD the policy (Judge#build_prompt) and this layer
       # checks the half that needs no reader.
       #
-      # Each rule is stated as the CUSTOMER-VISIBLE fact it checks. RFC-0014 phrased
-      # this as "questions before the first tool call", written before P19: text a
+      # Each rule is stated as the CUSTOMER-VISIBLE fact it checks. phrased
+      # this as "questions before the first tool call", written before: text a
       # model emits before calling a tool never reaches the customer now (it rides
       # `:intermediate`), and the eval is a client of `/v1/responses`, so what it can
       # observe per turn is the published answer plus the tools that turn called.
@@ -87,7 +88,7 @@ module Insika
 
       module_function
 
-      # WHAT THIS DEPLOYMENT LACKS for the case to be worth running (RFC-0014 §3.2).
+      # WHAT THIS DEPLOYMENT LACKS for the case to be worth running.
       # -> [reason]; empty = run it.
       #
       # `available` is the deployment's answer for this agent:
@@ -237,7 +238,7 @@ module Insika
 
       # Runs a named detector over the text. "pii_leak" = union of all PII detectors;
       # otherwise a single named pattern. Delegates to the runtime's single source
-      # (D4) — which itself fails loud on an unknown name (a typo'd assertion must not
+      # which itself fails loud on an unknown name (a typo'd assertion must not
       # silently pass).
       def detect(name, text)
         Insika::Safety::Detectors.detect(name, text)

data/lib/insika/evals/baseline.rb

@@ -4,7 +4,7 @@ require "json"
 
 module Insika
   module Evals
-    # Fase C gating (RFC-0008 §3.4). A baseline is the accepted state of the golden
+    # gating. A baseline is the accepted state of the golden
     # set — `{ cases: { id => { pass, score } } }`. A gated run compares against it and
     # blocks only on a REGRESSION, so known-failing cases don't wedge the gate while a
     # real drop (a passing case that now fails, or a judge score that fell past the
@@ -16,7 +16,7 @@ module Insika
 
       # [CaseResult] -> baseline hash. `at` is stamped by the caller (kept out of here
       # so the module stays deterministic/testable).
-      # A SKIPPED case is left out entirely (RFC-0014 §3.2): writing it as `pass:
+      # A SKIPPED case is left out entirely: writing it as `pass:
       # false` would accept "this deployment cannot run it" as the accepted state,
       # and the case would never block anywhere again.
       def snapshot(results, at:)
@@ -38,7 +38,7 @@ module Insika
       # in BOTH are compared: a new case (no baseline entry) never blocks the gate (it
       # shows in the report as ❌ but is not a "regression"); document this in README.
       #   • pass→fail   : baseline pass, now failing (hard regression).
-      #   • pass→skipped: baseline pass, now unrunnable HERE. RFC-0014 §3.2 says the
+      #   • pass→skipped: baseline pass, now unrunnable HERE. says the
       #                   gate never blocks ON a skip, and it does not: a case that was
       #                   already skipped or unknown stays silent. But a case that used
       #                   to run on this deployment and no longer can means the agent

data/lib/insika/evals/golden.rb

@@ -2,8 +2,8 @@
 
 require "yaml"
 
-# Evals — the quality harness (RFC-0008). It lives in `lib/` so the engine itself can
-# call it (the refinement gate of RFC-0013 needs to score a candidate agent, and a
+# Evals — the quality harness. It lives in `lib/` so the engine itself can
+# call it (the refinement gate of needs to score a candidate agent, and a
 # second copy of the judge would be the worst possible outcome), but it stays a
 # CLIENT: it reaches a running deployment over HTTP through `HttpTransport` and never
 # reads a store directly. `evals/run.rb` is a thin CLI over this module.
@@ -28,17 +28,17 @@ module Insika
       # Names of the negative assertions to run (e.g. "pii_leak", "tool_error").
       def must_not = Array(expect["must_not"]).map(&:to_s)
 
-      # How much the agent should ask before acting (RFC-0014 §3.3). nil = the store
+      # How much the agent should ask before acting. nil = the store
       # has no opinion and only the rubric decides.
       def policy = GoldenLoader.presence(expect["policy"])
 
-      # What the DEPLOYMENT must have for this case to mean anything (RFC-0014 §3.2).
+      # What the DEPLOYMENT must have for this case to mean anything.
       # Empty = runs everywhere.
       def required_tools = Array(requires["tools"]).map(&:to_s)
       def required_capabilities = Array(requires["capabilities"]).map(&:to_s)
       def requirements? = !(required_tools + required_capabilities).empty?
 
-      # THE INCUMBENT'S CONVERSATION for the same opening (RFC-0014 §3.4) — the other
+      # THE INCUMBENT'S CONVERSATION for the same opening — the other
       # half of a pairwise comparison. Data in the case, not a store read: the eval is
       # a client, and a pair that lives in one reviewable file cannot go stale against
       # a database nobody looked at.
@@ -47,14 +47,14 @@ module Insika
       def reference? = !reference_messages.empty?
 
       # Did a PERSON type part of the reference half? After a handoff the operator's
-      # words are stored as `role: assistant` (P23a), and comparing a model to a human
+      # words are stored as `role: assistant`, and comparing a model to a human
       # and calling it a win is a lie in both directions — so the pair is LABELLED and
       # the report never prints the outcome without it.
       def human_assisted?
         reference_messages.any? { |m| MessageOrigin.origin_of(m) == MessageOrigin::OPERATOR }
       end
 
-      # LLM-judge rubric + threshold (consumed in Fase B — deferred here).
+      # LLM-judge rubric + threshold (consumed in — deferred here).
       def rubric = expect["rubric"]
       def min_score = expect["min_score"]
     end
@@ -126,7 +126,7 @@ module Insika
         raise InvalidGolden, "#{where} needs a 'role' of user or assistant" unless %w[user assistant].include?(role)
 
         text = presence(raw["text"]) || (raise InvalidGolden, "#{where} needs a non-empty 'text'")
-        # The SAME closed vocabulary the engine stamps (P23a). A typo'd marker would
+        # The SAME closed vocabulary the engine stamps. A typo'd marker would
         # read as "absent" downstream, which is how a human turn gets scored as the
         # incumbent's model.
         origin = begin