insika 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 73bf4ba4e364c79f87d77202bc0f667bae1a9ea46b1c4b880350b10f4b2325cc
-  data.tar.gz: d1cfc50cc5968f041f4edf4ad803b33fbcbaef7ec68930fc00543d8bf30a7a8d
+  metadata.gz: 9e7913378bd8be19a7d9422524e62c6786c2abc8d26b5194ef8b1db8fef82be5
+  data.tar.gz: f1a279b7284d9756d7ad3dcef56329314062ef77c0fbb3d24df98e10c9bcb4ce
 SHA512:
-  metadata.gz: fef7d8d0d368700e24cd9646e1545592d3cfb1745eba671ee4b2fc130cb165d20b9a6eb775567d6ad981889d3bba9cbf36e29fef7cdb7eb011d4ef506a145025
-  data.tar.gz: 5b259bd2f22a8f781dbe1d66b0c6f40e6a635147239c79387f419364efd1f3f3c989483a912585185e226db421b0ca8c9df00718c51aa310e84a2883c5a4d152
+  metadata.gz: dcbf5403a982de5ee9dc8ed0c5fde2b21b5b63667cde0b47d2b9985b99fe7a9708d53fb82d43ce8464f46c38989d5b2b261156a84c8245e16199017515d24191
+  data.tar.gz: 349d532c16f5baed05fcd79318f3f68056e40f2a931e5e33ff12c339791edaa6fcdfe811d419cf3aff490118bd46698486470f234d9e820f0e568bb875e8b2cc

data/CHANGELOG.md

@@ -8,12 +8,78 @@ it is released. Entries land with the pull request that makes the change.
 
 ## [Unreleased]
 
-Nothing has been released yet — `Insika::VERSION` is `0.1.0` and no version is tagged.
-Everything below is what the first release will contain.
+Nothing yet.
+
+## [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.
+
+### Added
+
+- **Multi-tenant at the edge (WS1)** — `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
+  (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
+  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
+  `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
+  `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
+  action (`:fatal` / `:retryable` / `:rate_limited_*`) and wrapped with the
+  provider's `retry_after`; mechanical tool-output dedupe (C3) 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)
+  as a child of the turn supervisor: it re-drives outbox records left `:pending`
+  and sweeps orphaned `:queued`/`:running` tasks untouched past
+  `INSIKA_TICK_STALE_AFTER` (default 900s) — the orphans of a worker respawned
+  mid-generation are recovered without a deploy. One worker per window sweeps (a
+  single transactional claim); a task someone alive owns is skipped, never
+  failed. `:waiting`/`:paused` stay boot recovery's.
+
+### Fixed
+
+- **WS2/WS3/WS6 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
+  instead of dying as "fatal"; a failed half-open trial reopens the circuit;
+  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
+  `:` 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;
+  `:breaker_open` alerts only on the closed→open transition; the fallback chain
+  dedupes `"model"` vs `"provider/model"` spellings.
+
+## [0.1.0] - 2026-08-10
+
+The first release: `gem install insika`.
 
 ### Added
 
-- **A publishable core (RFC-0018)** — `gem install insika` gives every shape: `reply`
+- **A publishable core** — `gem install insika` gives every shape: `reply`
   in-process, `serve`, `Insika::Server.rack_app` mounted, and `embed(backend:)`. The
   server and the Studio moved under `lib/insika/` and ship in the gem; the exported
   store contract (`lib/insika/testing/store_contract.rb`) is what a third-party

data/README.md

@@ -35,7 +35,7 @@ gem install insika
 require "insika"
 
 assistant = Insika.agent("assistant") do
-  model "deepseek-chat"
+  model "deepseek-v4-flash"
   provider :deepseek
   instructions "You are Bia, a concise and friendly assistant. Answer briefly."
 end

data/bin/insika

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-# `insika` CLI (item 23 / §8.1 — "config estrito + doctor --fix"). The operator's
+# `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
@@ -45,9 +45,9 @@ module Insika
         Usage: insika <command> [options]
 
         Commands:
-          doctor [--fix] [--json]   diagnose the deployment configuration (item 23)
+          doctor [--fix] [--json]   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 (RFC-0013)
+          refine --agent ID [...]   report what broke in an agent's real traffic
           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
