insika 0.2.0 → 0.7.0

data/lib/insika/doctor.rb

@@ -57,9 +57,55 @@ module Insika
       end
     end
 
+    # one entry of the domain inventory. The engine never GUESSES
+    # a store (D3) — every entry is something a deployment explicitly declared,
+    # or the built-in corpus still in effect (source "gem-default"). A broken
+    # enumerator degrades to one error-marked entry, never raises.
+    DomainEntry = Data.define(:kind, :agent, :detail, :source, :how_to_clear) do
+      def to_h
+        { "kind" => kind, "agent" => agent, "detail" => detail,
+          "source" => source, "how_to_clear" => how_to_clear }.compact
+      end
+    end
+
+    # The domain section of the doctor: the E2 proof surface. Read-only
+    # and informational — it never fails the exit code (a pilot reporting its
+    # own artifacts exits 0).
+    DomainReport = Data.define(:generated_at, :gem_version, :entries) do
+      def empty? = entries.empty?
+      def count  = entries.length
+
+      def to_h
+        { "generated_at" => generated_at, "gem_version" => gem_version,
+          "count" => count, "entries" => entries.map(&:to_h) }
+      end
+
+      # The human section (prints AFTER the findings — a section, not a finding).
+      def to_s
+        header =
+          if count.zero?
+            "domain: 0 artifacts — a bare install declares no store and ships no corpus in use"
+          else
+            "domain: #{count} artifact(s) — declared by the deployment or inherited from the gem default"
+          end
+        lines = entries.map do |e|
+          agent = e.agent ? "#{e.agent}: " : ""
+          source = e.source ? " (#{e.source})" : ""
+          clear = e.how_to_clear ? " — clear: #{e.how_to_clear}" : ""
+          "  [#{e.kind}] #{agent}#{e.detail}#{source}#{clear}"
+        end
+        ([header] + lines).join("\n")
+      end
+    end
+
     def initialize(env: ENV, settings_store: nil, llm_provider_store: nil, tool_store: nil,
                    agent_file_store: nil, skill_store: nil, skill_catalog: nil,
-                   profile_source: nil, backend: nil, extra_env_specs: [])
+                   profile_source: nil, backend: nil, extra_env_specs: [],
+                   shadow_pair_store: nil, soak_envelope_path: nil, context_providers: nil,
+                   memory_store: nil, agent_ids: nil, funnel_store: nil, outcome_store: nil,
+                   followup_store: nil, contact_store: nil, proposal_store: nil,
+                   schedule_store: nil,
+                   harvest_store: nil, harvest_criterion: nil, mcp_store: nil)
       @env = env
       @settings_store = settings_store
       @llm_provider_store = llm_provider_store
@@ -70,6 +116,37 @@ module Insika
       @profile_source = profile_source
       @backend = backend
       @extra_env_specs = extra_env_specs
+      @shadow_pair_store = shadow_pair_store
+      @soak_envelope_path = soak_envelope_path
+      # [ContextProvider | Class] — classes accepted so the CLI
+      # can pass the builtin set without deps; the check only reads .layer /
+      # .name. nil = skip.
+      @context_providers = context_providers
+      # the memory-scopes check — Insika::MemoryStore | nil = skip;
+      # agent_ids excuse bare cells named like an agent (the agent-memory tab's).
+      @memory_store = memory_store
+      @agent_ids = Array(agent_ids).map(&:to_s)
+      # the outcome-funnel check — nil collaborators = the check
+      # reports declarations only (env-only callers stay cheap).
+      @funnel_store = funnel_store
+      @outcome_store = outcome_store
+      # the follow-up check — nil collaborators = the check
+      # reports declarations only.
+      @followup_store = followup_store
+      @contact_store = contact_store
+      # the distillation check — nil collaborator = the check
+      # reports declarations only (counts skipped).
+      @proposal_store = proposal_store
+      # the schedules check — nil collaborator = the check
+      # reports declarations only (skip counts skipped).
+      @schedule_store = schedule_store
+      # the harvest check — nil collaborators = the check
+      # reports declarations only (counts skipped).
+      @harvest_store = harvest_store
+      @harvest_criterion = harvest_criterion
+      # the mcp check — nil collaborator = the check reports nothing
+      # (env-only callers stay cheap).
+      @mcp_store = mcp_store
     end
 
     # -> Report. Never raises (a broken check degrades to an :error Finding).
@@ -84,11 +161,25 @@ module Insika
       [before, run]
     end
 
+    #   — the domain inventory: what a deployment declares (personas
+    # with a metadata.domain tag, outcome funnels, tool evidence) plus the
+    # built-in pt-BR corpora still in effect. Read-only: informational, never
+    # a gate — a pilot reporting its own artifacts must exit 0.
+    def domain
+      entries = %i[personas corpora funnels evidence].flat_map { |section| safe_domain(section) }.compact
+      DomainReport.new(generated_at: Time.now.utc.iso8601,
+                       gem_version: Insika::VERSION,
+                       entries: entries.freeze)
+    end
+
     private
 
     def checks = %i[check_env check_settings_schema check_default_model check_db check_llm_provider
-                    check_admin_token check_data_tools check_prompt_files check_relay_channel
-                    check_web_widget check_skill_eager check_skill_drift]
+                    check_admin_token check_web_concurrency check_data_tools check_mcp check_prompt_files
+                    check_relay_channel check_web_widget check_skill_eager check_skill_drift check_shadow_parity
+                    check_soak_envelope check_turn_timing check_grounding check_cache_layers
+                    check_memory_scopes check_funnel_declarations check_followup check_distill
+                    check_harvest check_schedules check_guardrail_corpora]
 
     def safe(check)
       Array(send(check))
@@ -97,6 +188,99 @@ module Insika
       [Finding.new(check: id, severity: :error, message: "check crashed: #{e.class}: #{e.message}", fix: nil)]
     end
 
