insika 0.0.1 → 0.2.0

data/lib/insika/refinement_store.rb

@@ -0,0 +1,295 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "time"
+
+module Insika
+  # 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.
+  #
+  # The key embeds the agent and the start timestamp:
+  #   "run:<agent_id>:<started_at>:<id>"
+  # so `list(SCOPE, "run:<agent>:")` comes back CHRONOLOGICAL for that agent (the
+  # 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.
+  #
+  # 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
+  #             ╰─▶ no_findings          ╰─▶ rejected  (the gate failed it,
+  #             ╰─▶ failed                    or the operator did)
+  #
+  # **The approval lives here, not in `PendingActionStore`** — a deliberate deviation
+  # 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 actually wanted is durability across a `kill -9`, and this store
+  # has had it since.
+  class RefinementStore
+    include Coercion
+
+    SCOPE = "refinements"
+    KEY_PREFIX = "run:"
+
+    STATUSES = %i[collecting completed gating awaiting_approval applied rejected
+                  no_findings failed].freeze
+
+    # 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 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.)
+    OPEN = %i[collecting gating awaiting_approval].freeze
+
+    # `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
+    # 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.
+    Run = Data.define(:id, :agent_id, :status, :window, :findings, :excluded,
+                      :started_at, :finished_at, :error,
+                      :candidate, :candidates, :gate, :cost, :decision) do
+      def terminal? = !OPEN.include?(status)
+      def findings_count = findings.size
+
+      # Is there a gated proposal waiting for a human? The one question the Studio
+      # and the apply command both ask.
+      def awaiting_approval? = status == :awaiting_approval
+      def gate_passed? = gate.is_a?(Hash) && gate["passed"] == true
+      def edits = (candidate || {})["edits"] || []
+      def panel = Array(candidates)
+    end
+
+    def initialize(store:)
+      @store = store
+    end
+
+    # Opens a run (:collecting). `window` is the collector's window as data
+    # ({ "last_sessions" => N } | { "since" => iso8601 }) — recorded so a report can
+    # be read months later and still say what it looked at. -> Run.
+    def create(agent_id:, window: {}, id: SecureRandom.uuid, at: nil)
+      agent = agent_id.to_s
+      raise Insika::ValidationError, "agent_id is required" if agent.empty?
+      raise Insika::ValidationError, "agent_id must not contain ':'" if agent.include?(":")
+
+      started = at || timestamp
+      record = {
+        "id" => id.to_s, "agent_id" => agent, "status" => "collecting",
+        "window" => deep_stringify(window || {}), "findings" => [], "excluded" => 0,
+        "started_at" => started, "finished_at" => nil, "error" => nil,
+        "candidate" => nil, "candidates" => [], "gate" => nil, "cost" => nil,
+        "decision" => nil
+      }
+      @store.set(SCOPE, key_for(agent, started, id), record)
+      to_run(record)
+    end
+
+    # Closes a run with its findings. Empty findings -> :no_findings (a distinct
+    # outcome from :completed — "we looked and it was clean" is a real answer, not a
+    # failure). -> Run. ArgumentError if the run is already terminal.
+    # `excluded` is how many turns the window dropped on purpose (synthetic
+    # traffic) — recorded so a report never reads cleaner than the data was.
+    def complete(id, findings:, excluded: 0)
+      update(id) do |record|
+        guard_open!(record)
+        list = Array(findings).map { |f| deep_stringify(f.respond_to?(:to_h) ? f.to_h : f) }
+        record["findings"] = list
+        record["excluded"] = Integer(excluded)
+        record["status"] = list.empty? ? "no_findings" : "completed"
+        record["finished_at"] = timestamp
+      end
+    end
+
+    # Closes a run as :failed, recording the error. -> Run.
+    def fail(id, error:)
+      update(id) do |record|
+        guard_open!(record)
+        record["status"] = "failed"
+        record["error"] = error.to_s
+        record["finished_at"] = timestamp
+      end
+    end
+
+    # 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
+    # from, and a failed one never finished looking.
+    #
+    # `candidate:` (one) and `candidates:` (a panel) are the same call — the panel is
+    # recorded before the gate runs so the Studio can show WHAT is being scored while
+    # it is being scored, which is minutes of real replay. No winner is claimed yet:
+    # `candidate` stays nil until `gated` says which one it is. -> Run.
+    def gating(id, candidate: nil, candidates: nil)
+      panel = Array(candidates || [candidate].compact)
+      raise Insika::ValidationError, "a candidate is required to gate" if panel.empty?
+
+      update(id) do |record|
+        unless record["status"] == "completed"
+          raise ArgumentError, "run #{record['id']} is #{record['status']}, expected completed"
+        end
+
+        record["candidates"] = panel.map { |c| entry_for(c) }
+        record["candidate"] = nil
+        record["gate"] = nil
+        record["status"] = "gating"
+      end
+    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. 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.
+    #
+    # `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; this store does not rank, it records. -> Run.
+    def gated(id, report:, panel: nil, cost: nil)
+      update(id) do |record|
+        unless record["status"] == "gating"
+          raise ArgumentError, "run #{record['id']} is #{record['status']}, expected gating"
+        end
+
+        gate = deep_stringify(report.respond_to?(:to_h) ? report.to_h : report)
+        record["candidates"] = panel.map { |e| entry_for(e) } if panel
+        record["candidate"] = winning_candidate(record, gate)
+        record["gate"] = gate
+        record["cost"] = deep_stringify(cost.respond_to?(:to_h) ? cost.to_h : cost) if cost
+        if gate["passed"]
+          record["status"] = "awaiting_approval"
+        else
+          record["status"] = "rejected"
+          record["decision"] = { "by" => "gate", "at" => timestamp, "note" => gate["reason"] }
+          record["finished_at"] = timestamp
+        end
+      end
+    end
+
+    # The operator's answer to a gated proposal. `applied` is recorded only after the
+    # writes land, so a crash between the two leaves the run awaiting approval and
+    # the operator re-approves — replaying a write that is already versioned and
+    # idempotent-ish beats recording a lie. -> Run.
+    def resolve(id, decision:, operator: nil, note: nil)
+      target = decision.to_sym
+      unless %i[applied rejected].include?(target)
+        raise Insika::ValidationError, "invalid decision: #{decision} (applied|rejected)"
+      end
+
+      update(id) do |record|
+        unless record["status"] == "awaiting_approval"
+          raise ArgumentError, "run #{record['id']} is #{record['status']}, expected awaiting_approval"
+        end
+
+        record["status"] = target.to_s
+        record["decision"] = { "by" => (Coercion.presence(operator) || "operator").to_s,
+                               "at" => timestamp, "note" => Coercion.presence(note) }.compact
+        record["finished_at"] = timestamp
+      end
+    end
+
+    # -> [Run] every run parked on a human, most recent first. What the Studio badges.
+    def awaiting_approval(limit: 20)
+      recent(limit: 200).select(&:awaiting_approval?).first(limit)
+    end
+
+    # -> Run | nil. O(n) scan over the scope (the key carries agent+timestamp, so
+    # there is no index by id): one node, local SQLite, runs are operator-paced.
+    def find(id)
+      key = key_for_id(id)
+      key && to_run(@store.get(SCOPE, key))
+    end
+
+    # -> [Run] for one agent, MOST RECENT FIRST, capped by `limit`.
+    def for_agent(agent_id, limit: nil)
+      keys = @store.list(SCOPE, "#{KEY_PREFIX}#{agent_id}:").reverse
+      keys = keys.first(limit) if limit
+      keys.filter_map { |k| to_run(@store.get(SCOPE, k)) }
+    end
+
+    # -> Run | nil (the agent's most recent run, whatever its status).
+    def latest_for(agent_id) = for_agent(agent_id, limit: 1).first
+
+    # -> [Run] across every agent, most recent first, capped.
+    def recent(limit: 20)
+      @store.list(SCOPE, KEY_PREFIX)
+            .filter_map { |k| to_run(@store.get(SCOPE, k)) }
+            .sort_by { |r| r.started_at.to_s }.reverse.first(limit)
+    end
+
+    private
+
+    # One panel row: `{ candidate:, proposers: [], gate: }`. A bare Candidate (phase
+    # C, an operator's own payload, an older record) is wrapped into the same shape,
+    # so every reader has ONE thing to read and the two eras of this record do not
+    # each need a branch in the Studio.
+    def entry_for(value)
+      raw = deep_stringify(value.respond_to?(:to_h) ? value.to_h : value)
+      return raw if raw.key?("candidate")
+
+      { "candidate" => raw, "proposers" => [raw["proposer"]].compact, "gate" => nil }
+    end
+
+    # The candidate the winning report belongs to, matched by id. A report whose
+    # candidate is not in the panel (an older record, a hand-built payload) leaves
+    # whatever was already there rather than inventing a winner.
+    def winning_candidate(record, gate)
+      match = Array(record["candidates"]).find do |entry|
+        (entry["candidate"] || {})["id"] == gate["candidate_id"]
+      end
+      match ? match["candidate"] : record["candidate"]
+    end
+
+    def key_for(agent, started_at, id) = "#{KEY_PREFIX}#{agent}:#{started_at}:#{id}"
+
+    # The id is the key's last segment; scanning is the price of keeping the key
+    # chronological (which is what every read except `find` actually wants).
+    def key_for_id(id)
+      suffix = ":#{id}"
+      @store.list(SCOPE, KEY_PREFIX).find { |k| k.end_with?(suffix) }
+    end
+
+    def update(id)
+      key = key_for_id(id)
+      raise Insika::NotFoundError, "refinement run not found: #{id}" if key.nil?
+
+      record = @store.get(SCOPE, key)
+      raise Insika::NotFoundError, "refinement run not found: #{id}" if record.nil?
+
+      yield record
+      @store.set(SCOPE, key, record)
+      to_run(record)
+    end
+
+    def guard_open!(record)
+      return if record["status"] == "collecting"
+
+      raise ArgumentError, "run #{record['id']} is already #{record['status']}"
+    end
+
+    def to_run(record)
+      return nil if record.nil?
+
+      Run.new(
+        id: record["id"], agent_id: record["agent_id"],
+        status: record["status"].to_sym, window: record["window"] || {},
+        findings: record["findings"] || [], excluded: record["excluded"] || 0,
+        started_at: record["started_at"], finished_at: record["finished_at"],
+        error: record["error"],
+        candidate: record["candidate"], candidates: record["candidates"] || [],
+        gate: record["gate"], cost: record["cost"], decision: record["decision"]
+      )
+    end
+
+    def timestamp = Time.now.utc.iso8601
+  end
+end

