insika 0.1.0 → 0.2.0

data/lib/insika/agent_profile.rb

@@ -16,11 +16,24 @@ module Insika
     :id, :model, :provider,
     :base_prompt, :prompt_files,
     :tools_allow, :tools_deny,
-    :tools_allow_groups,              # per-GROUP allowlist (Phase 7/D4/F5, Stage C):
+    :tools_allow_groups,              # per-GROUP allowlist:
     #                                   union with tools_allow; deny wins; both
     #                                   nil = all (parity). Expands to the group's
     #                                   tools in the ToolAllowlist policy.
     :skills,
+    :skills_eager,                    # progressive disclosure OFF, wholly or in part:
+    #                                   nil/false = level 1 + load_skill (parity); true = every
+    #                                   allowed skill; [names] = exactly these. An eager skill's
+    #                                   BODY enters the prompt each turn, it leaves the
+    #                                   <available_skills> catalog and load_skill refuses it.
+    #                                   Removes the activation DECISION (no miss rate) at the
+    #                                   cost of the bodies' tokens — measure them against
+    #                                   context_budget before turning it on. Same opt-in as
+    #                                   `memory`. It lives HERE and not in the SKILL.md
+    #                                   frontmatter because skills are shared between agents:
+    #                                   a per-skill flag forced one decision onto every
+    #                                   allowlist holding the skill. NOT `Allowlist`
+    #                                   semantics — nil means NONE here (SkillCatalog#eager_for).
     :context_providers,               # provider allowlist
     :workflows_allow,                 # applied by WorkflowAllowlist
     :policies,                        # names in the Policy Registry
@@ -30,7 +43,7 @@ module Insika
     :capabilities,                    # intents the agent can trigger.
     #                                   nil = NONE (opt-in, see above).
     :subagents,                       # allowlist of child agent ids this agent MAY spawn
-    #                                   (RFC-0010, item 21). CAPACITY field — NEVER inherits;
+    # CAPACITY field — NEVER inherits;
     #                                   opt-in like `capabilities`: nil/absent = NONE (do NOT
     #                                   "fix" to nil = all). Present => the `spawn_subagent`
     #                                   system tool is wired (ChatBuilder), gated by this set.
@@ -40,7 +53,7 @@ module Insika
     :memory,                          # cross-session memory.
     #                                   nil/false = OFF (parity: provider []; the `remember`
     #                                   tool not wired); true = ON. Same opt-in as capabilities.
-    :prompt_caching,                  # Anthropic prompt caching (§11 R3): nil/false = OFF
+    :prompt_caching,                  # Anthropic prompt caching (R3): nil/false = OFF
     #                                   (parity); true = ON. Same opt-in as `memory`. When ON
     #                                   AND the resolved provider is Anthropic, ChatBuilder sets
     #                                   ONE cache breakpoint at the end of the system block
@@ -50,34 +63,79 @@ module Insika
     #                                   a context provider injecting volatile content into
     #                                   :system turns every turn into a paid cache WRITE with
     #                                   no read hit. Enable only for stable-system agents.
-    :params,                          # LLM generation params (v2, §10): a Hash with
+    :tool_output_compression,          # MECHANICAL tool-result dedupe in the replayed
+    #                                   history (A3/C3): nil/false = OFF (parity); true = ON.
+    #                                   Same opt-in as `memory`. When ON, the history the
+    #                                   Session provider seeds replaces byte-identical repeated
+    #                                   tool results with a compact back-reference (first
+    #                                   occurrence stays full) — no LLM involved. CHANGES WHAT
+    #                                   THE MODEL SEES: an older full result is only the first
+    #                                   occurrence; a model that wants an older detail re-calls
+    #                                   the tool. Cheap half of compaction for bloated histories.
+    :params,                          # LLM generation params: a Hash with
     #                                   temperature/max_tokens/thinking, applied to the chat at
     #                                   stage 5. {} = provider defaults (parity).