+    # one domain section, wrapped — a broken read degrades to one
+    # error-marked entry, never raises (the same discipline as `safe`).
+    def safe_domain(section)
+      send(:"domain_#{section}")
+    rescue StandardError => e
+      [DomainEntry.new(kind: "error", agent: nil,
+                       detail: "#{section}: read failed — #{e.class}: #{e.message}",
+                       source: nil, how_to_clear: nil)]
+    end
+
+    # 1/4 personas/packs — `profile.metadata["domain"]` (pack `agent.config.json`
+    # passes it through; the DSL sets it via `metadata domain: "…"`).
+    def domain_personas
+      return [] unless @profile_source
+
+      @profile_source.all.filter_map do |p|
+        m = p.metadata
+        tag = m && m["domain"]
+        next if !Coercion.present?(tag)
+
+        DomainEntry.new(kind: "persona", agent: p.id, detail: "domain=#{tag}",
+                        source: "deployment", how_to_clear: nil)
+      end
+    end
+
+    # 2/4 corpora — the built-in pt-BR corpus still in effect (gem default) and
+    # the built-in pt-BR safe replies that are not fully overridden.
+    def domain_corpora
+      return [] unless @profile_source
+
+      @profile_source.all.each_with_object([]) do |p, acc|
+        config = Insika::Safety::Config.from_profile(p)
+        next unless config.enabled?
+
+        if config.corpus_languages.include?("pt-BR")
+          acc << DomainEntry.new(kind: "guardrail-corpus", agent: p.id,
+                                 detail: "languages=#{config.corpus_languages.join(',')}",
+                                 source: "gem-default",
+                                 how_to_clear: "docs/domain.md#guardrails")
+        end
+        fallback = builtin_response_categories(config)
+        next if fallback.empty?
+
+        acc << DomainEntry.new(kind: "safe-responses", agent: p.id,
+                               detail: "categories=#{fallback.join(',')}",
+                               source: "gem-default",
+                               how_to_clear: "docs/domain.md#guardrails")
+      end
+    end
+
+    # The safe-reply categories that still resolve to the built-in pt-BR
+    # DEFAULTS (a category the agent overrode — or a catch-all `default` that
+    # replaces every category — contributes none).
+    def builtin_response_categories(config)
+      Insika::Safety::SafeResponses::DEFAULTS.keys.select do |cat|
+        Insika::Safety::SafeResponses.for(cat, overrides: config.responses) == Insika::Safety::SafeResponses::DEFAULTS[cat]
+      end
+    end
+
+    # 3/4 funnels — the   declaration shape. Absent in the tree (or on a
+    # profile) -> absent in the report: a bare install shows no funnel and no
+    # stage names at all (the vocabulary note).
+    def domain_funnels
+      return [] unless @profile_source
+
+      @profile_source.all.filter_map do |p|
+        next unless p.respond_to?(:funnel) && p.funnel.is_a?(Hash) && !p.funnel.empty?
+
+        stages = Array(p.funnel["stages"]).join(",")
+        primary = p.funnel["primary"]
+        detail = +"stages=#{stages}"
+        detail << ", primary=#{primary}" if Coercion.present?(primary)
+        DomainEntry.new(kind: "funnel", agent: p.id, detail: detail,
+                        source: "deployment", how_to_clear: nil)
+      end
+    end
+
+    # 4/4 evidence — tool manifests carrying the   `evidence: <kind>`
+    # vocabulary. Kinds are pack vocabulary, never gem constants.
+    def domain_evidence
+      return [] unless @tool_store
+
+      @tool_store.all_raw.filter_map do |raw|
+        ev = raw["evidence"]
+        kind = ev.is_a?(Hash) ? ev["kind"] : ev
+        next if !Coercion.present?(kind)
+
+        DomainEntry.new(kind: "evidence", agent: nil,
+                        detail: "#{raw["name"]}: #{kind}",
+                        source: "deployment", how_to_clear: nil)
+      end
+    end
+
     # -- checks --------------------------------------------------------
 
     def check_env
@@ -159,6 +343,82 @@ module Insika
                    message: "ADMIN_TOKEN unset — /studio is fail-closed (login denied) and the gateway has no fallback token", fix: nil)]
     end
 
