insika 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9e7913378bd8be19a7d9422524e62c6786c2abc8d26b5194ef8b1db8fef82be5
-  data.tar.gz: f1a279b7284d9756d7ad3dcef56329314062ef77c0fbb3d24df98e10c9bcb4ce
+  metadata.gz: 9ac198fc4ba91d6f3d3b55ebdf782b326bee455d45be766befaff3fc761009ff
+  data.tar.gz: e315b3f30cbe8365bbb3c6db6477209935ac71f5d0cadca26b6a5bc3458fa1cb
 SHA512:
-  metadata.gz: dcbf5403a982de5ee9dc8ed0c5fde2b21b5b63667cde0b47d2b9985b99fe7a9708d53fb82d43ce8464f46c38989d5b2b261156a84c8245e16199017515d24191
-  data.tar.gz: 349d532c16f5baed05fcd79318f3f68056e40f2a931e5e33ff12c339791edaa6fcdfe811d419cf3aff490118bd46698486470f234d9e820f0e568bb875e8b2cc
+  metadata.gz: 985b9924a6996aeb9a180ae6c800191029aaaad48ea55c18ffb35e8df159b14fbbc801bf7fc7cc33dc2291c6f8e80ffba078578f715ee062410c0504579819d3
+  data.tar.gz: a3a7dd5ff765f9fd652b116f7a8b03c05d3fb29cc582e1a14508e5e0ee5afb088b2d755a194da9e378b262871f84a884adbbc18a8e5e65f8af36b49706b76047

data/CHANGELOG.md

@@ -8,44 +8,172 @@ it is released. Entries land with the pull request that makes the change.
 
 ## [Unreleased]
 