-    :model_policy,                    # governance of WHICH models the agent may use (v2, §10):
+    :budget,                          # spend caps per (tenant, agent) over
+    #                                   CALENDAR windows (WS2): { "daily" => int,
+    #                                   "monthly" => int, "soft" => bool, "alert_at" => 0.8 }.
+    #                                   HARD is the default: absent/"soft": false, a turn
+    #                                   arriving at/over the cap fails with Insika::BudgetExceeded
+    #                                   and the envelope quotes `budget_exceeded` + retry_after.
+    #                                   "soft": true crosses the cap and still runs
+    #                                   (one budget_warning event per window + a note in the
+    #                                   context).
+    #                                   Tokens count the billed spend (input+output+cached+
+    #                                   cache_creation). nil/absent = no budget (parity).
+    :reliability,                     # the provider-interaction reliability policy (WS3):
+    #                                   { "retries" => 3, "backoff" => "exponential",
+    #                                   "fallback" => ["gpt-4o-mini", ...],
+    #                                   "circuit_breaker" => { "after" => 10, "within" => 60,
+    #                                   "cooldown" => 300 }, "timeout" => 30 }. Data, never
+    #                                   DSL: retries + exponential backoff on :retryable /
+    #                                   :rate_limited_* failures (never :fatal), mid-turn
+    #                                   rotation across the fallback chain (profile's first,
+    #                                   then the platform's resolved fallbacks), and a circuit
+    #                                   breaker per (tenant, provider/model) that fail-fasts
+    #                                   with circuit_open + retry_after once the window count
+    #                                   trips. nil/absent = the plain single attempt (parity).
+    :alerts,                          # operator alert delivery (WS6): { "webhook" => url }.
+    #                                   When present, the agent's budget_warning /
+    #                                   breaker_open / delivery_failed events are POSTed to
+    #                                   the URL as JSON (outbox + claim, at-most-once).
+    #                                   nil/absent = no webhook (parity).
+    :stuck_signal,                    # the agent may signal it cannot proceed (WS5):
+    #                                   nil/false = OFF (parity — the signal_stuck system
+    #                                   tool is not wired); true = ON (the model may call
+    #                                   signal_stuck, which ends the turn with
+    #                                   `outcome: :stuck` + a final message + a :turn_stuck
+    #                                   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.
+    :model_policy,                    # governance of WHICH models the agent may use:
     #                                   { "allow" => [refs] }. nil = NO fence (all models —
     #                                   parity). Enforced on the RESOLVED model (ModelResolver).
-    :guardrails,                      # content-safety config (RFC-0009 §3.3): { input:, output:,
+    :guardrails,                      # content-safety config: { input:, output:,
     #                                   moderator:, strictness: }. OPT-IN like capabilities —
     #                                   nil/absent = the conservative default (Safety::Config:
     #                                   deterministic on, moderator off). Parsed, never a policy.
-    :sandbox,                         # confined-execution config (item 35, §4.6):
+    :sandbox,                         # confined-execution config:
     #                                   { provider: "local"|"docker", root:, timeout:, ...+provider
     #                                   keys }. Declarative provider selection (config-over-code) —
     #                                   consumed by Insika::Sandbox.build. {} = absent (a
     #                                   deployment builds a `local` sandbox by default). It is
     #                                   CONFIG, never a policy — it does not decide security by
     #                                   itself; the FS boundary + approvals do.
-    :refinement,                      # self-improvement config (RFC-0013 §3.8):
+    :refinement,                      # self-improvement config:
     #                                   { mode: "report"|"propose"|"auto_apply", window: {…},
     #                                   files: [allowlist], proposers: [refs], budget: {tokens:},
     #                                   auto_apply_max_edits:, max_findings:, … }. nil/absent =