@@ -108,9 +108,9 @@ module Insika
 
     # insika refine --agent ID [--last-sessions N] [--since ISO8601] [--full] [--json]
     #
-    # RFC-0013 phase A: reads the agent's own traffic and records a ranked failure
+    # reads the agent's own traffic and records a ranked failure
     # report. Read-only with respect to the agent — it writes only the run record.
-    # There is no scheduler in the engine (§3.10): this command and the Studio button
+    # There is no scheduler in the engine: this command and the Studio button
     # are how a run starts, and a cron that wants one calls this.
     def refine(argv)
       opts = { json: false, full: false }
@@ -149,7 +149,7 @@ module Insika
 # insika evals:import [--dir evals/golden] [--keep-existing]
 #
 # The corpus on disk is the SEED and the export format; the store is what a
-# deployment runs and what the Studio edits (RFC-0013 §3.7). Importing is how a
+# deployment runs and what the Studio edits. Importing is how a
 # fresh deploy gets the cases, and how a broken edit is undone.
 def evals_import(argv)
   opts = { dir: File.expand_path("../evals/golden", __dir__), overwrite: true }
@@ -189,7 +189,7 @@ end
 #
 # The accepted state of a golden set used to live ONLY in `evals/baseline.json`,
 # which is fine for the CLI (it runs from a checkout) and useless for the refinement
-# gate (RFC-0013 §3.7.3), which runs inside a deployment and has to know what "no
+# gate, which runs inside a deployment and has to know what "no
 # regression" means without one. So it became a per-agent record.
 #
 # `import` splits the one file into those records, resolving each case's agent from
@@ -333,10 +333,25 @@ end
         # Prompt-file corruption is invisible from the outside (the file is there, the
         # agent answers) — the sweep is the only thing that names it.
         agent_file_store: Insika::AgentFileStore.new(config_store: config_store),
+        # Skills + profiles: the eagerness/drift checks are about the RELATION between
+        # 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.
+        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),
         backend: backend
       )
     end
 
+    # The conventional seed roots, relative to where the operator runs the CLI —
+    # same "no app boot" rule as the rest of `doctor`, so the composition root that
+    # actually declares them is never loaded.
+    def skill_roots
+      %w[deploy/skills skills].map { |p| File.join(Dir.pwd, p) }.select { |p| Dir.exist?(p) }
+    end
+
     def display_value(spec, raw)
       return "(unset)" if raw.nil?
 

data/docs/AGENTS.md

