insika 0.1.0 → 0.3.0

data/lib/insika/refinement/gate.rb

@@ -2,8 +2,8 @@
 
 module Insika
   module Refinement
-    # Scores a candidate by RUNNING it (RFC-0013 §3.5). Not by asking a model whether
-    # the edit looks good — that measures nothing, and D3 says so in one line.
+    # Scores a candidate by RUNNING it. Not by asking a model whether
+    # the edit looks good — that measures nothing, and says so in one line.
     #
     #   1. clone the agent into a throwaway id (`<agent>-cand-<run8>`)
     #   2. copy its instruction files, apply the candidate's edits to the COPY
@@ -27,7 +27,7 @@ module Insika
       # it — nil when no turn carried usage. `cached` is how much of that came from
       # the prompt cache, kept separate because it is what explains one candidate
       # costing 8× another over the same cases. `tokens` is what the panel's budget
-      # (§3.9) spends and what the operator reads on the run: a gate is the expensive
+      # spends and what the operator reads on the run: a gate is the expensive
       # half of refinement and a loop whose cost is invisible is one nobody can decide
       # to keep.
       Report = Data.define(:candidate_id, :passed, :reason, :cases, :passed_cases,
@@ -48,9 +48,9 @@ module Insika
       # credential the operator can rotate.
       # capabilities_factory: -> an `Evals::HttpCapabilities` for the clone, or nil.
       # Without it a case whose `requires` the agent cannot satisfy RUNS and fails
-      # (RFC-0014 §3.2 says it must skip) — and then the gate and `evals/run.rb`, the
+      # (says it must skip) — and then the gate and `evals/run.rb`, the
       # two callers of the one evaluator, disagree about what the corpus even
-      # measures. §3.7 exists to prevent exactly that.
+      # measures. exists to prevent exactly that.
       def initialize(profiles:, agent_files:, goldens:, baselines:, transport_factory:,
                      capabilities_factory: nil, judge_factory: nil, tolerance: DEFAULT_TOLERANCE)
         @profiles = profiles
@@ -68,7 +68,7 @@ module Insika
       # not gate is more useful than an exception in a log.
       def score(agent_id:, candidate:, run_id:, tolerance: nil)
         cases = @goldens.for_agent(agent_id)
-        return refusal(candidate, "the agent has no golden cases — nothing to gate against (RFC-0013 D4)") if cases.empty?
+        return refusal(candidate, "the agent has no golden cases — nothing to gate against") if cases.empty?
 
         baseline = @baselines.get(agent_id)
         # Without an accepted state, `Baseline.compare` compares nothing and reports
@@ -109,7 +109,7 @@ module Insika
         # Measured, not reasoned: gating the real pilot agent with `settings["evals"]`
         # unset reported **6/6, no regression** against a baseline the same corpus had
         # just scored **2/6** — `produto-sem-cep` was judged 0.0 and "passed". Both
-        # candidates on the panel cleared. That is §3.7's failure exactly: the CLI and
+        # candidates on the panel cleared. That is's failure exactly: the CLI and
         # the gate, the two callers of the one evaluator, disagreeing about what the
         # corpus measures.
         judge = @judge_factory&.call

data/lib/insika/refinement/panel.rb

@@ -2,7 +2,7 @@
 
 module Insika
   module Refinement
-    # What a refinement run is allowed to SPEND (RFC-0013 §3.9, phase D).
+    # What a refinement run is allowed to SPEND.
     #
     # A panel of 3 proposers over a 7-case golden set is 3 model calls plus 21
     # replayed conversations, each a real turn with real tools. That is the honest
@@ -52,15 +52,15 @@ module Insika
                    "unmetered" => @unmetered }
     end
 
-    # The proposer PANEL (RFC-0013 §3.9 / §3.5): N models write N independent
+    # The proposer PANEL: N models write N independent
     # candidates, the gate scores each one by replaying the golden set, and the best
     # SURVIVOR becomes the proposal a human is asked about.
     #
     # Independent, not consensus-seeking. Two models agreeing on wording is weak
