insika 0.1.0 → 0.2.0

data/lib/insika/reliability.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+module Insika
+  # The reliability policy for the turn's provider interaction (WS3): retries
+  # with exponential backoff, mid-turn ROTATION across the fallback chain, and
+  # the circuit breaker — all as DATA on `AgentProfile#reliability`, never a
+  # parallel code path. The failure classification is B9's
+  # (ProviderErrorClassifier): ONLY :retryable / :rate_limited_* ever retry or
+  # rotate; a :fatal is re-raised immediately (a poisoned credential must not
+  # hammer N models).
+  #
+  # Each ATTEMPT is a fresh chat built by the caller (the coordinator yields the
+  # selection): a failed `ask` leaves its user message in the chat, so re-asking
+  # the same chat would double the input. The customer-visible answer comes only
+  # from the attempt that returns; the fragments of failed attempts ride
+  # :intermediate (operator-side) and die with the turn.
+  #
+  # The breaker is per (tenant, provider/model): a node whose circuit is open is
+  # skipped (fail-fast with CircuitOpenError when the PRIMARY is open — the turn
+  # dies in ms, no provider call); a node that tripped mid-turn moves on.
+  class Reliability
+    DEFAULT_TIMEOUT = 30 # seconds per attempt (reliability["timeout"])
+
+    # circuit_store: CircuitState (the breaker's durable cells).
+    # event_stream:  where the reliability events go (:provider_fallback, ...).
+    # sleeper:       ->(seconds) — the backoff wait; injectable for specs.
+    def initialize(circuit_store:, event_stream:, sleeper: nil)
+      @circuit_store = circuit_store
+      @event_stream = event_stream
+      @sleeper = sleeper || method(:backoff_wait)
+    end
+
+    # policy:   the profile's reliability data (string keys) — the caller skips
+    #           this coordinator entirely when nil (parity).
+    # tenant:   the command tenant (breaker scoping; nil = platform).
+    # agent:    the agent id (event attribution — WS6 alerts read it).
+    # selection: the resolved primary ModelSelection.
+    # chain:    [{ model:, provider: }] fallback candidates (profile's first,
+    #           then the platform's resolved fallbacks).
+    # attempt:  ->(selection, attempt_index) { response } — build the chat for
+    #           that selection and ask. May RAISE a provider-family error.
+    #
+    # -> the successful response. Raises CircuitOpenError (primary open),
+    # or the last retryable error when every node exhausted its retries.
+    def call(policy:, tenant:, agent: nil, selection:, chain:, &attempt)
+      @agent = agent # event attribution (WF6 alerts) for THIS run
+      nodes = ([selection] + Array(chain)).map { |node| { selection: node, tries: 0 } }
+      retries = [policy["retries"].to_i, 0].max
+      breaker = breaker_config(policy)
+      # The per-attempt ceiling. A policy WITHOUT a timeout is DEFAULT_TIMEOUT —
+      # nothing config overrides here (the old [.., 1].max silently made every
+      # unset profile die in ~1s, WS3).
+      configured_timeout = policy["timeout"].to_i
+      timeout = configured_timeout.positive? ? configured_timeout : DEFAULT_TIMEOUT
+      # declaraed HERE (not inside a block) so the post-loop `raise` sees the
+      # method-local binding — a first assignment inside a block would not leak.
+      last_error = nil
+
+      # Fail-fast BEFORE any provider call: the PRIMARY's circuit open means
+      # this provider family is known-dead — the turn dies in ms.
+      if breaker && breaker_open?(tenant, selection, breaker)
+        raise circuit_open(tenant, selection, breaker)
+      end
+      nodes.each do |node|
+        selection = node[:selection]
+        next if breaker && breaker_open?(tenant, selection, breaker)
+
+        attempts = retries + 1
+        attempts.times do |index|
+          node[:tries] += 1
+          begin
+            response = with_attempt_timeout(timeout) { yield selection, node[:tries] }
+            @circuit_store.record_success(tenant: tenant, ref: ref_of(selection)) if breaker
+            return response
+          rescue StandardError => e
+            last_error = e
+            # A :fatal provider error — or ANYTHING that is not a provider
+            # failure at all (a bug, a domain error, a guardrail raise) — is
+            # never retried, never rotated (B9's structural rule). Only
+            # retryable/rate-limited (and the per-attempt timeout we raised)
+            # spend the retry budget. The B9 classifier is class-name based, so
+            # OUR TimeoutError reads as :fatal — the retryable_failure? check
+            # (which owns the reliability-stage timeout) must decide FIRST, or
+            # the :fatal guard would swallow it (WS3: a timeout never retried,
+            # never rotated).
+            retryable = retryable_failure?(e)
+            raise unless retryable
+            raise if kind_of(e) == :fatal && !e.is_a?(Insika::TimeoutError)
+
+            record_failure(tenant, selection, breaker, e)
+            # the last attempt of the last node re-raises; otherwise back off
+            # and give the next attempt/node a turn.
+            if index < attempts - 1 || node != nodes.last
+              @sleeper.call(backoff_seconds(policy, index))
+            end
+          end
+        end
+      end
+      raise last_error if last_error
+
+      raise Insika::Error, "reliability loop exhausted without a result"
+    end
+
+    private
+
+    def breaker_config(policy)
+      b = policy["circuit_breaker"]
+      return nil unless b.is_a?(Hash) && b["after"].to_i.positive?
+
+      { after: b["after"].to_i, within: b["within"].to_i, cooldown: b["cooldown"].to_i }
+    end
+
+    # The breaker cell reads need the POLICY's numbers; they ride as args. Only
+    # :open FAIL-FASTS; :half_open (cooldown elapsed) is the TRIAL — allowed.
+    def breaker_open?(tenant, selection, breaker)
+      @circuit_store.state(tenant: tenant, ref: ref_of(selection),
+                           after: breaker[:after], within: breaker[:within],
+                           cooldown: breaker[:cooldown]) == :open
+    end
+
+    def circuit_open(tenant, selection, breaker)
+      Insika::CircuitOpenError.new(
+        "circuit open for #{ref_of(selection)}",
+        ref: ref_of(selection),
+        retry_after: @circuit_store.retry_after(tenant: tenant, ref: ref_of(selection),
+                                                cooldown: breaker[:cooldown])
+      )
+    end
+
+    def record_failure(tenant, selection, breaker, error)
+      return unless breaker
+
+      tripped = @circuit_store.record_failure(
+        tenant: tenant, ref: ref_of(selection),
+        after: breaker[:after], within: breaker[:within]
+      )
+      emit(:provider_failure,
+           { agent: @agent, ref: ref_of(selection), error: error.class.name, kind: kind_of(error) })
+      # the failure that TRIPPED the circuit is itself an alert (WS6).
+      emit(:breaker_open, { agent: @agent, ref: ref_of(selection), tenant: tenant }) if tripped == :open
+    end
+
+    def kind_of(error) = ProviderErrorClassifier.classify(error).kind
+
+    # A provider-family error OR the per-attempt timeout: both are transient
+    # transport-class failures that spend the retry budget.
+    def retryable_failure?(error)
+      ProviderErrorClassifier.provider_error?(error) ||
+        (error.is_a?(Insika::TimeoutError) && error.stage.to_s == "reliability")
+    end
+
+    def with_attempt_timeout(timeout, &blk)
+      return yield unless Async::Task.current?
+      Async::Task.current.with_timeout(timeout) { yield }
+    rescue Async::TimeoutError
+      # a per-attempt timeout is a TRANSPORT-class failure: counted, retried.
+      raise Insika::TimeoutError.new("provider attempt exceeded #{timeout}s", stage: :reliability)
+    end
+
+    # The breaker cell id: "provider/model" for the ref'd node — a ModelSelection
+    # (primary) or a { model:, provider: } hash (fallback node).
+    def ref_of(selection)
+      model = selection.respond_to?(:model) ? selection.model.to_s : selection[:model].to_s
+      provider = selection.respond_to?(:provider) ? selection.provider : selection[:provider]
+      provider ? "#{provider}/#{model}" : model
+    end
+
+    def backoff_seconds(policy, index)
+      case policy["backoff"].to_s
+      when "exponential" then 2**index
+      else index + 1
+      end
+    end
+
+    def backoff_wait(seconds)
+      Async::Task.current? ? Async::Task.current.sleep(seconds) : Kernel.sleep(seconds)
+    end
+
+    def emit(type, data)
+      @event_stream.emit(Insika::Event.new(
+                           type: type, data: data, meta: { at: Time.now.utc.iso8601 }
+                         ))
+    end
+  end
+end

