insika 0.2.0 → 0.7.0

data/lib/insika/safety/corpus.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+module Insika
+  module Safety
+    # The SHIPPED deterministic guardrail corpus as language-tagged DATA
+    # Pure data — no Insika requires, standalone-loadable
+    # like detectors.rb used to be.
+    #
+    # Pattern SOURCE now lives here; `Detectors` is the compiler/matcher on
+    # top. The runtime compiles a per-agent `Compiled` set — a deployment
+    # clears the pt-BR families via `guardrails.corpora.languages` and extends
+    # them via `guardrails.corpora.extra` (docs/domain.md). Absent config = the
+    # full shipped default: byte-for-byte today's behavior (parity).
+    #
+    # LANGUAGE: each regex lives in exactly ONE language. `compile` (no args)
+    # is the union of the shipped languages, each family in its shipped order.
+    # For a single-language input the default behaves exactly as the runtime
+    # that hard-coded one flat list — the ONE honest delta: the previous flat
+    # list INTERLEAVED the languages, so for a phrase matching patterns of
+    # BOTH languages the reported `matched` substring may differ (the
+    # category never does). Pinned in spec/insika/safety/corpus_spec.rb.
+    module Corpus
+      # ── The shipped input families ─────────────────────────────────────────
+      # "injection"/"sexual"/"abuse" per language. High-confidence heuristics
+      # that short-circuit the turn BEFORE the LLM runs (conservative by
+      # design — a false positive blocks a legitimate customer; the subtler
+      # judgment is the LLM moderator's).
+      DEFAULTS = {
+        "pt-BR" => {
+          "injection" => [
+            /\binstru[çc][õo]es\s+de\s+sistema\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,
+            # 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
+          ],
+          "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
+          ],
+          "abuse" => [
+            # Directed insult only — "a entrega foi uma merda" must NOT block;
+            # "você é uma merda de atendente" should. The `você é …` anchor
+            # keeps precision high.
+            /\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" => {
+          "injection" => [
+            /\bsystem\s*prompt\b/i,
+            /\b(ignore|disregard|forget)\b[^.?!]{0,30}\b(instructions|rules|prompt|above|previous|prior)\b/i
+          ],
+          "sexual" => [
+            /\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
+          ],
+          "abuse" => [
+            # 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
+
+      # ── The shipped OUTPUT detectors (PII/secret redaction targets) ────────
+      # Language-tagged: "secret" is universal (never cleared); "cpf"/"cnpj"
+      # are pt-BR tax-id formats — an EN-only corpus drops them (documented
+      # consequence, docs/domain.md). Key ORDER is the previous runtime's
+      # (cpf, cnpj, secret) — it is what `pii_names` and the "pii_leak" union
+      # iterate.
+      PII = {
+        "cpf" => {
+          "languages" => ["pt-BR"],
+          "pattern" => /\b\d{3}\.\d{3}\.\d{3}-\d{2}\b/
+        },
+        "cnpj" => {
+          "languages" => ["pt-BR"],
+          "pattern" => /\b\d{2}\.\d{3}\.\d{3}\/\d{4}-\d{2}\b/
+        },
+        "secret" => {
+          "languages" => nil,
+          "pattern" => /\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's hold-back). Universal: it covers the unbounded
+      # `sk-…`/`Bearer …` shapes and the in-progress CPF/CNPJ digit runs.
+      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
+
+      # The compiled corpus for ONE agent: the input families + output
+      # detectors filtered by its languages and extended by its `extra`
+      # patterns. Immutable (Data + deep-frozen collections) and shared safely.
+      Compiled = Data.define(:languages, :input, :pii) do
+        # The subset of `categories` (symbols) that have patterns in this
+        # corpus — the strictness gate applied to the compiled set.
+        def input_categories(categories)
+          categories.select { |cat| Array(input[cat.to_s]).any? }
+        end
+
+        # Runs a NAMED output detector over `text` -> the matched substring |
+        # nil. "pii_leak" = union of all patterns; an entirely UNKNOWN name
+        # fails LOUD (a typo'd assertion must never silently pass); a name the
+        # corpus knows but whose language was cleared matches nothing.
+        def detect_output(name, text)
+          patterns =
+            if name.to_s == "pii_leak"
+              pii.values
+            else
+              p = pii[name.to_s]
+              if p.nil? && !Corpus::PII.key?(name.to_s)
+                raise ArgumentError, "unknown detector: #{name.inspect}"
+              end
+
+              p ? [p] : []
+            end
+          patterns.each { |re| (m = text.to_s.match(re)) && (return m[0]) }
+          nil
+        end
+
+        # Replaces every PII/secret occurrence with an opaque `[REDACTED:<name>]`
+        # marker — the raw value NEVER survives. -> [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
+
+        # [[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
+
+        # The universal open-tail pattern (see Corpus::OPEN_TAIL).
+        def open_tail = Corpus::OPEN_TAIL
+      end
+
+      KNOWN_FAMILIES = %w[injection sexual abuse].freeze
+
+      # -> Compiled. `languages`: nil = ALL shipped languages (parity default);
+      # [] = no shipped input family (only `extra`); ["en"] = the EN-only
+      # corpus. `extra`: { "abuse" => ["/\\bdupa\\b/i", ...] } — per-category
+      # additions in the source-string syntax (or Regexp objects), compiled
+      # with the same syntax. Raises Insika::ValidationError naming the value
+      # for an unknown language/family or a malformed pattern.
+      #
+      # Compiled values are immutable, so the result is MEMOIZED per signature:
+      # a turn builds Config several times (input middleware, output validator,
+      # filter factory) and each build must not re-compile the same patterns.
+      def self.compile(languages: nil, extra: {})
+        key = [languages.is_a?(Array) ? languages.sort : languages, extra]
+        @cache ||= {}
+        @cache[key] ||= build(languages, extra)
+      end
+
+      def self.build(languages, extra)
+        langs = languages.nil? ? DEFAULTS.keys : validate_languages!(languages)
+        extra = validate_extra!(extra)
+
+        input = {}
+        langs.each do |lang|
+          DEFAULTS.fetch(lang).each do |cat, patterns|
+            input[cat] = Array(input[cat]) + patterns
+          end
+        end
+        extra.each do |cat, sources|
+          input[cat.to_s] = Array(input[cat.to_s]) + Array(sources).map { |src| compile_pattern(src, cat) }
+        end
+
+        pii = {}
+        PII.each do |name, meta|
+          meta_langs = meta["languages"]
+          next if meta_langs && (meta_langs & langs).empty?
+
+          pii[name] = meta["pattern"]
+        end
+
+        # `langs.dup`: the caller's array is never frozen out from under it.
+        Compiled.new(
+          languages: langs.dup.freeze,
+          input: input.transform_values(&:freeze).freeze,
+          pii: pii.freeze
+        )
+      end
+      private_class_method :build
+
+      def self.validate_languages!(languages)
+        unless languages.is_a?(Array) && (languages - DEFAULTS.keys).empty?
+          raise Insika::ValidationError,
+                "guardrails.corpora.languages must be an Array of known languages " \
+                "(#{DEFAULTS.keys.join(", ")}), got: #{languages.inspect}"
+        end
+        languages
+      end
+
+      def self.validate_extra!(extra)
+        unless extra.is_a?(Hash) && (extra.keys.map(&:to_s) - KNOWN_FAMILIES).empty?
+          unknown = extra.is_a?(Hash) ? extra.keys.map(&:to_s) - KNOWN_FAMILIES : []
+          label = unknown.empty? ? extra.inspect : unknown.join(", ")
+          raise Insika::ValidationError,
+                "guardrails.corpora.extra must be a Hash with known families " \
+                "(#{KNOWN_FAMILIES.join(", ")}), got: #{label}"
+        end
+        extra
+      end
+
+      # A pattern source -> Regexp. Accepts the source-string syntax
+      # ("/\\bdupa\\b/i") or a bare pattern; Regexp objects pass through.
+      # A malformed source fails with the pattern named.
+      def self.compile_pattern(source, family)
+        return source if source.is_a?(Regexp)
+
+        s = source.to_s
+        if (m = s.match(%r{\A/(.*)/([a-z]*)\z}m))
+          Regexp.new(m[1], m[2])
+        else
+          Regexp.new(s)
+        end
+      rescue RegexpError => e
+        raise Insika::ValidationError,
+              "guardrails.corpora.extra.#{family}: invalid pattern source " \
+              "#{source.inspect} (#{e.message})"
+      end
+
+      private_class_method :validate_languages!, :validate_extra!, :compile_pattern
+    end
+  end
+end

data/lib/insika/safety/detectors.rb

@@ -1,8 +1,13 @@
 # frozen_string_literal: true
 
+require_relative "corpus"
+
 module Insika
   module Safety
-    # SINGLE SOURCE of truth for content-safety pattern matching.
+    # The compiler/matcher over the language-tagged pattern corpus (
+    # C2). The pattern SOURCE lives in `Safety::Corpus`; every method here
+    # reads a compiled `Corpus::Compiled` set, defaulting to the full shipped
+    # corpus — byte-for-byte the runtime's pre-  behavior.
     #
     # Two families live here on purpose — the same lists back BOTH the runtime
     # guardrail AND the eval's `must_not` detectors: the eval
@@ -16,151 +21,65 @@ 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: a false positive blocks a
+    # Everything here is CONSERVATIVE by design: 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, 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.
+    # rely on the LLM moderator, which is language-agnostic. A deployment clears a
+    # language via `guardrails.corpora` (docs/domain.md) — adding a language is
+    # adding data to Corpus, never 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). 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 ──────────────────────────────────────────────────────
+      # The universal open-tail pattern — the prefix of a PII/secret shape
+      # that might still be growing. Lives in the corpus data (universal, not
+      # language-tagged); kept here for the module's readers.
+      OPEN_TAIL = Corpus::OPEN_TAIL
 
       # 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
+      # `corpus:` — the compiled set for the agent; nil = the full default.
+      def detect(name, text, corpus: nil)
+        (corpus || Corpus.compile).detect_output(name, text)
       end
 
       # Names of the PII detectors (for iteration by the eval / config).
-      def pii_names = PII.keys
+      def pii_names(corpus: nil) = (corpus || Corpus.compile).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
+      def match_ranges(text, corpus: nil)
+        (corpus || Corpus.compile).match_ranges(text)
       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]
+      def redact(text, corpus: nil)
+        (corpus || Corpus.compile).redact(text)
       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.
+      # (see Insika::Safety::Config) and by the agent's compiled corpus.
+      # 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])
+      def scan_input(text, categories: %i[injection sexual abuse], corpus: nil)
+        compiled = corpus || Corpus.compile
         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)
+        cats = compiled.input_categories(categories)
+        return { category: :injection, matched: first_match(compiled.input["injection"], s) } if cats.include?(:injection) && any?(compiled.input["injection"], s)
+        return { category: :sexual, matched: first_match(compiled.input["sexual"], s) }        if cats.include?(:sexual) && any?(compiled.input["sexual"], s)
+        return { category: :abuse, matched: first_match(compiled.input["abuse"], s) }          if cats.include?(:abuse) && any?(compiled.input["abuse"], s)
 
         nil
       end

data/lib/insika/safety/factory.rb

@@ -6,6 +6,10 @@ require_relative "moderator"
 require_relative "output_filter"
 require_relative "input_guardrail"
 require_relative "output_validator"
+# the grounding validator (flagged as the OutputValidator's first
+# step) and the enforcer (the executor's stage-8 boundary call). Pure Ruby.
+require_relative "grounding_validator"
+require_relative "grounding_enforcer"
 
 module Insika
   module Safety
@@ -36,15 +40,24 @@ module Insika
       end
 
       # The after_task hook (register with hooks.register(:task, after: ...)).
+      # the grounding validator is the OutputValidator's FIRST step —
+      # it runs before the output gate (D9), so grounding is independent of the
+      # guardrails opt-in.
       def output_validator
-        OutputValidator.new(ask_factory: ->(config) { ask_for(config) })
+        OutputValidator.new(ask_factory: ->(config) { ask_for(config) },
+                            grounding: GroundingValidator.new)
       end
 
+      # the `:enforce` boundary step the Executor calls between
+      # stages 6 and 8. Inert unless the profile's grounding.mode is :enforce.
+      def grounding_enforcer = GroundingEnforcer.new
+
       # Injected into the Executor. ->(state) { OutputFilter | nil }: a fresh stateful
       # filter per turn when the agent has output guardrails on; nil = off (parity).
       def content_filter_factory
         lambda do |state|
-          Config.from_profile(state.profile).output ? OutputFilter.new : nil
+          config = Config.from_profile(state.profile)
+          config.output ? OutputFilter.new(corpus: config.corpus) : nil
         end
       end
 

data/lib/insika/safety/grounding_enforcer.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Insika
+  module Safety
+    #   — the `:enforce` half of grounding: the claim's SENTENCE is
+    # cut from the content the turn persists and delivers. A NEW stage-8 boundary
+    # step (a plain executor call, NOT an after_task hook — after_task fires too
+    # late to change what is persisted).
+    #
+    # The cut removes the SENTENCE that contains an ungrounded claim (never a
+    # surgical span — removing half a sentence produces broken prose). What the
+    # cut CANNOT do is unsay a streamed delta — for a streaming surface `:enforce`
+    # still delivers the cut text via channel delivery and flags the turn; that
+    # honesty is why the own default is `:flag` (ship `:enforce` only after
+    # the matcher audit). Runs ONLY in :enforce mode — inert otherwise.
+    class GroundingEnforcer
+      # -> [new_content, state]. The stage-8 boundary call. Fail-open: grounding
+      # must never break a completed turn.
+      def call(task, state, content)
+        grounding = grounding_of(state)
+        return [content, state] unless grounding&.enforce?
+
+        ledger = state.respond_to?(:evidence_ledger) ? state.evidence_ledger : nil
+        return [content, state] unless ledger
+
+        text = content.to_s
+        refs = grounding.matcher.references(text)
+        claims = grounding.matcher.ungrounded(refs, evidence_ids: ledger.ids)
+        return [content, state] if claims.empty?
+
+        cut = cut_sentences(text, claims)
+        claims.each { |c| ledger.ungrounded_count(c) }
+        state.guardrail_flags = Array(state.guardrail_flags) + [{
+          category: "ungrounded", source: "evidence", action: "cut",
+          detail: "cut claim(s): #{claims.join(', ')}" }]
+        [cut, state]
+      rescue StandardError
+        [content, state] # fail-open: grounding must never break a completed turn
+      end
+
+      private
+
+      def grounding_of(state)
+        raw = state.profile.respond_to?(:grounding) ? state.profile.grounding : nil
+        raw && Insika::Grounding.parse(raw)
+      end
+
+      # The smallest self-contained unit: split on sentence boundaries and drop
+      # every sentence containing an ungrounded reference. Conservative on
+      # purpose — a sentence with TWO claims, one grounded and one not, is cut
+      # whole (documented behavior).
+      def cut_sentences(text, claims)
+        sentences = text.split(/(?<=[.!?])\s+/)
+        kept = sentences.reject { |sentence| claims.any? { |claim| sentence.include?(claim) } }
+        kept.join(" ").strip
+      end
+    end
+  end
+end

data/lib/insika/safety/grounding_validator.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Insika
+  module Safety
+    #   — the `:flag` half of grounding. A reply claiming a product
+    # whose reference is not in the evidence ledger is FLAGGED (audit via the
+    # existing `:guardrail_flagged` channel) — the text is already out, so
+    # flagging is audit, exactly like every other output flag.
+    #
+    # Runs as the FIRST step of the OutputValidator's after_task chain, BEFORE
+    # the `config.output` gate (D9): grounding is evidence integrity, independent
+    # of the guardrails opt-in — an agent with guardrails off and
+    # `grounding.mode: :flag` still gets the check. Fail-open on any error
+    # (grounding must never break a completed turn).
+    class GroundingValidator
+      # -> state (the after_task contract). Appends `:ungrounded` flags.
+      def call(state)
+        grounding = grounding_of(state)
+        # :flag only — :enforce is the enforcer's job, :off / absent is nothing.
+        return state if grounding.nil? || grounding.off? || grounding.enforce?
+
+        ledger = state.respond_to?(:evidence_ledger) ? state.evidence_ledger : nil
+        return state unless ledger
+
+        text = state.response_content.to_s
+        return state if text.empty?
+
+        refs = grounding.matcher.references(text)
+        claims = grounding.matcher.ungrounded(refs, evidence_ids: ledger.ids)
+        claims.each { |c| ledger.ungrounded_count(c) }
+        unless claims.empty?
+          state.guardrail_flags = Array(state.guardrail_flags) + [{
+            category: "ungrounded", source: "evidence",
+            detail: "product claim without tool evidence: #{claims.join(', ')}" }]
+        end
+        state
+      rescue StandardError
+        state # fail-open
+      end
+
+      private
+
+      def grounding_of(state)
+        raw = state.profile.respond_to?(:grounding) ? state.profile.grounding : nil
+        raw && Insika::Grounding.parse(raw)
+      end
+    end
+  end
+end

data/lib/insika/safety/input_guardrail.rb

@@ -33,7 +33,7 @@ module Insika
         config = Config.from_profile(state.profile)
         return nxt.call(state) unless config.input
 
-        hit = Detectors.scan_input(state.message.to_s, categories: config.input_categories)
+        hit = Detectors.scan_input(state.message.to_s, categories: config.input_categories, corpus: config.corpus)
         return block(state, config, category: hit[:category], source: :deterministic, detail: hit[:matched]) if hit
 
         if config.moderator? && (mod = build_moderator(config))

data/lib/insika/safety/moderator.rb

@@ -13,7 +13,7 @@ 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. Blocking is the high-stakes direction (RFC: a false
+    # legitimate customer. Blocking is the high-stakes direction (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`,

data/lib/insika/safety/output_filter.rb

@@ -9,7 +9,7 @@ module Insika
     # sits between the provider chunks and the `:content` event and only ever emits
     # text it has PROVEN clean.
     #
-    # The hard part (RFC, "fronteira de chunk"): a CPF/secret can arrive split
+    # The hard part ("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
@@ -21,7 +21,11 @@ module Insika
     class OutputFilter
       attr_reader :redaction_counts
 
-      def initialize
+      # `corpus` : the compiled corpus for the turn — the
+      # language-filtered PII set and its open-tail pattern. Default = the
+      # full shipped corpus (parity).
+      def initialize(corpus: Corpus.compile)
+        @corpus = corpus
         @buf = +""
         @emitted = +"" # full redacted text emitted so far (for the persisted content)
         @redaction_counts = Hash.new(0)
@@ -51,11 +55,11 @@ module Insika
       def safe_cut
         cut = @buf.length
 
-        if (m = @buf.match(Detectors::OPEN_TAIL))
+        if (m = @buf.match(@corpus.open_tail))
           cut = [cut, m.begin(0)].min
         end
 
-        Detectors.match_ranges(@buf).each do |b, e|
+        @corpus.match_ranges(@buf).each do |b, e|
           cut = b if b < cut && cut < e
         end
 
@@ -69,7 +73,7 @@ module Insika
 
         chunk = @buf[0...cut]
         @buf = @buf[cut..] || +""
-        redacted, counts = Detectors.redact(chunk)
+        redacted, counts = @corpus.redact(chunk)
         counts.each { |name, n| @redaction_counts[name] += n }
         @emitted << redacted
         redacted