-    #                                   REPORT-ONLY (phase A writes nothing to the agent, so
+    #                                   REPORT-ONLY (writes nothing to the agent, so
     #                                   reading your own traces needs no opt-in); `propose`
     #                                   and above must be enabled explicitly. It is CONFIG,
     #                                   never a policy — the write allowlist it carries is
     #                                   enforced by the applier, not by this field.
     :capabilities_declared,           # FACTS ABOUT THIS DEPLOYMENT that are not tools
-    #                                   (RFC-0014 §3.5): %w[promotions human_handoff
+    # %w[promotions human_handoff
     #                                   b2b_pricing]. An eval case declares what it
     #                                   `requires` and is SKIPPED — never failed — where
     #                                   the deployment lacks it, which is what makes one
@@ -106,7 +164,7 @@ module Insika
     #                                   default to inherit.
     :metadata                         # free-form agent metadata, stable per agent
     #                                   (from the pack `agent.config.json`). Home of the `store_id`
-    #                                   that becomes turn context (ctx.store_id, Phase 6/D2).
+    #                                   that becomes turn context (ctx.store_id).
     #                                   It is NOT a policy — never decides security. {} = absent.
   )
 
@@ -116,29 +174,34 @@ module Insika
     DEFAULT_LIMITS = {
       turn_timeout: 300, tool_timeout: 60, provider_timeout: 5,
       context_budget: 8_000, max_tool_calls: 50,
+      # consecutive identical (tool, args) calls that trigger the ONE
+      # loop warning; a repeat after it aborts like max_tool_calls. < 2 = off.
+      max_tool_repeat: 3,
       approval_timeout: 3_600, # cap on the wait for human approval (~1h)
-      # Item 30: parallel tool calls. ONE number is both the switch and the cap
+      # parallel tool calls. ONE number is both the switch and the cap
       # (nil/0/1 = serial, the default; N > 1 = at most N tool calls in flight).
       # It sits next to tool_timeout/max_tool_calls because it is the third bound
       # on tool execution. Read through TurnState#tool_concurrency, which also
-      # applies the approval gate (D3).
+      # applies the approval gate.
       tool_concurrency: 1
     }.freeze
 
-    # `model` is OPTIONAL as of v2 (§10): an agent without one resolves the
+    # `model` is OPTIONAL as of v2: an agent without one resolves the
     # platform `default_model` (Settings) at turn start via the ModelResolver.
     def self.build(id:, model: nil, provider: nil, base_prompt: "", prompt_files: [],
                    tools_allow: nil, tools_deny: [], tools_allow_groups: nil, skills: nil,
-                   context_providers: nil, workflows_allow: nil,
+                   skills_eager: nil, context_providers: nil, workflows_allow: nil,
                    policies: [], prompt_refs: [], limits: {}, approvals_required: nil,
                    capabilities: nil, subagents: nil, tools_deferred: nil, memory: nil,
-                   prompt_caching: nil,
+                   prompt_caching: nil, tool_output_compression: nil,
                    params: {}, model_policy: nil, guardrails: nil, sandbox: nil,
-                   refinement: nil, capabilities_declared: nil, edge_stream: nil, metadata: {})
+                   refinement: nil, capabilities_declared: nil, edge_stream: nil, metadata: {},
+                   budget: nil, reliability: nil, alerts: nil, stuck_signal: nil)
       new(
         id: id, model: model, provider: provider, base_prompt: base_prompt,
         prompt_files: Array(prompt_files), tools_allow: tools_allow,
         tools_deny: Array(tools_deny), tools_allow_groups: tools_allow_groups, skills: skills,
+        skills_eager: skills_eager,
         context_providers: context_providers, workflows_allow: workflows_allow,
         policies: Array(policies), prompt_refs: Array(prompt_refs),
         limits: DEFAULT_LIMITS.merge(limits), approvals_required: approvals_required,
@@ -147,7 +210,7 @@ module Insika
         # readers get a clean [] and the ChatBuilder gate (present? => wire) is stable.
         subagents: subagents.nil? ? nil : Array(subagents).map(&:to_s),
         tools_deferred: tools_deferred, memory: memory,
-        prompt_caching: prompt_caching,
+        prompt_caching: prompt_caching, tool_output_compression: tool_output_compression,
         # The free-form hashes arrive with symbol keys (internal build) OR string
         # keys (StoredProfileSource JSON round-trip). Normalize to string keys ONCE
         # here — the single front door every profile passes through — so no reader
@@ -161,7 +224,11 @@ module Insika
         # symbol/string mix there would be a silent miss.
         capabilities_declared: Array(capabilities_declared).map(&:to_s),
         edge_stream: Coercion.deep_stringify(edge_stream || {}),
-        metadata: Coercion.deep_stringify(metadata || {})
+        metadata: Coercion.deep_stringify(metadata || {}),
+        budget: Coercion.deep_stringify(budget),
+        reliability: Coercion.deep_stringify(reliability),
+        alerts: Coercion.deep_stringify(alerts),
+        stuck_signal: stuck_signal
       )
     end
 