data/lib/insika/safety/config.rb

@@ -2,7 +2,7 @@
 
 module Insika
   module Safety
-    # Per-agent guardrail configuration (RFC-0009 §3.3 / D6), read from
+    # Per-agent guardrail configuration, read from
     # `profile.guardrails`. OPT-IN like `capabilities`: an agent that says nothing
     # gets the CONSERVATIVE default — deterministic detectors ON, LLM moderator OFF.
     #
@@ -18,7 +18,7 @@ module Insika
     #     responses:  { <category> => "<safe reply>", ... }  # per-agent override, see below
     #   }
     #
-    # `responses` is the CONFIGURATION-OVER-CONVENTION knob (RFC-0009 §7). The engine
+    # `responses` is the CONFIGURATION-OVER-CONVENTION knob. The engine
     # ships neutral built-in refusals (Safety::SafeResponses::DEFAULTS), but this is
     # OSS across arbitrary businesses/languages, so we never hard-bake tone: an agent
     # overrides the safe reply per category (`injection`/`sexual`/`abuse`/`escalate`/

data/lib/insika/safety/detectors.rb

@@ -2,10 +2,10 @@
 
 module Insika
   module Safety
-    # SINGLE SOURCE of truth for content-safety pattern matching (RFC-0009 D4).
+    # SINGLE SOURCE of truth for content-safety pattern matching.
     #
     # Two families live here on purpose — the same lists back BOTH the runtime
