insika 0.1.0 → 0.3.0

data/lib/insika/safety/input_guardrail.rb

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

data/lib/insika/safety/moderator.rb

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

data/lib/insika/safety/output_filter.rb

@@ -4,12 +4,12 @@ require_relative "detectors"
 
 module Insika
   module Safety
-    # Deterministic output redaction on the STREAM (RFC-0009 §3.2 / D3). The turn
+    # Deterministic output redaction on the STREAM. The turn
     # streams `content` deltas, so we cannot "unsay" text already sent — the filter
     # sits between the provider chunks and the `:content` event and only ever emits
     # text it has PROVEN clean.
     #
-    # The hard part (RFC §6, "fronteira de chunk"): a CPF/secret can arrive split
+    # The hard part ("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

data/lib/insika/safety/output_validator.rb

@@ -6,11 +6,11 @@ require_relative "config"
 
 module Insika
   module Safety
-    # Post-turn output validator (RFC-0009 §3.2 / D3). Runs as an `after_task` hook:
+    # Post-turn output validator. Runs as an `after_task` hook:
     # with the FINAL assistant text assembled, it does a richer check than the
     # stream filter can — an unverified discount/price promise, a tone slip — and
     # FLAGS it (audit) rather than blocking. It is honest about the streaming limit
-    # (D3): for a streaming agent the text is already out the door, so this is
+    # for a streaming agent the text is already out the door, so this is
     # detection, not prevention; true pre-emission blocking needs `streaming:false`
     # (a per-profile override left for a later slice).
     #
@@ -27,13 +27,19 @@ module Insika
     class OutputValidator
       # `ask_factory` (optional): ->(config) { ->(prompt){text} | nil }, built by the
       # Safety::Factory from the utility_model. nil = deterministic only.
-      def initialize(ask_factory: nil)
+      # `grounding` (optional): a GroundingValidator — its step runs
+      # FIRST in #call, before the `config.output` gate (D9: grounding is
+      # evidence integrity, independent of the guardrails opt-in).
+      def initialize(ask_factory: nil, grounding: nil)
         @ask_factory = ask_factory
+        @grounding = grounding
       end
 
       # after_task hook body. Idempotent and defensive: never raises out (a hook
-      # error must not fail a committed turn).
+      # error must not fail a committed turn). Grounding runs BEFORE the output
+      # gate so an agent with guardrails off and grounding on still gets the check.
       def call(state)
+        state = @grounding&.call(state) || state
         config = Config.from_profile(state.profile)
         return state unless config.output
 
@@ -41,7 +47,7 @@ module Insika
         return state if text.empty?
 
         flags = []
-        flags.concat(deterministic_flags(text))
+        flags.concat(deterministic_flags(text, config.corpus))
         flags.concat(llm_flags(text, config)) if config.moderator?
 
         state.guardrail_flags = Array(state.guardrail_flags) + flags unless flags.empty?
@@ -55,8 +61,8 @@ module Insika
       # Residual PII/secret that somehow reached the final text (the stream filter
       # should have caught it — this is defense in depth, and the flag itself
       # carries category counts, never the raw value).
-      def deterministic_flags(text)
-        _redacted, counts = Detectors.redact(text)
+      def deterministic_flags(text, corpus)
+        _redacted, counts = Detectors.redact(text, corpus: corpus)
         return [] if counts.empty?
 
         [{ category: "pii_residual", source: "deterministic", detail: counts.map { |k, v| "#{k}:#{v}" }.join(",") }]

data/lib/insika/safety/safe_responses.rb

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

data/lib/insika/sandbox/boundary.rb

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

data/lib/insika/sandbox.rb

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

data/lib/insika/schema_guard.rb

@@ -131,6 +131,41 @@ module Insika
       end
     end
 
+    # Walks a dotted path on a plain object: nil when a segment
+    # is absent or the intermediate is not a Hash. Shared by the evidence output
+    # check and the Processor's extraction.
+    def dig(obj, path)
+      path.to_s.split(".").reduce(obj) do |cur, seg|
+        return nil unless cur.is_a?(Hash) && cur.key?(seg)
+
+        cur[seg]
+      end
+    end
+
+    # The evidence RESULT contract: {items: [{id, line}]} .
+    # -> nil | String. Same idiom as `violation`: nil = fine, one message = what
+    # is wrong. A malformed evidence result is a correctable TOOL answer — the
+    # envelope returns it to the model as `{error:}`, exactly like a malformed
+    # call is today. A raw body that is NOT an object (a bare JSON array from a
+    # search, a string, nil) is a violation — never a silent `{items: []}` that
+    # the model reads as "no products".
+    def violation_output(spec, raw)
+      return nil if spec.nil?
+      return "evidence: result must be an object" unless raw.is_a?(Hash)
+
+      items = dig(raw, spec.items_path)
+      return "evidence: items is missing" if items.nil?
+      return "evidence: items must be a list" unless items.is_a?(Array)
+
+      items.each_with_index do |item, i|
+        ok = item.is_a?(Hash) &&
+             Coercion.present?(item["id"] || item[:id]) &&
+             (item["line"] || item[:line]).is_a?(String)
+        return "evidence: items[#{i}] must be {id, line}" unless ok
+      end
+      nil
+    end
+
     # Name the shape the way a model reads it, not the way Ruby does.
     def kind(value)
       case value