insika 0.2.0 → 0.3.0

data/lib/insika/dsl/runtime.rb

@@ -178,7 +178,8 @@ module Insika
           guardrails: c[:guardrails], context_providers: context_providers(spine, c),
           edge_limiter: c[:edge_limiter],
           executor_extra: { settings_store: c[:settings_store], tool_trace_store: c[:tool_trace_store],
-                            context_trace_store: c[:context_trace_store], llm: @llm }
+                            context_trace_store: c[:context_trace_store],
+                            cache_series_store: c[:cache_series_store], llm: @llm }
         )
         register_authoring_commands(graph, c)
         register_workflows(graph)
@@ -229,6 +230,8 @@ module Insika
           mcp_store: Insika::McpStore.new(config_store: config_store),
           tool_trace_store: Insika::ToolTraceStore.new(store: backend),
           context_trace_store: Insika::ContextTraceStore.new(store: backend),
+          # the per-AGENT cache-hit series (the Studio agent-detail card).
+          cache_series_store: Insika::CacheSeriesStore.new(store: backend),
           tool_registry: tool_registry,
           tool_catalog: Insika::ToolCatalog.new(tool_registry: tool_registry),
           skill_catalog: Insika::SkillCatalog.new([], store: skill_store),
@@ -267,6 +270,7 @@ module Insika
         bus = graph.bus
         es = graph.event_stream
         mem = graph.memory_store
+        audit = graph.memory_audit_store
         bus.register(:create_agent, Insika::Commands::CreateAgent.new(profile_source: c[:profile_source], event_stream: es))
         bus.register(:update_agent, Insika::Commands::UpdateAgent.new(profile_source: c[:profile_source], event_stream: es))
         bus.register(:delete_agent, Insika::Commands::DeleteAgent.new(profile_source: c[:profile_source], event_stream: es))
@@ -276,9 +280,11 @@ module Insika
         bus.register(:restore_agent_file, Insika::Commands::RestoreAgentFile.new(profile_source: c[:profile_source], agent_file_store: c[:agent_file_store], event_stream: es))
         bus.register(:write_skill, Insika::Commands::WriteSkill.new(skill_store: c[:skill_store], skill_catalog: c[:skill_catalog], event_stream: es))
         bus.register(:set_skill_agents, Insika::Commands::SetSkillAgents.new(profile_source: c[:profile_source], event_stream: es))
-        bus.register(:memory_put_fact, Insika::Commands::MemoryPutFact.new(memory_store: mem, event_stream: es))
-        bus.register(:memory_forget_fact, Insika::Commands::MemoryForgetFact.new(memory_store: mem, event_stream: es))
+        bus.register(:memory_put_fact, Insika::Commands::MemoryPutFact.new(memory_store: mem, event_stream: es, audit_store: audit))
+        bus.register(:memory_forget_fact, Insika::Commands::MemoryForgetFact.new(memory_store: mem, event_stream: es, audit_store: audit))
         bus.register(:memory_add_note, Insika::Commands::MemoryAddNote.new(memory_store: mem, event_stream: es))
+        # the LGPD access right — the Studio Customers drill exports.
+        bus.register(:export_customer_memory, Insika::Commands::ExportCustomerMemory.new(memory_store: mem, event_stream: es))
         bus.register(:update_settings, Insika::Commands::UpdateSettings.new(settings_store: c[:settings_store], event_stream: es))
         bus.register(:upsert_llm_provider, Insika::Commands::UpsertLLMProvider.new(provider_store: c[:provider_store], configurator: c[:configurator], event_stream: es))
         bus.register(:delete_llm_provider, Insika::Commands::DeleteLLMProvider.new(provider_store: c[:provider_store], configurator: c[:configurator], event_stream: es))

data/lib/insika/dsl/server_boot.rb

@@ -31,6 +31,11 @@ module Insika
       end
 
       def run
+        # The boot refusal (shadow + no criterion) lives in the AppBuilder; run it
+        # BEFORE the Studio is configured so the criterion the Studio folds is the
+        # same object the delivery path stamps pairs with.
+        @builder.channels?
+        register_parity_commands
         configure_studio
         dispatch = Rack::URLMap.new("/studio" => Studio::App, "/" => @builder.app)
         endpoint = Async::HTTP::Endpoint.parse("http://#{@host}:#{@port}")