-    # guardrail (§3.1/§3.2) AND the eval's `must_not` detectors (RFC-0008): the eval
+    # guardrail AND the eval's `must_not` detectors: the eval
     # is a CLIENT of the runtime by design, so `evals/lib/evals/assertions.rb`
     # requires THIS file rather than keeping a divergent copy. The runtime must never
     # depend on `evals/`, so the file is deliberately self-contained (pure Ruby +
@@ -16,10 +16,10 @@ module Insika
     #   · INPUT side (injection/abuse/sexual) — high-confidence heuristics that
     #     short-circuit the turn with a safe refusal BEFORE the LLM runs.
     #
-    # Everything here is CONSERVATIVE by design (RFC §6: a false positive blocks a
+    # Everything here is CONSERVATIVE by design (RFC: a false positive blocks a
     # legitimate customer). The deterministic layer catches only the gross,
     # unambiguous cases; the subtler judgment (social engineering, tone) is the LLM
-    # moderator's job (Fase C), not regex.
+    # moderator's job, not regex.
     #
     # LANGUAGE: the input heuristics are inherently language-specific. We ship pt-BR
     # + EN (the pilot + the OSS lingua franca) as a BEST-EFFORT net; other languages
@@ -40,7 +40,7 @@ module Insika
       # A run of the output stream that MIGHT still be growing into a PII/secret
       # match if more chunks arrive — anchored at the buffer tail. The OutputFilter
       # holds back from the start of such a run so a value split across chunk