@@ -173,8 +240,8 @@ module Insika
     # store_id of the turn context (ctx.store_id): lives in `metadata` (stable
     # per store, comes from the pack). `build` string-keys metadata, so a plain
     # string lookup is enough. nil = absent (the data-tool emits an empty header).
-    # It is NOT achei-specific: `store_id` is a field of the turn-context contract
-    # (§5), generic per project.
+    # It is NOT consumer-specific: `store_id` is a field of the turn-context contract
+    # generic per project.
     def store_id = (metadata || {})["store_id"]
 
     # May this channel (:thinking / :intermediate) cross to the customer? Tolerant
@@ -182,7 +249,7 @@ module Insika
     # of anything else being absent: the safe reading is the default one.
     def stream_public?(channel)
       v = (edge_stream || {})[channel.to_s]
-      [true, "true", "1", "yes", "on"].include?(v)
+      Coercion.truthy?(v)
     end
   end
 end

data/lib/insika/alert_dispatcher.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require "digest"
+require "time"
+
+module Insika
+  # Operator alerts to a webhook (WS6): the events `:budget_warning`,
+  # `:breaker_open` and `:delivery_failed` are answered per AGENT — a profile
+  # declaring `alerts: { "webhook" => url }` gets its alerts POSTed there as
+  # JSON. The delivery reuses the outbox + claim mechanism whole
+  # (`ChannelDelivery`): the handler only WRITES the outbox row; the existing
+  # tick sweep and boot recovery claim and POST it, at-most-once with bounded
+  # retry, via a registered `Channels::Webhook`. The engine transports the event
+  # and does not interpret it — a Slack/CRM adapter is the consumer's.
+  #
+  # Started as a child of the turn supervisor (like the tick) in serving mode;
+  # tests drive `handle` directly.
+  class AlertDispatcher
+    ALERT_TYPES = %i[budget_warning breaker_open delivery_failed].freeze
+
+    def initialize(event_stream:, outbox:, channels:, profiles:, task_store: nil, http:)
+      @event_stream = event_stream
+      @outbox = outbox
+      @channels = channels
+      @profiles = profiles
+      @task_store = task_store
+      @http = http
+      @webhook_ids = {} # url -> registered channel id (one webhook per URL)
+      # WS6 (boot recovery): webhook channels are derived from PROFILE config,
+      # not from events. Registering lazily (on the first alert) means a pending
+      # outbox row a crashed process left is swept at boot against an EMPTY
+      # registry and marked failed terminal. Pre-registering every configured
+      # URL at wiring time lets the boot sweep find the channel and deliver.
+      register_all_webhooks
+    end
+
+    # Serving: a long-lived consumer that answers every alert event. Drains on
+    # the supervisor fiber (blocks on the queue — no spin), exactly like the tick.
+    # It subscribes TYPED (only the alert events enter its queue — it answers
+    # payloads a full-traffic stream would otherwise overflow away) and, on an
+    # overflow close, RE-SUBSCRIBES: a consumer that never re-binds is how alerts
+    # stop in silence (WS6).
+    def start(parent:)
+      parent.async do |t|
+        t.annotate("insika-alerts")
+        loop do
+          subscription = @event_stream.subscribe(types: ALERT_TYPES)
+          subscription.each { |event| handle(event) }
+          # the subscription closed (its overflow path) — alerts must not die here
+        end
+      end
+      true
+    end
+
+    # The event -> outbox row. Cheap (one transactional write); the DELIVERY is
+    # the tick's job. Never raises: an alerting failure must not break the turn.
+    def handle(event)
+      type = event.type.to_s.to_sym
+      return unless ALERT_TYPES.include?(type)
+
+      agent = agent_for(event)
+      return if agent.nil?
+
+      profile = @profiles.respond_to?(:fetch) ? @profiles.fetch(agent.to_s) : nil
+      return if profile.nil?
+
+      url = profile&.respond_to?(:alerts) ? profile.alerts&.dig("webhook") : nil
+      return if Coercion.blank?(url)
+
+      record_alert(agent: agent.to_s, url: url.to_s, event: event)
+    rescue StandardError
+      nil
+    end
+
+    private
+
+    # The agent the alert belongs to: the event carries it for the alerts the
+    # engine emits with context (budget_warning / breaker_open); a
+    # delivery_failed resolves its task's command. Guards the loop: a webhook's
+    # OWN delivery failing is not re-alerted.
+    def agent_for(event)
+      case event.type.to_sym
+      when :delivery_failed
+        channel = event.data[:channel]
+        return nil if channel.to_s.start_with?("webhook:") # loop guard
+        agent_for_task(event.meta[:task_id])
+      else
+        event.data[:agent] || agent_for_task(event.meta[:task_id])
+      end
+    end
+
+    def agent_for_task(task_id)
+      return nil if task_id.nil? || @task_store.nil?
+
+      task = @task_store.find(task_id.to_s)
+      command = task&.respond_to?(:command) ? task.command : nil
+      return nil unless command.is_a?(Hash)
+
+      payload = command["payload"] || command[:payload] || {}
+      payload["agent"] || payload[:agent]
+    rescue StandardError
+      nil
+    end
+
+    # The event's durable record, as the CHANNEL would see it. `to` is the
+    # webhook URL; `payload` is the event itself (type/data/meta).
+    def record_alert(agent:, url:, event:)
+      channel = webhook_id(url)
+      @outbox.create(
+        channel: channel, to: url,
+        task_id: event.meta[:task_id], session_id: event.meta[:session_id],
+        payload: { "type" => event.type.to_s, "data" => event.data,
+                   "meta" => event.meta, "agent" => agent }
+      )
+    end
+
+    # One channel per URL, registered so ChannelDelivery.sweep can claim it.
+    def webhook_id(url)
+      @webhook_ids[url] ||= begin
+        id = "webhook:#{Digest::SHA1.hexdigest(url)[0, 8]}"
+        @channels.register(id, Channels::Webhook.new(url, http: @http))
+        id
+      end
+    end
+
+    # Boot face of `webhook_id`: register every configured URL up front (at
+    # wiring time, before the boot recovery's channel sweep runs). The url is
+    # PROFILE data, so it is known before any alert ever fires.
+    def register_all_webhooks
+      profiles = @profiles.respond_to?(:all) ? @profiles.all : []
+      profiles.each do |profile|
+        next unless profile&.respond_to?(:alerts)
+
+        url = profile.alerts&.dig("webhook")
+        webhook_id(url.to_s) unless Coercion.blank?(url)
+      end
+    end
+  end
+end