@@ -18,7 +18,7 @@ keeps the profile it captured when it started; the next turn sees the new one.
 >
 > ```ruby
 > agent = Insika.agent("assistant") do
->   model "deepseek-chat"
+>   model "deepseek-v4-flash"
 >   provider :deepseek
 >   instructions "You are a concise, friendly assistant."
 > end
@@ -84,13 +84,19 @@ lookups.
 ```ruby
 DEFAULT_LIMITS = {
   turn_timeout: 300, tool_timeout: 60, provider_timeout: 5,
-  context_budget: 8_000, max_tool_calls: 50, approval_timeout: 3_600,
-  tool_concurrency: 1
+  context_budget: 8_000, max_tool_calls: 50, max_tool_repeat: 3,
+  approval_timeout: 3_600, tool_concurrency: 1
 }
 ```
 
 `build` merges your overrides over these — you set only the deltas.
 
+`max_tool_repeat` is the loop guard: the same tool called with **identical
+arguments** that many times in a row gets ONE in-turn warning (a user message at
+the next tool-batch boundary: "you already ran this, answer with what you
+have"). A repeat after the warning aborts the turn like `max_tool_calls` does.
+Set it below 2 to switch it off.
+
 ### Why some limits are missing from that list
 
 `chat_rate_limit`, `agent_token_ceiling`, `queue_mode`, `debounce_ms`,
@@ -304,7 +310,7 @@ What "abandoned" means, exactly:
   visible to an *operator* (its `tool_call`/`tool_result` events and the trace), not to
   the model — a half batch in the history would be an invalid prompt.
 
-> **No grace knob.** RFC-0015 sketched an `interrupt_grace_ms`; it is not
+> **No grace knob.** An `interrupt_grace_ms` was sketched; it is not
 > implemented, and would buy nothing here. The new turn is queued behind the abandoned
 > one either way (one turn at a time per session is the invariant), and waiting for a
 > boundary inside the request would break the ack-fast rule that put the debounce
@@ -330,7 +336,10 @@ For tools, a paired deny list (`tools_deny`) **always wins**, and
 
 Three capabilities invert the default — `nil`/absent means **OFF**, not "all":
 `subagents`, `memory`, and `guardrails` (each defaults to off or a conservative
-setting, never "everything on").
+setting, never "everything on"). `tool_output_compression` is a fourth: opt-in
+mechanical dedupe of repeated tool results in the history (see
+[Context](CONTEXT.md#compaction-is-not-wired--except-the-mechanical-dedupe)),
+off by default because it changes what the model sees.
 
 ### Declaring what this deployment has
 
@@ -386,6 +395,86 @@ per agent (blank inherits the platform value, `0` explicitly disables it).
 > *present but nil* reads as OFF for that agent — leave the key **absent** to
 > inherit. See [Security](SECURITY.md#edge-limits).
 
+#### Calendar budgets — the daily/monthly cost wall
+
+A third, opt-in ceiling for the *billing* shape the windows above cannot express:
+a spend cap over a CALENDAR day or month, per `(tenant, agent)` when
+multi-tenant. Data on the profile (DSL `budget` or the pack's `budget` key):
+
+```ruby
+budget daily: 100_000, monthly: 2_000_000, soft: false   # or soft: true
+```
+
+- Tokens count the **billed** spend — `input + output + cached + cache_creation`
+  (the cached prefix is the bulk of the bill, not an afterthought).
+- **Hard** (the default, `soft` absent/false): a turn that arrives with the
+  window's spend already at/over the cap **fails** with the typed
+  `Insika::BudgetExceeded` — the envelope reads `budget_exceeded` +
+  `retry_after` (seconds until the window rolls). It is NOT a customer reply; it
+  is an operator signal.
+- **Soft** (`soft: true`): the same turn RUNS — crossing the cap emits one
+  `budget_warning` event per window and injects a note into the context (the
+  model sees it, the transcript does not).
+- Either way, crossing `alert_at` (default `0.8` of the cap) fires the same
+  warning **before** the wall, once per window.
+
+> ⚠️ Unlike the ceilings above, the cap that counts is per **calendar** window —
+> a `daily` budget rolls at UTC midnight, a `monthly` one on the 1st, whatever
+> the sun. `agent_token_window` is a fixed seconds window and cannot express
+> "the day resets at midnight".
+
+#### Reliability — retries, fallback, circuit breaker (WS3)
+
+The provider interaction is a single attempt by default (RubyLLM's own 2
+transport retries aside). For a store that cannot have a dead model take the
+chat down, the reliability policy is DATA on the profile:
+
+```ruby
+reliability retries: 2, backoff: "exponential",
+            fallback: ["openai/gpt-4o-mini"],
+            circuit_breaker: { after: 10, within: 60, cooldown: 300 }
+```
+
+- **Retries** — transient failures (`:retryable` / `:rate_limited_*` per the
+  error classification) retry with exponential backoff, up to `retries`.
+  A `:fatal` (auth, billing, bad request) is NEVER retried or rotated. Each
+  attempt runs on a fresh chat — the customer-visible answer comes only from
+  the attempt that returns.
+- **Fallback** — after a node's retries, the turn ROTATES to the next model in
+  the chain: the profile's `fallback` refs first, then the platform
+  `fallback_models`. The turn's usage is attributed to the model that actually
+  spoke (`model_source: "fallback"`).
+- **Circuit breaker** — per `(tenant, provider/model)`: `after` failures within
+  `within` seconds open the circuit; while open, the turn fail-fasts with the
+  typed `circuit_open` + `retry_after` (remaining cooldown) and the provider is
+  never touched. After `cooldown` a half-open trial closes the circuit on
+  success or reopens it on failure.
+- **`timeout`** — per-attempt ceiling (default 30s), counted as a retryable
+  failure.
+
+Absent `reliability` = the plain single attempt, byte-for-byte today's
+behavior.
+
+#### Operator alerts — the webhook (WS6)
+
+Three operational events — `budget_warning`, `breaker_open`, `delivery_failed` —
+can be answered per agent with a webhook:
+
+```ruby
+alerts webhook: "https://ops.example.com/insika-alerts"
+```
+
+When present, each such event is POSTed to the URL as JSON (the event's
+type/data/meta, plus the agent). Delivery rides the same outbox + claim +
+bounded-retry pipeline as channel answers — at-most-once, crashed deliveries
+recovered at boot. The engine transports the event and does not interpret it: a
+Slack/CRM adapter is the consumer's. Absent `alerts` = nothing is sent.
+
+Separately, with `INSIKA_TURN_TIMING`, the provider's **live TTFB** is carried in
+the streaming envelope: the first content chunk emits an `insika.ttft` frame
+(`ttft_ms`) on `/v1/responses`, alongside the per-turn `timing` breakdown on the
+final `response.completed`. Additive and opt-in — absent by default.
+
 ### Layer 5: Reasoning (thinking)
 
 Controls the model's thinking budget, resolved by precedence
@@ -422,6 +511,41 @@ and each opted-in channel gets its own frame type, never the answer's. See
 > reads. That is the operator's call, which is why it is neither a default nor a
 > global.
 
+## The stuck signal — "I cannot proceed" (WS5)
+
+The engine doesn't decide what "I can't help you" means — the consumer does. What
+the engine provides is the deterministic signal, so that a product wanting
+**human escalation** can act on it instead of regexing the answer text:
+
+```ruby
+stuck_signal true
+```
+
+With `stuck_signal` on, the model may call `signal_stuck(reason:, message:)` when it
+determines it cannot proceed (out of scope, missing data, a case a human must take
+over). The turn then **ends** — a final message is published (the model's lead-in,
+or the tool's `message` when it wrote none) — and the contract carries the signal
+twice:
+
+- the terminal event `task_completed` gains an additive sibling
+  `"outcome": "stuck"` (and the OpenAI `response.completed` frame too), so a
+  consumer that only reads the response can react;
+- a dedicated `:turn_stuck` event is published with the `agent`, the `reason`, and
+  the final `message` — the subscription point for an operator inbox.
+
+```jsonc
+{ "type": "turn_stuck",
+  "data": { "agent": "store-support", "reason": "order outside my scope",
+            "message": "I'll transfer you to our human team." } }
+```
+
+Nothing about handing off, pausing, or resuming is in scope here — escalation is a
+consumer concern. How a human joins the conversation is exactly what
+`MessageOrigin.operator` ([Refinement](REFINEMENT.md#who-wrote-a-message)) stamps
+an imported transcript with; this workstream provides the point at which that
+handoff is *triggered*. Off by default (parity): without `stuck_signal`, the tool
+is not wired and the outcome never appears.
+
 ## Refinement
 
 `refinement` configures how an agent's own traffic is read back as a report — what

data/docs/CHANNELS.md

@@ -259,7 +259,7 @@ Content-Type: application/json
   "external_id": "5511999998888",        // required — YOUR key for this conversation
   "message":     "queria saber do pedido", // required
   "event_id":    "wamid.HBg…",           // optional but strongly recommended (dedup)
-  "vars":        { "store": "ocean-drop" } // optional — session vars on first contact
+  "vars":        { "store": "demo-store" } // optional — session vars on first contact
 }
 ```
 

