insika 0.3.0 → 0.7.0

data/docs/prompts/GO-LIVE.md

@@ -0,0 +1,138 @@
+---
+title: Prompt — go live
+parent: Reference
+nav_order: 5
+permalink: /go-live/
+layout: default
+render_with_liquid: false
+---
+
+# Take this agent to production
+
+> **You are a coding agent** (Claude Code, Codex, Cursor, …) reading this because a
+> developer pasted a prompt pointing here — something like *"deploy this"* or *"take
+> it to production"*. Treat this file as a **skill**: follow the steps in order and
+> apply the RULES literally. Production is where shortcuts become incidents.
+
+Your job: get **one working local setup** running as **one production instance**,
+verified end to end. The authoritative reference is
+[`docs/DEPLOY.md`](../DEPLOY.md) (served at `GET /docs/deploy.md`); this file is the
+ordered path through it.
+
+## Step 0 — Gather context (silently)
+
+- **Repo or gem?** The reference deployment is a checkout of the insika repo
+  (`Dockerfile` + `config.ru` + `railway.json` already in it). An adopter's own app
+  consumes the gem instead — then the developer's repo needs its own image; the env
+  contract below is identical.
+- **Which platform?** Railway is the documented path. Any Docker host works; the
+  Kubernetes caveats are in [`docs/DEPLOY.md`](../DEPLOY.md) § Kubernetes.
+- **Does it work locally?** One green `reply()` or `serve` turn first. Do not debug an
+  agent and a deployment at the same time.
+- Read [`docs/DEPLOY.md`](../DEPLOY.md) and
+  [`docs/SECURITY.md`](../SECURITY.md) before writing anything.
+
+## Step 1 — Mint the two secrets (RULES, not taste)
+
+Two tokens, **two different values** — the fallback of one onto the other is a dev
+convenience only:
+
+| Token | Gates | Rotating it |
+|---|---|---|
+| `ADMIN_TOKEN` | `/studio` login (the operator — just you) | safe, independent |
+| `OPENCLAW_GATEWAY_TOKEN` | Bearer for `/v1/responses` + `/v1/agents` (your API consumers) | both sides together, same step |
+
+Generate each: `ruby -rsecurerandom -e 'puts SecureRandom.hex(24)'`. Set them as
+platform env vars. **Never** write either into a file, a commit, or your own output.
+
+## Step 2 — The non-negotiable env
+
+- **`INSIKA_DB` on a mounted volume** (the image defaults to `/data/insika.db` —
+  mount a volume at `/data`). No volume = SQLite is ephemeral and recovery resumes
+  nothing after a redeploy.
+- **`WEB_CONCURRENCY` stays `1`.** It is a contract input, not a throughput knob:
+  N>1 without session-sticky routing in front is a guaranteed cross-session reply
+  leak, and `insika doctor` errors on it on Railway. The fix, when throughput is
+  actually needed, is [`insika-router`](../ROUTER.md) in front — not a bigger number.
+- **Provider key** (`DEEPSEEK_API_KEY` for the demo provider) — without it the engine
+  still boots (`/up` green) but every turn fails until it is configured.
+- **`INSIKA_EGRESS_HOSTS`** = exactly the hosts your data-tools call. A backend on the
+  developer's machine gets a public **https tunnel** + its host in this list — never
+  `INSIKA_EGRESS_ALLOW_HTTP`/`_ALLOW_PRIVATE` in cloud.
+- On Railway also **`RAILWAY_DEPLOYMENT_DRAINING_SECONDS=30`**: the platform default
+  is 0 — SIGKILL right after SIGTERM — which cancels the graceful drain entirely.
+
+## Step 3 — Deploy
+
+Railway (repo path — `railway.json` already sets builder, start command, `/up`
+healthcheck, restart policy):
+
+1. Create the project/service from the repo (builder = Dockerfile).
+2. Mount the volume at `/data`.
+3. Set the vars from Steps 1–2.
+4. Deploy; the healthcheck must go green on `/up`.
+
+Any Docker host, same contract:
+
+```bash
+docker build -t insika .
+docker run -p 9292:9292 -v insika-data:/data \
+  -e DEEPSEEK_API_KEY=... -e ADMIN_TOKEN=... -e OPENCLAW_GATEWAY_TOKEN=... \
+  insika
+```
+
+## Step 4 — Prove it with ONE real turn
+
+In order, each with evidence:
+
+1. `curl https://<host>/up` → `{"status":"ok"}`.
+2. `bin/insika doctor` against the deployed volume (or via the platform's shell) —
+   relay its findings verbatim; fix errors before continuing.
+3. One authenticated turn:
+
+```bash
+curl -N https://<host>/v1/responses \
+  -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"<agent-id>","user":"go-live-check","input":"hello"}'
+```
+
+The reply must be real model output. 401 → token mismatch (Step 1); a provider error
+→ key/model id (Step 2); anything else → stop and diagnose with
+[`docs/prompts/DIAGNOSE-TURN.md`](DIAGNOSE-TURN.md) before touching config.
+
+4. Log in to `/studio` with the new `ADMIN_TOKEN` and find the go-live-check session.
+
+## Step 5 — Close the total-loss hole (Litestream)
+
+A single volume is the one point of total loss. Enable continuous replication by env
+(off by default, zero code): set `LITESTREAM_REPLICA_URL` + credentials per
+[`docs/DEPLOY.md`](../DEPLOY.md) § Backup / DR. Then **run the restore drill** — an
+untested backup does not count:
+
+```bash
+scripts/litestream-restore-drill.sh   # local proof of the mechanism, or the
+                                      # production drill in DEPLOY.md § Restore drill
+```
+
+If the developer declines Litestream, record that as an explicit accepted risk in
+your report — do not silently skip it.
+
+## Step 6 — Self-check
+
+- [ ] `/up` green, `doctor` clean, one real authenticated turn with model output.
+- [ ] Two distinct tokens, both only in platform env; nothing secret in git or logs.
+- [ ] Volume mounted; `WEB_CONCURRENCY=1`; drain buffer set (Railway).
+- [ ] Egress allowlist names only the hosts the tools actually call.
+- [ ] Litestream on **and** a restore exercised — or the risk explicitly accepted.
+
+## Hard constraints
+
+- **Never raise `WEB_CONCURRENCY` to "fix" throughput.** The failure it causes is a
+  reply delivered to the wrong customer — read
+  [`docs/DEPLOY.md`](../DEPLOY.md) § The process model before proposing any scaling.
+- **`_ALLOW_HTTP`/`_ALLOW_PRIVATE` never in cloud.** They exist for fully-local loops.
+- **The onboarding surface (`/start.md`, `/docs`) is opt-in in production**
+  (`INSIKA_ONBOARDING=1`) — leaving it off is the default posture, not a bug.
+- **Report every deviation.** A var you had to add, a check that failed and was
+  worked around, a step the platform made impossible — findings, not noise.

data/docs/prompts/RUN-EXAMPLES.md

@@ -0,0 +1,70 @@
+---
+title: Prompt — run every example
+parent: Reference
+nav_order: 2
+permalink: /run-examples/
+layout: default
+render_with_liquid: false
+---
+
+# Run every example
+
+> **You are a coding agent** (Claude Code, Codex, Cursor, …) reading this because a
+> developer pasted a prompt pointing here. Treat this file as a **skill**: follow the
+> steps in order and apply the RULES literally. Do not improvise beyond them.
+
+Your job: get every runnable example under `examples/` running — one at a time — and
+explain to the developer what each one demonstrates. The authoritative list (and the
+one-line capability per example) is
+[`examples/README.md`](https://github.com/guizaols/insika/tree/main/examples/README.md)
+(`examples/README.md` when the repo is checked out). Read it first.
+
+## Step 0 — Gather context (do this first, silently)
+
+RULES — verify, do not assume:
+
+- **Ruby ≥ 3.3.** Run `ruby -v`. If lower, stop and tell the developer; do not try to
+  upgrade Ruby for them.
+- **Insika must be loadable** — `require "insika"` (installed gem) or the checked-out
+  repo's bundle. Do not copy source files around to "fix" a missing install.
+- **A provider key comes from the environment** (`DEEPSEEK_API_KEY` for the demo).
+  None is set → **ask the developer**; never invent or hard-code one.
+- **Read each example's own `README.md` before running it.** Some need more than one
+  terminal or extra env vars; the README is the contract.
+
+## Step 1 — Run in this order, ONE at a time
+
+| # | Example | Command | Note |
+|---|---------|---------|------|
+| 1 | hello-agent | `ruby examples/hello-agent/hello.rb` | smallest agent; one turn |
+| 2 | data-tool | `ruby examples/data-tool/currency_agent.rb` | declarative HTTP tool + the egress guard |
+| 3 | skills | `ruby examples/skills/skill_agent.rb` | progressive skill loading |
+| 4 | memory | `ruby examples/memory/memory_agent.rb` | cross-session `remember` |
+| 5 | guardrails | `ruby examples/guardrails/guarded_agent.rb` | content-safety guardrails |
+| 6 | agentic-workflows | `ruby examples/agentic-workflows/sequential.rb` | then routing/parallel/delegation/evaluator |
+| 7 | scheduled-report | `ruby examples/scheduled-report/report_agent.rb` | runs one report turn inline; add `--serve` only if asked |
+| 8 | relay-channel | see its README | TWO processes + env vars; skip unless asked |
+
+For each one: read its README → run → quote what it printed → explain in ≤ 3 lines
+what capability it demonstrated.
+
+Skip unless the developer asks: `insika-code/` (a full deployment, not a one-file
+script), `quickstart.rb` (hello-agent already covers it), and anything in `examples/`
+the table above does not list.
+
+## Step 2 — When one fails
+
+- **Auth or model error** → stop that example, report the exact error, ask for a valid
+  key/model id. Never retry with a guessed id.
+- **A cause you can read from the output** (missing env var, port already bound…) →
+  say so and fix only with the developer's OK.
+- **Never edit an example to make it pass silently.** An example that needed a change
+  to run is a finding, not noise.
+
+## Step 3 — Self-check before you report done
+
+- [ ] Every example above either printed real model output or was reported blocked,
+      with the exact blocker.
+- [ ] No provider key written into any file; no invented model ids.
+- [ ] Each example got its ≤ 3-line "what this demonstrates".
+- [ ] Nothing was edited to make a failure disappear.

data/docs/reference.md

@@ -0,0 +1,19 @@
+---
+title: Reference
+nav_order: 8
+has_children: true
+permalink: /reference/
+---
+
+# Reference
+
+The removability map, plus the paste-prompts that hand a journey to a coding
+agent. A running instance serves each prompt at `GET /docs/<name>.md`, so you can
+point Claude Code, Codex or Cursor at the URL instead of pasting the text.
+
+- **[The domain-free core](domain.md)** — what ships in the gem, what a deployment declares, and how to clear it.
+- **[Prompt — run every example](prompts/RUN-EXAMPLES.md)** — run `examples/` one at a time and explain what each proves.
+- **[Prompt — add a tool or skill](prompts/ADD-TOOL.md)** — pick the right kind, wire the allowlist, prove it with one turn.
+- **[Prompt — diagnose a failed turn](prompts/DIAGNOSE-TURN.md)** — symptom to mechanism, then fix one thing.
+- **[Prompt — go live](prompts/GO-LIVE.md)** — tokens, volume, deploy, one authenticated turn, and the backup hole.
+{: .card-grid }

data/docs/ship.md

@@ -1,10 +1,18 @@
 ---
 title: Ship it
-nav_order: 4
+nav_order: 5
 has_children: true
 permalink: /ship/
 ---
 
 # Ship it
 
-What stands between your agent and the open internet, and how to put it on a server.
+What stands between your agent and the open internet, and how to put it on a
+server without losing a turn to a restart.
+
+- **[Security](SECURITY.md)** — guardrails, egress, approvals, secrets, and the privacy obligations that come with memory.
+- **[Sandbox](SANDBOX.md)** — confined execution for tool code you did not write.
+- **[Deploy](DEPLOY.md)** — the container, the durable volume, the process model, and the full environment table.
+- **[Router](ROUTER.md)** — the session-sticky proxy that lets you run more than one worker.
+- **[Releasing](RELEASING.md)** — how the gem is cut, and the install proof that runs before it is published.
+{: .card-grid }

data/docs/start-here.md

@@ -0,0 +1,18 @@
+---
+title: Start here
+nav_order: 2
+has_children: true
+permalink: /start-here/
+---
+
+# Start here
+
+Four pages, in order: what problem the runtime solves, how to get one running on
+your machine, what actually happens inside a turn, and how to fill an empty
+install with enough data to see every loop working.
+
+- **[Why Insika](WHY.md)** — a runtime instead of a hand-rolled loop, an assembled framework, or a hosted gateway.
+- **[Running locally](RUNNING-LOCAL.md)** — boot the engine, open the control UI, point a Responses client at it.
+- **[Architecture](ARCHITECTURE.md)** — the turn pipeline, the tool-loop, checkpoint recovery, the concurrency model.
+- **[Demo data](DEMO.md)** — seed a deployment so funnels, refinement and approvals have something to show.
+{: .card-grid }

data/lib/insika/agent_profile.rb

@@ -128,6 +128,12 @@ module Insika
     #                                   event the consumer acts on). Same opt-in as
     #                                   `memory`. What "stuck" MEANS is the consumer's call
     #                                   (escalation via CRM/operator), never the engine's.
+    :stt_prompt,                     # STT vocabulary hint (WS9): domain words
+    #                                   (product names, brand terms) the transcriber should
+    #                                   expect on this agent's voice notes — passed straight
+    #                                   through to the Whisper-family provider's `prompt:`.
+    #                                   nil/absent = the deployment default (INSIKA_STT_PROMPT
+    #                                   env) or nothing. OPERATOR config, never customer input.
     :outputs,                         # generated-media output policy (WS9, saída):
     #                                   { "image" => { "model" => …, "size" => "1024x1024" },
     #                                   "tts" => { "model" => "tts-1", "voice" => "alloy",
@@ -244,20 +250,50 @@ module Insika
                                    # off (parity, byte-identical engine). Shape-validated by
                                    # the command/engine, never here (the refinement precedent).
                                    # Deep-stringified like the other free-form hashes.
-    :harvest                         # the gated-harvest declaration — pack data,
-                                   # exactly like refinement/distill:
-                                   # { "enabled" => bool,
-                                   #   "negative_list" => [ { "rule" => "…", "pattern" => "…",
-                                   #                          "note" => "…" } ],
-                                   #   "miner" => { "model" => "<ref — absent = the platform
-                                   #       utility_model>", "window" => { "last_sessions" => N },
-                                   #       "max_proposals" => N, "budget" => { "tokens" => N } },
-                                   #   "idle_hours" => 24, "min_messages" => 3 }.
-                                   # The ENGINE mines (reads sessions, asks the miner, filters
-                                   # through the negative list + grounding), never authors a
-                                   # rule (D4). nil/absent = the loop is off (parity).
-                                   # Shape-validated by the command/engine/doctor, never here.
+    :harvest,                        # the gated-harvest declaration — pack data,
+                                     # exactly like refinement/distill:
+                                     # { "enabled" => bool,
+                                     #   "negative_list" => [ { "rule" => "…", "pattern" => "…",
+                                     #                          "note" => "…" } ],
+                                     #   "miner" => { "model" => "<ref — absent = the platform
+                                     #       utility_model>", "window" => { "last_sessions" => N },
+                                     #       "max_proposals" => N, "budget" => { "tokens" => N } },
+                                     #   "idle_hours" => 24, "min_messages" => 3 }.
+                                     # The ENGINE mines (reads sessions, asks the miner, filters
+                                     # through the negative list + grounding), never authors a
+                                     # rule (D4). nil/absent = the loop is off (parity).
+                                     # Shape-validated by the command/engine/doctor, never here.
+                                     # Deep-stringified like the other free-form hashes.
+    :knowledge,                       # the post-turn learning declaration — pack
+                                   # data, exactly like distill/harvest:
+                                   # { "extract" => true, "retrieve" => true,
+                                   #   "model" => "<ref — absent = the platform
+                                   #       utility_model>", "top_k" => 5,
+                                   #   "index" => "scan", "types" => ["fact", …] }.
+                                   # The ENGINE extracts concepts after the turn and
+                                   # stamps their provenance/confidence/sources;
+                                   # the model only names concepts (same D1
+                                   # discipline as distill). nil/absent = the
+                                   # loop is off (parity). Shape-validated by
+                                   # the extractor/doctor, never here.
                                    # Deep-stringified like the other free-form hashes.
+    :schedules                       # the recurring-schedule declarations — pack
+                                     # data, exactly like followup/distill:
+                                     # [ { "id" => "daily_report",
+                                     #     "cron" | "every" => …,
+                                     #     "tz" => "America/Sao_Paulo",
+                                     #     "message" => "<the synthetic inbound>",
+                                     #     "session_mode" => "new"|"fixed",
+                                     #     "overrides" => { "turn_timeout" => N,
+                                     #                        "max_tool_calls" => N,
+                                     #                        "model" => … },
+                                     #     "enabled" => bool }, … ].
+                                     # The ENGINE owns the firing (the
+                                     # ScheduleEngine, the tick's duty); the
+                                     # store rows are declared-derived.
+                                     # Shape-validated by Insika::Schedule,
+                                     # never here. nil/empty = the feature is
+                                     # off for that agent (parity).
   )
 
   # Reopened class (not a Data.define block): a constant assigned inside
@@ -289,8 +325,8 @@ module Insika
                     params: {}, model_policy: nil, guardrails: nil, sandbox: nil,
                     refinement: nil, capabilities_declared: nil, edge_stream: nil, metadata: {},
                      budget: nil, reliability: nil, alerts: nil, routes: nil, stuck_signal: nil,
-                     outputs: nil, briefing_fields: nil, grounding: nil, funnel: nil,
-                     followup: nil, distill: nil, harvest: nil)
+outputs: nil, stt_prompt: nil, briefing_fields: nil, grounding: nil, funnel: nil,
+                      followup: nil, distill: nil, harvest: nil, knowledge: nil, schedules: nil)
       new(
         id: id, model: model, provider: provider, base_prompt: base_prompt,
         prompt_files: Array(prompt_files), tools_allow: tools_allow,
@@ -326,6 +362,9 @@ module Insika
         routes: Coercion.deep_stringify(routes),
         stuck_signal: stuck_signal,
         outputs: Coercion.deep_stringify(outputs),
+        # plain vocabulary string, like `base_prompt` — no deep_stringify (not
+        # a Hash/Array). "" round-trips as nil (Coercion.presence).
+        stt_prompt: Coercion.presence(stt_prompt),
         # Flat [String] — same discipline as capabilities_declared: a
         # symbol/string mix would be a silent miss in the provider's known-set.
         briefing_fields: normalize_briefing_fields(briefing_fields),
@@ -348,10 +387,28 @@ module Insika
         # harvest is profile DATA, deep-stringified like the other
         # free-form hashes; shape-validated by the command/engine/doctor
         # (never here — the refinement precedent). nil = off (parity).
-        harvest: Coercion.deep_stringify(harvest)
+        harvest: Coercion.deep_stringify(harvest),
+        # knowledge is profile DATA, deep-stringified like the other
+        # free-form hashes; shape-validated by the extractor/doctor
+        # (never here — the refinement precedent). nil = off (parity).
+        knowledge: Coercion.deep_stringify(knowledge),
+        # schedules is profile DATA, deep-stringified like the other
+        # free-form hashes (an ARRAY of declarations); parsed into
+        # Insika::Schedule entries by the engine/doctor/Studio (shape-validated
+        # THERE, never here). nil/[] = the feature is off (parity).
+        schedules: normalize_schedules(schedules)
       )
     end
 