data/lib/insika/baseline_store.rb

@@ -3,8 +3,8 @@
 require "time"
 
 module Insika
-  # The ACCEPTED state of an agent's golden set (RFC-0008 §3.4, promoted to a store
-  # by RFC-0013 §3.7.3). One record per agent in the ConfigStore (scope "baselines"):
+  # The ACCEPTED state of an agent's golden set (promoted to a store
+  # by). One record per agent in the ConfigStore (scope "baselines"):
   #
   #   { "at" => iso8601, "cases" => { "<case id>" => { "pass" => bool, "score" => n } } }
   #

data/lib/insika/budget_ledger.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module Insika
+  # Fixed-window spend counters for BUDGETS (WS2): the accounting layer the
+  # edge middleware rolls against. One scope, cells keyed
+  # "tenant:agent:window:calendar-bucket":
+  #
+  #   · DAILY    — the UTC calendar day (epoch/86400 IS midnight-aligned).
+  #   · MONTHLY  — (year * 12 + month) of the UTC calendar month: a budget month
+  #                is the CALENDAR month, however many days long it is (a fixed
+  #                N-day window drifts its bucket start across month lengths).
+  #                UTC like the daily, so both rollovers agree on any host.
+  #
+  # Built on the UsageLedger vocabulary (tenant/agent instead of kind/id) but
+  # on the store directly, with the increment riding `@store.transaction` — the
+  # exact read-modify-write discipline WS2's enforcement will build on. Two
+  # processes (or two SQLite handles) racing the same cell serialize on
+  # BEGIN IMMEDIATE: no lost update. No enforcement here — the middleware is
+  # WS2; this file is only correct accounting.
+  #
+  # Growth is bounded like UsageLedger: each `add` deletes the (id)'s previous
+  # day AND previous month cell, so an active scope holds at most 4 keys and an
+  # idle one converges to 2.
+  class BudgetLedger
+    SCOPE = "budget_counters"
+    ALERT_SCOPE = "budget_alerts"
+    DAY = 86_400
+
+    def initialize(store:)
+      @store = store
+    end
+
+    # Adds `by` across both windows; -> { daily:, monthly: } the NEW totals
+    # for (tenant, agent). Atomic per call: one transaction, both bumps.
+    def add(tenant:, agent:, by:, now: Time.now)
+      id = cell_id(tenant, agent)
+      @store.transaction do
+        daily = bump(id, daily_bucket(now), by)
+        monthly = bump(id, month_bucket(now), by)
+        @store.delete(SCOPE, key(id, daily_bucket(now - DAY)))   # previous day cell
+        @store.delete(SCOPE, key(id, month_bucket(now) - 1))     # previous calendar month cell
+        { daily: daily, monthly: monthly }
+      end
+    end
+
+    # -> { daily:, monthly: } current totals for (tenant, agent). Purely
+    # read; an expired window reads as 0 (rolls over at the boundary).
+    def current(tenant:, agent:, now: Time.now)
+      id = cell_id(tenant, agent)
+      { daily: @store.get(SCOPE, key(id, daily_bucket(now))).to_i,
+        monthly: @store.get(SCOPE, key(id, month_bucket(now))).to_i }
+    end
+
+    # Seconds until the window's bucket rolls over (the retry_after the
+    # enforcement quotes when a hard budget refuses a turn). Both windows are
+    # UTC-aligned (the daily via the epoch, the monthly via UTC components) so a
+    # non-UTC host never quotes a negative or local-midnight reset.
+    def reset_in(window, now: Time.now)
+      case window
+      when :daily then DAY - (now.to_i % DAY)
+      when :monthly then (next_utc_month_start(now) - now).to_i
+      end
+    end
+
+    # "1× per window" alert markers (the soft enforcement's event): a flag per
+    # (id, window, level, bucket) so a budget that stays over the threshold
+    # cannot spam one event per turn. `level:` separates DISTINCT triggers in
+    # the same window (WS2): the `alert_at` crossing and the real soft-cap
+    # crossing each warn once — the cap event must not be swallowed by the
+    # 80% marker having fired earlier. Marked/read in the same transaction
+    # discipline. -> bool: had the window already been marked?
+    def mark_alert(tenant:, agent:, window:, level: nil, now: Time.now)
+      id = cell_id(tenant, agent)
+      flag = alert_key(id, window, now, level)
+      @store.transaction do
+        # `next`, NOT `return`: a non-local return from inside the block skips
+        # the store's COMMIT and leaks the BEGIN IMMEDIATE open — the 2nd turn
+        # over a threshold then locks the whole backend (WS2).
+        next true unless @store.get(ALERT_SCOPE, flag).nil?
+
+        @store.set(ALERT_SCOPE, flag, 1)
+        false
+      end
+    end
+
+    def alerted?(tenant:, agent:, window:, level: nil, now: Time.now)
+      !@store.get(ALERT_SCOPE, alert_key(cell_id(tenant, agent), window, now, level)).nil?
+    end
+
+    private
+
+    # No tenant (single_tenant default) is a LITERAL "platform" cell, never a
+    # null-key collision with some other scope.
+    def cell_id(tenant, agent)
+      [tenant || "platform", agent].join(":")
+    end
+
+    def bump(id, bucket, by)
+      total = @store.get(SCOPE, key(id, bucket)).to_i + by
+      @store.set(SCOPE, key(id, bucket), total)
+      total
+    end
+
+    # the UTC calendar day's start (epoch is aligned to midnight UTC).
+    def daily_bucket(now)
+      (now.to_i / DAY) * DAY
+    end
+
+    # the UTC calendar month as one integer (2026-08 -> 24296). UTC, not local:
+    # the month boundary must agree with the daily epoch-day boundary on a
+    # non-UTC host (WS2), or the cap resets at a different moment than the day.
+    def month_bucket(now)
+      u = now.utc
+      u.year * 12 + u.month
+    end
+
+    # Midnight UTC of the 1st of the window's NEXT month — December-safe
+    # (Time.utc(y, 13, 1) raises; y+1/1 is the calendar answer).
+    def next_utc_month_start(now)
+      u = now.utc
+      u.month == 12 ? Time.utc(u.year + 1, 1, 1) : Time.utc(u.year, u.month + 1, 1)
+    end
+
+    def key(id, bucket)
+      "#{id}:#{bucket}"
+    end
+
+    # One alert flag per (id, window, level, calendar bucket): daily cells are
+    # keyed by day, monthly by (year*12+month) — a flag dies with its window.
+    def alert_key(id, window, now, level = nil)
+      bucket = window == :monthly ? month_bucket(now) : daily_bucket(now)
+      level ? "#{id}:#{window}:#{level}:#{bucket}" : "#{id}:#{window}:#{bucket}"
+    end
+  end
+end