-      # boundaries is never emitted in the clear (RFC §3.2 / D3). Covers the
+      # boundaries is never emitted in the clear (RFC). Covers the
       # unbounded `sk-…`/`Bearer …` case that a fixed window cannot.
       #
       # Crucially it also matches a PARTIAL literal PREFIX at the tail — a lone "s"

data/lib/insika/safety/factory.rb

@@ -9,7 +9,7 @@ require_relative "output_validator"
 
 module Insika
   module Safety
-    # Composition helper for the guardrail subsystem (RFC-0009). Keeps the wiring
+    # Composition helper for the guardrail subsystem. Keeps the wiring
     # (config.ru / deployment.rb) a one-liner and the Executor decoupled from Safety:
     # the Executor only ever sees a duck-typed `content_filter_factory` callable and
     # reads plain Hash fields (`guardrail_block`/`guardrail_flags`) off the state.
@@ -21,10 +21,10 @@ module Insika
     class Factory
       # `settings_store` (optional): source of the platform `utility_model` fallback.
       # nil = no fallback (moderator only when the agent pins its own model ref).
-      # `llm` (optional, RFC-0017 A2): the graph's own RubyLLM context. nil = the
+      # `llm` (optional): the graph's own RubyLLM context. nil = the
       # process-wide RubyLLM constant. A guardrail asking on the global while the
       # turn asks on the graph's key is a leak with a false sense of isolation, so
-      # this seam is part of A2 and not a follow-up.
+      # this seam is part of and not a follow-up.
       def initialize(settings_store: nil, llm: nil)
         @settings_store = settings_store
         @llm = llm

data/lib/insika/safety/input_guardrail.rb

@@ -7,14 +7,14 @@ require_relative "config"
 
 module Insika
   module Safety
-    # Input guardrail as a Middleware (RFC-0009 §3.1). It sits on the ONE seam that
+    # Input guardrail as a Middleware. It sits on the ONE seam that
     # already short-circuits structurally (stage 4: a link that does not call `nxt`),
     # and uses the NEW graceful-halt contract: instead of `halt_reason` (which the
     # Executor maps to a turn FAILURE), it sets `halt_response` (a safe reply) +
     # `guardrail_block` (audit metadata) and returns without calling `nxt`. The
     # Executor completes the turn with that safe reply, never touching the LLM.
     #
-    # Two tiers (D2):
+    # Two tiers:
     #   1. deterministic scan (always, cheap, zero-token) — Detectors#scan_input;
     #   2. LLM moderator (opt-in per agent) — only when the deterministic tier let
     #      the message through, so the cheap layer short-circuits the expensive one.
@@ -23,7 +23,7 @@ module Insika
     # link lives ONCE in the global MiddlewareStack — there is no per-agent stack.
     #
     # `moderator_factory` (optional): ->(config) { Moderator | nil }, built by the
-    # Safety::Factory. nil = deterministic only (Fase A/B parity).
+    # Safety::Factory. nil = deterministic only (B parity).
     class InputGuardrail < Insika::Middleware
       def initialize(moderator_factory: nil)
         @moderator_factory = moderator_factory
@@ -43,6 +43,11 @@ module Insika
             return block(state, config, category: category, source: :moderator,
                                         detail: verdict.reason, action: verdict.action)
           end
+          # an UNAVAILABLE moderator fails open — the turn proceeds —
+          # but silence is not a negative: record the degradation on the state so the
+          # Executor (single emitter) emits :guardrail_flagged and a degraded tier
+          # never looks identical to a healthy one in the audit stream.
+          flag_unavailable(state, verdict) if verdict.unavailable?
         end
 
         nxt.call(state)
@@ -54,11 +59,21 @@ module Insika
         @moderator_factory&.call(config)
       end
 