-    # evidence and a golden case passing is strong evidence (D7), so convergence only
+    # evidence and a golden case passing is strong evidence, so convergence only
     # ever breaks a tie between candidates the gate already ranked equal.
     #
-    # A panel of one is phase C unchanged, which is why there is no second code path:
+    # A panel of one is unchanged, which is why there is no second code path:
     # `refinement.proposer` (a single ref) resolves to a one-element panel.
     class Panel
       # One member of the panel: the candidate, WHO wrote it (more than one model when
@@ -80,7 +80,7 @@ module Insika
       # gate:      a Refinement::Gate (anything answering #score).
       # proposers: [Refinement::Proposer], already resolved by ProposerFactory.panel.
       # budget:    a Budget. The default is unlimited — a deployment that configured
-      #            none gets phase C's behaviour, which had no ceiling either.
+      #            none gets behaviour, which had no ceiling either.
       def initialize(gate:, proposers: [], budget: Budget.new, fan_out: nil)
         @gate = gate
         @proposers = Array(proposers)
@@ -112,7 +112,7 @@ module Insika
       # -> the best SURVIVOR, or nil when none passed.
       #
       # Highest graded score first; ties broken by the fewest edits (a smaller diff is
-      # a smaller bet), then by how many proposers converged on it (§3.5). `min_by`
+      # a smaller bet), then by how many proposers converged on it. `min_by`
       # over a negated tuple keeps the comparison in one place and stays stable, so
       # two genuinely indistinguishable candidates resolve to the first proposer the
       # operator listed rather than to whichever fiber finished first.
@@ -131,7 +131,7 @@ module Insika
 
       private
 
-      # All proposers at once, bounded by the RFC-0010 fan-out cap (§3.9 says the
+      # All proposers at once, bounded by the fan-out cap (says the
       # panel reuses it). Each is one blocking HTTP call to a provider, so the
       # wall-clock is the slowest model rather than their sum.
       #

data/lib/insika/refinement/proposer.rb

@@ -4,7 +4,7 @@ require "json"
 
 module Insika
   module Refinement
-    # Writes a CANDIDATE from a run's findings (RFC-0013 §3.4, phase C / PR 3b) — the
+    # Writes a CANDIDATE from a run's findings — the
     # one place in refinement where a model is asked for anything.
     #
     # It is deliberately the WEAKEST link and it is built that way: everything this
@@ -180,8 +180,8 @@ module Insika
 
     # Resolves WHICH model(s) write the candidate, and builds the ask.
     #
-    #   refinement.proposers  on the agent  (phase D: a PANEL, RFC-0013 §3.9)
-    #   -> refinement.proposer  ("deepseek/deepseek-chat" | "deepseek-chat")
+    #   refinement.proposers  on the agent  (a PANEL)
+    #   -> refinement.proposer  ("deepseek/deepseek-v4-flash" | "deepseek-v4-flash")
     #   -> the platform utility_model
     #   -> nothing, and the caller refuses. There is no default model here on purpose:
     #      guessing one spends an operator's provider budget without being asked.
@@ -189,17 +189,17 @@ module Insika
       module_function
 
       # config: the agent's `refinement` hash. -> Proposer | nil (the FIRST of the
-      # panel — phase C's single-proposer entry point, kept because a deployment that
+      # panel — single-proposer entry point, kept because a deployment that
       # never configured a panel is a panel of one).
       def build(config, utility_model: nil, ask_factory: nil, llm: nil)
         panel(config, utility_model: utility_model, ask_factory: ask_factory, llm: llm).first
       end
 
       # -> [Proposer], in configured order, DEDUPED by model ref and capped at the
-      # RFC-0010 fan-out (§3.9 says the panel reuses it). Two entries naming the same
+      # fan-out (says the panel reuses it). Two entries naming the same
       # model are one proposer: asking the same model twice at temperature 0 measures