+    # WEB_CONCURRENCY>1 is a legitimate config (docs/DEPLOY.md "The process
+    # model") — but it silently drops per-worker session guarantees
+    # (FIFO/collect/steer) unless the operator has sticky routing per session in
+    # front, and nothing else in the deployment surfaces that drift. This is
+    # exactly how a staging service ended up at N=4 unnoticed and leaked a reply
+    # across sessions. The engine cannot see whether sticky routing exists off
+    # Railway, so that case only warns — N>1 stays a valid choice for an
+    # operator who put a real sticky proxy in front. On Railway it is not a
+    # valid choice TODAY: Railway's own docs say it "does not support sticky
+    # sessions" and randomly distributes traffic — there is no way to satisfy
+    # the precondition on this platform, so this errors instead of warning.
+    # RAILWAY_ENVIRONMENT_NAME is injected into every Railway deployment
+    # (docs.railway.com/variables/reference), so its presence is a reliable
+    # "are we on Railway" signal.
+    def check_web_concurrency
+      n = @env["WEB_CONCURRENCY"].to_i
+      return [ok("web-concurrency", "WEB_CONCURRENCY=1 (default) — session semantics hold cluster-wide")] if n <= 1
+
+      if router_detected?
+        return [ok("web-concurrency", "WEB_CONCURRENCY=#{n} behind a detected insika-router " \
+                                       "sticky routing satisfies the precondition")]
+      end
+
+      if Insika::Coercion.present?(@env["RAILWAY_ENVIRONMENT_NAME"])
+        return [Finding.new(check: "web-concurrency", severity: :error,
+                             message: "WEB_CONCURRENCY=#{n} on Railway — Railway does not support sticky " \
+                                      "sessions (docs.railway.com/deployments/scaling), so per-session " \
+                                      "FIFO/collect/steer WILL break across workers with no way to fix it " \
+                                      "at the routing layer; set WEB_CONCURRENCY=1, or run insika-router " \
+                                      "in front of N local workers instead", fix: nil)]
+      end
+
+      [Finding.new(check: "web-concurrency", severity: :warn,
+                   message: "WEB_CONCURRENCY=#{n} — per-session FIFO/collect/steer only hold on the worker " \
+                            "that owns the session; make sure sticky routing per session sits in front (e.g. " \
+                            "insika-router, set INSIKA_ROUTER_BACKENDS/_DNS), or accept " \
+                            "per-worker best-effort (docs/DEPLOY.md \"The process model\")", fix: nil)]
+    end
+
+    # A router is "detected", not verified — the doctor cannot see whether a
+    # process at these addresses actually runs `insika-router`, only that the
+    # operator configured one. Same precedent as every other
+    # env-based capability check in this file.
+    def router_detected?
+      Insika::Coercion.present?(@env["INSIKA_ROUTER_BACKENDS"]) ||
+        Insika::Coercion.present?(@env["INSIKA_ROUTER_BACKENDS_DNS"])
+    end
+
+    # the soak envelope (a deployment-side file). Absent is :info — not every
+    # deployment soaks, and the tooling is optional. Present-and-broken is
+    # :error — an envelope that exists but does not parse is a pre-declaration
+    # somebody wrote down that the runner will refuse, and only this check says
+    # so before the run is attempted.
+    def check_soak_envelope
+      return [Finding.new(check: "soak-envelope", severity: :info, fix: nil,
+                          message: "no soak envelope (#{@soak_envelope_path || 'unset'}) — `insika soak` is available, not required")] if @soak_envelope_path.nil? || !File.file?(@soak_envelope_path)
+
+      Insika::Soak::Envelope.load(@soak_envelope_path)
+      [ok("soak-envelope", "soak envelope parses (#{@soak_envelope_path})")]
+    rescue Insika::ConfigError => e
+      [Finding.new(check: "soak-envelope", severity: :error, fix: nil,
+                   message: "soak envelope present but broken: #{e.message}")]
+    end
+
+    # the soak's prep_p95 gate needs INSIKA_TURN_TIMING on the
+    # target. Off is :info normally, and the message names what a soak would
+    # refuse — the preflight failure must never be a surprise found 72 hours in.
+    def check_turn_timing
+      if Insika::EnvSchema.truthy?(Insika::EnvSchema.read("INSIKA_TURN_TIMING", @env))
+        [ok("turn-timing", "INSIKA_TURN_TIMING on — the soak's prep_p95 gate is measurable")]
+      else
+        [Finding.new(check: "turn-timing", severity: :info, fix: nil,
+                     message: "INSIKA_TURN_TIMING off — a soak would refuse at preflight (P2: no timing block)")]
+      end
+    end
+
     # A half-configured relay is the silent kind of broken: with only
     # the deliver URL set, nothing is mounted and every inbound POST 404s; with only
     # the token, the engine accepts turns it can never answer and the customer waits
@@ -316,8 +576,8 @@ module Insika
     end
 
     # D2. A skill in more than one allowlist that names one of its OWN holders in its
-    # text is specialized text in shared clothing — the pilot served the Cacau Show
-    # agent three shared skills that each said "na Natura". Specialize it per agent
+    # text is specialized text in shared clothing — a pilot deployment served every
+    # holder three shared skills that each named one of them. Specialize it per agent
     # (write_skill with `agent:`) instead of leaving one store's policy in a shared body.
     #
     # Merchant vocabulary beyond the holders' identities is deliberately out of scope:
@@ -489,11 +749,554 @@ def wrapped_content?(content) = /\A\s*\{\s*"[^"]+"\s*=>/.match?(content.to_s)
     def check_data_tools
       return [] unless @tool_store
 