data/docs/CONTEXT.md

@@ -23,7 +23,8 @@ into a deterministic prompt:
 | Provider | Block | Priority | Notes |
 |----------|-------|:--------:|-------|
 | **Identity** | system | **100 — pinned** | The agent's prompt files (global system files first). Never cut. |
-| **Skills** | `<available_skills>` | 80 | Level-1 skill list — see [Skills](SKILLS.md). |
+| **Skill trigger** | `<active_skill>` | 85 | Level-2 bodies: the agent's `skills_eager` set, plus the ones whose `triggers:` match the message — see [Skills](SKILLS.md). |
+| **Skills** | `<available_skills>` | 80 | Level-1 skill list, minus whatever is already eager — see [Skills](SKILLS.md). |
 | **Memory** | `<memory>` | 75 | Durable facts + recent notes, only if `memory` is on. Cuttable. |
 | **Tool search** | `<available_tools>` | 70 | Level-1 list of deferred tools — see [Tools](TOOLS.md). |
 | **Session** | history | 60–79 | The running transcript; priority scales with recency. |
@@ -48,13 +49,29 @@ prefix cache below).
 > returns empty turns, raise `context_budget` (e.g. to `60000`) before looking
 > anywhere else. See [Agents](AGENTS.md#default-limits).
 
-### Compaction is not wired
+### Compaction is not wired — except the mechanical dedupe
 
 There is a settings stub for LLM-summarization compaction (`enabled: false`,
-`keep_last`, a reserved utility-model slot), and the Studio exposes it, but
-**nothing consumes it today** — size is managed purely by hard budget eviction.
+`keep_last`, a reserved utility-model slot), but **nothing consumes it today**
+— and the Studio no longer shows a form for it, so the setting cannot be
+switched on by accident. Size is managed purely by hard budget eviction.
 Do not rely on compaction to shrink a bloated agent: tune `context_budget` and