@@ -56,6 +61,23 @@ module Insika
       def workflows? = @builder.workflows?
       def channels? = @builder.channels?
 
+      # The parity page renders whenever a shadow channel exists, so the judge
+      # button must reach a registered command — the deployment bus registers the
+      # same one (config/deployment.rb); a page that answers "unknown command"
+      # would make this root a second-class citizen. Registered only when the
+      # criterion loaded (a command without one would be a fake judge).
+      def register_parity_commands
+        criterion = @builder.criterion
+        return unless criterion
+
+        @graph.bus.register(:judge_shadow_pairs,
+                            Insika::Commands::JudgeShadowPairs.new(
+                              shadow_pairs: @graph.shadow_pair_store,
+                              settings_store: @rt.component(:settings_store),
+                              criterion: criterion, event_stream: @graph.event_stream
+                            ))
+      end
+
       def configure_studio
         Studio::App.configure(
           command_bus: @graph.bus, profile_source: @graph.profiles,
@@ -64,16 +86,63 @@ module Insika
           agent_file_store: @rt.component(:agent_file_store), skill_store: @rt.component(:skill_store),
           skill_catalog: @graph.skill_catalog, tool_catalog: @graph.tool_catalog,
           tool_store: @rt.component(:tool_store), memory_store: @graph.memory_store,
+          # the Customers drill renders the audit lines.
+          memory_audit_store: @graph.memory_audit_store,
           session_store: @graph.session_store,
           settings_store: @rt.component(:settings_store), llm_provider_store: @rt.component(:provider_store),
           mcp_store: @rt.component(:mcp_store), system_file_store: @rt.component(:system_file_store),
           tool_trace_store: @rt.component(:tool_trace_store),
           context_trace_store: @rt.component(:context_trace_store),
+          # the per-agent cache-hit series (agent-detail card).
+          cache_series_store: @rt.component(:cache_series_store),
           task_store: @graph.task_store, checkpoint_store: @graph.checkpoint_store,
-          pending_action_store: @graph.pending_action_store
+          pending_action_store: @graph.pending_action_store,
+          # WS7: the agents-grid scorecard reads the outcome store.
+          outcome_store: @graph.outcome_store,
+          # the outcome-funnel page reads the fold's cells and the
+          # BudgetLedger's current counters (D6); the only mutation — the
+          # baseline freeze — dispatches :freeze_funnel_baseline on the bus.
+          funnel_store: @graph.funnel_store,
+          budget_ledger: @graph.budget_ledger,
+          # the parity page (only rendered when a shadow channel exists —
+          # the nav row keys off the registry).
+          shadow_pair_store: @graph.shadow_pair_store,
+          parity_criterion: @builder.criterion,
+          channel_registry: @graph.channel_registry,
+          # the Follow-ups page reads the stores directly;
+          # its only mutations (cancel, force-revoke) dispatch bus commands.
+          followup_store: @graph.followup_store,
+          contact_store: @graph.contact_store,
+          # the Facts (wiki) page reads the proposal store
+          # directly; its mutations dispatch :resolve_proposal on the bus.
+          proposal_store: @graph.proposal_store,
+          # the Harvest page reads the harvest store + the two
+          # pre-registered artifacts directly; its mutations dispatch the
+          # harvest bus commands. The criterion/negative list load best-effort
+          # (nil = the page renders the refusal/empty states).
+          harvest_store: @graph.harvest_store,
+          harvest_criterion: harvest_criterion,
+          negative_list: harvest_negative_list
         )
       end
 
+      # The frozen criterion — best-effort at boot: a bare install
+      # without the env var renders the ruler's hole instead of
+      # crashing the Studio.
+      def harvest_criterion
+        path = Insika::EnvSchema.read("INSIKA_HARVEST_CRITERION")
+        path && Insika::Harvest::Criterion.load(path)
+      rescue Insika::ConfigError, Insika::ValidationError
+        nil
+      end
+
+      def harvest_negative_list
+        path = Insika::EnvSchema.read("INSIKA_HARVEST_NEGATIVE")
+        path && Insika::Harvest::NegativeList.parse(File.read(path))
+      rescue Errno::ENOENT
+        nil
+      end
+
       def persistence
         @graph.durable? ? "durable (sqlite)" : "ephemeral (memory)"
       end

