insika 0.0.1 → 0.2.0

data/lib/insika/chat_builder.rb

@@ -0,0 +1,303 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  # Assembles the turn's chat (pipeline stages 5-7): instructions, eager/deferred
+  # tool partition, system tools (tool_search/load_skill/remember),
+  # history and callbacks. Extracted from the Executor so it can coordinate the
+  # pipeline without also carrying the RubyLLM glue.
+  #
+  # The Executor creates the chat (stage 6, the RubyLLM boundary) and passes it
+  # here to be configured; event numbering (monotonic seq per task) stays in the
+  # Executor, injected as the `emit` callable.
+  class ChatBuilder
+    def initialize(tool_registry:, skill_catalog:, checkpoint_store:, event_stream:,
+                   hooks:, tool_catalog: nil, memory_store: nil, subagent_runner: nil,
+                   tool_trace_store: nil)
+      @tool_registry = tool_registry
+      @skill_catalog = skill_catalog
+      @checkpoint_store = checkpoint_store
+      @event_stream = event_stream
+      @hooks = hooks
+      @tool_catalog = tool_catalog
+      @memory_store = memory_store
+      # only to trace load_skill, which is not enveloped — nil = no trace (parity).
+      @tool_trace_store = tool_trace_store
+      # the object exposing #run_subagent (the Executor). nil = the
+      # spawn_subagent system tool is never wired (parity for a builder used
+      # without delegation, e.g. some unit stubs).
+      @subagent_runner = subagent_runner
+    end
+
+    # Configures an already-created chat with the context (stage 2) and the
+    # Resolution (stage 3), seeds the history and wires the callbacks. `emit` is
+    # the Executor's emitter (seq+task correlation), called as emit.call(type,
+    # data). The system tools (Tools::ToolSearch/LoadSkill/Remember) were already
+    # lazy-loaded by Executor#create_chat before reaching here.
+    def assemble(chat, state, emit:)
+      configure_chat(chat, state)
+      seed_history(chat, Array(state.context.history))
+      wire_callbacks(chat, state, emit)
+      chat
+    end
+
+    # Assembles the chat with the context (stage 2) and the Resolution's tools (stage 3).
+    def configure_chat(chat, state)
+      system = state.context.system.to_s
+      apply_instructions(chat, system, state) unless system.empty?
+
+      tools = Array(state.allowed_tools).dup
+
+      # Tool Search: the partition only runs with @tool_catalog present (parity
+      # when nil — the `&&` short-circuits before reading `.name`).
+      # `deferred_allowed` = allowed_tools ∩ tools_deferred. The <available_tools>
+      # catalog comes from Context::Providers::ToolSearch (stage 2); here we only
+      # decide chat.tools.
+      deferred_allowed = if @tool_catalog
+                           Array(state.profile.tools_deferred).map(&:to_s) &
+                             tools.map { |t| t.name.to_s }
+                         else
+                           []
+                         end
+
+      unless deferred_allowed.empty?
+        tools.reject! { |t| deferred_allowed.include?(t.name.to_s) }
+        # a system tool (outside the allowlist), like load_skill — never enveloped.
+        tools << Tools::ToolSearch.new(@tool_catalog, deferred_allowed, chat,
+                                       tool_registry: @tool_registry,
+                                       checkpoint_store: @checkpoint_store,
+                                       event_stream: @event_stream, state: state)
+      end
+
+      # load_skill is a system default (outside the allowlist), otherwise
+      # progressive disclosure breaks. allowed_skills comes from the Resolution
+      # (policy), minus the EAGER ones: their bodies are already in the prompt, so a
+      # call could only pay for a duplicate. Nothing lazy left -> the tool is not
+      # wired at all. Keeping it for the discretionary skills is deliberate: that
+      # call is the only record of which skill the model actually reached for.
+      skill_names = lazy_skill_names(state)
+      unless skill_names.empty?
+        tools << Tools::LoadSkill.new(@skill_catalog, skill_names,
+                                      trace_recorder: @tool_trace_store, state: state,
+                                      agent: state.profile.id)
+      end
+
+      # remember is the memory-write system tool — wired only with
+      # @memory_store present AND profile.memory (a double gate). Never enveloped.
+      if @memory_store && state.profile.memory
+        tools << Tools::Remember.new(@memory_store, state.tenant,
+                                     event_stream: @event_stream, state: state)
+      end
+
+      # signal_stuck is the "I cannot proceed" system tool (WS5) — wired only
+      # when the agent opted in (`profile.stuck_signal`), never enveloped. It is a
+      # deterministic signal; the consumer decides what "stuck" means. Defensive
+      # read: a minimal profile double without the reader means off (nil = parity).
+      if state.profile.respond_to?(:stuck_signal) && state.profile.stuck_signal
+        tools << Tools::StuckSignal.new(state: state)
+      end
+
+      # spawn_subagent is the delegation system tool — wired only with a
+      # runner present AND profile.subagents non-empty (a double gate, like
+      # remember). Never enveloped: in the synchronous mode the child lives in the
+      # parent's envelope. The runtime gate on WHICH agent is spawnable is the
+      # parent's subagents allowlist, enforced in Executor#run_subagent.
+      if @subagent_runner && !Array(state.profile.subagents).empty?
+        tools << Tools::Subagent.new(runner: @subagent_runner, state: state)
+        # and its parallel sibling: fan-out N children at once.
+        tools << Tools::Subagents.new(runner: @subagent_runner, state: state)
+      end
+
+      unless tools.empty?
+        # the ONLY place the gem is told to run tool calls in parallel.
+        # `:fibers` is not a preference but the only admissible mode — `:threads`
+        # breaks ToolEnvelope's `Async::Task.current.with_timeout`, the SQLite
+        # store's fiber semaphore, and the turn's own durability (mailbox,
+        # approvals, cancellation are all expressed in fiber terms). The number
+        # the operator configured is OUR cap (ToolAssembly#install_tool_gate);
+        # the gem has none.
+        if tool_concurrency_for(state)
+          chat.with_tools(*tools, concurrency: :fibers)
+        else
+          chat.with_tools(*tools)
+        end
+      end
+
+      chat
+    end
+
+    # The skills the model still has to ask for: the Resolution's set minus the eager
+    # ones. Intersected by NAME against the catalog's own verdict (SkillCatalog#eager_for)
+    # so the tool and the level-1 list can never disagree about who is eager. A catalog
+    # without the reader (a unit stub) falls back to the whole set — parity.
+    def lazy_skill_names(state)
+      names = Array(state.allowed_skills).map { |s| s.respond_to?(:name) ? s.name : s.to_s }
+      return names unless @skill_catalog.respond_to?(:eager_for)
+
+      eager = @skill_catalog.eager_for(state.profile).map(&:name)
+      names - eager
+    end
+
+    # The turn's effective tool concurrency (nil = serial), plus the ONE thing the
+    # gate owes the operator: when the profile asked for parallel tool calls and
+    # this turn silently cannot have them (an approval-required tool would
+    # deadlock two fibers on the single per-task mailbox), say so once. Otherwise
+    # the speedup just vanishes with no reason given. The rule itself lives in
+    # TurnState; a state predating those readers (a unit stub) means off.
+    def tool_concurrency_for(state)
+      return nil unless state.respond_to?(:tool_concurrency)
+
+      effective = state.tool_concurrency
+      return effective if effective
+
+      requested = state.requested_tool_concurrency
+      warn_tool_concurrency_gated(state, requested) if requested
+      nil
+    end
+
+    def warn_tool_concurrency_gated(state, requested)
+      gated = Array(state.requires_approval)
+      @event_stream.emit(Insika::Event.new(
+                           type: :provider_warning,
+                           data: { provider: "tool_concurrency",
+                                   message: "parallel tool calls (#{requested}) disabled for this turn: " \
+                                            "#{gated.size} tool(s) require approval (#{gated.join(', ')})" },
+                           meta: { task_id: state.task&.id, at: Time.now.utc.iso8601 }
+                         ))
+    end
+
+    # R3: opt-in Anthropic prompt caching. When the agent enables
+    # prompt_caching AND the resolved provider is Anthropic, wrap the system in
+    # the provider's native Content helper with cache: true — ONE breakpoint at
+    # the END of the system block. By Anthropic's prefix order
+    # (tools -> system -> messages), a breakpoint on the last system block caches
+    # tools + system together and is immune to history eviction (messages come
+    # after it). RubyLLM::Content::Raw is Anthropic-specific: build_system_content
+    # emits its blocks verbatim, so the cache_control rides along.
+    #
+    # Any other case (caching off, or a non-Anthropic provider) uses the plain
+    # string — OpenAI caches its prefix on its own; the Raw shape would confuse
+    # non-Anthropic providers. The gem only supports MANUAL caching, and only for
+    # Anthropic.
+    #
+    # PRE-AUDIT (why this is opt-in): the system must be BYTE-STABLE between turns
+    # for a read hit. A context provider that injects volatile content into
+    # :system (timestamps, per-turn data) makes every turn a paid cache WRITE
+    # with no hit — worse than off. Enable only for stable-system agents.
+    def apply_instructions(chat, system, state)
+      if state.profile.prompt_caching && anthropic_provider?(chat)
+        chat.with_instructions(RubyLLM::Providers::Anthropic::Content.new(system, cache: true))
+      else
+        chat.with_instructions(system)
+      end
+    end
+
+    # The RESOLVED provider (chat.model.provider is the slug string, e.g.
+    # "anthropic"), authoritative even when the agent left provider nil and
+    # RubyLLM inferred it from the model id. Any surface without a model (fakes,
+    # a provider that raises) -> false: caching silently stays off.
+    def anthropic_provider?(chat)
+      chat.respond_to?(:model) && chat.model && chat.model.provider.to_s == "anthropic"
+    rescue StandardError
+      false
+    end
+
+    # History comes from the context/checkpoint. The {role:, content:} shape
+    # tolerates string keys (JSON from the stores). `flatten(1)` dissolves the
+    # Session provider's "eviction units" (an assistant+tool_results cycle grouped
+    # as one Array, R1) back into a flat message stream.
+    #
+    # tool_calls / tool_call_id are rehydrated ONLY when present, so a message
+    # without them keeps the 2-arg shape the specs' FakeChat expects (no unknown
+    # keyword). This is what lets the model SEE the tools it already called.
+    def seed_history(chat, messages)
+      Array(messages).flatten(1).each do |m|
+        attrs = { role: (m[:role] || m["role"]).to_sym, content: m[:content] || m["content"] }
+        tool_calls = m[:tool_calls] || m["tool_calls"]
+        tool_call_id = m[:tool_call_id] || m["tool_call_id"]
+        attrs[:tool_calls] = rehydrate_tool_calls(tool_calls) if tool_calls && !Array(tool_calls).empty?
+        attrs[:tool_call_id] = tool_call_id if tool_call_id
+        chat.add_message(**attrs)
+      end
+    end
+
+    # [{id,name,arguments}] (string|symbol keys) -> {id => RubyLLM::ToolCall}, the
+    # shape RubyLLM seeds an assistant message with. Called only when the gem is
+    # already loaded (create_chat required it before assemble).
+    def rehydrate_tool_calls(list)
+      Array(list).each_with_object({}) do |tc, acc|
+        id = (tc[:id] || tc["id"]).to_s
+        acc[id] = RubyLLM::ToolCall.new(
+          id: id, name: (tc[:name] || tc["name"]).to_s,
+          arguments: tc[:arguments] || tc["arguments"] || {}
+        )
+      end
+    end
+
+    # RubyLLM's additive callbacks become events. load_skill becomes
+    # :skill_activated. Adds the max_tool_calls counter: the loop is RubyLLM's;
+    # here we only count and abort.
+    def wire_callbacks(chat, state, emit)
+      # Per-TURN counter: safe as a closure local even under concurrent tool calls
+      # (MRI fibers do not preempt between the read and the write). The per-CALL
+      # correlation is NOT — it lives in fiber storage behind TurnState, because
+      # each call gets its own fiber once tool concurrency is on.
+      tool_calls = 0
+      max_tool_calls = state.profile.limits[:max_tool_calls] || 50
+
+      # the loop detector. Needs #after_message + #add_message for the
+      # batch-boundary intervention; a chat without them (smoke shim, minimal
+      # double) stays bounded by max_tool_calls alone — never half-wired.
+      detector = if %i[after_message add_message].all? { |m| chat.respond_to?(m) }
+                   repeat = state.profile.limits[:max_tool_repeat] || Insika::AgentProfile::DEFAULT_LIMITS[:max_tool_repeat]
+                   Insika::LoopDetector.new(chat: chat, limit: repeat, emit: emit) if repeat >= 2
+                 end
+
+      chat.before_tool_call do |tool_call|
+        # call<->decorator correlation (side-effects/skip) — 1st line.
+        state.current_tool_call = tool_call
+        # max_tool_calls guard-rail: stays inline (not as a registered hook)
+        # because Hooks is shared across turns and has no unregister.
+        tool_calls += 1
+        if tool_calls > max_tool_calls
+          raise Insika::TimeoutError.new("tool call limit exceeded (#{max_tool_calls})",
+                                           stage: :tool_limit)
+        end
+
+        # AFTER the count, BEFORE the call runs — a post-warning
+        # repeat raises here, so the stubborn loop pays for no extra call.
+        detector&.tool_call(tool_call.name, tool_call.arguments)
+
+        # :tool pair: RubyLLM's callbacks are additive — the altered subject
+        # feeds later hooks and the events, but does not rewrite the call the
+        # model executes. A hook exception here aborts the turn.
+        tool_call = @hooks.run_before(:tool, tool_call)
+
+        # The name of the (possibly hook-altered) subject, for the :tool_result
+        # label. Also fiber-scoped: as a closure local it belonged to the TURN, so
+        # under concurrency `after_tool_result` labelled every result with whichever
+        # call started last.
+        state.current_tool_name = tool_call.name.to_s
+        if state.current_tool_name == "load_skill"
+          args = tool_call.arguments || {}
+          emit.call(:skill_activated, { name: args["name"] || args[:name] })
+        else
+          emit.call(:tool_call, { name: tool_call.name, arguments: tool_call.arguments })
+        end
+      end
+
+      chat.after_tool_result do |result|
+        # the RAW result — the only place a Tool::Halt (halt_when) is
+        # still recognizable, and a halted batch must receive no intervention.
+        detector&.tool_result(result)
+        result = @hooks.run_after(:tool, result)
+        emit.call(:tool_result, { name: state.current_tool_name, result: result.to_s })
+      end
+
+      # the intervention appends at the batch boundary (the Nth tool
+      # result closing) — never between two tool results of one batch.
+      chat.after_message { |message| detector.message_ended(message) } if detector
+    end
+  end
+end