-Nothing yet.
+## [0.3.0] - 2026-08-19
+
+The proof-and-consultant wave: shadow parity against a frozen criterion, the
+72h soak, perceived latency (progressive delivery), the session briefing,
+evidence grounding, the layered identity cache, customer memory in the Studio,
+the conversion ledger, `schedule()` with consent, human-gated facts, the gated
+skill harvest — and a domain-free core: the e-commerce defaults are removable,
+and what ships in the gem is asserted by the suite.
+
+### Added
+
+- **Shadow mode** — the relay channel can run every turn end to end and deliver
+  nothing: the incumbent keeps answering, the engine records what it *would*
+  have answered, and the two replies are judged pairwise against a **frozen,
+  pre-registered criterion** (the file `INSIKA_PARITY_CRITERION` points at; its
+  SHA-256 stamps every pair, and editing it mid-window turns the verdict
+  `invalid`, never stale). A panel of judges scores each pair twice with the
+  sides swapped, so a preference that flips with presentation order is recorded
+  as comparable, not as a preference. The Studio's Parity page folds the
+  running verdict on demand. No criterion, no shadow: boot refuses.
+- **The 72h soak** — `insika soak` sustains a declared arrival rate for days and
+  asks whether the *process itself* degrades with uptime. A deployment-side
+  envelope freezes the load shape and the gated ceilings before the first hour
+  (its hash stamps every snapshot); `--preflight` refuses to start on a missing
+  precondition; the runner appends hourly vitals as they happen, so a crash at
+  hour 60 leaves 60 usable hours; `--verify` recomputes the whole verdict
+  offline from the raw records. A fail means *find the leak* — never cut, and
+  never loosen the envelope.
+- **Progressive delivery** — the relay can flush the outbox one balloon per
+  paragraph (`INSIKA_RELAY_DELIVERY=progressive`), with the first balloon
+  posted as soon as the answer exists; the default `:at_end` is byte-identical
+  to before. Every channel turn records `first_balloon_ms` (inbound receipt →
+  first outbox flush) so the target is measured, not assumed.
+- **Session briefing** — the pack can declare `briefing_fields`; the engine
+  keeps the session's working state as data (known fields, still-missing list,
+  next step), a tool updates it, and the context provider injects it into the
+  turn — the consultant stops re-asking what it already knows.
+- **Grounding** — an `evidence:` contract on the tool envelope: a model claim
+  must cite ids that came out of a tool call, with `:enforce` / `:flag` / `:off`
+  modes and a per-turn ledger. A claim without evidence is refused or flagged —
+  never silently passed through.
+- **Layered identity + observable cache** — context providers are split into
+  identity/volatile layers behind a byte-stable cache prefix; the per-agent
+  cache-hit series is recorded (`CacheSeriesStore`) and shown on the Studio
+  agent detail. Invalidations and hits are measurable, not guessed.
+- **Customer memory in the Studio** — a Customers drill reads and edits the
+  per-customer memory cell, with an append-only operator-mutation audit trail
+  (content-free digests), provenance metadata, expiry, the LGPD export
+  (`/v1/commands/export_customer_memory`) and the existing right to be
+  forgotten.
+- **The outcome funnel** — outcomes fold into a store-declared stage funnel
+  (`funnel:` on the pack) on the tick: idempotent cumulative counts, an
+  attribution window carried as data, a frozen baseline (`:freeze_funnel_baseline`)
+  and a Studio page per agent. The stage vocabulary is the deployment's; a bare
+  install shows no funnel at all.
+- **Follow-ups** — the agent can book a future contact: `schedule()` and
+  `cancel_followup()` tools, a durable per-customer contact state
+  (`granted | revoked | unavailable`, where silence is not a refusal), a policy
+  engine over the tick (quiet hours, frequency ceilings, dedup, opt-out
+  keywords) and a Studio page per agent. A customer who opted out can never be
+  rescheduled; blocking happens at fire time, never at schedule time.
+- **Distilled facts** — finished conversations are read back as proposed
+  customer facts; a human approves/rejects/dismisses each on the Studio Facts
+  page, with a latched dedup ledger (a dismissed tuple is never proposed again),
+  optimistic CAS writes and LGPD-friendly retention. Nothing is ever applied
+  automatically.
+- **Gated skill harvest** — finished traffic can be mined for skill proposals
+  behind a versioned negative list and an evidence ledger (product claims must
+  reference ids the origin sessions actually saw); promotion requires the eval
+  replay **and** the store's conversion ruler not to regress, with an
+  append-only log and snapshot rollback. Nothing is ever applied automatically.
+- **A domain-free core** — the gem payload is a spec-asserted boundary
+  (`lib/` + `docs/` + the four root files; `deploy/`, `packs/`, `examples/`,
+  `evals/`, `scripts/` and `spec/` never ship, even when tracked). The pt-BR
+  guardrail corpus is language-tagged removable data, and `insika doctor --domain`
+  inventories what a deployment declares. A bare install names no store.
+- **Model-visible conformance** — every byte that reaches the provider is
+  reconstructable from checkpoints + traces, proven byte-for-byte by the
+  conformance suite (`spec/insika/conformance/`): what the chat held == the
+  checkpoint transcript == the model trace, across plain, tool-calling, steered,
+  subagent, scheduled and resuming turns.
+- **Intent routing** — `AgentProfile#routes` classifies the turn's
+  message into one configured route with a cheap model before the ask, from a
+  prompt auto-generated out of the route descriptions. The route rides the
+  turn (`state.route`, the `:route_classified` event, the terminal event), its
+  provider cost is counted in the usage, and a route can `delegate` to an
+  existing agent (its answer becomes the parent's) or end the turn with the
+  stuck outcome (`stuck: true`). Deterministic `default` fallback;
+  classifier failure leaves the turn unrouted (additive).
+- **Outcomes** — `POST /v1/outcomes` records a conversation's business
+  outcome (`conversion`/`escalation`/`deflected`/…, optional monetary value)
+  from the operator or the integration — additive, outside the response
+  contract, tenant-stamped. `GET /v1/outcomes` serves the last outcome
+  per agent + per-day series; the Studio's agent grid shows the last-outcome
+  pill and the agent detail shows the per-day series.
+- **Customer-scoped memory + right to be forgotten** — a message
+  carrying a `customer` key moves the memory scope to the `[tenant:]customer`
+  cell: two customers under one tenant never read each other (phase 1), and
+  the `<request_context>` merchant label stays untouched. Facts gained an
+  optimistic CAS write (`replace_if_revision`, microsecond revisions).
+  `POST /v1/commands/forget_customer` (phase 2, LGPD) purges one customer's
+  memory cell, their sessions and per-session traces — nothing else's.
+- **Tenant deletion + retention** —
+  `POST /v1/commands/delete_tenant_data` purges everything the engine holds
+  about one tenant (sessions, traces, every memory cell under the tenant and
+  its outcome records); the `retention_days` settings key turns on the tick's
+  daily age-based sweep (sessions + traces, terminal tasks + checkpoints,
+  memory cells and outcomes — OFF by default). The KV store contract gained
+  an additive `scopes(prefix)` enumeration.
+- **Media in the message contract** — messages accept
+  additive content parts (`text`/`image`/`audio` with a URL). Audio is
+  transcribed via RubyLLM STT (model/language via `INSIKA_STT_MODEL`/
+  `INSIKA_STT_LANGUAGE`) and the text enters the turn marked
+  `source: "voice"` on the terminal event; images attach to the model's ask
+  (provider-billed, usage flows) and the first image URL is
+  `{{ctx.image_url}}` for data/HTTP tools; media URLs pass the egress guard. The
+  OpenAI multimodal `input` array shape works on `/v1/responses`.
+- **Generated media as outputs** — the turn can produce an
+  image or a voice clip when BOTH gates agree: the agent opts in
+  (`AgentProfile#outputs` — per-kind model/voice/size config) and the request
+  declares the channel can receive it (`channel.capabilities`, one of
+  `image_output`/`audio_output`; unknown values are a 422 — the abstraction
+  admits only what leaks). The `generate_image`/`tts` system tools are wired
+  only then, the media rides the envelope additively (`output_parts` on the
+  terminal event and the `/v1/responses` completed frame — base64 parts, never
+  the answer text), image tokens merge into the turn's usage and every call
+  adds an honest `usage.media` counter (the speech API reports no tokens; the
+  part carries the model for consumer-side pricing). Generators are injectable
+  seams; the defaults are lazy (RubyLLM paint; a thin POST to the
+  OpenAI-compatible `/audio/speech` using the same provider config).
 
 ## [0.2.0] - 2026-08-13
 
 The workstreams between the first release and the one the gem actually became:
-multi-tenancy at the edge (WS1), calendar budgets (WS2), provider reliability
-(WS3), the stuck signal (WS5), operator alerts + live TTFB (WS6), and the
-failure-classification core (B9) — plus the two fix rounds that made them
-safe to ship.
+multi-tenancy at the edge, calendar budgets, provider reliability, the stuck
+signal, operator alerts + live TTFB, and the failure-classification core — plus
+the two fix rounds that made them safe to ship.
 
 ### Added
 
-- **Multi-tenant at the edge (WS1)** — `INSIKA_TENANCY=multi_tenant` resolves the
+- **Multi-tenant at the edge** — `INSIKA_TENANCY=multi_tenant` resolves the
   Bearer to a principal before the routes: per-tenant + operator tokens stored
   only as SHA-256 hashes, a tenant's sessions/tasks/streams living under its own
   `<tenant>:` namespace (fail-closed: another tenant's reads as `404`), and every
   authoring/config surface refused to a tenant.
-- **Calendar budgets (WS2)** — `AgentProfile#budget` caps the billed spend
+- **Calendar budgets** — `AgentProfile#budget` caps the billed spend
   (input + output + cached + cache-creation) per calendar day/month and
   (tenant, agent): HARD (default) fails the turn with the typed
   `Insika::BudgetExceeded` + `retry_after`; `soft: true` runs the turn and warns
   once per window — with the `alert_at` (`0.8`) crossing and the real cap
   crossing as separate events.
-- **Reliability (WS3)** — retries with backoff, mid-turn rotation to the
+- **Reliability** — retries with backoff, mid-turn rotation to the
   fallback chain, a per-`(tenant, provider/model)` circuit breaker with
   half-open trials (a failed trial reopens), and a per-attempt `timeout`
   (default 30s) counted as retryable. A `:fatal` provider error is never
   retried.
-- **Stuck signal (WS5)** — an agent declared stuck ends its turn with
+- **Stuck signal** — an agent declared stuck ends its turn with
   `outcome: "stuck"` on the envelope and a dedicated `:turn_stuck` event — the
   deterministic point a consumer escalates on.
-- **Operator alerts + live TTFB (WS6)** — `budget_warning`, `breaker_open` and
+- **Operator alerts + live TTFB** — `budget_warning`, `breaker_open` and
   `delivery_failed` POSTed to a per-agent `alerts.webhook` over the at-most-once
   outbox pipeline (boot-recoverable); under `INSIKA_TURN_TIMING` the first
   content chunk emits a live `:ttft` on the streaming envelope.
-- **Failure classification (B9)** — provider/transport failures classified by
+- **Failure classification** — provider/transport failures classified by
   action (`:fatal` / `:retryable` / `:rate_limited_*`) and wrapped with the
-  provider's `retry_after`; mechanical tool-output dedupe (C3) back-references a
+  provider's `retry_after`; mechanical tool-output dedupe back-references a
   byte-identical repeat only when the reference is genuinely shorter.
 - **The periodic tick** — durability no longer waits for a reboot. Serving
   workers run a tick every `INSIKA_TICK_INTERVAL` (default 60s, `0` disables)
@@ -58,7 +186,7 @@ safe to ship.
 
 ### Fixed
 
-- **WS2/WS3/WS6 criticals** — the budget alert marker no longer returns inside
+- **Budget/reliability/alerts criticals** — the budget alert marker no longer returns inside
   the store transaction (a leaked `BEGIN IMMEDIATE` locked SQLite on the 2nd
   over-threshold turn); the monthly reset is December-safe and UTC-aligned; an
   unset reliability timeout is 30s, not 1s, and a timeout retries/rotates
@@ -66,10 +194,10 @@ safe to ship.
   webhook deliveries pass the egress guard (SSRF); `:ttft` is emitted once per
   turn; webhook channels pre-register so the boot sweep recovers pending alerts;
   the alert dispatcher subscribes typed and re-subscribes on overflow.
-- **WS1** — `#revoke` rides the store transaction; a `tenant_id` containing
+- **Tenancy** — `#revoke` rides the store transaction; a `tenant_id` containing
   `:` is refused (the session-namespace delimiter); `POST /v1/sessions` mints a
   tenant's session under its own prefix.
-- **WS2/WS3 softs** — a failed turn's consumed tokens count against the budget;
+- **Budget and reliability softs** — a failed turn's consumed tokens count against the budget;
   `:breaker_open` alerts only on the closed→open transition; the fallback chain
   dedupes `"model"` vs `"provider/model"` spellings.
 
@@ -143,7 +271,7 @@ The first release: `gem install insika`.
 - **The gate refuses to grade a judged baseline without a judge** — a rubric'd case
   with no verdict counts as a pass, so replaying without a judge against a baseline
   recorded with one does not measure less, it measures backwards. Found by running the
-  panel against the real pilot: the gate reported *6/6, no regression* against a
+  panel against real traffic: the gate reported *6/6, no regression* against a
   baseline the same corpus had just scored *2/6*, and both candidates cleared. With the
   judge configured, the same two candidates were correctly rejected on judge-score
   drops. Third member of the same family as the missing and all-red baseline refusals.
@@ -151,7 +279,7 @@ The first release: `gem install insika`.
   input + output and excludes the cached prefix (a 27 KB pack reports `88` total against
   `26624` cached), so a ceiling built on it alone let a run send hundreds of times what
   it said. Cost now bills `total + cached` and records the cached share, which on a real
-  panel run was 95% of the spend. A run that cannot be gated is also refused **before**
+  run was 95% of the spend. A run that cannot be gated is also refused **before**
   the proposal is paid for, not after.
 - **The eval baseline is a per-agent record, not only a file** — `evals/baseline.json`
   works from a checkout; the refinement gate runs inside a deployment that has none.

data/README.md

@@ -22,6 +22,10 @@ deployment.
 - **Safe by default** — content-safety guardrails, an egress guard, confined execution, approvals, edge limits.
 - **Observable** — an event stream, per-session tool-call traces, optional OpenTelemetry.
 - **~0.4 ms of engine per turn** — p50 overhead on a neutral, key-free benchmark you can rerun yourself ([methodology](docs/BENCHMARK.md)).
+- **Domain-free core** — the gem carries no store vocabulary, no persona and no fixed
+  conversation language: the built-in pt-BR guardrail corpus is removable data, a
+  deployment declares what it is, and the payload boundary is a spec the suite asserts
+  on ([the domain-free map](docs/domain.md)).
 
 ## Your first agent
 
@@ -37,7 +41,7 @@ require "insika"
 assistant = Insika.agent("assistant") do
   model "deepseek-v4-flash"
   provider :deepseek
-  instructions "You are Bia, a concise and friendly assistant. Answer briefly."
+  instructions "You are a concise and friendly assistant. Answer briefly."
 end
 
 puts assistant.reply("hi, what can you do?")   # one turn, in-process
@@ -109,6 +113,8 @@ markdown). Public and on by default when you `serve`; opt-in in production
 - [Load test](docs/LOADTEST.md) — load-testing and data topology.
 - [Evals](docs/EVALS.md) — the cases that grade an agent: rubrics, the judge panel, and the pre-merge gate.
 - [Refinement](docs/REFINEMENT.md) — read an agent's own traffic back as a ranked report of what broke.
+- [Facts](docs/FACTS.md) — distill finished customer conversations into proposed facts; a human approves them into memory (nothing is ever applied automatically).
+- [Harvest](docs/HARVEST.md) — mine real traffic for SKILL proposals; the negative list, the evidence-ledger grounding filter and the double gate hold every proposal to a human approval and the append-only log (nothing is ever applied automatically).
 
 All of the above is also browsable, searchable and cross-linked at
 **[guizaols.github.io/insika](https://guizaols.github.io/insika/)** — the same files,

data/bin/insika

@@ -4,8 +4,9 @@
 # `insika` CLI — strict config + doctor --fix. The operator's
 # DX front door to the strict-config discipline:
 #
-#   insika doctor [--fix] [--json]   diagnose the deployment config; --fix applies
-#                                     the safe autofixes; exits non-zero on any error
+#   insika doctor [--fix] [--json] [--domain]  diagnose the deployment config; --fix applies
+#                                     the safe autofixes; --domain appends the domain inventory;
+#                                     exits non-zero on any error
 #   insika env    [--json]           list the known config keys + current (masked) values
 #   insika version                   print the engine version
 #   insika help                      this text
@@ -27,6 +28,10 @@ module Insika
       when "doctor"  then doctor(argv)
       when "env"     then env(argv)
       when "refine"  then refine(argv)
+      when "harvest" then harvest(argv)
+      when "harvest:negative" then harvest_negative_import(argv)
+      when "harvest:criterion" then harvest_criterion_check(argv)
+      when "soak"    then exit(Insika::Soak::Runner.main(argv, stdout: $stdout, stderr: $stderr))
       when "evals:import" then evals_import(argv)
       when "evals:export" then evals_export(argv)
       when "evals:baseline" then evals_baseline(argv)
@@ -45,9 +50,15 @@ module Insika
         Usage: insika <command> [options]
 
         Commands:
-          doctor [--fix] [--json]   diagnose the deployment configuration
+          doctor [--fix] [--json] [--domain]  diagnose the deployment configuration
           env    [--json]           list known config keys + current (masked) values
           refine --agent ID [...]   report what broke in an agent's real traffic
+          harvest --agent ID [...]  mine one window of finished traffic
+          harvest:negative import --agent ID --file F
+                                    seed the profile's negative list from a rules file
+          harvest:criterion check --file F
+                                    strict-load the frozen conversion criterion
+          soak   --run | --verify FILE | --preflight   the 72h soak
           evals:import [--dir D]    load the golden corpus into the store (editable in Studio)
           evals:export [--dir D]    write the stored cases back out as YAML
           evals:baseline <sub>      the accepted state per agent: show | import | export
@@ -60,13 +71,14 @@ module Insika
       TXT
     end
 
-    # insika doctor [--fix] [--json]
+    # insika doctor [--fix] [--json] [--domain]
     def doctor(argv)
-      opts = { fix: false, json: false }
+      opts = { fix: false, json: false, domain: false }
       OptionParser.new do |o|
-        o.banner = "Usage: insika doctor [--fix] [--json]"
+        o.banner = "Usage: insika doctor [--fix] [--json] [--domain]"
         o.on("--fix", "apply the safe autofixes, then re-diagnose") { opts[:fix] = true }
         o.on("--json", "emit the report as JSON") { opts[:json] = true }
+        o.on("--domain", "append the domain inventory (declared personas, corpora, funnels, evidence)") { opts[:domain] = true }
       end.parse!(argv)
 
       doc = build_doctor
@@ -74,9 +86,12 @@ module Insika
 
       if opts[:json]
         require "json"
-        puts JSON.pretty_generate(report.to_h)
+        envelope = report.to_h
+        envelope["domain"] = doc.domain.to_h if opts[:domain]
+        puts JSON.pretty_generate(envelope)
       else
         puts report.to_s(color: $stdout.tty?)
+        puts doc.domain.to_s if opts[:domain]
       end
       exit(report.ok? ? 0 : 1)
     end
@@ -296,6 +311,153 @@ end
                                         }.compact, transport: :cli))
     end
 