data/lib/insika/dsl.rb

@@ -215,6 +215,46 @@ module Insika
       #   budget daily: 100_000, monthly: 2_000_000, soft: false
       def budget(hash) = (@config[:budget] ||= {}).merge!(hash.transform_keys(&:to_s))
 
+      # The outcome funnel declaration: the store's stage vocabulary
+      # as pack data — the engine folds WS7 outcome kinds into the DECLARED
+      # stages, and never hard-codes one itself. Merges, so repeated calls
+      # accumulate (like budget).
+      #   funnel stages: %w[greeted qualified cart paid],
+      #          advance_on: { "pix_paid" => "paid", "abandoned_cart" => "cart" },
+      #          primary: "paid", attribution_window: "72h"
+      def funnel(hash) = (@config[:funnel] ||= {}).merge!(hash.transform_keys(&:to_s))
+
+      # The follow-up declaration: the agent may book a follow-up
+      # with a customer at a future time (`schedule` tool); the engine fires the
+      # synthetic turn and enforces the policy (quiet hours, max frequency,
+      # cancellation keywords, silence detection) at fire time. Pack data —
+      # merges, so repeated calls accumulate (like budget).
+      #   followup arm: "schedule",
+      #            policy: { quiet_hours: { timezone: "America/Sao_Paulo",
+      #                                     start: "21:30", end: "09:00" },
+      #                      max_frequency: "2/24h",
+      #                      cancel_keywords: ["não quero mais contato"],
+      #                      silence_after_sends: 3 }
+      def followup(hash) = (@config[:followup] ||= {}).merge!(hash.transform_keys(&:to_s))
+
+      # The session-distillation declaration: what counts as a fact
+      # for THIS store, distilled from finished customer conversations. Pack
+      # data — merges, so repeated calls accumulate (like budget). `prompt` and
+      # `model` are pack-authored keys the DSL passes through.
+      #   distill enabled: true, idle_hours: 6, max_proposals: 10
+      def distill(hash) = (@config[:distill] ||= {}).merge!(hash.transform_keys(&:to_s))
+
+      # The gated-harvest declaration: the engine may read this
+      # agent's finished traffic and propose SKILLS for the store's playbook —
+      # through the negative list, the grounding filter and the double gate,
+      # never applied automatically. Pack data — merges, so repeated calls
+      # accumulate (like budget). `prompt`/`model` are pack-authored keys the
+      # DSL passes through.
+      #   harvest enabled: true,
+      #           negative_list: [ { rule: "no-competitor-prices", pattern: "concorrente" } ],
+      #           miner: { model: "deepseek-v4-flash", window: { last_sessions: 200 } }
+      def harvest(hash) = (@config[:harvest] ||= {}).merge!(hash.transform_keys(&:to_s))
+
       # Provider-interaction reliability, as DATA (WS3): retries + exponential
       # backoff on transient failures, a fallback model chain (mid-turn
       # rotation), and a circuit breaker per (tenant, provider/model) that
@@ -226,17 +266,51 @@ module Insika
         (@config[:reliability] ||= {}).merge!(hash.transform_keys(&:to_s))
       end
 
-      # Operator alert delivery (WS6): POST this agent's budget_warning /
-      # breaker_open / delivery_failed events to the webhook, as JSON.
-      #   alerts webhook: "https://ops.example.com/insika-alerts"
+# Operator alert delivery (WS6): POST this agent's budget_warning /
+      # breaker_open / delivery_failed events to the webhook as JSON.
       def alerts(hash) = (@config[:alerts] ||= {}).merge!(hash.transform_keys(&:to_s))
 