-      broken = @tool_store.all_raw.filter_map { |raw| broken_tool(raw) }
-      total = @tool_store.names.length
-      return [ok("data-tools", "#{total} data tool(s): every definition valid")] if broken.empty?
+      raws = @tool_store.all_raw
+      broken = raws.filter_map { |raw| broken_tool(raw) }
+      legacy = raws.select { |raw| raw["group"].to_s.start_with?("mcp:") }.map { |raw| legacy_mcp_snapshot(raw) }
+      base = broken.empty? ? [ok("data-tools", "#{raws.length} data tool(s): every definition valid")] : broken
+      base + legacy
+    end
+
+    # A data-tool in an `mcp:*` group was ingested by the
+    # RETIRED snapshot path (McpToolIngestor) — the live registry now serves
+    # that same MCP instance's tools directly. Still executes fine (never
+    # removed automatically), just a duplicate worth cleaning up.
+    def legacy_mcp_snapshot(raw)
+      Finding.new(check: "data-tools", severity: :info, fix: nil,
+                  message: "data tool '#{raw["name"]}' (group #{raw["group"]}) is a legacy MCP " \
+                           "snapshot — that instance's tools now run LIVE via the MCP registry; " \
+                           "this frozen copy still works but duplicates it, safe to remove.")
+    end
+
+    # An http/sse instance whose credentials still sit under `env`
+    # (the pre-RFC meaning) is READ as `headers` (McpStore#raw), but the
+    # record on disk is unchanged until the operator re-saves it — flag it so
+    # it doesn't linger silently. A stdio instance that is enabled but
+    # INSIKA_MCP_STDIO is not set will save fine but refuse to start.
+    def check_mcp
+      return [] unless @mcp_store
+
+      raws = @mcp_store.all_raw
+      gated = raws.select do |r|
+        r["transport"].to_s == "stdio" && r["enabled"] &&
+          !Insika::EnvSchema.truthy?(Insika::EnvSchema.read("INSIKA_MCP_STDIO", @env))
+      end
+      findings = @mcp_store.legacy_header_names.map do |name|
+        Finding.new(check: "mcp", severity: :warn, fix: nil,
+                    message: "MCP instance '#{name}' still stores credentials under 'env' — " \
+                             "re-save it so they move to 'headers' (env is now stdio-only).")
+      end
+      findings += gated.map do |r|
+        Finding.new(check: "mcp", severity: :info, fix: nil,
+                    message: "MCP instance '#{r["name"]}' is stdio and enabled, but INSIKA_MCP_STDIO " \
+                             "is not set — it will refuse to start.")
+      end
+      return [ok("mcp", "#{raws.length} MCP instance(s): no legacy env-as-headers records")] if findings.empty?
+
+      findings
+    end
+
+    # the doctor cannot run a turn, so it cannot prove purity — it
+    # CAN verify the declaration. An identity-layer provider that is not one of
+    # the engine's three known-safe classes is :warn; one of the engine's
+    # known-volatile classes overriding to :identity is :error (a volatile
+    # identity block bills a cache write every turn).
+    IDENTITY_BUILTINS = %w[
+      Insika::Context::Providers::Prompt
+      Insika::Context::Providers::Skill
+      Insika::Context::Providers::ToolSearch
+    ].freeze
+    VOLATILE_BUILTINS = %w[
+      Insika::Context::Providers::Request
+      Insika::Context::Providers::Session
+      Insika::Context::Providers::Memory
+      Insika::Context::Providers::SkillTrigger
+    ].freeze
+
+    def check_cache_layers
+      return [] unless @context_providers
+
+      findings = @context_providers.flat_map do |p|
+        name = p.is_a?(Class) ? p.name : p.class.name
+        layer = declared_layer(p)
+        next [] unless layer == :identity
+        next [] if builtin_of?(p, IDENTITY_BUILTINS)
+
+        known_volatile = builtin_of?(p, VOLATILE_BUILTINS)
+        [Finding.new(check: "cache-layers", severity: known_volatile ? :error : :warn, fix: nil,
+                     message: "context provider '#{name}' declares layer :identity but is " \
+                              "#{known_volatile ? 'engine-known turn-dependent' : 'not engine-verified'} — " \
+                              "a volatile block above the cache boundary bills a cache WRITE every turn. " \
+                              "Verify the output is byte-stable across turns (no timestamps, no per-turn data).")]
+      end
+      return findings if findings.any?
+
+      [ok("cache-layers", "context layers: #{@context_providers.size} provider(s), identity partition verified")]
+    end
+
+    # The declaration is an INSTANCE method, so a class passed as-is does not
+    # respond to .layer. Evaluate it on a bare instance (allocate skips
+    # initialize — the declaration must not depend on constructor state; a
+    # method that does degrades to :volatile, the conservative side). This is
+    # what makes an explicit `def layer = :volatile` read as volatile instead of
+    # a warning.
+    def declared_layer(provider)
+      return provider.layer unless provider.is_a?(Class)
+      return :volatile unless provider.instance_methods.include?(:layer)
+
+      provider.instance_method(:layer).bind_call(provider.allocate)
+    rescue StandardError
+      :volatile
+    end
+
+    # The declaration check is by CLASS: a subclass of an engine-known provider
+    # inherits its data source (a Memory subclass is still turn-dependent no
+    # matter what it overrides). Accepts instances OR classes; anonymous
+    # classes (Class.new(...)) have no .name, so the ancestor walk is what
+    # catches them.
+    def builtin_of?(provider, consts)
+      klass_of = provider.is_a?(Class) ? provider : provider.class
+
+      consts.any? do |c|
+        klass = Object.const_get(c)
+        klass_of == klass || klass_of < klass
+      rescue NameError
+        false
+      end
+    end
+
+    # grounding with a matcher that matches NOTHING (no sku) is
+    # harmless but useless — every claim passes and the audit reads zero. A
+    # warning, never an error: the pack owns matcher quality; the engine refuses
+    # only uncompileable data.
+    def check_grounding
+      return [] unless @profile_source
+
+      findings = @profile_source.all.flat_map do |profile|
+        grounding = profile.respond_to?(:grounding) ? profile.grounding : nil
+        next [] if grounding.nil? || grounding == false
+        next [] if Coercion.present?(grounding["matcher"].is_a?(Hash) ? grounding["matcher"]["sku"] : nil)
+
+        [Finding.new(check: "grounding", severity: :warn, fix: nil,
+                     message: "agent '#{profile.id}' has grounding enabled but no matcher.sku — " \
+                              "it matches nothing, so no claim is ever flagged or cut. " \
+                              "Add the store's SKU regex to grounding.matcher.sku.")]
+      end
+      findings.empty? ? [ok("grounding", "grounding: no agent with an empty matcher")] : findings
+    end
+
+    # the memory-scopes check. Reads the cells via C1's enumeration.
+    # Warn-only: the doctor never moves data across cells (D2).
+    #
+    # What it flags, and what it deliberately does NOT:
+    # - "memory:chat:<session id>" cells are the engine's OWN per-session shape
+    #    — never flagged.
+    # - a BARE cell is the DESIGNED single-tenant customer shape ("nil tenant +
+    #   customer -> memory:<customer>, NEVER _default") — with no tenant to
+    #   migrate to, warning is a false positive, so the check only fires in a
+    #   multi_tenant deployment (INSIKA_TENANCY), where every customer must
+    #   live in a [tenant:]customer cell.
+    # - `agent_ids:` excuses the agent-memory tab's cells (a bare cell named
+    #   like an agent is a profile, not a customer).
+    def check_memory_scopes
+      return [] unless @memory_store
+
+      findings = []
+      @memory_store.cells.each do |cell|
+        next if Insika::MemoryStore.session_cell?(cell) # the engine's per-session cell
+        next if cell[:customer].nil? # _default — the shared cell
+        next if cell[:tenant] # [tenant:]customer — scoped
+        next if single_tenant? # bare = the designed single-tenant customer shape
+        next if @agent_ids.include?(cell[:customer].to_s)
+
+        findings << Finding.new(check: "memory-scopes", severity: :warn, fix: nil,
+                                message: "memory cell '#{cell[:scope]}' is unscoped — in a multi-tenant " \
+                                         "deployment customer memory must live in a [tenant:]customer cell. " \
+                                         "Migrate it, or confirm it is an agent-memory cell " \
+                                         "(a bare cell named like an agent is excused).")
+      end
+      return findings if findings.any?
+
+      [ok("memory-scopes", "memory cells: #{@memory_store.cells.size}, all scoped")]
+    end
+
+    def single_tenant?
+      Insika::EnvSchema.read("INSIKA_TENANCY", @env) != "multi_tenant"
+    end
+
+    # the outcome-funnel check — declarations on every pilot store,
+    # the plan's "no 1.0 target without a remeasure" backstop. Warn/error only:
+    # the doctor never rewrites a declaration (the pack is authoritative;
+    # `--fix` has nothing to fix here).
+    def check_funnel_declarations
+      return [] unless @profile_source
+
+      findings = @profile_source.all.flat_map do |profile|
+        next [] if profile.funnel.nil?
+
+        decl = Insika::FunnelDeclaration.parse(profile.funnel)
+        if decl.nil?
+          # D8: the fold skips this agent until it is fixed — the doctor is the
+          # only report of why.
+          [Finding.new(check: "outcome-funnel", severity: :error, fix: nil,
+                       message: "agent '#{profile.id}': malformed funnel declaration — " \
+                                "#{funnel_defect(profile.funnel)}. The fold skips it " \
+                                "until this is fixed.")]
+        else
+          [ok("outcome-funnel",
+              "agent '#{profile.id}': outcome funnel declared — #{decl.stages.length} " \
+              "stages, primary '#{decl.primary}', window #{decl.attribution_window}")] +
+            funnel_data_findings(profile, decl)
+        end
+      end
+
+      # visibility is the feature — a profile with outcomes but no
+      # funnel shows the hole. Warn only; the pack owns the vocabulary.
+      without = outcomes_without_funnel
+      without.each do |agent, count|
+        findings << Finding.new(check: "outcome-funnel", severity: :warn, fix: nil,
+                                message: "agent '#{agent}' records #{count} outcomes and " \
+                                         "declares no funnel: nothing folds — the funnel " \
+                                         "shows the hole. Add a `funnel:` block to the pack.")
+      end
+
+      return findings unless findings.empty?
 