+    # nil/absent -> nil; a single Hash -> [Hash]; else an Array of Hashes —
+    # deep-stringified so JSON round-trips stay stable.
+    def self.normalize_schedules(list)
+      return nil if list.nil?
+
+      entries = list.is_a?(Hash) ? [list] : Array(list)
+      entries.empty? ? nil : Coercion.deep_stringify(entries)
+    end
+
     # nil -> []; strings; trim + drop empties + uniq (stable order); every name
     # must match ToolDefinition::NAME_RE (\A[a-z][a-z0-9_]*\z) or it is a
     # ValidationError at build time — the names become tool-description text,

data/lib/insika/artifact_signing.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "time"
+
+module Insika
+  # The signed-link half of the artifact serving surface. The signing key
+  # lives in the environment (INSIKA_ARTIFACT_SIGNING_KEY), never in a store:
+  # HMAC-SHA256 over (id, expiry), verified in constant time on the serve
+  # path. Without the key, only the authenticated Studio URL exists.
+  #
+  # The token is deterministic for a (id, expiry) pair — no nonce, on purpose:
+  # a rotated key invalidates every outstanding link, which is the documented
+  # rotation behavior (an artifact link is short-lived by TTL, not by
+  # unguessability of a single-use nonce).
+  module ArtifactSigning
+    module_function
+
+    # The route's path shapes — the ONE place the URL grammar lives, shared
+    # by the tool (which hands URLs to the model) and the route (which serves
+    # them).
+    AUTHENTICATED_PATH = "/studio/artifacts/%{id}/content"
+    SIGNED_PATH = "/studio/artifacts/s/%{id}?exp=%{exp}&sig=%{sig}"
+
+    # -> hex token (64 chars) | nil when the key is blank (no signed surface).
+    def sign(id:, expires_at:, key:)
+      key = key.to_s
+      return nil if key.empty?
+
+      OpenSSL::HMAC.hexdigest("SHA256", key, payload(id, expires_at))
+    end
+
+    # -> bool. Re-signs the (id, exp) pair the route extracted from the URL
+    # and compares in constant time; an expired link or a blank key/token is
+    # false (the route 404s — no oracle). Expiry is inclusive: a link at its
+    # exact `expires_at` still verifies.
+    def valid?(id:, token:, key:, exp:, now: Time.now.utc)
+      token = token.to_s
+      key = key.to_s
+      return false if key.empty? || token.empty?
+
+      expected = sign(id: id.to_s, expires_at: exp, key: key)
+      return false unless expected && secure_compare(expected, token)
+
+      exp_time = exp.is_a?(Time) ? exp.to_time.utc : Time.iso8601(exp.to_s).utc
+      now.to_time <= exp_time
+    rescue ArgumentError, TypeError
+      false # a malformed exp (or a time that never parses) is an invalid link
+    end
+
+    # -> the artifact's shareable URL. With a key + ttl: the signed link
+    # (shares OUTSIDE the Studio, expires). Without: the authenticated Studio
+    # content URL. An empty base yields the relative path — still openable in
+    # the Studio, useless on a channel (the doc says exactly that).
+    def url_for(id:, base: nil, key: nil, ttl: nil, now: Time.now.utc)
+      base = base.to_s.sub(%r{/\z}, "")
+      if key && key.to_s.length.positive? && ttl && ttl.to_i.positive?
+        exp = (now.to_time + ttl.to_i).utc.iso8601
+        sig = sign(id: id.to_s, expires_at: exp, key: key)
+        "#{base}#{format(SIGNED_PATH, id: id, exp: exp, sig: sig)}"
+      else
+        "#{base}#{format(AUTHENTICATED_PATH, id: id)}"
+      end
+    end
+
+    # Constant-time comparison of two hex strings. Length-independent compare
+    # is fine here: the token length is public (fixed by the algorithm).
+    def secure_compare(a, b)
+      return false unless a.bytesize == b.bytesize
+
+      a.bytes.zip(b.bytes).reduce(0) { |acc, (x, y)| acc | (x ^ y) }.zero?
+    end
+
+    # The signed payload: id + expiry — both are what the route must not let
+    # an attacker change. The id is the store key; the expiry bounds the link.
+    # Accepts a Time or an ISO8601 String (the route passes the query param).
+    def payload(id, expires_at)
+      time = expires_at.is_a?(Time) ? expires_at.utc : Time.iso8601(expires_at.to_s).utc
+      "#{id}:#{time.iso8601}"
+    end
+  end
+end