-      # its variance, which is exactly what D6 rejected for the judges.
-      # `llm` (RFC-0017 A2): the graph's own RubyLLM context; nil = the global
+      # its variance, which is exactly what rejected for the judges.
+      # `llm`: the graph's own RubyLLM context; nil = the global
       # constant. Today only the deployment root builds a panel, and a deployment
       # is one graph per process — the seam exists so an embedded graph that ever
       # gains the refinement commands proposes on its own credentials.
@@ -213,8 +213,8 @@ module Insika
         end
       end
 
-      # `proposers` accepts either syntax — a bare ref ("deepseek/deepseek-chat") or
-      # the RFC's `{ "model" =>, "provider"? => }` — because the two already coexist in
+      # `proposers` accepts either syntax — a bare ref ("deepseek/deepseek-v4-flash") or
+      # the hash form `{ "model" =>, "provider"? => }` — because the two already coexist in
       # this config (`proposer` is a bare ref, `judges` are hashes) and refusing one of
       # them would only teach operators which page they were reading.
       def refs_for(config, utility_model)
@@ -248,7 +248,7 @@ module Insika
       # is actually configured.
       #
       # Returns the MESSAGE, not `.content`: the token counts ride on it and the
-      # budget (§3.9) is what spends them. `Proposer` reads either shape.
+      # budget is what spends them. `Proposer` reads either shape.
       def ruby_llm_ask(model, provider, llm: nil)
         require "ruby_llm"
         llm ||= RubyLLM

data/lib/insika/refinement_store.rb

@@ -4,7 +4,7 @@ require "securerandom"
 require "time"
 
 module Insika
-  # REFINEMENT DOMAIN store (RFC-0013, phase A). One record per refinement RUN:
+  # REFINEMENT DOMAIN store. One record per refinement RUN:
   # the window that was read, the ranked findings the EvidenceCollector produced,
   # and the run's outcome. RUNTIME data (it is derived from sessions/tasks/traces),
   # so it takes the raw `store:` like SessionStore/TaskStore — not the ConfigStore.
@@ -15,8 +15,8 @@ module Insika
   # Store contract orders lexicographically) and `latest_for` is its last element.
   # An agent id containing ":" would break that split, so it is rejected on write.
   #
-  # Phase A wrote no edits anywhere — a Run was a REPORT and every non-collecting
-  # status was terminal. Phase C (RFC-0013 §3.2) adds the rest of the lifecycle on
+  # wrote no edits anywhere — a Run was a REPORT and every non-collecting
+  # status was terminal. adds the rest of the lifecycle on
   # the SAME record, additively: a gated candidate and the operator's decision.
   #
   #   collecting ─▶ completed ─▶ gating ─▶ awaiting_approval ─▶ applied
@@ -24,13 +24,13 @@ module Insika
   #             ╰─▶ failed                    or the operator did)
   #
   # **The approval lives here, not in `PendingActionStore`** — a deliberate deviation
-  # from §3.6. That store is coupled to a suspended TURN: `ApproveAction` resolves
+  # from That store is coupled to a suspended TURN: `ApproveAction` resolves
   # the record and then calls `executor.approve(task_id)` to wake a fiber. A
   # refinement proposal has no turn and no fiber, so reusing it would mean inventing
   # a task id, a fake `tool` name, and a wake-up that must never do anything — and
   # the operator's approvals inbox would fill with rows that are not tool calls. The
-  # property §3.6 actually wanted is durability across a `kill -9`, and this store
-  # has had it since phase A.
+  # property actually wanted is durability across a `kill -9`, and this store
+  # has had it since.
   class RefinementStore
     include Coercion
 
@@ -42,7 +42,7 @@ module Insika
 
     # OPEN means "this run will change without anyone asking": work is in flight
     # (`collecting`, `gating`) or a human owes it an answer (`awaiting_approval`).
-    # Everything else is terminal — INCLUDING `completed`, which phase A already
+    # Everything else is terminal — INCLUDING `completed`, which already
     # treated that way and which stays true: a report is finished, and gating one is
     # a new deliberate action, not a continuation. (Widening `terminal?` here is what
     # the Studio's "latest report" lookup reads, so getting it wrong hides the report.)