+    # insika harvest --agent ID [--last-sessions N] [--since ISO8601] [--full] [--json]
+    #
+    # mines one window of the agent's finished traffic and records
+    # the candidates. Writes nothing but the run + candidates + markers (D2's
+    # fork discipline); a cron or the operator's own habit runs it.
+    def harvest(argv)
+      opts = { json: false, full: false }
+      OptionParser.new do |o|
+        o.banner = "Usage: insika harvest --agent ID [options]"
+        o.on("--agent ID", "agent whose traffic to mine (required)") { |v| opts[:agent] = v }
+        o.on("--last-sessions N", Integer, "mine the N most recent conversations") { |v| opts[:last_sessions] = v }
+        o.on("--since ISO8601", "mine only turns from this instant on") { |v| opts[:since] = v }
+        o.on("--full", "ignore the mined markers and re-read the window") { opts[:full] = true }
+        o.on("--json", "emit the summary as JSON") { opts[:json] = true }
+      end.parse!(argv)
+
+      abort "insika harvest: --agent is required" if Insika::Coercion.blank?(opts[:agent])
+
+      result = begin
+        run_harvest(opts)
+      rescue Insika::Error, ArgumentError => e
+        warn "insika harvest: #{e.message}"
+        exit 2
+      end
+      if opts[:json]
+        require "json"
+        puts JSON.pretty_generate(result)
+      else
+        puts harvest_report(result)
+      end
+      exit(1) if result[:mined] && result[:run_id] && run_failed?(result)
+    end
+
+    # insika harvest:negative import --agent ID --file F
+    #
+    # the seed path: reads the VERSIONED rules file (parse! — loud), and
+    # writes the rules into the profile's harvest.negative_list via UpdateAgent
+    # (the operative, hot-editable list the engine applies).
+    def harvest_negative_import(argv)
+      opts = {}
+      OptionParser.new do |o|
+        o.banner = "Usage: insika harvest:negative import --agent ID --file F"
+        o.on("--agent ID", "agent whose profile receives the rules (required)") { |v| opts[:agent] = v }
+        o.on("--file F", "the negative-list rules file (required)") { |v| opts[:file] = v }
+      end.parse!(argv)
+
+      abort "insika harvest:negative import: --agent is required" if Insika::Coercion.blank?(opts[:agent])
+      abort "insika harvest:negative import: --file is required" if Insika::Coercion.blank?(opts[:file])
+
+      rules = begin
+        list = Insika::Harvest::NegativeList.parse!(File.read(opts[:file]))
+        list.rules.map { |r| { "rule" => r.rule, "pattern" => r.pattern, "note" => r.note } }
+      rescue Insika::Error, Errno::ENOENT => e
+        warn "insika harvest:negative import: #{e.message}"
+        exit 2
+      end
+
+      backend = Insika::Wiring::Graph.backend_from_env
+      config_store = Insika::ConfigStore.new(store: backend)
+      profiles = Insika::StoredProfileSource.new(config_store: config_store)
+      profile = profiles.fetch(opts[:agent]) ||
+                (abort "insika harvest:negative import: agent '#{opts[:agent]}' not configured")
+      handler = Insika::Commands::UpdateAgent.new(profile_source: profiles,
+                                                  event_stream: Insika::EventStream.new)
+      merged = (profile.harvest || {}).merge("negative_list" => rules)
+      handler.call(Insika::Command.build(:update_agent,
+                                         { id: opts[:agent], harvest: merged }, transport: :cli))
+      puts "imported #{rules.size} rule(s) into #{opts[:agent]}.harvest.negative_list"
+    end
+
+    # insika harvest:criterion check --file F
+    #
+    # strict-loads the frozen conversion criterion — a missing key, an unknown
+    # key or an absent file exits non-zero. The hook before any promotion is
+    # allowed.
+    def harvest_criterion_check(argv)
+      opts = {}
+      OptionParser.new do |o|
+        o.banner = "Usage: insika harvest:criterion check --file F"
+        o.on("--file F", "the frozen criterion (required)") { |v| opts[:file] = v }
+      end.parse!(argv)
+
+      abort "insika harvest:criterion check: --file is required" if Insika::Coercion.blank?(opts[:file])
+
+      criterion = Insika::Harvest::Criterion.load(opts[:file])
+      puts "criterion ok: #{criterion.rule.metric} / #{criterion.rule.window} " \
+           "threshold #{criterion.rule.threshold} min_span #{criterion.rule.min_span} " \
+           "(#{criterion.sha})"
+      0
+    rescue Insika::Error => e
+      warn "insika harvest:criterion check: #{e.message}"
+      exit 1
+    end
+
+    def run_failed?(result)
+      backend = Insika::Wiring::Graph.backend_from_env
+      run = Insika::HarvestStore.new(store: backend).find_run(result[:run_id])
+      run && run.status == "failed"
+    end
+
+    # Builds the handler over the real durable backend — same "no app boot" rule as
+    # `doctor`: no DEEPSEEK, no seeding, no reactor.
+    def run_harvest(opts)
+      backend = Insika::Wiring::Graph.backend_from_env
+      config_store = Insika::ConfigStore.new(store: backend)
+      profiles = Insika::StoredProfileSource.new(config_store: config_store)
+      handler = Insika::Commands::RunHarvest.new(
+        profiles: profiles,
+        harvest_store: Insika::HarvestStore.new(store: backend),
+        session_store: Insika::SessionStore.new(store: backend),
+        task_store: Insika::TaskStore.new(store: backend),
+        skill_store: Insika::SkillStore.new(config_store: config_store),
+        settings_store: Insika::SettingsStore.new(config_store: config_store),
+        negative_list: begin
+          path = Insika::EnvSchema.read("INSIKA_HARVEST_NEGATIVE")
+          path && Insika::Harvest::NegativeList.parse(File.read(path))
+        rescue Errno::ENOENT
+          nil
+        end,
+        miner_factory: nil,
+        event_stream: Insika::EventStream.new
+      )
+      handler.call(Insika::Command.build(:run_harvest, {
+                                           agent: opts[:agent], since: opts[:since],
+                                           last_sessions: opts[:last_sessions], full: opts[:full]
+                                         }.compact, transport: :cli))
+    end
+
+    def harvest_report(result)
+      head = if result[:mined]
+               "harvest: #{result[:candidates]} candidate(s) — #{harvest_rejected(result[:rejected])}"
+             else
+               "harvest: skipped (#{result[:skipped]})"
+             end
+      if result[:cost] && result[:cost]["spent"].to_i.positive?
+        head += " — #{result[:cost]['spent']} tokens" \
+                "#{result[:cost]['cached'].to_i.positive? ? " (#{result[:cost]['cached']} cached)" : ''}"
+      end
+      head
+    end
+
+    def harvest_rejected(rejected)
+      return "nothing rejected" if rejected.nil? || rejected.values.all?(&:zero?)
+
+      rejected.reject { |_k, v| v.to_i.zero? }.map { |k, v| "#{k}: #{v}" }.join(", ")
+    end
+
     INDENT = " " * 23 # aligns the provenance line under the finding's title
 
     def refine_report(run)
@@ -337,10 +499,51 @@ end
         # a skill and the agents holding it, so neither half alone is enough. The
         # catalog brings the DISK seeds into the sweep (deploy/skills in a deployment,
         # skills/ in the minimal wiring — whichever exists here); without it a stale
-        # `eager:` or a Natura-in-shared-body sitting in a seed pack is invisible.
+        # `eager:` or a store-specific phrase sitting in a shared seed pack is invisible.
         skill_store: Insika::SkillStore.new(config_store: config_store),
         skill_catalog: Insika::SkillCatalog.new(skill_roots),
         profile_source: Insika::StoredProfileSource.new(config_store: config_store),
+        # the shadow-parity check reads the pair store over the same
+        # runtime backend (pairs hold raw customer text — the check reports their
+        # age and the criterion's loadability before boot does).
+        shadow_pair_store: Insika::ShadowPairStore.new(store: backend),
+        # the cache-layers check — the BUILTIN set as classes (the
+        # check reads the layer declaration off the class, no instances needed).
+        context_providers: [
+          Insika::Context::Providers::Request, Insika::Context::Providers::Prompt,
+          Insika::Context::Providers::Skill, Insika::Context::Providers::SkillTrigger,
+          Insika::Context::Providers::ToolSearch, Insika::Context::Providers::Memory,
+          Insika::Context::Providers::Session
+        ],
+# the memory-scopes check reads the cells over the same
+        # runtime backend; `agent_ids` excuses the agent-memory tab's cells
+        # (a bare cell named like an agent is a profile, not a customer —
+        # the profile source is right here, so the CLI names them).
+        memory_store: Insika::MemoryStore.new(store: backend),
+        agent_ids: Insika::StoredProfileSource.new(config_store: config_store).all.map(&:id),
+        # the outcome-funnel check reads the fold's cells and the
+        # outcomes over the same runtime backend — a profile with outcomes but
+        # no funnel warns, and a frozen baseline is confirmed before it is
+        # relied on.
+        funnel_store: Insika::FunnelStore.new(store: backend),
+        outcome_store: Insika::OutcomeStore.new(store: backend),
+        # the follow-up check reads the schedule records and the
+        # contact cells over the same runtime backend (nil collaborators = the
+        # CLI reports declarations only).
+        followup_store: Insika::FollowupStore.new(store: backend),
+        contact_store: Insika::ContactStore.new(store: backend),
+        # the distillation check reads the proposal store over
+        # the same runtime backend (nil = the CLI reports declarations only).
+        proposal_store: Insika::ProposalStore.new(store: backend),
+        # the harvest check reads the candidates over the same
+        # runtime backend + the frozen criterion (nil = declarations only).
+        harvest_store: Insika::HarvestStore.new(store: backend),
+        harvest_criterion: begin
+          path = Insika::EnvSchema.read("INSIKA_HARVEST_CRITERION")
+          path && Insika::Harvest::Criterion.load(path)
+        rescue Insika::ConfigError, Insika::ValidationError
+          nil
+        end,
         backend: backend
       )
     end