data/lib/insika/checkpoint.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Insika
+  # Per-turn snapshot. The checkpoint of
+  # turn n holds the state AT THE START of turn n — resuming = re-executing the
+  # whole turn n. `messages` is the MATERIALIZED transcript (not a cursor): the
+  # checkpoint is self-contained and resumption does not depend on the Session Store.
+  #
+  # `completed_side_effects`: ids of non-idempotent tool calls already completed
+  # within the turn (resumption answers them with "already_executed").
+  Checkpoint = Data.define(:task_id, :turn, :session_id, :agent_id,
+                           :messages, :completed_side_effects, :created_at)
+end

data/lib/insika/checkpoint_store.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  # Domain store for checkpoints. A per-turn snapshot written
+  # in an ALL-OR-NOTHING transaction (invariant: a checkpoint is either fully
+  # valid or does not exist), a record of non-idempotent side effects in a spill
+  # key during the turn, and `prune` to bound growth.
+  #
+  # Two key families in the "checkpoints" scope:
+  #   "checkpoint:<task_id>:turn:<n>"  -> Checkpoint JSON
+  #   "sideeffects:<task_id>:turn:<n>" -> ["tool_call_id", ...] (spill key)
+  #
+  # The spill key exists because the turn's checkpoint does not exist yet when
+  # the tool calls run (it is only saved at stage 8): it is written BEFORE the
+  # tool result goes back to the model, and the following `save` consolidates it
+  # into `completed_side_effects` and deletes it in the SAME transaction.
+  class CheckpointStore
+    include Coercion
+
+    SCOPE = "checkpoints"
+
+    def initialize(store:)
+      @store = store
+    end
+
+    # -> Checkpoint (with the consolidated side-effect list). ALWAYS in a
+    # transaction. Order: validate monotonicity -> consolidate the previous
+    # turn's spill key -> write the checkpoint -> delete the absorbed spill key.
+    # Any exception in the middle -> full rollback (neither a partial checkpoint
+    # nor a lost spill key).
+    def save(checkpoint)
+      @store.transaction do
+        current = latest(checkpoint.task_id)
+        if current && current.turn >= checkpoint.turn
+          raise ArgumentError,
+                "checkpoint with non-monotonic turn: #{checkpoint.turn} <= #{current.turn}"
+        end
+
+        # Stage 8 of turn n saves turn n+1's checkpoint:
+        # the spill key to absorb is that of the turn that just executed (n).
+        spill_key = sideeffects_key(checkpoint.task_id, checkpoint.turn - 1)
+        spilled = @store.get(SCOPE, spill_key) || []
+        consolidated = Array(checkpoint.completed_side_effects).map(&:to_s) | spilled
+
+        record = deep_stringify(checkpoint.to_h)
+        record["completed_side_effects"] = consolidated
+        record["created_at"] ||= timestamp
+        @store.set(SCOPE, checkpoint_key(checkpoint.task_id, checkpoint.turn), record)
+        @store.delete(SCOPE, spill_key)
+
+        to_checkpoint(record)
+      end
+    end
+
+    # -> Checkpoint | nil (highest turn). NUMERIC ordering: `list` sorts
+    # lexicographically and "turn:9" > "turn:10" — parse n as an Integer.
+    def latest(task_id)
+      turns = checkpoint_turns(task_id)
+      return nil if turns.empty?
+
+      find(task_id, turn: turns.max)
+    end
+
+    # -> Checkpoint | nil
+    def find(task_id, turn:)
+      record = @store.get(SCOPE, checkpoint_key(task_id, turn))
+      record && to_checkpoint(record)
+    end
+
+    # -> nil; idempotent (recording twice = one entry). In a transaction
+    # (written before the tool goes back to the model).
+    def record_side_effect(task_id, turn:, tool_call_id:)
+      @store.transaction do
+        key = sideeffects_key(task_id, turn)
+        ids = @store.get(SCOPE, key) || []
+        id = tool_call_id.to_s
+        @store.set(SCOPE, key, ids + [id]) unless ids.include?(id)
+      end
+      nil
+    end
+
+    # -> [tool_call_id] = spill key ∪ checkpoint of the same turn.
+    # Covers both places where an id may live during the cycle; since
+    # tool_call_id is globally unique, the union never causes an improper skip.
+    def side_effects(task_id, turn:)
+      spilled = @store.get(SCOPE, sideeffects_key(task_id, turn)) || []
+      from_checkpoint = find(task_id, turn: turn)&.completed_side_effects || []
+      spilled | from_checkpoint
+    end
+
+    # -> void. Keeps the `keep` checkpoints with the highest turn (numeric); deletes the
+    # rest. Also clears spill keys of turns strictly smaller than the smallest
+    # kept turn (unreachable garbage after consolidation). In a transaction
+    # so it never leaves a partial prune. No-op if there are <= keep checkpoints.
+    def prune(task_id, keep: 1)
+      @store.transaction do
+        turns = checkpoint_turns(task_id).sort
+        next if turns.size <= keep
+
+        kept = turns.last(keep)
+        smallest_kept = kept.first
+        (turns - kept).each { |n| @store.delete(SCOPE, checkpoint_key(task_id, n)) }
+        sideeffect_turns(task_id).each do |n|
+          @store.delete(SCOPE, sideeffects_key(task_id, n)) if n < smallest_kept
+        end
+      end
+      nil
+    end
+
+    private
+
+    def checkpoint_key(task_id, turn)
+      "checkpoint:#{task_id}:turn:#{turn}"
+    end
+
+    def sideeffects_key(task_id, turn)
+      "sideeffects:#{task_id}:turn:#{turn}"
+    end
+
+    def checkpoint_turns(task_id)
+      @store.list(SCOPE, "checkpoint:#{task_id}:turn:").map { |k| turn_of(k) }
+    end
+
+    def sideeffect_turns(task_id)
+      @store.list(SCOPE, "sideeffects:#{task_id}:turn:").map { |k| turn_of(k) }
+    end
+
+    # n is the last segment of the key "...:turn:<n>"; parse it as an Integer.
+    def turn_of(key)
+      key.split(":").last.to_i
+    end
+
+    # Materializes at the edge: `turn` as an Integer; the other fields as they come from the
+    # backend (string keys in `messages`).
+    def to_checkpoint(record)
+      Checkpoint.new(
+        task_id: record["task_id"],
+        turn: record["turn"].to_i,
+        session_id: record["session_id"],
+        agent_id: record["agent_id"],
+        messages: record["messages"],
+        completed_side_effects: record["completed_side_effects"],
+        created_at: record["created_at"]
+      )
+    end
+
+    def timestamp
+      Time.now.utc.iso8601
+    end
+  end
+end