+      # Intent routing (WS4): classify each turn's message into one route with a
+      # cheap model BEFORE the ask. A Hash: route name -> description (or a Hash
+      # with description/delegate/stuck/message), plus the reserved keys
+      # "default" (the deterministic fallback) and "model"/"provider" (the cheap
+      # classifier). The classifier prompt is generated — data only.
+      #   routes "shopping" => "the customer wants to browse products",
+      #          "order"    => { "description" => "asks about an existing order",
+      #                          "delegate" => "order-agent" },
+      #          "human"    => { "description" => "the customer asks for a person",
+      #                          "stuck" => true },
+      #          "default"  => "shopping", "model" => "deepseek-v4-flash"
+      def routes(hash) = (@config[:routes] ||= {}).merge!(hash.transform_keys(&:to_s))
+
       # The agent may signal it cannot proceed (WS5): when on, the model
       # can call `signal_stuck`, which ends the turn with `outcome: :stuck` + a final
       # message + a `:turn_stuck` event. What "stuck" means is the consumer's call.
       #   stuck_signal true
       def stuck_signal(on = true) = @config[:stuck_signal] = on
 
+      # The per-session working-state schema this agent keeps and asks for
+      # a flat list of field names. [] = off (no provider output,
+      # no update_briefing/set_next_step tools).
+      #   briefing_fields "size", "budget", "delivery_day"
+      def briefing_fields(*names)
+        @config[:briefing_fields] = names.flatten.map(&:to_s)
+      end
+
+      # Generated-media output policy (WS9, saída): the media kinds this
+      # agent MAY generate as turn outputs, with per-kind config. The other
+      # half of the gate is the CHANNEL's: the request must declare the
+      # matching capability for the tools to exist at all.
+      #   outputs image: { model: "gpt-image-1", size: "1024x1024" },
+      #           tts:   { model: "tts-1", voice: "alloy" }
+      def outputs(hash) = (@config[:outputs] ||= {}).merge!(hash.transform_keys(&:to_s))
+
+      # The engine's "Tool discipline" block in the system prompt (retry a
+      # weak/empty tool result with a different approach before giving up).
+      # ON by default — this setter exists to turn it OFF:
+      #   tool_persistence false
+      def tool_persistence(on = true) = @config[:tool_persistence] = on
+
       # Mechanical tool-result dedupe in the replayed history
       # (no-LLM compaction, apt for bloated transcripts). CHANGES WHAT THE MODEL
       # SEES: repeated identical tool results collapse to a back-reference.
@@ -250,6 +324,12 @@ module Insika
       #              responses: { "injection" => "I can't help with that." }
       def guardrails(hash) = (@config[:guardrails] ||= {}).merge!(hash.transform_keys(&:to_s))
 
+      # Evidence-grounding policy: the pack declares how the engine
+      # polices product claims against the evidence ledger. Same
+      # config-over-code shape as `guardrails`; absent = off (parity).
+      #   grounding mode: :flag, matcher: { sku: '\b[A-Z]{2,4}\d{4,8}\b' }
+      def grounding(hash = {}) = (@config[:grounding] ||= {}).merge!(hash.transform_keys(&:to_s))
+
       # Refinement — how the agent's own instruction files may be
       # improved from real traffic. Same config-over-code shape as `guardrails`;
       # omitting it entirely leaves the agent report-only (writes nothing).

data/lib/insika/edge_limiter.rb

@@ -65,8 +65,14 @@ module Insika
       # the rate-limit reply exactly when the window is saturated. Entry checks
       # are skipped; the turn's usage still lands on the ledger below.
       resumed = state.resumed
-
-      if !resumed && (limit = positive(limits.key?(:chat_rate_limit) ? limits[:chat_rate_limit] : edge["chat_rate_limit"]))
+      # a SCHEDULED turn (the FollowupEngine's kick) skips the
+      # ENTRY checks exactly like a resume — a follow-up that trips the token
+      # ceiling must not receive the rate-limit REPLY (the customer agreed to
+      # this message; the volume control is the follow-up policy, not the flood
+      # rail). The turn still runs and its usage still lands on the ledger.
+      scheduled = scheduled_turn?(state)
+
+      if !resumed && !scheduled && (limit = positive(limits.key?(:chat_rate_limit) ? limits[:chat_rate_limit] : edge["chat_rate_limit"]))
         breach = check_chat_rate(state, limit, edge)
         return block(state, edge, **breach) if breach
       end
