insika 0.0.1 → 0.1.0

data/lib/insika/refinement_store.rb

@@ -0,0 +1,295 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "time"
+
+module Insika
+  # REFINEMENT DOMAIN store (RFC-0013, phase A). 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.
+  #
+  # 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
+  # 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 §3.6. 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.
+  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 phase A 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
+    # (RFC-0013 §3.9, phase D): 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
+
+    # -- phase C: 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 (D2). 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).
+    #
+    # `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.
+    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/safety/config.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Insika
+  module Safety
+    # Per-agent guardrail configuration (RFC-0009 §3.3 / D6), 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 (RFC-0009 §7). 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

data/lib/insika/safety/detectors.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module Insika
+  module Safety
+    # SINGLE SOURCE of truth for content-safety pattern matching (RFC-0009 D4).
+    #
+    # 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
+    # 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 +
+    # frozen regexes, no other Insika require) — it loads standalone from either side.
+    #
+    #   · OUTPUT side (PII/secret) — patterns that must never reach a customer turn.
+    #     Consumed by the OutputFilter (stream redaction) and the eval `pii_leak`.
+    #   · 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
+    # 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.
+    #
+    # 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
+    # rely on the LLM moderator, which is language-agnostic. Adding a language = adding
+    # patterns to the arrays below — it never needs core changes.
+    module Detectors
+      module_function
+
+      # ── OUTPUT: PII / secret (redaction targets) ────────────────────────────
+      # Formatted BR CPF/CNPJ only — a bare digit run (an order number, a price) is
+      # too ambiguous to flag. Credential shapes that must never leak.
+      PII = {
+        "cpf"    => /\b\d{3}\.\d{3}\.\d{3}-\d{2}\b/,
+        "cnpj"   => /\b\d{2}\.\d{3}\.\d{3}\/\d{4}-\d{2}\b/,
+        "secret" => /\b(?:sk-[A-Za-z0-9]{16,}|Bearer\s+[A-Za-z0-9._-]{16,})\b/
+      }.freeze
+
+      # 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
+      # unbounded `sk-…`/`Bearer …` case that a fixed window cannot.
+      #
+      # Crucially it also matches a PARTIAL literal PREFIX at the tail — a lone "s"
+      # (start of "sk-"), "Bear" (start of "Bearer "), a trailing digit run — because
+      # the prefix ITSELF can be split across chunks (emitting the "s" then matching
+      # "k-…" alone would miss the secret entirely). The cost is a few chars of tail
+      # latency on words ending in "s"/"B"/a digit, released on the next chunk or flush.
+      OPEN_TAIL = %r{
+        (?:
+          s(?:k(?:-[A-Za-z0-9]*)?)?                    # prefix of "sk-" + optional body
+          | B(?:e(?:a(?:r(?:e(?:r(?:\s+[A-Za-z0-9._-]*)?)?)?)?)?)?  # prefix of "Bearer " + body
+          | \d[\d./-]*                                 # in-progress CPF/CNPJ digit run
+        )\z
+      }x
+
+      # ── INPUT: prompt-injection / exfiltration ──────────────────────────────
+      INJECTION = [
+        # exfil of the system prompt / internal rules
+        /\binstru[çc][õo]es\s+de\s+sistema\b/i,
+        /\bsystem\s*prompt\b/i,
+        /\b(regras|instru[çc][õo]es|orienta[çc][õo]es|diretrizes)\s+internas\b/i,
+        /\b(revele|mostre|exiba|me\s+(d[êe]|mande|envie|passe)|repita|imprima)\b[^.?!]{0,40}\b(prompt|instru[çc][õo]es|regras|configura[çc][ãa]o|system)\b/i,
+        # "ignore/disregard the (previous) instructions"
+        /\b(ignore|ignora|desconsidere|esque[çc]a)\b[^.?!]{0,30}\b(instru[çc][õo]es|regras|orienta[çc][õo]es|acima|anteriores)\b/i,
+        /\b(ignore|disregard|forget)\b[^.?!]{0,30}\b(instructions|rules|prompt|above|previous|prior)\b/i,
+        # encode/translate the prompt (the base64/rot13 exfil trick, either order)
+        /\b(base64|rot13|codific|encode|cifr)\w*\b[^.?!]{0,60}\b(instru[çc][õo]es|prompt|regras|sistema|system)\b/i,
+        /\b(instru[çc][õo]es|prompt|regras|sistema|system)\b[^.?!]{0,60}\b(base64|rot13|codific|encode|cifr)\w*\b/i
+      ].freeze
+
+      # ── INPUT: sexual / inappropriate ───────────────────────────────────────
+      # pt-BR + EN. Deterministic coverage is best-effort per language (see the
+      # module note): other languages fall to the LLM moderator (language-agnostic).
+      SEXUAL = [
+        /\b(nudes?|pelad[oa]s?|s?exo|transar|transa\b|gozar|tes[ãa]o|s[ãa]fad[oa]|puta|pau|buceta|piroca|caralho\s+(duro|na))\b/i,
+        /\bo\s+que\s+voc[êe]\s+faria\s+comigo\b/i,
+        /\b(descrev|imagina|conta)\w*\b[^.?!]{0,30}\bcomigo\s+(na\s+cama|pelad)/i,
+        /\b(quer|vamos)\b[^.?!]{0,20}\b(transar|fazer\s+sexo|sexo)\b/i,
+        # EN
+        /\b(horny|blow\s?job|hand\s?job|jerk\s+off|have\s+sex|send\s+(me\s+)?(a\s+)?nudes?|dick\s+pic)\b/i,
+        /\bwhat\s+(would|will)\s+you\s+do\s+to\s+me\b/i
+      ].freeze
+
+      # ── INPUT: verbal abuse / harassment (directed at the assistant) ─────────
+      # Directed insult only — "a entrega foi uma merda" (frustration about the
+      # service) must NOT block; "você é uma merda de atendente" (insult at the bot)
+      # should. The `você é …` anchor keeps precision high.
+      ABUSE = [
+        /\bvoc[êe]\s+(é|e|ta|est[áa])\b[^.?!]{0,25}\b(lixo|in[uú]til|merda|imprest[aá]vel|idiota|burr[oa]|est[uú]pid[oa]|otári[oa]|in[uú]teis|incompetente|p[áa]ssim[oa])\b/i,
+        /\b(seu|sua)\s+(lixo|in[uú]til|idiota|imbecil|otári[oa]|burr[oa]|est[uú]pid[oa]|merda|escrot[oa])\b/i,
+        /\bvai\s+(se\s+)?(fuder|foder|tomar\s+no)\b/i,
+        # EN — directed insult only (keeps precision high; frustration ≠ abuse)
+        /\byou\s*(?:'?re|\s+are)\b[^.?!]{0,25}\b(useless|garbage|trash|idiot|stupid|worthless|pathetic|incompetent|dumb|a\s+joke)\b/i,
+        /\b(fuck|screw)\s+you\b/i,
+        /\byou\s+(suck|are\s+the\s+worst)\b/i
+      ].freeze
+
+      # ── OUTPUT helpers ──────────────────────────────────────────────────────
+
+      # Runs a NAMED output detector over `text` -> the matched substring | nil.
+      # "pii_leak" = union of all PII patterns; otherwise a single named pattern.
+      # Unknown name fails LOUD (a typo'd assertion must never silently pass).
+      def detect(name, text)
+        patterns =
+          if name.to_s == "pii_leak"
+            PII.values
+          else
+            p = PII[name.to_s]
+            raise ArgumentError, "unknown detector: #{name.inspect}" unless p
+
+            [p]
+          end
+        patterns.each { |re| (m = text.to_s.match(re)) && (return m[0]) }
+        nil
+      end
+
+      # Names of the PII detectors (for iteration by the eval / config).
+      def pii_names = PII.keys
+
+      # [[begin, end), ...] byte-index ranges of every PII/secret match in `text`
+      # (used by the OutputFilter to avoid splitting a complete match at a chunk
+      # boundary).
+      def match_ranges(text)
+        ranges = []
+        PII.each_value do |re|
+          text.to_s.scan(re) { ranges << [Regexp.last_match.begin(0), Regexp.last_match.end(0)] }
+        end
+        ranges
+      end
+
+      # Replaces every PII/secret occurrence with an opaque `[REDACTED:<name>]`
+      # marker — the raw value NEVER survives (D "o redigido nunca aparece em
+      # claro"). -> [redacted_text, {name => count}].
+      def redact(text)
+        counts = Hash.new(0)
+        out = text.to_s.dup
+        PII.each do |name, re|
+          out = out.gsub(re) do
+            counts[name] += 1
+            "[REDACTED:#{name}]"
+          end
+        end
+        [out, counts]
+      end
+
+      # ── INPUT helpers ───────────────────────────────────────────────────────
+
+      # Scans a user message against the input heuristics, gated by strictness
+      # (see Insika::Safety::Config). Returns { category:, matched: } for the FIRST
+      # category that fires (injection is checked first — the highest-stakes), or
+      # nil when the message is clean. `categories` limits which families run.
+      #
+      #   :injection -> always high confidence
+      #   :sexual    -> medium+
+      #   :abuse     -> medium+
+      def scan_input(text, categories: %i[injection sexual abuse])
+        s = text.to_s
+        return { category: :injection, matched: first_match(INJECTION, s) } if categories.include?(:injection) && any?(INJECTION, s)
+        return { category: :sexual, matched: first_match(SEXUAL, s) }        if categories.include?(:sexual) && any?(SEXUAL, s)
+        return { category: :abuse, matched: first_match(ABUSE, s) }          if categories.include?(:abuse) && any?(ABUSE, s)
+
+        nil
+      end
+
+      def any?(patterns, text) = patterns.any? { |re| re.match?(text) }
+
+      def first_match(patterns, text)
+        patterns.each { |re| (m = text.match(re)) && (return m[0]) }
+        nil
+      end
+    end
+  end
+end