data/lib/insika/registry.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Insika
+  # Generic executable base: Registry =
+  # EXECUTABLE content (tools/workflows/policies). Catalog (skills/prompts) is
+  # non-executable and does not inherit from here.
+  #
+  # Immutable post-boot by CONSTRUCTION (only boot registers): there
+  # is no `freeze!`; immutability is not enforced at runtime.
+  class Registry
+    Entry = Data.define(:name, :plugin, :metadata, :factory)
+
+    def initialize
+      @entries = {}
+    end
+
+    # factory = block OR the positional callable. metadata captured by **kw
+    # (Symbol keys, stored as-is). Duplicate: FIRST wins (plugin precedence)
+    # — the second is discarded with a warn, never overwritten.
+    def register(name, callable = nil, plugin: nil, **metadata, &block)
+      name = name.to_s
+      factory = block || (callable.nil? ? nil : -> { callable })
+      raise ArgumentError, "registration without factory: #{name}" if factory.nil?
+
+      if @entries.key?(name)
+        existing = @entries[name]
+        warn "[registry] '#{name}' already registered by #{existing.plugin.inspect}; " \
+             "descartando registro de #{plugin.inspect} (primeiro vence)"
+        return self
+      end
+
+      @entries[name] = Entry.new(name: name, plugin: plugin&.to_s, metadata: metadata, factory: factory)
+      self
+    end
+
+    # -> instance (factory.call) | raise NotFoundError.
+    def resolve(name)
+      entry(name).factory.call
+    end
+
+    # -> the raw Entry (name/plugin/metadata/factory) | raise NotFoundError. For
+    # readers that need the metadata WITHOUT resolving the factory (discovery,
+    # WorkflowRegistry#definition).
+    def entry(name)
+      @entries[name.to_s] ||
+        (raise Insika::NotFoundError, "'#{name}' not registered in #{self.class}")
+    end
+
+    def entries = @entries.values
+    def names = @entries.keys
+
+    # Loader rollback support: removes the entries of a
+    # plugin. NOT a runtime API (registries are immutable post-boot).
+    def deregister_plugin(plugin_id)
+      @entries.delete_if { |_name, entry| entry.plugin == plugin_id.to_s }
+      nil
+    end
+  end
+end

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

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Insika
+  module Safety
+    # 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.
+    #
+    # Tolerant of the JSON round-trip (string OR symbol keys / values), same
+    # discipline as ModelPolicy — the StoredProfileSource persists this as a plain
+    # Hash and it comes back stringified.
+    #
+    #   guardrails: {
+    #     input:      true|false,        # run the input guardrail middleware (default true)
+    #     output:     true|false,        # run the output filter + validator (default true)
+    #     moderator:  "provider/model"|nil,  # LLM moderator model; nil = deterministic only
+    #     strictness: "low"|"medium"|"high", # which input categories fire (default medium)
+    #     responses:  { <category> => "<safe reply>", ... }  # per-agent override, see below
+    #   }
+    #
+    # `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`/
+    # …) or sets a single catch-all `default`. Resolution order (SafeResponses.for):
+    # agent[category] → agent["default"] → built-in[category] → built-in[:default].
+    class Config
+      # strictness -> input categories that the deterministic scan runs.
+      #   low    = only injection (+ output redaction) — highest confidence, fewest FPs
+      #   medium = injection + sexual + abuse (the default)
+      #   high   = same families, reserved for future broader lists
+      STRICTNESS_CATEGORIES = {
+        low: %i[injection],
+        medium: %i[injection sexual abuse],
+        high: %i[injection sexual abuse]
+      }.freeze
+
+      DEFAULT_STRICTNESS = :medium
+
+      attr_reader :input, :output, :moderator, :strictness, :responses
+
+      def initialize(input:, output:, moderator:, strictness:, responses: {})
+        @input = input
+        @output = output
+        @moderator = moderator
+        @strictness = strictness
+        @responses = responses # { "category" => "safe reply" }, agent override map
+      end
+
+      # Builds a Config from a profile. A nil/empty `guardrails` -> the
+      # conservative default (see from_hash).
+      def self.from_profile(profile) = from_hash(profile.guardrails)
+
+      def self.from_hash(raw)
+        h = symbolize(raw)
+        new(
+          input: bool(h.fetch(:input, true)),
+          output: bool(h.fetch(:output, true)),
+          moderator: presence(h[:moderator]),
+          strictness: normalize_strictness(h[:strictness]),
+          responses: normalize_responses(h[:responses])
+        )
+      end
+
+      # Input categories the deterministic scan should run, per strictness.
+      def input_categories = STRICTNESS_CATEGORIES.fetch(@strictness, STRICTNESS_CATEGORIES[DEFAULT_STRICTNESS])
+
+      # A guardrail is fully off only when BOTH sides are disabled — cheap early-out.
+      def enabled? = @input || @output
+
+      def moderator? = !@moderator.nil?
+
+      def self.symbolize(raw)
+        return {} unless raw.is_a?(Hash)
+
+        raw.each_with_object({}) { |(k, v), acc| acc[k.to_sym] = v }
+      end
+
+      def self.bool(v)
+        return v if v == true || v == false
+        return false if v.nil?
+
+        s = v.to_s.strip.downcase
+        !s.empty? && !%w[false 0 off no].include?(s)
+      end
+
+      def self.presence(v) = Insika::Coercion.presence(v)
+
+      def self.normalize_strictness(v)
+        sym = v.to_s.strip.downcase.to_sym
+        STRICTNESS_CATEGORIES.key?(sym) ? sym : DEFAULT_STRICTNESS
+      end
+
+      # Per-agent safe-reply overrides -> { "category" => "text" } with STRING keys
+      # (SafeResponses looks up by string), blanks dropped. Tolerant of the JSON
+      # round-trip and of a non-Hash (ignored -> {}).
+      def self.normalize_responses(v)
+        return {} unless v.is_a?(Hash)
+
+        v.each_with_object({}) do |(k, val), acc|
+          text = val.to_s.strip
+          acc[k.to_s] = text unless text.empty?
+        end
+      end
+
+      private_class_method :symbolize, :bool, :presence, :normalize_strictness, :normalize_responses
+    end
+  end
+end