data/lib/insika/channel_delivery.rb

@@ -3,7 +3,7 @@
 require "time"
 
 module Insika
-  # Hands a finished turn's answer to a Shape B channel (RFC-0011 §6.5). The turn
+  # Hands a finished turn's answer to a Shape B channel. The turn
   # ended; the recipient is not on any connection; the reply has to travel out of
   # band and survive a crash on the way. Three moves, in this order, and the order
   # is the whole design:
@@ -41,7 +41,7 @@ module Insika
     #   · the turn did not come in through a channel,
     #   · the channel is Shape A (answers on its own stream — no `deliver`),
     #   · the answer is empty (a turn that died mid-message published nothing, and
-    #     half a sentence was never an answer — P19),
+    #     half a sentence was never an answer),
     #   · or we do not know who to send it to.
     def record(task:, channel_id:, content:)
       return nil if content.to_s.strip.empty?
@@ -111,7 +111,7 @@ module Insika
     end
 
     # The consumer's own key for this conversation. Written into the session's vars
-    # when the channel minted it (§4.3); the channel's own id parser is the fallback
+    # when the channel minted it; the channel's own id parser is the fallback
     # for a session created before those vars existed.
     def recipient(channel, session_id)
       session = session_id && @session_store.find(session_id)
@@ -130,14 +130,17 @@ module Insika
     def emit(delivery)
       return unless @event_stream
 