-      broken
+      [ok("outcome-funnel", "outcome funnels: every declared funnel valid")]
+    end
+
+    # -> { agent_id => outcome count } — profiles with records but no funnel.
+    # ONE scan of the outcome store, grouped by agent (a per-profile `all`
+    # would scan it once PER profile — the store is not that big, but the
+    # key shape exists precisely so this stays a single pass).
+    def outcomes_without_funnel
+      return {} unless @outcome_store && @profile_source
+
+      counts = @outcome_store.all.group_by(&:agent).transform_values(&:size)
+      @profile_source.all.each_with_object({}) do |p, acc|
+        next unless p.funnel.nil?
+
+        n = counts[p.id.to_s].to_i
+        acc[p.id.to_s] = n if n.positive?
+      end
+    end
+
+    # The named defect, for the error message. `parse!` gives the exact field.
+    def funnel_defect(hash)
+      Insika::FunnelDeclaration.parse!(hash).to_s
+    rescue Insika::ValidationError => e
+      e.message
+    end
+
+    # Data-age findings, gated on the optional collaborators (nil = skip, env-only
+    # callers stay cheap). Tenant-agnostic: folds are per (tenant, agent), so the
+    # check reads the store's `pairs` and aggregates over every tenant of the agent
+    # (a single-tenant deployment reads the "platform" pair).
+    def funnel_data_findings(profile, decl)
+      return [] unless @funnel_store
+
+      pairs = @funnel_store.pairs.select { |p| p[:agent] == profile.id.to_s }
+      return [] if pairs.empty?
+
+      findings = []
+      folded_days = 0
+      primary_count = 0
+      baseline = false
+      pairs.each do |pair|
+        days = @funnel_store.days(tenant: pair[:tenant], agent: pair[:agent])
+        folded_days += days.size
+        primary_count += days.values.sum { |c| c[decl.primary].to_i }
+        baseline ||= !@funnel_store.baseline(tenant: pair[:tenant], agent: pair[:agent]).nil?
+      end
+
+      if primary_count.zero?
+        findings << Finding.new(check: "outcome-funnel", severity: :info, fix: nil,
+                                message: "agent '#{profile.id}': the primary event " \
+                                         "'#{decl.primary}' was never observed over the " \
+                                         "folded days — check the integration.")
+      end
+      if folded_days >= 28 && !baseline
+        findings << Finding.new(check: "outcome-funnel", severity: :info, fix: nil,
+                                message: "agent '#{profile.id}': #{folded_days} folded " \
+                                         "days and no baseline frozen —   " \
+                                         "read the baseline. Freeze it in the Studio.")
+      end
+      findings
+    end
+
+    # the follow-up check — declarations validated where they are
+    # declared (D9), plus the two data-age reads that answer "whose follow-ups
+    # will fire" and "what is blocked right now" without reading the store:
+    #   · a pending record whose `at` is more than one claim window in the past
+    #     will NEVER fire — a blocked rule or a broken policy is holding it
+    #     (warn; the Follow-ups page is the drill);
+    #   · revoked contact cells per tenant (info — the human opt-out bar).
+    def check_followup
+      return [] unless @profile_source
+
+      declared = @profile_source.all.select do |profile|
+        profile.respond_to?(:followup) && !profile.followup.nil?
+      end
+      # a bare install (no follow-up on any profile) reports NOTHING — no
+      # follow-up vocabulary leaks into the doctor of a store that never
+      # scheduled one.
+      return [] if declared.empty?
+
+      findings = declared.flat_map do |profile|
+        followup = profile.followup
+        decl = Insika::FollowupPolicy.parse(followup)
+        if decl.nil?
+          [Finding.new(check: "follow-up", severity: :error, fix: nil,
+                       message: "agent '#{profile.id}': malformed follow-up declaration — " \
+                                "#{followup_defect(followup)}. The engine will never fire its " \
+                                "follow-ups until this is fixed.")]
+        else
+          [ok("follow-up",
+              "agent '#{profile.id}': follow-up declared — arm #{decl.arm}, " \
+              "#{decl.quiet_hours ? "quiet hours #{decl.quiet_hours.start}-#{decl.quiet_hours.end} " \
+              "<#{decl.quiet_hours.timezone}>" : 'no quiet hours'}, " \
+              "#{decl.cancel_keywords.size} keyword(s), " \
+              "silence after #{decl.silence_after_sends} send(s)")] +
+            followup_data_findings(profile, decl)
+        end
+      end
+
+      findings
+    end
+
+    # The named defect, for the error message — `parse!` gives the exact field.
+    def followup_defect(hash)
+      Insika::FollowupPolicy.parse!(hash).to_s
+    rescue Insika::ValidationError => e
+      e.message
+    end
+
+    # the recurring-schedule check — declarations
+    # validated where they are declared (each one through the SAME
+    # Insika::Schedule parser the engine fires on, never a second opinion),
+    # plus the data read that answers "what is being skipped right now".
+    # A bare install (no schedule on any profile) reports NOTHING.
+    def check_schedules
+      return [] unless @profile_source
+
+      declared = @profile_source.all.select do |profile|
+        profile.respond_to?(:schedules) && Array(profile.schedules).any?
+      end
+      return [] if declared.empty?
+
+      declared.flat_map do |profile|
+        Array(profile.schedules).flat_map do |schedule|
+          decl = Insika::Schedule.parse(schedule)
+          if decl.nil?
+            [Finding.new(check: "schedules", severity: :error, fix: nil,
+                         message: "agent '#{profile.id}': malformed schedule — " \
+                                  "#{schedule_defect(schedule)}. The engine will never " \
+                                  "fire it until this is fixed.")]
+          else
+            ok_finding = schedule_ok(profile, decl)
+            [ok_finding] + schedule_data_findings(profile, decl)
+          end
+        end
+      end
+    end
+
+    # The ok finding for one valid declaration — plus the warning that
+    # names the cadence ceiling: the engine claims ONE window per pass, so an
+    # `every` shorter than the claim window cannot fire more often than it.
+    def schedule_ok(profile, decl)
+      trigger = decl.cron ? "cron #{decl.cron} <#{decl.tz}>" : "every #{decl.every}s"
+      floor = Insika::ScheduleEngine::DEFAULT_WINDOW
+      if !decl.cron.nil? || decl.every >= floor
+        ok("schedules",
+           "agent '#{profile.id}': schedule '#{decl.id}' — #{trigger}, " \
+           "#{decl.fixed_session? ? "a fixed standing session" : 'a new session per run'}, " \
+           "#{decl.enabled ? 'enabled' : 'disabled'}")
+      else
+        Finding.new(check: "schedules", severity: :warn, fix: nil,
+                    message: "agent '#{profile.id}': schedule '#{decl.id}' declares " \
+                             "every #{decl.every}s, but the engine fires at most once per " \
+                             "#{floor}s claim window — the effective cadence is one run " \
+                             "per ~#{floor}s, not one per #{decl.every}s.")
+      end
+    end
+
+    # The named defect, for the error message — the engine's parser's words.
+    def schedule_defect(hash)
+      Insika::Schedule.parse!(hash).to_s
+    rescue Insika::ValidationError => e
+      e.message
+    end
+
+    # Data-age findings, gated on the optional collaborator (nil = skip,
+    # env-only callers stay cheap): the row's last skip, when the schedule
+    # was created and has one — visible in the Studio, named here too.
+    def schedule_data_findings(profile, decl)
+      return [] unless @schedule_store
+
+      row = @schedule_store.find(tenant: Insika::ScheduleEngine.tenant_for(profile),
+                                 agent: profile.id.to_s, id: decl.id)
+      return [] unless row&.last_skip
+
+      [Finding.new(check: "schedules", severity: :info, fix: nil,
+                   message: "agent '#{profile.id}' schedule '#{decl.id}': the last run was " \
+                            "SKIPPED at #{row.last_skip['at']} — reason " \
+                            "#{row.last_skip['reason'].inspect} (overlap = the previous " \
+                            "run still live; budget = a hard cap reached; late = the " \
+                            "window was missed by the no-catch-up policy).")]
+    end
+
+    # Data-age findings, gated on the optional collaborators (nil = skip,
+    # env-only callers stay cheap).
+    def followup_data_findings(profile, decl)
+      return [] unless @followup_store && @contact_store
+
+      findings = []
+      # a pending record more than one claim window PAST its `at` (the sign:
+      # due(now - window)) is a promise the tick will never honor. A
+      # quiet-hours deferral is EXCLUDED — that record still fires next pass;
+      # only a record the tick could fire RIGHT NOW and doesn't is stuck.
+      now = Time.now.utc
+      window = Insika::FollowupEngine::DEFAULT_WINDOW
+      deferred_now = decl.quiet?(now)
+      stale = @followup_store.due(now: now - window)
+                 .reject { |r| r.agent != profile.id.to_s }
+                 .reject { deferred_now }
+      unless stale.empty?
+        findings << Finding.new(check: "follow-up", severity: :warn, fix: nil,
+                                message: "agent '#{profile.id}': #{stale.size} pending " \
+                                         "follow-up(s) past their scheduled time by more than " \
+                                         "one claim window — the tick will never fire them. A " \
+                                         "blocked rule or a broken policy is pending; see the " \
+                                         "Follow-ups page.")
+      end
+      revoked_for(profile).each do |tenant, count|
+        findings << Finding.new(check: "follow-up", severity: :info, fix: nil,
+                                message: "agent '#{profile.id}': #{count} revoked contact cell(s) " \
+                                         "in tenant #{tenant.inspect} — the human opt-out bar " \
+                                         "(opt-outs are per tenant/customer, shared across agents).")
+      end
+      findings
+    end
+
+    # { tenant => revoked-cell count } among the cells this agent may message.
+    # The contact cell is per (tenant, customer) — shared across agents (D2's
+    # multi-agent note), so the count is a per-tenant tally of revoked cells.
+    def revoked_for(_profile)
+      return {} unless @contact_store
+
+      @contact_store.cells.each_with_object(Hash.new(0)) do |(key, cell), tally|
+        next unless cell["state"] == "revoked"
+
+        tally[key.split(":", 2).first] += 1
+      end
+    end
+
+    # the distillation check — per profile WITH a `distill`
+    # hash: a declared-and-enabled distiller with NO resolvable model (no
+    # distill.model, no platform utility_model) can never run — the warn is
+    # the "declared but dead" signal (D4 — the engine never guesses a model).
+    # A bare install reports one ok ("off"), unlike follow-up's silence: the
+    # Facts page exists with or without declarations and the doctor names why
+    # it stays empty. nil proposal_store = declarations only (counts skipped).
+    def check_distill
+      return [] unless @profile_source
+
+      declared = @profile_source.all.select do |profile|
+        profile.respond_to?(:distill) && !profile.distill.nil?
+      end
+      return [ok("distill", "distillation off — no agent declares it")] if declared.empty?
+
+      settings = @settings_store ? @settings_store.get : {}
+      # one scan pair per run, not per declared profile (the counts are the
+      # store's, printed identically on each line).
+      counts = @proposal_store ? distill_counts : nil
+      declared.flat_map do |profile|
+        config = profile.distill
+        if Coercion.truthy?(config["enabled"]) &&
+           Coercion.presence(config["model"]).nil? &&
+           Coercion.presence(settings["utility_model"]).nil?
+          [Finding.new(check: "distill", severity: :warn, fix: nil,
+                       message: "agent '#{profile.id}': the distiller is declared but has " \
+                                "no model slot — distillation will never run (set " \
+                                "distill.model or the platform utility_model).")]
+        else
+          suffix = counts ? " — #{counts[:pending]} proposal(s) pending, #{counts[:stale]} stale" : ""
+          [ok("distill", "agent '#{profile.id}': distillation declared#{suffix}")]
+        end
+      end
+    end
+
+    def distill_counts
+      { pending: @proposal_store.pending(limit: 10_000).size,
+        stale: @proposal_store.stale(limit: 10_000).size }
+    end
+
+    # the harvest check — per profile WITH a harvest hash:
+    #   declared-without-model warn (D12), no grounding matcher warn (D3),
+    #   malformed negative list error (D4), else ok with the pending counts.
+    # With @harvest_criterion: the loaded criterion line + a warn when the
+    # file at its path no longer loads (the frozen rule moved).
+    def check_harvest
+      return [] unless @profile_source
+
+      declared = @profile_source.all.select do |profile|
+        profile.respond_to?(:harvest) && !profile.harvest.nil?
+      end
+      findings = []
+      if declared.empty?
+        findings << ok("harvest", "harvest off — no agent declares it")
+      else
+        settings = @settings_store ? @settings_store.get : {}
+        declared.each do |profile|
+          config = profile.harvest
+          id = profile.id
+          if Coercion.truthy?(config["enabled"]) &&
+             Coercion.presence(config.dig("miner", "model")).nil? &&
+             Coercion.presence(settings["utility_model"]).nil?
+            findings << Finding.new(check: "harvest", severity: :warn, fix: nil,
+                                    message: "agent '#{id}': the harvester is declared but has no " \
+                                             "model slot — mining will never run (set " \
+                                             "harvest.miner.model or the platform utility_model).")
+          end
+          grounding = begin
+            Insika::Grounding.parse(profile.grounding)
+          rescue Insika::ValidationError
+            nil
+          end
+          if Coercion.truthy?(config["enabled"]) && (grounding.nil? || !grounding.matcher.sku?)
+            findings << Finding.new(check: "harvest", severity: :warn, fix: nil,
+                                    message: "agent '#{id}': product claims cannot be verified — " \
+                                             "mining is skipped (set grounding.matcher.sku).")
+          end
+          if config["negative_list"].is_a?(Array) &&
+             Insika::Harvest::NegativeList.parse(config["negative_list"]).nil?
+            findings << Finding.new(check: "harvest", severity: :error, fix: nil,
+                                    message: "agent '#{id}': the harvest.negative_list is malformed " \
+                                             "— the whole list is refused (half a list silently " \
+                                             "admits what the store banned).")
+          end
+          suffix = harvest_counts(id) if @harvest_store
+          findings << ok("harvest", "agent '#{id}': harvest declared#{suffix}")
+        end
+      end
+      if @harvest_criterion
+        findings << ok("harvest-criterion",
+                       "criterion #{@harvest_criterion.rule.metric} / #{@harvest_criterion.rule.window} " \
+                       "threshold #{@harvest_criterion.rule.threshold} (#{@harvest_criterion.sha})")
+        begin
+          Insika::Harvest::Criterion.load(@harvest_criterion.path)
+        rescue Insika::ConfigError, Insika::ValidationError
+          findings << Finding.new(check: "harvest-criterion", severity: :warn, fix: nil,
+                                  message: "the criterion file at #{@harvest_criterion.path} no longer " \
+                                           "loads — the frozen rule moved since boot.")
+        end
+      end
+      findings
+    end
+
+    def harvest_counts(agent_id)
+      awaiting = @harvest_store.candidates(agent_id: agent_id, status: "awaiting_approval").size
+      pending = @harvest_store.candidates(agent_id: agent_id, status: "pending").size
+      " — #{awaiting} awaiting, #{pending} pending"
     end
 
     def broken_tool(raw)