data/lib/insika/circuit_state.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  # The circuit breaker's durable state (WS3): one cell per
+  # (tenant, provider/model ref) holding the recent failures and when the
+  # circuit opened. The read-modify-write rides `@store.transaction` — the same
+  # discipline as the dispatch claim (A1): two concurrent failures of the same
+  # cell serialize, so the "10 failures in 60s" count is never lost to a race.
+  #
+  # States, standard semantics:
+  #   :closed    fewer than `after` failures in the `within` window — attempts flow.
+  #   :open      the window count is met AND the cooldown hasn't elapsed — the
+  #              edge FAIL-FASTS (no provider call) with retry_after = remaining
+  #              cooldown. Reached at the `after`-th failure, which stamps
+  #              opened_at.
+  #   :half_open the cooldown elapsed — the next attempt is the TRIAL: a success
+  #              closes (record_success clears the cell), a failure reopens
+  #              (a new failure count / opened_at).
+  class CircuitState
+    SCOPE = "circuit_state"
+
+    # Timestamps are pruned to COUNT_LIMIT — a pathological loop cannot grow the
+    # cell unboundedly (the window is 60s-wide; 100 reads and writes bounded).
+    COUNT_LIMIT = 100
+
+    Record = Data.define(:failures, :opened_at)
+
+    def initialize(store:)
+      @store = store
+    end
+
+    # Records ONE failure for (tenant, ref). If this failure makes the window
+    # reach `after` and the circuit is not already open, it stamps opened_at
+    # (the instant the breaker trips). -> :closed (still closed) | :open (JUST
+    # tripped — closed->open, the ONLY transition that alerts) | :reopened (an
+    # already-tripped cell re-stamped: a half-open trial failed; the circuit is
+    # open again but the node already told the operator it is sick — no NEW
+    # alert (WS3)).
+    def record_failure(tenant:, ref:, after: 10, within: 60, now: Time.now)
+      key = key_for(tenant, ref)
+      @store.transaction do
+        record = load(key)
+        cutoff = (now.to_i - within)
+        retained = record.failures.select { |t| t > cutoff }.last(COUNT_LIMIT)
+        failures = (retained + [now.to_i]).last(COUNT_LIMIT)
+        opened_at = record.opened_at
+        tripped = :closed
+        if opened_at.nil?
+          if failures.size >= after
+            opened_at = now.to_i
+            tripped = :open
+          end
+        else
+          # the circuit was tripped before; a failure here can only be a HALF-OPEN
+          # trial that failed. Re-stamp opened_at so it RE-OPENS — a breaker that
+          # never restamps is one-shot: after the first cooldown every later turn
+          # is an unlocked half-open trial (WS3).
+          opened_at = now.to_i
+          tripped = :reopened
+        end
+        @store.set(SCOPE, key, { "failures" => failures, "opened_at" => opened_at })
+        tripped
+      end
+    end
+
+    # A successful attempt CLOSES the circuit: the cell is cleared so the
+    # failure window starts fresh (half-open trial success included).
+    def record_success(tenant:, ref:)
+      @store.delete(SCOPE, key_for(tenant, ref))
+    end
+
+    # -> :closed | :open | :half_open
+    def state(tenant:, ref:, after: 10, within: 60, cooldown: 300, now: Time.now)
+      record = load(key_for(tenant, ref))
+      opened = record.opened_at.to_i
+      # :closed needs BOTH doors shut: the window count is under `after` AND the
+      # circuit never tripped. A surviving opened_at tombstone keeps the circuit
+      # governed by the cooldown (open, then half-open) even after its original
+      # failures age out of the rolling window — only a SUCCESS clears it (WS3:
+      # a failed half-open trial must reopen, not silently close).
+      return :closed if record.failures.size < after && opened.zero?
+
+      return :open if opened.zero? || (now.to_i - opened) < cooldown
+
+      :half_open
+    end
+
+    # Seconds until the circuit can be retried (the remaining cooldown). nil
+    # while closed.
+    def retry_after(tenant:, ref:, cooldown: 300, now: Time.now)
+      record = load(key_for(tenant, ref))
+      return nil if record.failures.empty?
+
+      opened = record.opened_at.to_i
+      return nil if opened.zero?
+
+      remaining = cooldown - (now.to_i - opened)
+      remaining.positive? ? remaining : nil
+    end
+
+    private
+
+    def key_for(tenant, ref) = "#{tenant || 'platform'}:#{ref}"
+
+    def load(key)
+      record = @store.get(SCOPE, key)
+      return Record.new([], nil) if record.nil?
+
+      Record.new(Array(record["failures"]), record["opened_at"])
+    end
+  end
+end