-keep the identity lean. Turning the setting on does nothing yet.
+keep the identity lean.
+
+One cheap half **is** wired, opt-in per agent: `tool_output_compression` (DSL
+`tool_output_compression`, or `"tool_output_compression": true` in the pack).
+When on, byte-identical repeated **tool results** in the replayed history
+collapse to a compact back-reference (the first occurrence stays full, with a
+one-line summary) — no LLM involved. It changes what the model sees, so it is
+never a default: an older detail is only in the first occurrence, and a model
+that wants it re-calls the tool. Reach for it when a tool keeps returning the
+same body (a catalog page, a status) and history is the fragment blowing the
+budget first.
+
+> The **Studio session screen** shows what the builder assembled per turn —
+> tokens per category (identity, history, memory, …), the tools-schema estimate
+> and the budget verdict (`used / cap`, evicted sources). Counts only, never
+> fragment content.
 
 ## Memory
 

data/docs/DEPLOY.md

@@ -33,9 +33,12 @@ curl localhost:9292/up      # {"status":"ok"}
 ## The process model
 
 The image boots **N Falcon worker processes over one SQLite file**
-(`WEB_CONCURRENCY`, default 2). That number is a **contract input, not a tuning
+(`WEB_CONCURRENCY`, default 1). That number is a **contract input, not a tuning
 knob**: it decides which engine semantics hold cluster-wide and which are
-per-worker. The contract:
+per-worker. The default is 1 because the per-worker semantics are the product
+— the queue modes (`collect`/`steer`) and FIFO ordering need one
+session actor; raise N only with sticky routing per session in front. The
+contract:
 
 > Everything here describes N workers of **one** deployment — one graph, replicated.
 > N *graphs* inside one process is a different contract, and it is
@@ -76,6 +79,18 @@ per-worker. The contract:
    that buffer defaults to 0** — SIGKILL right after SIGTERM, which cancels the
    whole drain — so set `RAILWAY_DEPLOYMENT_DRAINING_SECONDS=30` on the
    service.