+      # Appends the audit flag for a degraded moderator tier. Same
+      # state-carried channel the OutputValidator uses; detail is the moderator's
+      # own reason string ("moderator error (fail-open)" / "unparseable
+      # (fail-open)"), never message content.
+      def flag_unavailable(state, verdict)
+        state.guardrail_flags = Array(state.guardrail_flags) + [{
+          category: "moderator_unavailable", source: "moderator", detail: verdict.reason.to_s[0, 200]
+        }]
+      end
+
       # The block category. `escalate` (an ACTION) becomes the `escalate` category so
       # the agent can address it; otherwise the moderator's own category flows
       # through UNCOLLAPSED — the safe-reply lookup (SafeResponses.for) resolves an
       # unknown one to the agent's `default` / the neutral built-in, so we don't need
-      # to force it into a fixed bucket here (configuration over convention, §7).
+      # to force it into a fixed bucket here (configuration over convention).
       def moderator_category(verdict)
         return :escalate if verdict.action.to_s == "escalate"
 

data/lib/insika/safety/moderator.rb

@@ -4,7 +4,7 @@ require "json"
 
 module Insika
   module Safety
-    # LLM content moderator (RFC-0009 Fase C / D2). The subtle tier the regex can't
+    # LLM content moderator. The subtle tier the regex can't
     # reach: social engineering (a fabricated prior promise), veiled hostility, tone.
     #
     # Pure over an injected `ask` callable (prompt -> raw model text), exactly like
@@ -13,48 +13,56 @@ module Insika
     #
     # FAIL-OPEN by construction: the deterministic layer already ran and caught the
     # gross cases, so an unparseable/failed moderator reply must NOT block a
-    # legitimate customer — it degrades to `allow`. Blocking is the high-stakes
-    # direction (RFC §6: a false positive turns away a real buyer).
+    # legitimate customer. Blocking is the high-stakes direction (RFC: a false
+    # positive turns away a real buyer). But fail-open is not a fake negative
+    # a moderator that could not answer returns the third state
+    # `unavailable` — it does not block, and it is NOT recorded as a clean `allow`,
+    # so a degraded tier is distinguishable from a healthy one in the audit stream.
     class Moderator
       Verdict = Struct.new(:category, :action, :reason, keyword_init: true) do
         def block? = %w[refuse escalate].include?(action.to_s)
+        def unavailable? = action.to_s == "unavailable"
       end
 
       CATEGORIES = %w[injection abuse sexual self_harm off_topic safe].freeze
-      ACTIONS = %w[allow refuse escalate].freeze
+      ACTIONS = %w[allow refuse escalate unavailable].freeze
 
       # ask: ->(prompt) { "<raw model text>" }.
       def initialize(ask:)
         @ask = ask
       end
 
-      # Classifies a user message. Returns a Verdict; on ANY failure -> allow/safe
-      # (fail-open). `context` is optional free text (e.g. the agent's domain) woven
+      # Classifies a user message. Returns a Verdict; on ANY failure -> unavailable
+      # (fail-open: never blocks, but never masquerades as a real `allow` either —
+      # `context` is optional free text (e.g. the agent's domain) woven
       # into the prompt.
       def classify(message, context: nil)
         raw = @ask.call(build_prompt(message.to_s, context)).to_s
         parse(raw)
       rescue StandardError
-        Verdict.new(category: "safe", action: "allow", reason: "moderator error (fail-open)")
+        Verdict.new(category: "safe", action: "unavailable", reason: "moderator error (fail-open)")
       end
 
       private
 
       def parse(raw)
         json = raw[/\{.*\}/m]
-        return safe_verdict unless json
+        return unavailable_verdict unless json
 
         data = JSON.parse(json)
         action = data["action"].to_s.strip.downcase
-        action = "allow" unless ACTIONS.include?(action)
+        # An out-of-enum action is a reply we cannot honor — normalize to
+        # unavailable, not allow: inventing a negative the model never gave is the
+        # same ambiguity removes.
+        action = "unavailable" unless ACTIONS.include?(action)
         category = data["category"].to_s.strip.downcase
         category = "safe" unless CATEGORIES.include?(category)
         Verdict.new(category: category, action: action, reason: data["reason"].to_s)
       rescue JSON::ParserError