-      @event_stream.emit(Insika::Event.new(
-                           type: :channel_delivered,
-                           data: { channel: delivery.channel, outbox_id: delivery.id,
-                                   status: delivery.status.to_s, attempts: delivery.attempts,
-                                   error: delivery.last_error },
-                           meta: { task_id: delivery.task_id, session_id: delivery.session_id,
-                                   at: Time.now.utc.iso8601 }
-                         ))
+      data = { channel: delivery.channel, outbox_id: delivery.id,
+               status: delivery.status.to_s, attempts: delivery.attempts,
+               error: delivery.last_error }
+      meta = { task_id: delivery.task_id, session_id: delivery.session_id,
+               at: Time.now.utc.iso8601 }
+      # :delivery_failed is the ALERT face of a failed delivery (WS6) — emitted
+      # alongside :channel_delivered so the delivery audit stream is unchanged.
+      @event_stream.emit(Insika::Event.new(type: :channel_delivered, data: data, meta: meta))
+      if delivery.status == :failed
+        @event_stream.emit(Insika::Event.new(type: :delivery_failed, data: data, meta: meta))
+      end
     end
 
     # Async when there is a reactor (production: the retry must not block the

data/lib/insika/channel_registry.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Insika
-  # The channels this deployment speaks, by id (RFC-0011 §4.2). A `Registry` like
+  # The channels this deployment speaks, by id. A `Registry` like
   # tools and workflows — same plugin bookkeeping, so `deregister_plugin` rolls a
   # half-registered plugin back exactly as it does for a tool.
   #