@@ -511,8 +1314,6 @@ def wrapped_content?(content) = /\A\s*\{\s*"[^"]+"\s*=>/.match?(content.to_s)
       Finding.new(check: "data-tools", severity: :error, fix: fix, message: message)
     end
 
-    # A fix ONLY when spelling the legacy bare `array` explicitly is enough to make the
-    # definition build — never a guess at a broken definition we don't understand.
     def array_sugar_fix(raw)
       params = raw.is_a?(Hash) ? raw["parameters"] : nil
       return nil unless params.is_a?(Array) && params.any? { |p| p.is_a?(Hash) && p["type"].to_s == "array" }
@@ -528,6 +1329,83 @@ def wrapped_content?(content) = /\A\s*\{\s*"[^"]+"\s*=>/.match?(content.to_s)
 
     # -- helpers -------------------------------------------------------
 
+    #   shadow parity. Shadow holds raw customer conversations, so
+    # every dangerous configuration says so BEFORE the experiment starts — and
+    # the one automated reminder to turn it off. The pairs themselves are only
+    # loaded when shadow is ON (a full scan pays for customer text); the off
+    # path needs just a count, which the store answers from its keys.
+    def check_shadow_parity
+      shadow_on = Insika::EnvSchema.truthy?(@env["INSIKA_RELAY_SHADOW"])
+      path = Insika::EnvSchema.read("INSIKA_PARITY_CRITERION", @env)
+
+      unless shadow_on
+        stored = @shadow_pair_store ? @shadow_pair_store.size : 0
+        return [] if stored.zero?
+
+        return [ok("shadow-parity",
+                   "shadow off — #{stored} pair(s) still stored, evidence is not forgotten")]
+      end
+
+      if path.nil?
+        return [Finding.new(check: "shadow-parity", severity: :error, fix: nil,
+                            message: "shadow on but INSIKA_PARITY_CRITERION is unset — the frozen criterion is required to record pairs")]
+      end
+
+      pairs = @shadow_pair_store ? @shadow_pair_store.each.to_a : []
+
+      criterion = begin
+        Insika::Parity::Criterion.load(path)
+      rescue Insika::Error => e
+        return [Finding.new(check: "shadow-parity", severity: :error, fix: nil,
+                            message: "shadow on but the criterion did not load from #{path}: #{e.message}")]
+      end
+
+      findings = [ok("shadow-parity", "shadow on — criterion frozen (#{criterion.sha}) at #{path}")]
+      if Insika::EnvSchema.present?(@env["INSIKA_RELAY_DELIVER_URL"])
+        findings << Finding.new(check: "shadow-parity", severity: :warn, fix: nil,
+                                message: "INSIKA_RELAY_DELIVER_URL is set — the URL is INERT: a shadow relay never delivers")
+      end
+      judges = ((@settings_store&.get || {})["evals"] || {})
+      if Array(judges["judges"]).reject { |j| j["model"].to_s.strip.empty? }.empty?
+        findings << Finding.new(check: "shadow-parity", severity: :warn, fix: nil,
+                                message: "no judges in settings['evals'] — pairs will accumulate and nothing can judge them")
+      end
+      window = criterion.rule.window_days
+      oldest = pairs.filter_map { |p| parse_pair_time(p) }.min
+      if oldest && oldest < Time.now.utc - (2 * window * 86_400)
+        findings << Finding.new(check: "shadow-parity", severity: :warn, fix: nil,
+                                message: "the oldest pair is older than 2 × window_days — shadow is not a permanent mode; judge and turn it off")
+      end
+      findings
+    end
+
+    def parse_pair_time(pair)
+      Time.iso8601(pair.created_at.to_s)
+    rescue ArgumentError
+      nil
+    end
+
+    # the BOOT gate for a malformed guardrail corpus. A typo'd
+    # language/family or a broken pattern source raises ValidationError inside
+    # Safety::Config on the FIRST TURN — mid-conversation, unrecoverable. This
+    # check makes `insika doctor` the place it surfaces instead: an :error
+    # finding (non-zero exit), so a deployment learns at boot, never mid-turn.
+    def check_guardrail_corpora
+      return [] unless @profile_source
+
+      findings = @profile_source.all.each_with_object([]) do |p, acc|
+        Insika::Safety::Config.from_profile(p) # compiles the corpus — raises on a bad declaration
+      rescue Insika::ValidationError => e
+        acc << Finding.new(check: "guardrail-corpora", severity: :error, fix: nil,
+                           message: "agent '#{p.id}': malformed guardrails.corpora — #{e.message}. " \
+                                    "Every message would fail the guardrail; fix the declaration " \
+                                    "(docs/domain.md#guardrails).")
+      end
+      return findings unless findings.empty?
+
+      [ok("guardrail-corpora", "guardrail corpora: every declaration compiles")]
+    end
+
     def ok(check, message) = Finding.new(check: check, severity: :ok, message: message, fix: nil)
 
     # A model to seed the platform default from: DEEPSEEK_MODEL env, else the first