-        safe_verdict
+        unavailable_verdict
       end
 
-      def safe_verdict = Verdict.new(category: "safe", action: "allow", reason: "unparseable (fail-open)")
+      def unavailable_verdict = Verdict.new(category: "safe", action: "unavailable", reason: "unparseable (fail-open)")
 
       def build_prompt(message, context)
         <<~PROMPT

data/lib/insika/safety/output_filter.rb

@@ -4,12 +4,12 @@ require_relative "detectors"
 
 module Insika
   module Safety
-    # Deterministic output redaction on the STREAM (RFC-0009 §3.2 / D3). The turn
+    # Deterministic output redaction on the STREAM. The turn
     # streams `content` deltas, so we cannot "unsay" text already sent — the filter
     # sits between the provider chunks and the `:content` event and only ever emits
     # text it has PROVEN clean.
     #
-    # The hard part (RFC §6, "fronteira de chunk"): a CPF/secret can arrive split
+    # The hard part (RFC, "fronteira de chunk"): a CPF/secret can arrive split
     # across two chunks and neither half matches on its own. A naive delta-by-delta
     # regex leaks "by construction". So the filter keeps a SLIDING BUFFER: it retains
     # the tail that might still be growing into a match (Detectors::OPEN_TAIL, which

data/lib/insika/safety/output_validator.rb

@@ -6,11 +6,11 @@ require_relative "config"
 
 module Insika
   module Safety
-    # Post-turn output validator (RFC-0009 §3.2 / D3). Runs as an `after_task` hook:
+    # Post-turn output validator. Runs as an `after_task` hook:
     # with the FINAL assistant text assembled, it does a richer check than the
     # stream filter can — an unverified discount/price promise, a tone slip — and
     # FLAGS it (audit) rather than blocking. It is honest about the streaming limit
-    # (D3): for a streaming agent the text is already out the door, so this is
+    # for a streaming agent the text is already out the door, so this is
     # detection, not prevention; true pre-emission blocking needs `streaming:false`
     # (a per-profile override left for a later slice).
     #

data/lib/insika/safety/safe_responses.rb

@@ -2,7 +2,7 @@
 
 module Insika
   module Safety
-    # Safe reply for a blocked turn (RFC-0009 D5/§7). A blocked turn NEVER returns a
+    # Safe reply for a blocked turn. A blocked turn NEVER returns a
     # raw error nor silence — it completes gracefully with one of these.
     #
     # CONFIGURATION OVER CONVENTION: this is OSS across arbitrary businesses and

data/lib/insika/sandbox/boundary.rb

@@ -10,8 +10,8 @@ module Insika
     # sandbox primitive — always on, independent of the exec provider (local or
     # docker) and of the engine's approval layer.
     #
-    # Extracted VERBATIM from the insika-code prototype's `Workspace` (item 5)
-    # and promoted to a core primitive (item 35). The two layers of defense:
+    # Extracted VERBATIM from the insika-code prototype's `Workspace`
+    # and promoted to a core primitive. The two layers of defense:
     #   1. `File.expand_path` normalizes `..` traversal; the expanded path must be
     #      the root itself or a descendant of it (string containment on a
     #      separator boundary, so `/ws-evil` does not pass for root `/ws`).

data/lib/insika/sandbox.rb

@@ -7,7 +7,7 @@ require_relative "sandbox/local"
 require_relative "sandbox/docker"
 
 module Insika
-  # Sandbox primitive (item 35 / COMPETITIVE-ANALYSIS §4.6): a single, pluggable
+  # Sandbox primitive (COMPETITIVE-ANALYSIS): a single, pluggable
   # interface for confined execution, promoted to the core from the insika-code
   # prototype. Two halves:
   #