data/lib/insika/channels/relay.rb

@@ -8,7 +8,7 @@ require "uri"
 module Insika
   module Channels
     # The channel for an adopter who ALREADY owns a messaging integration
-    # (RFC-0011 §6). A WhatsApp BSP, a Zendesk, a legacy Rails app: they want the
+    # A WhatsApp BSP, a Zendesk, a legacy Rails app: they want the
     # engine for the TURN, not for the platform. Two routes and an envelope —
     #
     #   consumer --POST /channels/relay/events--> engine   acked now, never the reply
@@ -16,7 +16,7 @@ module Insika
     #
     # — and everything platform-shaped stays theirs: the 24-hour window, template
     # approval, media, read receipts, and how markdown becomes WhatsApp formatting
-    # (§6.3). That is the promise, not the limitation: an integration someone has
+    # That is the promise, not the limitation: an integration someone has
     # already tuned for years does not have to move for them to adopt the engine.
     # A relay that starts growing template logic has stopped being a relay.
     #
@@ -106,7 +106,7 @@ module Insika
           event_id: presence(body["event_id"]), vars: vars }
       end
 
-      # RFC-0011 §4.3 — the engine namespaces the platform's conversation key, so a
+      # the engine namespaces the platform's conversation key, so a
       # Slack channel id and a phone number can never collide, an operator can see
       # where a conversation came from, and an id minted for one channel cannot be
       # used to read another's session.

data/lib/insika/channels/web/widget.js

@@ -1,4 +1,4 @@
-// Insika web widget (RFC-0011 §5.2).
+// Insika web widget.
 //
 // One <script> tag, no framework, no build step, no dependency:
 //
@@ -176,7 +176,7 @@
   }
 
   // The engine issues the session id; we only ever store the one it gave us
-  // (RFC-0011 §4.3 — a client that proposes its own id on a public endpoint is
+  // (a client that proposes its own id on a public endpoint is
   // one enumeration away from reading someone else's conversation).
   function session() {
     var saved = remembered;