@@ -50,7 +50,7 @@ module Insika
 
     # `candidate`/`gate` are the WINNER — the one proposal a human is asked about, and
     # the only thing `ResolveRefinement` ever applies. `candidates` is the whole panel
-    # (RFC-0013 §3.9, phase D): every candidate that was built, who wrote it, and how
+    # every candidate that was built, who wrote it, and how
     # it scored, including the ones that lost and the ones the budget never gated. A
     # phase-C run recorded one candidate and no panel; it still reads back correctly,
     # because a panel of one is the same shape.
@@ -118,7 +118,7 @@ module Insika
       end
     end
 
-    # -- phase C: the proposal's lifecycle -------------------------------
+    # the proposal's lifecycle -------------------------------
 
     # Attaches the candidate(s) under gate and moves the run to :gating. Only a
     # `completed` run can be gated: a report with no findings has nothing to propose
@@ -145,15 +145,15 @@ module Insika
     end
 
     # Records the gate's verdict. A PASS parks the run at :awaiting_approval — a
-    # human still has to say yes, which is the product and not a formality (D2). A
+    # human still has to say yes, which is the product and not a formality. A
     # FAIL is terminal as :rejected, with the gate report as the stated reason: the
     # same finding must re-surface with new evidence before anything is proposed
-    # again, so there is no silent retry loop (§3.6).
+    # again, so there is no silent retry loop.
     #
     # `report` is the WINNER's (or, when nothing survived, the most informative
     # refusal). `panel` is every scored entry — the store attaches it as-is and picks
     # the winning candidate out of it by id. Which candidate WON is the caller's
-    # ranking decision (§3.5); this store does not rank, it records. -> Run.
+    # ranking decision; this store does not rank, it records. -> Run.
     def gated(id, report:, panel: nil, cost: nil)
       update(id) do |record|
         unless record["status"] == "gating"

data/lib/insika/reliability.rb

@@ -0,0 +1,211 @@
+# 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.
+    # NOTHING about a run is stored on `self`: one Reliability instance serves
+    # every concurrent turn, and `ask` is a suspension point — an ivar written
+    # here would be read back after another fiber's turn overwrote it, and the
+    # WS6 alert would name the wrong agent (and, through it, the wrong tenant).
+    # The run's identity rides the stack.
+    def call(policy:, tenant:, agent: nil, selection:, chain:, &attempt)
+      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
+      # the last node we actually ASKED: the `from` of a rotation. A node the
+      # breaker skipped was never asked, so it is never the `from`.
+      asked = nil
+      nodes.each do |node|
+        selection = node[:selection]
+        next if breaker && breaker_open?(tenant, selection, breaker)
+
+        # ROTATION is an EVENT, not an inference from the usage attribution
+        # (WS3): the trace names the node we left, the node we moved to and why.
+        # Emitted for every node past the first one asked — with or WITHOUT a
+        # breaker (a fallback policy with no circuit_breaker used to rotate in
+        # complete silence).
+        emit_fallback(agent, asked, selection, last_error) if asked
+        asked = selection
+
+        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, agent)
+            # 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
+
+    # The failure is ALWAYS an event; only the circuit bump needs a breaker (the
+    # old `return unless breaker` made a retry/fallback policy without a
+    # circuit_breaker run with no trace at all).
+    def record_failure(tenant, selection, breaker, error, agent)
+      emit(:provider_failure,
+           { agent: agent, ref: ref_of(selection), error: error.class.name, kind: kind_of(error) })
+      return unless breaker
+
+      tripped = @circuit_store.record_failure(
+        tenant: tenant, ref: ref_of(selection),
+        after: breaker[:after], within: breaker[:within]
+      )
+      # 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
+
+    # The mid-turn rotation across the fallback chain: the node we left, the one
+    # we moved to, and the error that spent the previous node's retries.
+    def emit_fallback(agent, from, to, error)
+      emit(:provider_fallback,
+           { agent: agent, from: ref_of(from), to: ref_of(to),
+             error: error&.class&.name, kind: error && kind_of(error) })
+    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