data/lib/insika/coercion.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Insika
+  # Shared coercions at the input/persistence boundary. They used to live
+  # copied in each store/handler; a single home keeps them from drifting.
+  module Coercion
+    module_function
+
+    # Present string or nil: nil and blank (incl. whitespace-only) become nil;
+    # everything else becomes a stripped String.
+    def presence(str)
+      s = str.to_s.strip
+      s.empty? ? nil : s
+    end
+
+    # nil or blank (incl. whitespace-only) -> true.
+    def blank?(value) = value.nil? || value.to_s.strip.empty?
+
+    # Inverse of blank? — a usable, non-empty value.
+    def present?(value) = !blank?(value)
+
+    # The operator-facing truthy: what a form checkbox ("1"), a JSON round-trip
+    # ("true") or the DSL (true) produce for an opt-in. One list, one reading —
+    # AgentProfile#stream_public?, SkillCatalog#blanket? and the Studio all consult
+    # it, so a value that opts in on one surface cannot opt out on another.
+    TRUTHY = [true, "true", "1", "yes", "on"].freeze
+
+    def truthy?(value) = TRUTHY.include?(value)
+
+    # Bytes that come from outside the engine (sockets, pipes, subprocesses)
+    # arrive tagged BINARY, or as UTF-8 carrying invalid sequences. Both break
+    # `JSON.generate` the moment the text has an accent or an emoji — today a
+    # warning ("UTF-8 string passed as BINARY"), an exception from json 3.0 — and
+    # that text ends up in a transcript, an event and an SSE frame. Reinterprets
+    # the bytes as UTF-8 (the wire encoding of every source we read) and scrubs
+    # what is not valid, so what crosses the boundary is always serializable.
+    def utf8(str)
+      s = str.to_s
+      s = s.dup.force_encoding(Encoding::UTF_8) unless s.encoding == Encoding::UTF_8
+      s.valid_encoding? ? s : s.scrub
+    end
+
+    # Normalizes keys and Symbols to String recursively (the stores' JSON model
+    # has no Symbol). Hash -> keys and values; Array -> elements.
+    def deep_stringify(obj)
+      case obj
+      when Hash
+        obj.each_with_object({}) { |(k, v), acc| acc[k.to_s] = deep_stringify(v) }
+      when Array
+        obj.map { |v| deep_stringify(v) }
+      when Symbol
+        obj.to_s
+      else
+        obj
+      end
+    end
+  end
+end

data/lib/insika/command.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "time"
+
+module Insika
+  # Every mutating interaction becomes a Command. Shared shape:
+  #   type:    Symbol (:create_session, :send_message, :trigger_workflow,
+  #                    :cancel_task, :resume_task)
+  #   payload: Hash validated by the handler
+  #   meta:    { command_id:, tenant:, transport:, issued_at: }
+  #
+  # `Command` does not validate payload (that's the handler's job) and does not
+  # know about the bus.
+  Command = Data.define(:type, :payload, :meta) do
+    # Factory that fills in the meta defaults. `type` is
+    # normalized to Symbol; a nil `payload` becomes {} (the handler decides
+    # whether required fields are missing).
+    def self.build(type, payload = {}, transport: :internal, tenant: nil)
+      new(
+        type: type.to_sym,
+        payload: payload || {},
+        meta: {
+          command_id: SecureRandom.uuid,
+          tenant: tenant,
+          transport: transport,
+          issued_at: Time.now.utc.iso8601
+        }
+      )
+    end
+  end
+end