@@ -75,7 +81,7 @@ module Insika
       # `"chat_rate_limit": null`) reads as OFF for that agent, not "inherit".
       if (ceiling = positive(limits.key?(:agent_token_ceiling) ? limits[:agent_token_ceiling] : edge["agent_token_ceiling"]))
         token_window = positive(edge["agent_token_window"]) || DEFAULT_TOKEN_WINDOW
-        unless resumed
+        unless resumed || scheduled
           spent = @ledger.count(TOKENS_KIND, state.profile.id.to_s, window: token_window)
           if spent >= ceiling
             return block(state, edge, category: :token_ceiling,
@@ -90,9 +96,11 @@ module Insika
       # typed error (never a customer-facing reply); the alert_at warning and
       # the SOFT over-cap both warn once per window + inject a context note.
       # A resumed turn (crash/pause replay) was already admitted: it is never
-      # refused twice — its spend still lands on the ledger below.
+      # refused twice — its spend still lands on the ledger below. A scheduled
+      # turn  rides the same rule: the follow-up policy is the
+      # volume control, not the budget wall.
       budget_on = budget_configured?(state)
-      budget_enforce(state) unless resumed
+      budget_enforce(state) unless resumed || scheduled
 
       result = begin
         nxt.call(state)
@@ -110,6 +118,14 @@ module Insika
 
     private
 
+    # is this turn the FollowupEngine's synthetic kick? The
+    # command type is stamped by the engine only — a consumer cannot send it
+    # (the SendMessage edge refuses the spelling, C8).
+    def scheduled_turn?(state)
+      command = state.respond_to?(:task) && state.task&.command
+      command.is_a?(Hash) && command["type"].to_s == "scheduled_followup"
+    end
+
     # One KV get per turn (same order of cost as the guardrail's config read);
     # no SettingsStore in the wiring -> per-agent limits only.
     def platform_edge
@@ -231,12 +247,17 @@ module Insika
       return if @budget_ledger.mark_alert(tenant: tenant, agent: agent, window: w[:window],
                                           level: level, now: now)
 
+      # `tenant` on the META too, not only in the payload: the tenant-scoped
+      # /v1/events subscription filters on meta[:tenant] and is fail-closed, so
+      # a warning about the tenant's OWN budget never reached the tenant.
+      meta = { task_id: state.task&.id, session_id: state.task&.session_id,
+               at: Time.now.utc.iso8601 }
+      meta[:tenant] = tenant unless tenant.nil?
       @event_stream&.emit(Insika::Event.new(
                             type: :budget_warning,
                             data: { agent: agent, tenant: tenant, window: w[:window],
                                     spent: spent, cap: w[:cap], level: level },
-                            meta: { task_id: state.task&.id, session_id: state.task&.session_id,
-                                    at: Time.now.utc.iso8601 }
+                            meta: meta
                           ))
     end
 

data/lib/insika/env_schema.rb

@@ -102,9 +102,9 @@ module Insika
       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_HTTP", type: :boolean, description: "Allow plain http egress from data-tools, channel callbacks and media fetches (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_EGRESS_HOSTS", type: :csv, description: "Comma-separated host allowlist for data-tool egress (media fetches are NOT pinned by it)."),
       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)."),
@@ -115,11 +115,18 @@ module Insika
       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)."),
       spec(name: "INSIKA_TICK_INTERVAL", type: :integer, description: "Seconds between tick passes (outbox drain + stale recovery sweep). Default 60; 0 disables."),
       spec(name: "INSIKA_TICK_STALE_AFTER", type: :integer, description: "Seconds a :queued/:running task must sit untouched before the tick sweeps it (default 900). Must exceed the largest turn_timeout of the deployment."),
