insika 0.0.1 → 0.1.0

data/lib/insika/env_schema.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+module Insika
+  # STRICT config, environment layer (item 23 / §8.1). OpenClaw's config discipline
+  # — "recusa boot com chave desconhecida, no silent config compat" — applied to the
+  # env vars the engine reads at boot. A declarative registry of the keys the engine
+  # OWNS (config over convention: the schema IS data), used two ways:
+  #
+  #   · `validate(env)` — returns structured Findings: a value that fails its type
+  #     (INSIKA_PORT=abc), an UNKNOWN key inside a namespace the engine owns
+  #     (INSIKA_EGRES_ALLOW_HTTP — a typo the runtime would otherwise ignore in
+  #     silence), and a DEPRECATED legacy key still set under the old HARNESS_ prefix.
+  #     Unknown-key detection is scoped to the OWNED prefixes only, so the platform's
+  #     own vars (Railway's RAILWAY_*, PORT, PATH, the litestream sidecar's
+  #     LITESTREAM_*, the deployment's DEEPSEEK_*/ACHEI_*) are never flagged.
+  #   · `enforce!(strict:)` — the boot gate. WARNS on every finding by default and
+  #     lets the engine come up (last-known-good — a rotated key or a typo must never
+  #     take the whole service down, same reasoning as the resilient DEEPSEEK boot);
+  #     RAISES ConfigError only when strictness is on (INSIKA_CONFIG_STRICT truthy,
+  #     or `strict: true`).
+  #
+  # RENAME (env pass 2): the engine's owned prefix is now INSIKA_. The old HARNESS_
+  # names still work — `reconcile_legacy!` backfills INSIKA_* from any HARNESS_* alias
+  # at boot (new name wins), and `read` gives the same dual-read to the self-contained
+  # readers (Telemetry, TurnTiming, SubagentGraph) that receive an env hash directly.
+  # A legacy name in use surfaces as a `:deprecated` warning (never fatal) so operators
+  # get a clear "rename to INSIKA_*" without a broken boot.
+  #
+  # Insika::Doctor reuses `validate` for its `env:*` checks; the boot roots call
+  # `enforce!`. A deployment layers its own keys on via `extra:` (see
+  # config/deployment.rb) so `insika env` and `insika doctor` see the full picture.
+  module EnvSchema
+    module_function
+
+    # One env key the engine knows about. `type` drives validation; `secret` masks
+    # the value in `insika env`; `enum` restricts allowed values; `required` makes
+    # a blank value a finding (engine keys are all optional — deployment resilience —
+    # so `required` is used by deployment extras, not the defaults here).
+    Spec = Data.define(:name, :type, :secret, :required, :enum, :description) do
+      def secret? = secret
+      def required? = required
+
+      # nil/blank when optional -> no finding. Present -> must satisfy the type. ->
+      # error string or nil.
+      def error_for(raw)
+        value = raw.to_s
+        return "is required (unset)" if value.strip.empty? && required
+        return nil if value.strip.empty?
+
+        case type
+        when :integer
+          "must be an integer, got #{value.inspect}" unless value.match?(/\A-?\d+\z/)
+        when :boolean
+          "must be a boolean (#{BOOLEANS.join('/')}), got #{value.inspect}" unless EnvSchema.boolean?(value)
+        when :enum
+          "must be one of #{enum.inspect}, got #{value.inspect}" unless Array(enum).include?(value)
+        when :url
+          "must be an http(s) URL, got #{value.inspect}" unless value.match?(%r{\Ahttps?://\S+\z})
+        end # :string / :csv / :path -> any string is valid
+      end
+    end
+
+    # A problem (or an :ok note) about the environment. dry/serializable — the proc-
+    # free shape Doctor and `insika env` both render.
+    Finding = Data.define(:key, :kind, :severity, :message) do
+      def to_h = { "key" => key, "kind" => kind.to_s, "severity" => severity.to_s, "message" => message }
+    end
+
+    # The engine's owned prefix and its deprecated predecessor.
+    PREFIX = "INSIKA_"
+    LEGACY_PREFIX = "HARNESS_"
+
+    # Prefixes the engine fully OWNS: an unknown key under one of these is a typo, not
+    # a foreign var. INSIKA_ (current) and HARNESS_ (legacy, still honored during the
+    # deprecation window). Deliberately NOT OPENCLAW_ (shared with the OpenClaw gateway
+    # product, which sets its own OPENCLAW_HOME/_STATE_DIR/… — the engine merely borrows
+    # 3 names for interop), nor LITESTREAM_ (the sidecar owns it), nor OTEL_ (the
+    # OpenTelemetry SDK owns its env).
+    OWNED_PREFIXES = [PREFIX, LEGACY_PREFIX].freeze
+
+    BOOLEANS = %w[1 0 true false yes no on off].freeze
+
+    def boolean?(value) = BOOLEANS.include?(value.to_s.strip.downcase)
+
+    # Truthy per the engine's convention (telemetry/turn_timing agree). The single
+    # home for "is this env flag on?".
+    def truthy?(value) = %w[1 true yes on].include?(value.to_s.strip.downcase)
+
+    def present?(value) = !value.nil? && !value.to_s.strip.empty?
+
+    def spec(name:, type: :string, secret: false, required: false, enum: nil, description: "")
+      Spec.new(name: name, type: type, secret: secret, required: required, enum: enum, description: description)
+    end
+
+    # The engine's own keys. Deployment/app keys (DEEPSEEK_*, ACHEI_*, …) are NOT
+    # here — a root passes them as `extra:`.
+    DEFAULT = [
+      spec(name: "INSIKA_DB", type: :path, description: "SQLite path; durable config+state. Unset -> ephemeral memory."),
+      spec(name: "INSIKA_BIND", description: "Bind address for the transport server."),
+      spec(name: "INSIKA_PORT", type: :integer, description: "Port for the transport server."),
+      spec(name: "INSIKA_PUBLIC_URL", type: :url, description: "Public base URL (A2A agent card, links)."),
+      spec(name: "INSIKA_ENV", description: "Environment name shown in the Studio (falls back to RACK_ENV)."),
+      spec(name: "INSIKA_A2A_AGENT", description: "Agent id to expose over inbound A2A (opt-in)."),
+      spec(name: "INSIKA_A2A_REMOTES", type: :csv, description: "Comma-separated remote A2A endpoints."),
+      spec(name: "INSIKA_EGRESS_ALLOW_HTTP", type: :boolean, description: "Allow plain http egress from data-tools (default: https only)."),
+      spec(name: "INSIKA_EGRESS_ALLOW_PRIVATE", type: :boolean, description: "Allow egress to private/loopback ranges (SSRF guard off)."),
+      spec(name: "INSIKA_EGRESS_HOSTS", type: :csv, description: "Comma-separated host allowlist for data-tool egress."),
+      spec(name: "INSIKA_OTEL", type: :boolean, description: "Turn on OpenTelemetry export (opt-in)."),
+      spec(name: "INSIKA_MODEL_PRICING", description: "JSON rates table (USD per million tokens) for the estimated-cost attribute; unset -> no cost reported."),
+      spec(name: "INSIKA_TURN_TIMING", type: :boolean, description: "Emit per-turn TTFB breakdown in responses (opt-in, item 34)."),
+      spec(name: "INSIKA_SUBAGENT_DEPTH_CAP", type: :integer, description: "Max delegation depth in the subagent graph (default 5)."),
+      spec(name: "INSIKA_SUBAGENT_FANOUT_CAP", type: :integer, description: "Max parallel children in spawn_subagents (default 8)."),
+      spec(name: "INSIKA_CONFIG_STRICT", type: :boolean, description: "Refuse boot on any config finding instead of warning (item 23)."),
+      spec(name: "INSIKA_BOOT_ID", description: "Boot generation id shared by all workers of one container start; the recovery task sweep runs once per id (RFC-0016). Unset -> every boot sweeps."),
+      spec(name: "INSIKA_DRAIN_TIMEOUT", type: :integer, description: "Seconds a stopping worker waits for in-flight turns before abandoning them to the next boot's recovery (default 20, RFC-0016 A3)."),
+      spec(name: "INSIKA_ONBOARDING", type: :boolean, description: "Expose the public onboarding surface (/start.md, /models.json, /docs) in production (opt-in, item 20)."),
+      spec(name: "INSIKA_RELAY_TOKEN", secret: true, description: "Bearer the relay consumer sends us. Unset -> the relay channel is not mounted (RFC-0011 §6)."),
+      spec(name: "INSIKA_RELAY_DELIVER_URL", type: :url, description: "Consumer callback the relay POSTs each reply to."),
+      spec(name: "INSIKA_RELAY_DELIVER_TOKEN", secret: true, description: "Bearer the relay sends TO the consumer's callback (optional)."),
+      spec(name: "INSIKA_WIDGET_ORIGINS", type: :csv, description: "Exact-match origins allowed to embed the web widget. Unset -> the widget channel is not mounted (RFC-0011 §5)."),
+      spec(name: "INSIKA_WIDGET_AGENTS", type: :csv, description: "Agent ids a widget visitor may address. Unset -> the widget channel is not mounted."),
+      spec(name: "OPENCLAW_GATEWAY_TOKEN", secret: true, description: "Bearer for /v1 + /a2a (falls back to ADMIN_TOKEN)."),
+      spec(name: "OPENCLAW_AGENTS_DIR", type: :path, description: "Directory of OpenClaw-style agent packs."),
+      spec(name: "OPENCLAW_PLUGIN_DIR", type: :path, description: "Directory of plugins to load."),
+      spec(name: "ADMIN_TOKEN", secret: true, description: "Studio login token; unset -> /studio fail-closed."),
+      spec(name: "OTEL_SERVICE_NAME", description: "Service name for OTEL spans (default: insika).")
+    ].freeze
+
+    # -- dual-read (rename compat) -------------------------------------
+
+    # HARNESS_X -> INSIKA_X for the deprecated alias of a canonical key; nil if `name`
+    # is not an INSIKA_ key.
+    def legacy_alias(name)
+      s = name.to_s
+      s.start_with?(PREFIX) ? LEGACY_PREFIX + s[PREFIX.length..] : nil
+    end
+
+    # The current (canonical) name for any owned key: HARNESS_X -> INSIKA_X; an INSIKA_
+    # key or any non-owned key is returned unchanged.
+    def canonical(name)
+      s = name.to_s
+      s.start_with?(LEGACY_PREFIX) ? PREFIX + s[LEGACY_PREFIX.length..] : s
+    end
+
+    def legacy?(name) = name.to_s.start_with?(LEGACY_PREFIX)
+    def owned?(name) = OWNED_PREFIXES.any? { |p| name.to_s.start_with?(p) }
+
+    # Reads a canonical INSIKA_* key, falling back to the deprecated HARNESS_* alias
+    # (new name wins). For the self-contained readers that get an env hash directly and
+    # so never see `reconcile_legacy!`'s process-wide backfill. -> value | nil.
+    def read(canonical_name, env = ENV)
+      value = env[canonical_name]
+      return value if present?(value)
+
+      (legacy = legacy_alias(canonical_name)) ? env[legacy] : value
+    end
+
+    # BOOT backfill: copies every still-set HARNESS_* var to its INSIKA_* name (new name
+    # wins if both are set) so the process ENV speaks the new names before any read.
+    # Generic (not schema-bound) so plugin/deployment HARNESS_* keys migrate too. WARNS
+    # once with the migrated list. -> [migrated legacy names]. Idempotent.
+    def reconcile_legacy!(env = ENV, warn: method(:default_warn))
+      migrated = env.keys.map(&:to_s).select { |k| k.start_with?(LEGACY_PREFIX) }.sort.each_with_object([]) do |legacy, acc|
+        canonical = PREFIX + legacy[LEGACY_PREFIX.length..]
+        next if present?(env[canonical]) # the new name already wins
+        next if env[legacy].nil?
+
+        env[canonical] = env[legacy]
+        acc << legacy
+      end
+      unless migrated.empty?
+        warn.call("deprecation: #{migrated.join(', ')} — HARNESS_* env vars are renamed to INSIKA_*; " \
+                  "honored via the new names this run, please update your environment (legacy names removed in a future release)")
+      end
+      migrated
+    end
+
+    # -- validation ----------------------------------------------------
+
+    # -> [Finding]. `extra` = deployment/app specs to fold into the known set (and to
+    # widen unknown-key detection over their names). Never raises.
+    def validate(env = ENV, extra: [])
+      specs = index(DEFAULT + Array(extra))
+      findings = []
+
+      # VALUE + required checks over the KNOWN specs (owned or not — DEEPSEEK_API_KEY
+      # is not prefixed). Dual-read: the canonical name wins, the legacy alias is honored.
+      specs.each_value do |s|
+        legacy = legacy_alias(s.name)
+        set_name = if env.key?(s.name) then s.name
+                   elsif legacy && env.key?(legacy) then legacy
+                   end
+
+        if set_name.nil?
+          findings << Finding.new(key: s.name, kind: :missing_required, severity: :error,
+                                  message: "#{s.name} is required (unset)") if s.required?
+          next
+        end
+
+        msg = s.error_for(env[set_name])
+        findings << Finding.new(key: set_name, kind: :invalid, severity: :error, message: "#{set_name} #{msg}") if msg
+      end
+
+      # OWNED-PREFIX scan: a legacy alias of a known key is DEPRECATED (warn); any other
+      # owned key with no matching spec is UNKNOWN (a typo the runtime would ignore).
+      env.each_key do |raw|
+        key = raw.to_s
+        next unless owned?(key)
+
+        if legacy?(key) && specs.key?(canonical(key))
+          findings << Finding.new(key: key, kind: :deprecated, severity: :warn,
+                                  message: "#{key} is deprecated — rename to #{canonical(key)}")
+        elsif !specs.key?(canonical(key)) && !specs.key?(key)
+          findings << Finding.new(key: key, kind: :unknown, severity: :error,
+                                  message: "#{key} is not a known config key (typo? unknown key in an owned namespace)")
+        end
+      end
+
+      findings
+    end
+
+    # -> the specs the engine + a root know about (DEFAULT + extra), for `insika env`.
+    def known_specs(extra: []) = (DEFAULT + Array(extra)).sort_by(&:name)
+
+    # BOOT GATE. Validates the environment, WARNS every finding via `warn` (a callable
+    # taking a String), and RAISES ConfigError only when strict. `strict` defaults to
+    # the INSIKA_CONFIG_STRICT flag (HARNESS_CONFIG_STRICT still honored). -> [Finding]
+    # (also on the happy path). The root keeps booting on warnings (last-known-good).
+    def enforce!(env = ENV, extra: [], strict: nil, warn: method(:default_warn))
+      strict = truthy?(read("INSIKA_CONFIG_STRICT", env)) if strict.nil?
+      findings = validate(env, extra: extra)
+      findings.each { |f| warn.call("config: #{f.message}") }
+
+      errors = findings.select { |f| f.severity == :error }
+      raise Insika::ConfigError.new("strict config check refused boot", findings: errors) if strict && errors.any?
+
+      findings
+    end
+
+    def default_warn(message) = Kernel.warn("[config] #{message}")
+
+    # -- internal ------------------------------------------------------
+
+    def index(specs) = specs.each_with_object({}) { |s, acc| acc[s.name] = s }
+  end
+end

data/lib/insika/errors.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module Insika
+  # Single error taxonomy.
+  # General rule: an error becomes an event, a task has an explicit terminal
+  # state, a checkpoint is never corrupted.
+  class Error < StandardError; end
+
+  class ValidationError < Error; end  # Malformed Command -> HTTP 422, no Task created
+  class NotFoundError   < Error; end  # nonexistent session/task/agent -> HTTP 404
+
+  # Policy Engine denied -> :policy_denied event, task :failed
+  class PolicyDenied < Error
+    attr_reader :policy, :reason
+
+    def initialize(message = nil, policy: nil, reason: nil)
+      @policy = policy
+      @reason = reason
+      super(message || "policy #{policy} denied: #{reason}")
+    end
+  end
+
+  # A required provider failed -> task :failed
+  class ContextError < Error
+    attr_reader :provider
+
+    def initialize(message = nil, provider: nil)
+      @provider = provider
+      super(message || "provider #{provider} failed")
+    end
+  end
+
+  class ProviderError  < Error; end  # RubyLLM exhausted retries -> task :failed
+  class StoreError     < Error; end  # persistence backend failed -> task :failed
+  class CancelledError < Error; end  # cooperative cancellation -> task :cancelled
+
+  # Stage timeout overflow. Inside the Insika namespace this constant
+  # shadows the stdlib ::Timeout::Error — reference it without :: in here
+  # (the contract forbids stdlib Timeout.timeout anyway).
+  class TimeoutError < Error
+    attr_reader :stage
+
+    def initialize(message = nil, stage: nil)
+      @stage = stage
+      super(message || "timeout at stage #{stage}")
+    end
+  end
+
+  # Capability resolution failed -> task :failed at the
+  # :capability stage. Root of the subtree; it does NOT get its own event —
+  # it propagates through the existing :error/:task_failed events, same
+  # discipline as the taxonomy. Never raised directly (only its subclasses).
+  class CapabilityError < Error; end
+
+  # 0 candidates left after availability + deny.
+  class CapabilityUnavailable < CapabilityError
+    attr_reader :capability
+
+    def initialize(message = nil, capability: nil)
+      @capability = capability
+      super(message || "capability #{capability} has no available provider")
+    end
+  end
+
+  # >=2 candidates tied at the top (same priority AND same plugin) -> a
+  # configuration error, NEVER a silent choice. `candidates` carries enough
+  # for the operator to break the tie in the manifest.
+  class CapabilityAmbiguous < CapabilityError
+    attr_reader :capability, :candidates
+
+    def initialize(message = nil, capability: nil, candidates: [])
+      @capability = capability
+      @candidates = candidates
+      super(message || "capability #{capability} ambiguous between #{candidates.inspect}")
+    end
+  end
+
+  # Subagent graph integrity (RFC-0010 §4.4). Raised at DEFINITION-time
+  # (CreateAgent/UpdateAgent/boot) by SubagentGraph.validate! — a subagents
+  # allowlist that forms a cycle or exceeds the depth cap is a configuration
+  # error, never a runtime surprise. A ValidationError so the authoring Command
+  # fails cleanly (HTTP 422, no profile persisted).
+  class SubagentError < ValidationError; end
+
+  class SubagentCycleError < SubagentError
+    attr_reader :cycle
+
+    def initialize(message = nil, cycle: [])
+      @cycle = cycle
+      super(message || "subagent cycle detected: #{cycle.join(' -> ')}")
+    end
+  end
+
+  class SubagentDepthExceeded < SubagentError
+    attr_reader :depth, :cap
+
+    def initialize(message = nil, depth: nil, cap: nil)
+      @depth = depth
+      @cap = cap
+      super(message || "subagent depth #{depth} exceeds cap #{cap}")
+    end
+  end
+
+  # Workflow I/O contract violation (item 22 / §4.4). A workflow may declare an
+  # `input_schema` / `output_schema`; a value that does not conform is rejected.
+  # INPUT is validated SYNCHRONOUSLY (TriggerWorkflow) so it is a ValidationError
+  # -> HTTP 422, no run created. OUTPUT is validated inside the fiber after the
+  # workflow returns -> task :failed at the :workflow_schema stage. `errors` is the
+  # per-field detail (dry-schema-compatible `#errors.to_h`); `phase` is :input|:output.
+  class WorkflowSchemaError < ValidationError
+    attr_reader :phase, :errors
+
+    def initialize(message = nil, phase: nil, errors: {})
+      @phase = phase
+      @errors = errors || {}
+      detail = @errors.map { |field, msgs| "#{field}: #{Array(msgs).join(', ')}" }.join("; ")
+      base = message || "workflow #{phase} failed schema validation"
+      super(detail.empty? ? base : "#{base} (#{detail})")
+    end
+  end
+
+  # A channel could not hand a reply to its recipient (RFC-0011 §6.5). NOT a turn
+  # failure: the turn already completed and its answer is durable in the session —
+  # what failed is the delivery, which lives in the OutboxStore with its own status
+  # and its own bounded retry. Raised by a channel's `deliver` so the dispatcher can
+  # tell "the recipient refused" from "the engine has a bug".
+  class DeliveryError < Error; end
+
+  # Strict configuration violation (item 23 / §8.1 — OpenClaw's config discipline:
+  # "recusa boot com chave desconhecida, no silent config compat"). Raised by
+  # EnvSchema.enforce! at boot ONLY when strictness is on (INSIKA_CONFIG_STRICT) —
+  # by default a bad key WARNS and the engine still boots (last-known-good: a rotated
+  # env or a typo never takes the whole service down). `findings` carries the
+  # per-key detail (EnvSchema::Finding) so the operator can fix the config.
+  class ConfigError < Error
+    attr_reader :findings
+
+    def initialize(message = nil, findings: [])
+      @findings = findings || []
+      detail = @findings.map { |f| f.respond_to?(:message) ? f.message : f.to_s }.join("; ")
+      base = message || "strict config check failed"
+      super(detail.empty? ? base : "#{base}: #{detail}")
+    end
+  end
+end

data/lib/insika/evals/assertions.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+# D4 (RFC-0009): the PII/secret patterns live in the RUNTIME (single source of
+# truth) — the eval consumes them rather than keeping a divergent copy. Since the
+# module moved under `lib/`, `Safety::Detectors` is loaded by `insika.rb` before this
+# file; the explicit climb out of `evals/` that used to be here is gone.
+
+module Insika
+  module Evals
+    # What the runner extracts from ONE replayed conversation, entirely from the
+    # public SSE stream of POST /v1/responses (no store reads — the eval stays a
+    # client). The assertion engine is pure over this value, so it's unit-testable
+    # offline without a server.
+    #
+    #   output_text: the final assistant text (for content checks)
+    #   tool_calls:  [{ "name" =>, "status" => }] captured from the stream's tool events
+    #   error:       transport/turn error string, or nil on a clean turn
+    TurnResult = Struct.new(:output_text, :tool_calls, :error, keyword_init: true) do
+      def tool_names = Array(tool_calls).map { |t| (t["name"] || t[:name]).to_s }
+
+      # A tool call whose status is anything but a success ("ok"/2xx/"success").
+      def errored_tools
+        Array(tool_calls).reject { |t| Assertions.ok_status?(t["status"] || t[:status]) }
+      end
+    end
+
+    # A single check within a case (e.g. "tool:shipping_quote", "must_not:pii_leak").
+    Check = Struct.new(:name, :pass, :detail, keyword_init: true)
+
+    # The verdict for one golden case. `judge` (a Judge::Verdict) is attached AFTER
+    # the deterministic pass when the case has a rubric and a judge is configured;
+    # until then a rubric'd case is `judge_pending?` — it reads as "not fully
+    # evaluated", never a silent pass. A case passes only if the deterministic checks
+    # pass AND (there's no judge verdict OR it passed).
+    #
+    # `skipped` (a reason, nil = it ran) is the THIRD outcome (RFC-0014 §3.2): the
+    # deployment lacks something the case declared it needs, so there was nothing to
+    # assert. It is never a pass and never a failure — a suite of 40 cases where 12
+    # are skipped says something true, where 40 cases with 12 failures on capability
+    # grounds says nothing and gets ignored.
+    # `pairwise` (a Pairwise::Verdict, RFC-0014 §3.4) is attached when the case
+    # carries a `reference:` and a panel is configured. It DELIBERATELY does not enter
+    # `pass?`: "worse than the incumbent" is a judgement about a replacement decision,
+    # not a regression in the suite, and letting it fail a case would put an opinion
+    # about two conversations in the pre-merge gate.
+    CaseResult = Struct.new(:id, :agent, :checks, :error, :rubric, :judge, :skipped, :pairwise,
+                            keyword_init: true) do
+      def skipped? = !skipped.nil?
+      def pass? = !skipped? && error.nil? && checks.all?(&:pass) && (judge.nil? || judge.pass)
+      def failures = checks.reject(&:pass)
+      # Has a rubric to score but no verdict yet (judge disabled / not run). A skipped
+      # case is not pending anything — nobody is going to judge a turn that never ran.
+      def judge_pending? = !skipped? && !rubric.to_s.strip.empty? && judge.nil?
+    end
+
+    # Deterministic (Fase A) evaluation — cheap, zero-token, zero-flakiness. It's the
+    # layer that catches the gross regressions (a tool stopped being called, a secret
+    # leaked, the turn errored). Subjective scoring is the LLM-judge in Fase B.
+    module Assertions
+      # Named negative detectors for `must_not` now live in the runtime (D4). Kept as
+      # an alias so any external reference to Evals::Assertions::PII_DETECTORS still
+      # resolves; the values ARE the runtime's, never a fork.
+      PII_DETECTORS = Insika::Safety::Detectors::PII
+
+      # HOW MUCH THE AGENT SHOULD ASK BEFORE ACTING (RFC-0014 §3.3). Declared per
+      # case because it is a per-STORE decision, not a universal rule: sometimes the
+      # agent should establish the objective before searching ("energia, treino ou
+      # sono?" — Ocean Drop does this well), and sometimes asking again is the
+      # failure and it should just search. A global assertion would be wrong half
+      # the time; the judge is TOLD the policy (Judge#build_prompt) and this layer
+      # checks the half that needs no reader.
+      #
+      # Each rule is stated as the CUSTOMER-VISIBLE fact it checks. RFC-0014 phrased
+      # this as "questions before the first tool call", written before P19: text a
+      # model emits before calling a tool never reaches the customer now (it rides
+      # `:intermediate`), and the eval is a client of `/v1/responses`, so what it can
+      # observe per turn is the published answer plus the tools that turn called.
+      # That is also the honest scope — a question nobody received is not a question.
+      POLICIES = {
+        # "UMA PERGUNTA POR VEZ" — the rule Insika broke twice under a 28 KB prompt.
+        "ask_once" => "at most one question per reply",
+        # Establish the objective before acting on a vague opener.
+        "investigate_first" => "asks before calling a tool, on the first turn",
+        # Act on the first plausible reading; refine after.
+        "act_fast" => "calls a tool on the first turn instead of asking"
+      }.freeze
+
+      module_function
+
+      # WHAT THIS DEPLOYMENT LACKS for the case to be worth running (RFC-0014 §3.2).
+      # -> [reason]; empty = run it.
+      #
+      # `available` is the deployment's answer for this agent:
+      #   { "tools" => [names] | nil, "capabilities" => [names] }
+      # `tools` nil means an OPEN allowlist — the agent may call every registered tool,
+      # so no tool requirement can be judged missing and the case runs. That is the
+      # deliberate reading: "I could not rule it out" must not become a skip, or a
+      # permissive agent would quietly stop being tested.
+      def unmet_requirements(golden, available)
+        tools = available["tools"]
+        declared = Array(available["capabilities"]).map(&:to_s)
+
+        missing_tools = tools.nil? ? [] : golden.required_tools - Array(tools).map(&:to_s)
+        missing_caps = golden.required_capabilities - declared
+
+        reasons = []
+        reasons << "tool not available: #{missing_tools.join(', ')}" unless missing_tools.empty?
+        reasons << "capability not declared: #{missing_caps.join(', ')}" unless missing_caps.empty?
+        reasons
+      end
+
+      # The case did not run and MUST NOT read as either a pass or a failure.
+      def skip(golden, reason)
+        CaseResult.new(id: golden.id, agent: golden.agent, checks: [], error: nil,
+                       rubric: nil, judge: nil, skipped: reason)
+      end
+
+      # A tool status counts as success when it's blank/"ok"/"success" or a 2xx code.
+      def ok_status?(status)
+        return true if status.nil?
+
+        s = status.to_s.strip.downcase
+        return true if s.empty? || %w[ok success succeeded done].include?(s)
+
+        code = Integer(s, exception: false)
+        code ? code.between?(200, 299) : false
+      end
+
+      # Golden + TurnResult -> CaseResult. A turn that failed to run yields a single
+      # failing check (there's nothing to assert on a turn that never produced output).
+      #
+      # `turns` is every turn of the conversation, in order; `result` is the last one
+      # (what the tool/content assertions have always run on). The policy checks need
+      # all of them — "one question per reply" is a rule about every reply, and the
+      # violation that motivated this was on the FIRST turn. Defaults to the single
+      # result so existing callers keep working.
+      def evaluate(golden, result, turns: nil)
+        if result.error
+          return CaseResult.new(id: golden.id, agent: golden.agent, error: result.error, rubric: nil, judge: nil,
+                                checks: [Check.new(name: "turn", pass: false, detail: "turn error: #{result.error}")])
+        end
+
+        # NOT `Array(turns)`: TurnResult is a Struct, so Array() would explode a single
+        # one into its members and hand the policy checks three strings.
+        conversation = turns.nil? || turns.empty? ? [result] : turns
+        checks = tool_checks(golden, result) + must_not_checks(golden, result) +
+                 policy_checks(golden, conversation)
+        CaseResult.new(id: golden.id, agent: golden.agent, error: nil, checks: checks,
+                       rubric: golden.rubric, judge: nil)
+      end
+
+      # Each REQUIRED expected tool must appear in the turn's tool calls. Optional
+      # ("name?") tools are informational — present or not, they never fail.
+      def tool_checks(golden, result)
+        names = result.tool_names
+        golden.tools_called.filter_map do |t|
+          next if t[:optional]
+
+          present = names.include?(t[:name])
+          Check.new(name: "tool:#{t[:name]}", pass: present,
+                    detail: present ? "called" : "expected but not called (saw: #{names.join(', ')})")
+        end
+      end
+
+      # `must_not` detectors. "tool_error" is special (inspects statuses); the rest
+      # are content detectors over the output text.
+      def must_not_checks(golden, result)
+        golden.must_not.map do |name|
+          if name == "tool_error"
+            bad = result.errored_tools
+            Check.new(name: "must_not:tool_error", pass: bad.empty?,
+                      detail: bad.empty? ? "no tool errors" : "errored: #{bad.map { |t| t['name'] || t[:name] }.join(', ')}")
+          else
+            hit = detect(name, result.output_text.to_s)
+            Check.new(name: "must_not:#{name}", pass: hit.nil?,
+                      detail: hit ? "matched #{hit.inspect}" : "clean")
+          end
+        end
+      end
+
+      # The declared `policy`, checked deterministically over the conversation. No
+      # policy -> no check (and nothing to explain in the report).
+      def policy_checks(golden, turns)
+        name = golden.policy
+        return [] if name.nil?
+
+        # Exhaustive on purpose: a policy added to POLICIES without a rule here would
+        # otherwise fall into whichever branch was last and check the wrong thing.
+        pass, detail = case name
+                       when "ask_once" then ask_once(turns)
+                       when "investigate_first" then investigate_first(turns.first)
+                       when "act_fast" then act_fast(turns.first)
+                       else raise ArgumentError, "policy #{name.inspect} has no rule"
+                       end
+        [Check.new(name: "policy:#{name}", pass: pass, detail: detail)]
+      end
+
+      # Every reply asks at most one question. Reported with the offending turn and
+      # the reply itself — "2 questions" alone sends the reader digging.
+      def ask_once(turns)
+        offender = turns.each_with_index.find { |t, _| count_questions(t.output_text) > 1 }
+        return [true, "at most one question per reply"] unless offender
+
+        turn, i = offender
+        [false, "turn #{i + 1} asked #{count_questions(turn.output_text)} questions: " \
+                "#{turn.output_text.to_s.strip[0, 160].inspect}"]
+      end
+
+      def investigate_first(turn)
+        return [false, "no turn to check"] if turn.nil?
+
+        tools = turn.tool_names
+        return [false, "called #{tools.join(', ')} before asking anything"] unless tools.empty?
+        return [false, "answered without asking: #{turn.output_text.to_s.strip[0, 160].inspect}"] if
+          count_questions(turn.output_text).zero?
+
+        [true, "asked before acting"]
+      end
+
+      def act_fast(turn)
+        return [false, "no turn to check"] if turn.nil?
+
+        tools = turn.tool_names
+        return [true, "acted: called #{tools.join(', ')}"] unless tools.empty?
+
+        [false, "asked instead of acting: #{turn.output_text.to_s.strip[0, 160].inspect}"]
+      end
+
+      # Questions in ONE reply. Deliberately crude and deliberately documented: a run
+      # of "?" counts once ("já pensou??" is one question), and URLs are dropped first
+      # so a tracking link's query string is not read as the agent asking something.
+      # It is a policy signal, not grammar — and it already caught a real violation
+      # ("é pra você ou tá pensando em presentear alguém? E qual seu tamanho?").
+      def count_questions(text)
+        text.to_s.gsub(%r{https?://\S+}, " ").scan(/\?+/).size
+      end
+
+      # Runs a named detector over the text. "pii_leak" = union of all PII detectors;
+      # otherwise a single named pattern. Delegates to the runtime's single source
+      # (D4) — which itself fails loud on an unknown name (a typo'd assertion must not
+      # silently pass).
+      def detect(name, text)
+        Insika::Safety::Detectors.detect(name, text)
+      end
+    end
+  end
+end