data/lib/insika/artifact_store.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "time"
+
+module Insika
+  # The report destination: one record per run, no versioning, the listing
+  # IS the history. A store, not a CMS.
+  #
+  # The tenant is a BINDING of the row — inherited from the agent that saved
+  # the artifact (the tool reads it from the turn context, never from the
+  # model), so a purge is a tenant-prefix scan and store A's report can never
+  # appear in, or be linked from, store B.
+  #
+  # Record key: "<tenant>:<agent>:<id>" — per-tenant / per-agent scans are
+  # prefixes; the id is the LAST segment, so a find is a suffix match (the
+  # followup_store.rb idiom — there is no stable prefix for an id alone).
+  # Blank tenant -> the literal "platform" (the outcome_store.rb rule, so the
+  # purge prefix scans line up).
+  class ArtifactStore
+    SCOPE = "artifacts"
+
+    # The mime allowlist — a page, not an attachment: no binaries, no uploads.
+    MIMES = %w[text/html text/markdown image/svg+xml].freeze
+
+    # The size cap on `content` (INSIKA_ARTIFACT_MAX_BYTES; the audio-message
+    # precedent is 1 MB — an artifact is a page, not an attachment).
+    DEFAULT_MAX_BYTES = 1_000_000
+    TITLE_MAX = 200
+
+    Record = Data.define(:id, :tenant, :agent, :task_id, :title, :mime,
+                         :content, :created_at)
+
+    def initialize(store:)
+      @store = store
+    end
+
+    # -> Record. Validates the mime allowlist, a non-empty title (<= 200
+    # chars) and content within `max_bytes` — ValidationError otherwise (the
+    # tool returns it to the model as `{ error: }`).
+    def create(tenant:, agent:, task_id:, title:, mime:, content:,
+               id: SecureRandom.uuid, now: Time.now.utc, max_bytes: DEFAULT_MAX_BYTES)
+      mime = "text/html" if mime.to_s.empty?
+      raise Insika::ValidationError, "mime must be one of #{MIMES.join(', ')}, got #{mime.inspect}" unless MIMES.include?(mime.to_s)
+
+      title = title.to_s
+      raise Insika::ValidationError, "title is required (1..#{TITLE_MAX} chars)" if title.strip.empty? || title.length > TITLE_MAX
+
+      content = content.to_s
+      raise Insika::ValidationError, "content is required" if content.empty?
+      raise Insika::ValidationError, "content exceeds #{max_bytes} bytes (#{content.bytesize})" if content.bytesize > max_bytes
+
+      record = { "id" => id.to_s, "tenant" => tenant_id(tenant), "agent" => agent.to_s,
+                 "task_id" => task_id.to_s, "title" => title, "mime" => mime.to_s,
+                 "content" => content, "created_at" => now.iso8601 }
+      @store.set(SCOPE, key(record), record)
+      to_record(record)
+    end
+
+    # -> Record | nil. Suffix match over the scope's keys (no stable prefix
+    # for an id alone — the followup_store.rb idiom).
+    def find(id)
+      key = @store.list(SCOPE).find { |k| k.end_with?(":#{id}") }
+      key && to_record(@store.get(SCOPE, key))
+    end
+
+    # -> [Record] — one agent's artifacts, newest first (the listing IS the
+    # history; the Studio tab's read).
+    def for_agent(tenant:, agent:)
+      prefix = "#{tenant_id(tenant)}:#{agent}:"
+      @store.list(SCOPE).filter_map do |k|
+        next unless k.start_with?(prefix)
+
+        to_record(@store.get(SCOPE, k))
+      end.sort_by { |r| [r.created_at.to_s, r.id] }.reverse
+    end
+
+    # -> [Record] — EVERY agent's artifacts for the tenant, newest first (same
+    # prefix scan as #purge, but reads instead of deletes). Needs the CALLER
+    # to know the right tenant string — see #all below for the Studio, which
+    # doesn't.
+    def for_tenant(tenant:)
+      prefix = "#{tenant_id(tenant)}:"
+      @store.list(SCOPE).filter_map do |k|
+        next unless k.start_with?(prefix)
+
+        to_record(@store.get(SCOPE, k))
+      end.sort_by { |r| [r.created_at.to_s, r.id] }.reverse
+    end
+
+    # -> [Record] — every artifact in the store, optionally narrowed to one
+    # agent, with NO tenant guess. For the Studio only: it is already
+    # operator-only (sees every tenant's agents), and unlike #for_agent/
+    # #for_tenant (hot, tenant-scoped runtime paths that a real multi-tenant
+    # caller uses because it KNOWS its own tenant) the Studio often does not
+    # — `save_artifact` binds tenant from the turn (`agent` when the Playground
+    # dispatched it, `"platform"` for a plain single-tenant API turn), so a
+    # page guessing one fixed string is wrong for the other half of the time.
+    # Filtering by the record's own `agent` field sidesteps the guess entirely.
+    def all(agent: nil)
+      @store.list(SCOPE).filter_map do |k|
+        record = to_record(@store.get(SCOPE, k))
+        next if record.nil?
+        next if agent && record.agent != agent.to_s
+
+        record
+      end.sort_by { |r| [r.created_at.to_s, r.id] }.reverse
+    end
+
+    # -> bool (did it exist?).
+    def delete(id)
+      key = @store.list(SCOPE).find { |k| k.end_with?(":#{id}") }
+      key ? @store.delete(SCOPE, key) : false
+    end
+
+    # -> count removed. The tenant-erasure reach — one tenant's artifacts die
+    # with it, never a neighbour's.
+    def purge(tenant:)
+      prefix = "#{tenant_id(tenant)}:"
+      keys = @store.list(SCOPE).select { |k| k.start_with?(prefix) }
+      keys.each { |k| @store.delete(SCOPE, k) }
+      keys.size
+    end
+
+    # -> count removed. The retention knob's reach (`artifact_ttl_days`) —
+    # the guarantee that PII inside a report expires even though no reader
+    # can see inside the opaque HTML.
+    def delete_older_than(time)
+      cutoff = time.utc.iso8601
+      removed = 0
+      @store.list(SCOPE).each do |k|
+        record = @store.get(SCOPE, k)
+        next unless record && record["created_at"].to_s < cutoff
+
+        @store.delete(SCOPE, k)
+        removed += 1
+      end
+      removed
+    end
+
+    private
+
+    def key(record)
+      "#{record['tenant']}:#{record['agent']}:#{record['id']}"
+    end
+
+    def tenant_id(tenant)
+      t = tenant.to_s
+      t.empty? ? "platform" : t
+    end
+
+    def to_record(rec)
+      return nil if rec.nil?
+
+      Record.new(id: rec["id"], tenant: rec["tenant"], agent: rec["agent"],
+                 task_id: rec["task_id"], title: rec["title"], mime: rec["mime"],
+                 content: rec["content"], created_at: rec["created_at"])
+    end
+  end
+end

data/lib/insika/channel_delivery.rb

@@ -17,7 +17,7 @@ module Insika
   #      party with outages, so "keep trying" is a real requirement and "keep trying
   #      forever" is a real outage of ours.
   #
-  # It is NOT a job queue: no scheduler, no priorities, no fan-out. The moment it
+  # It is NOT a job queue: no priorities, no fan-out. The moment it
   # grows one, the thing to do is take a real queue, not to finish building this.
   class ChannelDelivery
     MAX_ATTEMPTS = 3