+      spec(name: "INSIKA_STT_MODEL", description: "Model used to transcribe audio message parts (WS9). Unset -> RubyLLM's default transcription model."),
+      spec(name: "INSIKA_STT_LANGUAGE", description: "Language hint for the transcription of audio message parts (WS9)."),
       spec(name: "INSIKA_TENANCY", enum: %w[single_tenant multi_tenant], description: "single_tenant (default: one operator credential) or multi_tenant (per-tenant + operator tokens resolved from the store)."),
       spec(name: "INSIKA_ONBOARDING", type: :boolean, description: "Expose the public onboarding surface (/start.md, /models.json, /docs) in production (opt-in)."),
       spec(name: "INSIKA_RELAY_TOKEN", secret: true, description: "Bearer the relay consumer sends us. Unset -> the relay channel is not mounted."),
       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_RELAY_SHADOW", type: :boolean, description: "Shadow mode: the relay records replies instead of delivering them."),
+      spec(name: "INSIKA_RELAY_DELIVERY", type: :enum, enum: %w[at_end progressive], description: "How the relay flushes the outbox: at_end (one POST) or progressive (one POST per balloon). Unset -> at_end."),
+      spec(name: "INSIKA_PARITY_CRITERION", type: :path, description: "The frozen parity criterion file (required in shadow mode)."),
+      spec(name: "INSIKA_HARVEST_CRITERION", type: :path, description: "The frozen harvest conversion criterion file (strict-loaded before any promotion)."),
+      spec(name: "INSIKA_HARVEST_NEGATIVE", type: :path, description: "The negative-list seed file the harvest CLI imports into agent profiles."),
       spec(name: "INSIKA_WIDGET_ORIGINS", type: :csv, description: "Exact-match origins allowed to embed the web widget. Unset -> the widget channel is not mounted."),
       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)."),

data/lib/insika/errors.rb

@@ -182,6 +182,17 @@ module Insika
   # tell "the recipient refused" from "the engine has a bug".
   class DeliveryError < Error; end
 
+  # WS4 routing failed: a route's delegate agent is not configured, or its turn
+  # failed. An operator/config error — the envelope names the :routing stage
+  # instead of swallowing it as :unknown.
+  class RoutingError < Error; end
+
+  # WS9 media failed: an audio part could not be fetched or transcribed, an
+  # image attachment could not be built, or a media URL was egress-blocked. A
+  # customer's voice message that never entered the turn must not be silently
+  # dropped — the :media stage names it.
+  class MediaError < Error; end
+
   # Strict configuration violation (— 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) —

data/lib/insika/evals/assertions.rb

@@ -59,8 +59,9 @@ module Insika
     module Assertions
       # Named negative detectors for `must_not` now live in the runtime. 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
+      # resolves; the values ARE the runtime's, never a fork. the
+      # pattern data moved to the corpus, still under the same Safety umbrella.
+      PII_DETECTORS = Insika::Safety::Corpus::PII
 
       # HOW MUCH THE AGENT SHOULD ASK BEFORE ACTING. Declared per
       # case because it is a per-STORE decision, not a universal rule: sometimes the

data/lib/insika/evals/pairwise.rb

@@ -60,12 +60,19 @@ module Insika
       def compare(golden:, turns:)
         return nil unless golden.reference?
 
-        ours = Pairwise.transcript(golden.user_turns, turns)
-        theirs = Pairwise.reference_transcript(golden.reference_messages)
-        return nil if ours.strip.empty?
+        compare_texts(ours: Pairwise.transcript(golden.user_turns, turns),
+                      theirs: Pairwise.reference_transcript(golden.reference_messages),
+                      vs: golden.human_assisted? ? "human-assisted" : "agent")
+      end
+
+      # two transcripts, no golden — the shadow seam. The judge is
+      # the SAME object with the SAME prompt, so shadow pairs and golden cases are
+      # graded by one rule. An empty side returns nil (never a verdict against an
+      # empty string — that was a bug in the golden path until this seam landed).
+      def compare_texts(ours:, theirs:, vs: "agent")
+        return nil if ours.to_s.strip.empty? || theirs.to_s.strip.empty?
 
-        panel = @asks.map { |ask| judge_once(ask, ours, theirs) }
-        combine(panel, vs: golden.human_assisted? ? "human-assisted" : "agent")
+        combine(@asks.map { |ask| judge_once(ask, ours, theirs) }, vs: vs)
       end
 
       # The replayed conversation as the judge reads it: the user turns we sent,