+5. **A periodic tick closes the gap between boots.** Serving workers run a tick
+   every `INSIKA_TICK_INTERVAL` (default **60s**, `0` disables) as a child of
+   the turn supervisor: it re-drives any outbox record left `:pending` (each
+   carries its own claim — every worker may drain), and sweeps orphaned tasks
+   **without waiting for a deploy** — which is what recovers the orphans of a
+   worker respawned mid-generation (item 3's hole). One worker per window
+   sweeps (a single transactional claim), and only `:queued`/`:running` tasks
+   untouched for `INSIKA_TICK_STALE_AFTER` (default **900s**) are candidates:
+   a live turn is bounded by `turn_timeout`, so anything older cannot be alive.
+   **If you raise `turn_timeout` past it, raise `INSIKA_TICK_STALE_AFTER` too** —
+   the threshold must exceed the largest `turn_timeout` of the deployment.
+   `:waiting`/`:paused` tasks are idle by nature and stay boot recovery's.
 
 `deploy/entrypoint.sh` sets `WEB_CONCURRENCY` next to a pointer to this section;
 this section is the single source of truth for what changing it means.
@@ -86,14 +101,16 @@ this section is the single source of truth for what changing it means.
 |-----|---------|--------|
 | `INSIKA_DB` | `/data/insika.db` (in the image) | durable SQLite path (**mount a volume!**) |
 | `PORT` | `9292` | HTTP bind port |
-| `WEB_CONCURRENCY` | `2` | number of Falcon worker processes — a contract input, see [The process model](#the-process-model) |
+| `WEB_CONCURRENCY` | `1` | number of Falcon worker processes — a contract input, see [The process model](#the-process-model) |
 | `INSIKA_BOOT_ID` | set by `deploy/entrypoint.sh` | boot generation id; the recovery **task sweep** runs once per id (process model, item 3). Unset = every boot sweeps (single-process default) |
 | `INSIKA_DRAIN_TIMEOUT` | `20` | seconds a stopping worker waits for in-flight turns before abandoning them to the next boot's recovery (process model, item 4). The entrypoint sizes Falcon's `--graceful-stop` from it; on Railway also set `RAILWAY_DEPLOYMENT_DRAINING_SECONDS` ≥ drain + 10 |
+| `INSIKA_TICK_INTERVAL` | `60` | seconds between tick passes — outbox drain + stale recovery sweep (process model, item 5). `0` disables |
+| `INSIKA_TICK_STALE_AFTER` | `900` | seconds a `:queued`/`:running` task must sit untouched before the tick sweeps it. Must exceed the largest `turn_timeout` of the deployment |
 | `OPENCLAW_GATEWAY_TOKEN` | falls back to `ADMIN_TOKEN` | Bearer for `/v1/responses` and `/v1/agents` (the API contract) |
 | `ADMIN_TOKEN` | `local-demo` | login token for `/studio` (**change in production**) |
 | `DEEPSEEK_API_KEY` | — | provider key. **Without it the engine still boots** (`/up` green), but turns fail until it is configured (env or Studio → LLM providers) — cloud resilience |
-| `DEEPSEEK_MODEL` | `deepseek-chat` | model |
-| `ACHEI_INTERNAL_URL` | — | base URL for data-tools calling back a consumer's internal API (see below) |
+| `DEEPSEEK_MODEL` | `deepseek-v4-flash` | model |
+| `CONSUMER_INTERNAL_URL` | — | base URL for data-tools calling back a consumer's internal API (see below) |
 | `INSIKA_EGRESS_HOSTS` | — | outbound host allowlist (SSRF guard) |
 | `INSIKA_EGRESS_ALLOW_HTTP` / `_ALLOW_PRIVATE` | off | for `http`/loopback callbacks only (**never in cloud**) |
 | `INSIKA_RELAY_TOKEN` | — | **mounts the relay channel** at `POST /channels/relay/events`, and is the Bearer it requires. Empty = the route does not exist (`404`). See [Channels](CHANNELS.md) |
@@ -165,10 +182,13 @@ insika env               # lists known keys + current values (secrets masked)
 Checks: env (the schema above), settings schema version (a pending migration →
 `--fix` applies it), a missing platform `default_model` (`--fix` seeds it from
 `DEEPSEEK_MODEL`), durable vs ephemeral backend, LLM provider configured,
-`ADMIN_TOKEN` set, data-tool definitions still valid, and **prompt files that hold
+`ADMIN_TOKEN` set, data-tool definitions still valid, **prompt files that hold
 text rather than a serialized object** (a file whose content is a stringified Hash
 serves a mangled prompt on every turn while looking perfectly healthy — present,
-non-empty, and the agent still answers). Settings-schema migrations are **explicit**
+non-empty, and the agent still answers), and **skill drift** — a shared skill whose
+body names one store, a prompt file routing to a skill the agent cannot load, a broken
+companion pair, a stale `eager:` key (see
+[Skills](SKILLS.md#drift-guards)). Settings-schema migrations are **explicit**
 — no Studio save silently reinterprets old-shape data.
 
 ### Data-tool callbacks to a backend — via a tunnel
@@ -178,8 +198,8 @@ cloud** and your backend **on your machine** (`:3000`), expose it over a public
 `https` tunnel and point the engine at it:
 
 ```bash
-# in the tool/manifest: base_url = {{env.ACHEI_INTERNAL_URL}}
-ACHEI_INTERNAL_URL=https://your-tunnel.example.dev
+# in the tool/manifest: base_url = {{env.CONSUMER_INTERNAL_URL}}
+CONSUMER_INTERNAL_URL=https://your-tunnel.example.dev
 INSIKA_EGRESS_HOSTS=your-tunnel.example.dev
 ```
 
@@ -197,7 +217,7 @@ healthcheck, and a restart policy.
 2. **Volume**: mount it at `/data` (the default `INSIKA_DB` points there) —
    without a volume, SQLite is ephemeral and recovery resumes nothing after a
    redeploy.
-3. **Vars**: `DEEPSEEK_API_KEY`, `OPENCLAW_GATEWAY_TOKEN`, `ACHEI_INTERNAL_URL`,
+3. **Vars**: `DEEPSEEK_API_KEY`, `OPENCLAW_GATEWAY_TOKEN`, `CONSUMER_INTERNAL_URL`,
    `INSIKA_EGRESS_HOSTS` (and `WEB_CONCURRENCY` to match your plan/CPU).
 4. The healthcheck hits `/up`.
 5. Point your consumer at the service's public URL, with a matching API token

data/docs/EMBEDDING.md

@@ -21,7 +21,7 @@ makes your responsibility.
 # config/initializers/insika.rb
 INSIKA = Insika.embed(backend: Insika::Stores::SQLite.new(path: Rails.root.join("storage/insika.sqlite3").to_s)) do
   agent "support" do
-    model "deepseek-chat"
+    model "deepseek-v4-flash"
     provider :deepseek
     api_key ENV.fetch("DEEPSEEK_API_KEY")
     instructions "You answer questions about orders. Be brief."
@@ -57,7 +57,7 @@ Rails' `mount` (and `Rack::URLMap`, and anything else that moves the prefix into
 
 ## Why the store is an argument
 
-Until RFC-0017 the engine was not one process — it was one *program*. Two graphs
+The engine was not always one process — it was one *program*. Two graphs
 built in the same Ruby process shared things they never declared:
 
 | What | What actually happened |
@@ -163,15 +163,19 @@ was given a backend never looks at it.
 | The reactor / `supervised` | You, matching your server |
 | Recovery of orphaned turns at boot | You, if you want it — the sweep is `Insika::Recovery`, wired by `Insika::Server::Boot` for the standalone deployment, not by `embed` |
 
-### Embedding is not multi-tenancy
+### Embedding is not the multi-tenant server
 
 Two graphs stop corrupting each other. That is all this contract says. **Who is
 allowed to talk to which graph** is authorization, and it is not here: `token:` is
 a single Bearer gating the whole mounted app, exactly as it does for the
-standalone server — the written decision is [one deployment, one token;
-multi-tenancy belongs to the host](SECURITY.md#the-bearer-gate). If your app has
-users, put the mounted app behind your own authentication and pass `session:`
-yourself — do not hand the mount point to the browser.
+standalone server in the default mode. Multi-tenancy is a property of the
+*standalone* server, not of an embed: with `INSIKA_TENANCY=multi_tenant` the
+Bearer resolves to a principal before the routes — per-tenant tokens scoped to
+their own sessions, tasks and events, operator tokens with the run of the
+deployment (see [Security](SECURITY.md#the-bearer-gate)). An embedded graph keeps
+no token store, so an embed's tenancy belongs to the host: put the mounted app
+behind your own authentication and pass `session:` yourself — do not hand the
+mount point to the browser.
 
 ---
 

data/docs/EVALS.md

@@ -132,7 +132,7 @@ reference:
 ```
 
 ```bash
-ruby evals/run.rb --agent ocean-drop --pairwise
+ruby evals/run.rb --agent loja-chocolates --pairwise
 ```
 
 Three outcomes — `better`, `comparable`, `worse` — and two more the panel can produce

data/docs/LOADTEST.md

@@ -23,6 +23,7 @@ There are three scripts, each answering a different question:
 | `scripts/bench_store.rb` | Does SQLite (WAL) hold up N processes writing the same file? | No |
 | `scripts/loadtest.rb` | End-to-end: TTFB/total/tokens/cache/error against `/v1/responses` | Yes |
 | `scripts/loadtest-local.sh` | Single-proc baseline vs N-worker multi-proc on one box | Yes |
+| `scripts/loadtest_session.rb` | A full multi-message session (CEP, searches, FAQ) under C concurrent sessions — direct to the engine (`--surface engine`, stream vs steer) or through the consumer's real ingress (`--surface web`, the consumer's widget API) | Yes |
 
 All three take `--help` / `-h`.
 
@@ -54,7 +55,7 @@ sits ~100× below this ceiling. See DEPLOY.md for the measured numbers.
 ## 2. `loadtest.rb` — end-to-end against `/v1/responses` (with provider)
 
 Hits `POST /v1/responses` (SSE) directly — the production path
-(achei-b2b/WhatsApp → engine). Standard library only. Fires `agents × concurrency ×
+(a consumer app, e.g. WhatsApp, → engine). Standard library only. Fires `agents × concurrency ×
 iterations` turns in waves of `concurrency`, and per turn records TTFB (time to
 first SSE byte), total time, and the `usage` block (tokens + cache hit) of the last
 frame that carries it.
@@ -109,7 +110,7 @@ and TTFB drop. Run both to bracket cold vs hot behaviour.
 
 ---
 
-## 3. `loadtest-local.sh` — baseline vs multi-worker on one box (§1.3 proof)
+## 3. `loadtest-local.sh` — baseline vs multi-worker on one box
 
 Boots Falcon with `--count 1` (single-process baseline), runs the sweep, then boots
 `--count N` (multi-process) over the **same** SQLite file (WAL), runs the sweep

data/docs/OBSERVABILITY.md

@@ -36,7 +36,16 @@ something that left no task of its own behind:
 | `:turn_steered` | `task_id`, `count`, `total` | a message arrived mid-run and was appended to the turn in flight |
 | `:turn_steer_released` | `task_id`, `released_as`, `count` | the run could not absorb it, so it became the turn `released_as` |
 | `:turn_interrupted` | `task_id`, `replaced_by` | the turn was abandoned mid-run, and which turn replaced it |
+| `:turn_stuck` | `task_id`, `agent`, `reason`, `message` | the agent declared it could not proceed (`signal_stuck`, WS5) — the deterministic signal a consumer escalates on |
 | `:channel_delivered` | `channel`, `outbox_id`, `status`, `attempts`, `error` | the answer reached the platform (or did not) — the turn completing says nothing about that |
+| `:delivery_failed` | `channel`, `outbox_id`, `status`, `attempts`, `error` | a delivery exhausted its bounded retries — the alert face of the row above (WS6) |
+| `:budget_warning` | `agent`, `tenant`, `window`, `spent`, `cap` | a calendar budget crossed its threshold (`alert_at` or a soft cap) — once per window (WS2) |
+| `:breaker_open` | `agent`, `ref`, `tenant` | the reliability circuit breaker tripped for a `(tenant, provider/model)` — further turns fail fast until the cooldown (WS3/WS6) |
+| `:ttft` | `task_id`, `session_id`, `ttft_ms` | the provider's time-to-first-token on the streaming envelope — only under `INSIKA_TURN_TIMING`, once per turn (WS6) |
+
+`delivery_failed` and `breaker_open` are the two the operator config is pointed at
+(`alerts.webhook` on the profile): each only fires when something durable did
+not land. `:ttft` is additive debug, absent unless `INSIKA_TURN_TIMING` is set.
 
 `:channel_delivered` is the one worth alerting on: a turn can be `:task_completed`
 and correct while the customer got nothing, because delivery is a separate,
@@ -181,13 +190,13 @@ million tokens**:
 
 ```bash
 INSIKA_MODEL_PRICING='{
-  "deepseek-chat":       {"input": 0.27, "output": 1.10, "cached_input": 0.07},
+  "deepseek-v4-flash":       {"input": 0.27, "output": 1.10, "cached_input": 0.07},
   "claude-sonnet-4-5":   {"input": 3.00, "output": 15.00, "cached_input": 0.30, "cache_write": 3.75}
 }'
 ```
 
 - A key matches the model id the provider reports, **with or without** the
-  `provider/` prefix — `deepseek/deepseek-chat` and `deepseek-chat` both hit the
+  `provider/` prefix — `deepseek/deepseek-v4-flash` and `deepseek-v4-flash` both hit the
   same entry.
 - `input` / `output` are required (one of them is enough for the entry to load).
 - `cached_input`, when given, bills cache **reads** at that rate and subtracts them