@@ -81,8 +88,13 @@ module Insika
       # is the conversation as the customer received it, and telling it "a person wrote
       # this one" is an invitation to grade the author instead. The fact is carried to
       # the READER as `vs: human-assisted` instead, which is where it changes a decision.
+      # A reference with no text at all returns "" — the caller's empty guard then
+      # refuses instead of judging against an empty string .
       def self.reference_transcript(messages)
-        Array(messages).map do |m|
+        msgs = Array(messages)
+        return "" if msgs.all? { |m| m["text"].to_s.strip.empty? }
+
+        msgs.map do |m|
           speaker = m["role"].to_s == "user" ? "customer" : "assistant"
           "#{speaker}: #{m['text'].to_s.strip}"
         end.join("\n")

data/lib/insika/evidence.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Insika
+  #   — the evidence contract (engine half).
+  #
+  # A tool DECLARES `evidence` in its manifest; the engine then does BOTH jobs
+  # from the same declaration: strips the result down to `{items: [{id, line}]}`
+  # for the model (the lean envelope), and appends every `id` to the session
+  # evidence ledger. No second flag, no "lean but not evidence" mode — a
+  # half-configuration cannot exist, which is what keeps "no claim without a
+  # tool ID" a tautology at the envelope instead of a convention.
+  #
+  # Everything here is pure Ruby, no IO: the ToolEnvelope calls it after the real
+  # tool returns. It does NOT write anything — the ledger write is the envelope's,
+  # via the state.
+  module Evidence
+    # The declaration (D1/C2.1). Parses three authorable shapes:
+    #
+    #   { "evidence": "products" }                             // bare kind
+    #   { "evidence": { "kind": "products" } }                 // full form
+    #   { "evidence": { "kind": "products",
+    #                   "items": "results",
+    #                   "attachments": "cards" } }             // non-default paths
+    #
+    # `kind` is the PILOT PACK's value, never a gem constant (the
+    # engine owns nothing about product shape).
+    Spec = Data.define(:kind, :items_path, :attachments_path) do
+      PATH_RE = /\A[a-zA-Z0-9_]+(?:\.[a-zA-Z0-9_]+)*\z/
+
+      # String | Hash | nil -> Spec | nil. Raises ValidationError on a blank kind
+      # or an empty/ill-formed path. All at ingestion, never at the turn.
+      def self.parse(raw)
+        return nil if raw.nil? || raw == false
+
+        h = raw.is_a?(String) ? { "kind" => raw } : Coercion.deep_stringify(raw)
+        h = h.is_a?(Hash) ? h : {}
+        kind = Coercion.presence(h["kind"])
+        raise Insika::ValidationError, "evidence.kind is required" if kind.nil?
+
+        items = presence_path(h["items"], "items")
+        attachments = presence_path(h["attachments"], "attachments")
+        new(kind: kind, items_path: items, attachments_path: attachments)
+      end
+
+      def to_h
+        { "kind" => kind, "items" => items_path, "attachments" => attachments_path }.compact
+      end
+
+      def self.presence_path(value, default)
+        s = Coercion.presence(value)
+        s = default if s.nil?
+        raise Insika::ValidationError, "evidence.#{default}: not a dotted path" unless PATH_RE.match?(s)
+
+        s
+      end
+      private_class_method :presence_path
+    end
+
+    # The lean result the model sees — the ONLY thing that survives the envelope.
+    MAX_ITEMS = 16
+    # Line truncation keeps the transcript lean by force (E1).
+    LINE_MAX = 200
+    # Attachments are a channel nicety, never the answer; bounded on purpose.
+    MAX_ATTACHMENTS = 16
+    URL_MAX = 500
+
+    # The attachments contract, validated for the outbox (channel side, never the
+    # model): [{ "type" => "card"|"image", "url" => String, "caption" => String|nil }].
+    # Entries without a String url, or beyond MAX_ATTACHMENTS, are DROPPED — never
+    # a turn failure (the card is a channel nicety, not the answer).
+    def self.valid_attachments(list)
+      Array(list).filter_map do |entry|
+        next unless entry.is_a?(Hash)
+
+        url = (entry["url"] || entry[:url]).to_s
+        next if url.empty?
+
+        caption = Coercion.presence(entry["caption"] || entry[:caption])
+        { "type" => (entry["type"] || entry[:type]).to_s,
+          "url" => url[0, URL_MAX],
+          "caption" => caption }
+      end.first(MAX_ATTACHMENTS)
+    end
+
+    # Result shaping, stateless — callable from any tool-call fiber (the parallel
+    # tool_concurrency path). No shared state in this class.
+    class Processor
+      class << self
+        # -> the parsed Hash the evidence paths dig into. For `evidence_envelope`
+        # the raw body lives under `__insika_body` (D3); a code tool returns the
+        # object itself. Raises JSON::ParserError on a non-JSON envelope body —
+        # the envelope turns that into `{error:}`, nothing recorded (fail closed:
+        # no IDs, no claims to make).
+        def raw(spec, result)
+          return result unless result.is_a?(Hash) && result.key?("__insika_body")
+
+          JSON.parse(result["__insika_body"].to_s)
+        end
+
+        # -> [lean, attachments]. Assumes the shape already passed
+        # SchemaGuard.violation_output. Items are capped and lines truncated; the
+        # model must never see a null where the contract says items.
+        def build(spec, raw)
+          items = SchemaGuard.dig(raw, spec.items_path) || []
+          lean_items = items.first(MAX_ITEMS).map do |item|
+            { "id" => (item["id"] || item[:id]).to_s,
+              "line" => Coercion.utf8((item["line"] || item[:line]).to_s)[0, LINE_MAX] }
+          end
+          lean = { "items" => lean_items }
+          attachments = Insika::Evidence.valid_attachments(SchemaGuard.dig(raw, spec.attachments_path))
+          [lean, attachments]
+        end
+      end
+    end
+  end
+
+  # The session evidence ledger (C4). A session-scoped SET with an `ungrounded`
+  # counter: records every product id that entered the context via an
+  # evidence-declared tool this session , plus the ungrounded
+  # counter that feeds the daily metric. It is NOT a policy object — it records
+  # and answers `ids` / `ungrounded` / `lines`; it never decides.
+  class EvidenceLedger
+    # Oldest-evicted cap: a session that outlives it needs a real cap or the row
+    # grows forever.
+    MAX_IDS = 1_000
+
+    def initialize(store: nil, session_id: nil)
+      @store = store
+      @session_id = session_id
+      @ids = []
+      @ungrounded = 0
+    end
+
+    # The in-memory accumulator (the envelope appends, the validator/enforcer
+    # read the union). The PERSISTED list is appended on flush (Executor, stage 8)
+    # — the envelope never blocks on the store.
+    def record(ids)
+      @ids.concat(Array(ids).map(&:to_s).reject(&:empty?))
+      self
+    end
+
+    # -> the effective set for THIS turn: persisted session evidence (loaded at
+    # build) + the turn's new ids, deduped, capped.
+    def ids
+      (session_ids + @ids).uniq.last(MAX_IDS)
+    end
+
+    attr_reader :ungrounded
+
+    def ungrounded_count(claim)
+      @ungrounded += 1
+      claim
+    end
+
+    # -> self, flushed to the session record. Idempotent. A store OR not-found
+    # failure is swallowed (evidence is audit — it must never fail a committed
+    # turn; a session purged mid-turn by forget_customer/session_purge reads as
+    # "nothing to append", never an explosion).
+    def flush!
+      return self unless @store && @session_id
+
+      @store.append_evidence(@session_id, ids: @ids, ungrounded: @ungrounded)
+      @ids = []
+      @ungrounded = 0
+      self
+    rescue Insika::Error
+      self
+    end
+
+    private
+
+    def session_ids
+      return [] unless @store && @session_id
+
+      session = @store.find(@session_id)
+      Array(session&.evidence&.fetch("ids", [])).map(&:to_s)
+    rescue Insika::NotFoundError
+      []
+    end
+  end
+end