insika 0.1.0 → 0.2.0

data/lib/insika/commands/issue_tenant_token.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Insika
+  module Commands
+    # WS1: issues a PER-TENANT token (multi_tenant mode). Operator-only BY
+    # CONSTRUCTION: the edge refuses a tenant principal on POST /v1/commands
+    # (403), and an internal command stamped with a tenant is refused here —
+    # a tenant can never mint credentials. The plaintext token is the response
+    # and exists nowhere else; the store keeps only its hash. -> Issue.to_h.
+    class IssueTenantToken
+      def initialize(token_store:, event_stream:)
+        @token_store = token_store
+        @event_stream = event_stream
+      end
+
+      def call(command)
+        raise Insika::ValidationError, "token commands are operator-only" if command.meta[:tenant]
+
+        tenant_id = Insika::Coercion.presence(
+          command.payload[:tenant_id] || command.payload["tenant_id"]
+        )
+        raise Insika::ValidationError, "tenant_id is required" if tenant_id.nil?
+
+        label = command.payload[:label] || command.payload["label"] || "default"
+        issue = @token_store.issue(tenant_id: tenant_id, label: label)
+        emit(issue.id, tenant_id)
+        { token: issue.token, id: issue.id, tenant_id: tenant_id, label: label.to_s }
+      end
+
+      private
+
+      def emit(token_id, tenant_id)
+        @event_stream.emit(Insika::Event.new(
+                             type: :tenant_token_issued,
+                             data: { token_id: token_id, tenant_id: tenant_id },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+      end
+    end
+  end
+end

data/lib/insika/commands/resolve_refinement.rb

@@ -4,7 +4,7 @@ require "time"
 
 module Insika
   module Commands
-    # Control command (RFC-0013 §3.6): the human's answer to a gated proposal.
+    # Control command: the human's answer to a gated proposal.
     #
     #   approve -> each edit is written through `AgentFileStore#write`, which pushes
     #              the previous content into `history`. Rollback is therefore already

data/lib/insika/commands/revoke_token.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Insika
+  module Commands
+    # WS1: revokes ONE token by id. The edge resolves tokens by hash, so the
+    # plaintext is not needed to kill a credential. Idempotent: revoking an
+    # already-revoked or unknown id -> { revoked: false }, never an error.
+    # -> { id:, revoked: bool }.
+    class RevokeToken
+      def initialize(token_store:, event_stream:)
+        @token_store = token_store
+        @event_stream = event_stream
+      end
+
+      def call(command)
+        raise Insika::ValidationError, "token commands are operator-only" if command.meta[:tenant]
+
+        id = Insika::Coercion.presence(
+          command.payload[:token_id] || command.payload["token_id"]
+        )
+        raise Insika::ValidationError, "token_id is required" if id.nil?
+
+        revoked = @token_store.revoke(id)
+        emit(id, revoked)
+        { id: id, revoked: revoked }
+      end
+
+      private
+
+      def emit(token_id, revoked)
+        @event_stream.emit(Insika::Event.new(
+                             type: :tenant_token_revoked,
+                             data: { token_id: token_id, revoked: revoked },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+      end
+    end
+  end
+end

data/lib/insika/commands/rotate_tenant_token.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Insika
+  module Commands
+    # WS1: rotates a tenant's credential — revokes every active token of the
+    # tenant and issues a fresh one, in ONE transaction (a crashed half-rotation
+    # must never leave the tenant with nothing valid). Only the tenant's own
+    # tokens are touched; the operator token and other tenants are untouched.
+    # -> { revoked: n, token: Issue.to_h }.
+    class RotateTenantToken
+      def initialize(token_store:, event_stream:)
+        @token_store = token_store
+        @event_stream = event_stream
+      end
+
+      def call(command)
+        raise Insika::ValidationError, "token commands are operator-only" if command.meta[:tenant]
+
+        tenant_id = Insika::Coercion.presence(
+          command.payload[:tenant_id] || command.payload["tenant_id"]
+        )
+        raise Insika::ValidationError, "tenant_id is required" if tenant_id.nil?
+
+        label = command.payload[:label] || command.payload["label"] || "default"
+        result = @token_store.rotate(tenant_id: tenant_id, label: label)
+        issue = result[:issue]
+        emit(issue.id, tenant_id, result[:revoked])
+        { revoked: result[:revoked],
+          token: { token: issue.token, id: issue.id, tenant_id: tenant_id, label: label.to_s } }
+      end
+
+      private
+
+      def emit(token_id, tenant_id, revoked)
+        @event_stream.emit(Insika::Event.new(
+                             type: :tenant_token_rotated,
+                             data: { token_id: token_id, tenant_id: tenant_id, revoked: revoked },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+      end
+    end
+  end
+end

data/lib/insika/commands/run_refinement.rb

@@ -4,11 +4,11 @@ require "time"
 
 module Insika
   module Commands
-    # Control command (RFC-0013 phase A): reads a window of the agent's real traffic
+    # Control command: reads a window of the agent's real traffic
     # and records a ranked failure REPORT. Synchronous — it only scans durable stores
     # (no provider call, no fiber), so it answers with the Run and does not create a
     # Task. It is the ONLY way a refinement run starts: the CLI, the Studio button
-    # and any external cron all dispatch this one command (§3.10 — there is no
+    # and any external cron all dispatch this one command (there is no
     # scheduler in the engine).
     #
     # Payload:
@@ -23,8 +23,8 @@ module Insika
     # the previous run for this agent, unless `full`) -> the agent's configured
     # `refinement.window` -> the collector's default.
     #
-    # Phase A writes NOTHING to the agent, so it needs no opt-in: an absent
-    # `refinement` config reads as report-only. Only `propose`/`auto_apply` (phase C)
+    # writes NOTHING to the agent, so it needs no opt-in: an absent
+    # `refinement` config reads as report-only. Only `propose`/`auto_apply`
     # require the operator to enable them explicitly.
     class RunRefinement
       READ_ONLY_MODES = %w[report propose auto_apply].freeze
@@ -77,7 +77,7 @@ module Insika
 
       # An unknown mode is a config typo, and a typo that silently degrades to
       # "report" would be the kind of quiet wrong the strict-config rule exists to
-      # prevent (item 23).
+      # prevent.
       def validate_mode!(config)
         mode = AgentPayload.presence(config["mode"]) || "report"
         return if READ_ONLY_MODES.include?(mode)

data/lib/insika/commands/send_message.rb

@@ -7,16 +7,16 @@ module Insika
     # Stream. Validations that fail do NOT create a Task
     # (ValidationError/NotFoundError -> direct HTTP response).
     class SendMessage
-      # RFC-0015 §5.5 — surfaces whose response can carry the "you do not own the reply"
+      # surfaces whose response can carry the "you do not own the reply"
       # verdict (`merged` for `collect`, `steered` for `steer`), and therefore the only
       # ones where a message may join another turn. `/v1/responses` is NOT here: its body
       # is OpenAI-shaped SSE with nowhere to put the field, and it is frozen because a
       # live consumer speaks it. Joining a caller that cannot hear the verdict makes it
       # deliver the same answer once per message, which is worse than not joining at all.
-      # Channels declare themselves by `channel:<id>` once RFC-0011 §6 lands.
+      # Channels declare themselves by `channel:<id>` once lands.
       COALESCABLE_TRANSPORTS = %i[http:json].freeze
 
-      # RFC-0011 §6.4 — `inbound_log` is the retry window for channel event ids.
+      # `inbound_log` is the retry window for channel event ids.
       # nil = no dedup (every surface that does not send an `event_id`, which is all
       # of them today), and a caller that cannot supply a stable id gets
       # at-least-once turns rather than a content hash pretending to be dedup.
@@ -42,7 +42,7 @@ module Insika
 
         # session_id XOR history (both -> error; neither -> one-shot).
         if p[:session_id] && p[:history]
-          raise Insika::ValidationError, "session_id and history are mutually exclusive (D2)"
+          raise Insika::ValidationError, "session_id and history are mutually exclusive"
         end
 
         validate_history!(p[:history]) if p[:history]
@@ -56,7 +56,7 @@ module Insika
             (raise Insika::NotFoundError, "session '#{p[:session_id]}' not found")
         end
 
-        # RFC-0011 §6.4 — the platform retried a webhook it already delivered. Answer
+        # the platform retried a webhook it already delivered. Answer
         # with the turn it ALREADY produced and run nothing: without this, one flaky
         # ack costs a second LLM turn and sends the customer the same answer twice.
         # Checked before the queue doors on purpose — a duplicate is not a fragment to
@@ -77,18 +77,18 @@ module Insika
       def start_turn(command, p, profile)
         message = p[:message]
 
-        # RFC-0015 §5.3 — a fragment for a session whose turn is still at the door
+        # a fragment for a session whose turn is still at the door
         # joins it instead of becoming a turn of its own. Asked BEFORE `create` so a
         # merge leaves no orphan :queued task behind (Recovery replays :queued at
         # boot). Only offered on a surface that can report the verdict back —
-        # §5.5: coalescing a caller that cannot hear `merged` makes it deliver the
+        # coalescing a caller that cannot hear `merged` makes it deliver the
         # same answer twice.
         if coalescable?(command)
           if (joined = @executor.collect_into_pending(p[:session_id], message, profile: profile))
             return { task_id: joined, merged: true }
           end
 
-          # RFC-0015 §5.1 — the turn is already RUNNING: the message is appended to it at
+          # the turn is already RUNNING: the message is appended to it at
           # the next tool-batch boundary. Same verdict as a merge, different word: the
           # answer comes out of `task_id`, which is not this call's to deliver. Asked
           # after `collect` because the two cannot both apply — a turn is either still at
@@ -101,7 +101,7 @@ module Insika
         # command.to_h persists the entire Command in the Task;
         # ResumeTask re-reads payload.message from there.
         task = @task_store.create(command: command.to_h, session_id: p[:session_id])
-        # RFC-0015 §6.4 — `interrupt` mode: the turn in flight is now answering the wrong
+        # `interrupt` mode: the turn in flight is now answering the wrong
         # question, so it is abandoned at its next boundary. This message keeps its OWN
         # task and its own reply (that is why it needs no verdict and no surface gate), and
         # the cancel is posted after `create` so the event can name what replaced what.

data/lib/insika/commands/set_agent_tools.rb

@@ -6,7 +6,7 @@ module Insika
   module Commands
     # Control command: adjusts an agent's tools allow/denylist.
     # `allow` nil = all (AgentProfile rule); `deny` always
-    # wins. `allow_groups` (Phase 7/D4/F5, Step C): per-group allowlist, only
+    # wins. `allow_groups`: per-group allowlist, only
     # overwritten if the key comes in the payload (otherwise preserved). Takes effect on the next
     # dispatch (hot). -> AgentProfile.
     class SetAgentTools

data/lib/insika/commands/set_skill_agents.rb

@@ -5,8 +5,15 @@ require "time"
 module Insika
   module Commands
     # Control command: enables/disables a skill on N
-    # agents at once, adjusting each one's `profile.skills` allowlist.
-    # Takes effect on the next dispatch (hot via ProfileSource). -> { name, enabled_for }.
+    # agents at once, adjusting each one's `profile.skills` allowlist — and, with
+    # `eager_ids`, which of them keep the body in the prompt on EVERY turn
+    # (`profile.skills_eager`). Takes effect on the next dispatch (hot via
+    # ProfileSource). -> { name, enabled_for, eager_for, skipped_all, skipped_eager_all }.
+    #
+    # Both are per-agent decisions about the same skill, which is why they are one
+    # command: eagerness lives on the agent precisely BECAUSE the skill is shared, so
+    # the screen that says "which agents can load this" is the screen that says "and
+    # which of them always have it".
     #
     # Allowlist semantics (AgentProfile): nil = ALL, [] = none,
     # [names] = subset. Important and deliberate consequence:
@@ -16,6 +23,11 @@ module Insika
     #    allowlist (destructive/surprising). These agents are left intact and
     #    go into `skipped_all`. To restrict, use an explicit :set_agent_tools/allowlist
     #    first.
+    #
+    # `skills_eager` is NOT allowlist semantics (nil = NONE, see
+    # SkillCatalog#eager_for), so the two fields are adjusted by different rules: nil
+    # there is an empty set that can simply be added to, and only the BLANKET `true`
+    # has the same "cannot remove one name from all" problem (-> skipped_eager_all).
     class SetSkillAgents
       def initialize(profile_source:, event_stream:)
         @profile_source = profile_source
@@ -27,35 +39,46 @@ module Insika
         name = AgentPayload.presence(p[:name])
         raise Insika::ValidationError, "name is required" if name.nil?
         raise Insika::ValidationError, "agent_ids must be a list" unless p[:agent_ids].nil? || p[:agent_ids].is_a?(Array)
+        raise Insika::ValidationError, "eager_ids must be a list" unless p[:eager_ids].nil? || p[:eager_ids].is_a?(Array)
 
         wanted = Array(p[:agent_ids]).map(&:to_s)
-        enabled_for = []
-        skipped_all = []
-
-        @profile_source.all.each do |profile|
-          want = wanted.include?(profile.id)
-          new_skills = next_skills(profile.skills, name, want)
-
-          if new_skills == :skip
-            skipped_all << profile.id
-            next
-          end
-          next if new_skills == profile.skills # no change
+        # eager_ids ABSENT means "this form does not manage eagerness" — leave every
+        # profile's setting alone. An empty ARRAY means "none of them", which is a real
+        # instruction and must be applied. `nil` and `[]` are not the same request.
+        eager_wanted = p[:eager_ids].nil? ? nil : Array(p[:eager_ids]).map(&:to_s)
+        result = { enabled_for: [], eager_for: [], skipped_all: [], skipped_eager_all: [] }
 
-          @profile_source.put(Insika::AgentProfile.build(**profile.to_h.merge(skills: new_skills)))
-          enabled_for << profile.id if want
-        end
+        @profile_source.all.each { |profile| apply(profile, name, wanted, eager_wanted, result) }
 
         @event_stream.emit(Insika::Event.new(
                              type: :skill_agents_set,
-                             data: { name: name, agent_ids: wanted, skipped_all: skipped_all },
+                             data: { name: name, agent_ids: wanted, eager_ids: eager_wanted,
+                                     skipped_all: result[:skipped_all] }.compact,
                              meta: { at: Time.now.utc.iso8601 }
                            ))
-        { name: name, enabled_for: enabled_for, skipped_all: skipped_all }
+        { name: name }.merge(result)
       end
 
       private
 
+      def apply(profile, name, wanted, eager_wanted, result)
+        want = wanted.include?(profile.id)
+        new_skills = next_skills(profile.skills, name, want)
+        new_eager = next_eager(profile, name, eager_wanted, result)
+
+        if new_skills == :skip
+          result[:skipped_all] << profile.id
+          new_skills = profile.skills
+        end
+        result[:enabled_for] << profile.id if want
+        result[:eager_for] << profile.id if eager_wanted&.include?(profile.id)
+        return if new_skills == profile.skills && new_eager == profile.skills_eager
+
+        @profile_source.put(Insika::AgentProfile.build(
+                              **profile.to_h.merge(skills: new_skills, skills_eager: new_eager)
+                            ))
+      end
+
       # -> new allowlist | :skip (agent with nil that requested disable).
       def next_skills(current, name, want)
         if want
@@ -66,6 +89,24 @@ module Insika
           Array(current).map(&:to_s) - [name]
         end
       end
+
+      # -> new skills_eager. nil eager_wanted = not managed by this call.
+      def next_eager(profile, name, eager_wanted, result)
+        current = profile.skills_eager
+        return current if eager_wanted.nil?
+
+        want = eager_wanted.include?(profile.id)
+        # Blanket `true` already includes every skill; removing ONE name from it would
+        # mean materializing the whole catalog as a list, the same destructive surprise
+        # `skipped_all` exists for.
+        if Coercion.truthy?(current)
+          result[:skipped_eager_all] << profile.id unless want
+          return current
+        end
+
+        list = current.nil? || current == false ? [] : Array(current).map(&:to_s)
+        want ? (list | [name]) : (list - [name])
+      end
     end
   end
 end

data/lib/insika/commands/trigger_workflow.rb

@@ -45,7 +45,7 @@ module Insika
           raise Insika::NotFoundError, "workflow '#{workflow}' not registered"
         end
 
-        # I/O by schema (item 22 / §4.4): the INPUT is validated SYNCHRONOUSLY —
+        # I/O by schema: the INPUT is validated SYNCHRONOUSLY —
         # a non-conforming input is a WorkflowSchemaError (< ValidationError -> 422)
         # with NO run created. `definition` reads the schema metadata without
         # resolving the factory (stays out of the fiber). No-op without an input_schema.

data/lib/insika/commands/update_agent.rb

@@ -25,7 +25,7 @@ module Insika
         # what was sent. id never changes (rename = create+delete, out of scope).
         merged = existing.to_h.merge(patch).merge(id: id)
         profile = Insika::AgentProfile.build(**merged)
-        # RFC-0010 §4.4: definition-time cycle + depth check (an update may ADD
+        # definition-time cycle + depth check (an update may ADD
         # subagents to an existing agent). Raises SubagentError before persisting.
         validate_subagent_graph!(profile)
         @profile_source.put(profile)

data/lib/insika/commands/write_data_tool.rb

@@ -5,7 +5,7 @@ require "time"
 module Insika
   module Commands
     # Writes (upserts) a DATA-defined tool into the ToolStore and RELOADS the overlay +
-    # catalog — takes effect without a restart (F5). Rejects a name that collides with a
+    # catalog — takes effect without a restart. Rejects a name that collides with a
     # code tool (R3). Validating the definition (format, method/url, types,
     # placeholders) is the ToolStore/ToolDefinition's job. Secrets (headers) reconcile
     # in the store; the event carries only the name (0 leakage). -> { name, definition }.

data/lib/insika/commands/write_golden.rb

@@ -4,7 +4,7 @@ require "time"
 
 module Insika
   module Commands
-    # Control command: writes an eval case (RFC-0008 §3.1) into the GoldenStore. This
+    # Control command: writes an eval case into the GoldenStore. This
     # is what lets a domain owner add a case — above all its RUBRIC, the part of an eval
     # that is plain language — without a checkout and a text editor.
     #

data/lib/insika/commands/write_skill.rb

@@ -5,10 +5,15 @@ require "yaml"
 
 module Insika
   module Commands
-    # Control command: writes a shared skill
-    # (complete SKILL.md) into the SkillStore and RELOADS the catalog — takes effect
-    # without a restart (hot). Validates the frontmatter (name required) before writing.
-    # -> { name, updated_at }.
+    # Control command: writes a skill (complete SKILL.md) into
+    # the SkillStore and RELOADS the catalog — takes effect without a restart (hot).
+    # Validates the frontmatter (name required) before writing. -> { name, agent, updated_at }.
+    #
+    # `agent` (optional) writes into that agent's scope instead of the shared one: the
+    # SPECIALIZATION of a shared skill, or a skill private to one agent. Same `name`
+    # either way — the store position is the identity, so the frontmatter inside an
+    # override keeps saying the bare shared name and the level-1 catalog, load_skill,
+    # the labels and the events all keep displaying it.
     class WriteSkill
       def initialize(skill_store:, skill_catalog:, event_stream:)
         @skill_store = skill_store
@@ -19,21 +24,26 @@ module Insika
       def call(command)
         p = AgentPayload.symbolize(command.payload)
         name = AgentPayload.presence(p[:name])
+        agent = AgentPayload.presence(p[:agent])
         content = p[:content].to_s
         raise Insika::ValidationError, "name is required" if name.nil?
         validate_frontmatter!(content)
 
-        rec = @skill_store.write(name, content, create_only: !!p[:create_only])
+        rec = @skill_store.write(name, content, agent: agent, create_only: !!p[:create_only])
         @skill_catalog.reload
+        emit(:skill_written, name, agent)
+        { name: name, agent: agent, updated_at: rec["updated_at"] }
+      end
+
+      private
+
+      def emit(type, name, agent)
         @event_stream.emit(Insika::Event.new(
-                             type: :skill_written, data: { name: name },
+                             type: type, data: { name: name, agent: agent }.compact,
                              meta: { at: Time.now.utc.iso8601 }
                            ))
-        { name: name, updated_at: rec["updated_at"] }
       end
 
-      private
-
       # Mirrors the SkillCatalog parse: without YAML frontmatter with `name`, the skill
       # would be silently ignored on reload — fail early, in the Command.
       def validate_frontmatter!(content)

data/lib/insika/config_store.rb

@@ -18,15 +18,19 @@ module Insika
     # agent_files/skills: the CONTENT of per-agent prompts
     # and shared skills lives in the Store (single source of truth,
     # a SQLite backup), not on disk — disk becomes only seed/import.
-    # goldens: authored eval cases (RFC-0008 §3.1 / RFC-0013 §3.7) — config, like the
+    # goldens: authored eval cases — config, like the
     # prompts and skills: the corpus on disk is seed and export, the store is what a
     # deployment runs and what the Studio edits.
-    # baselines: the ACCEPTED state of each agent's golden set (RFC-0013 §3.7.3).
+    # baselines: the ACCEPTED state of each agent's golden set.
     # Config for the same reason: it is a curated decision ("this is the bar"), the
     # file is its export, and the refinement gate reads it from inside a deployment
     # that has no checkout.
-    SCOPES = %w[agents settings llm_providers mcp agent_files skills system_files tools
-                goldens baselines].freeze
+    # agent_skills: the per-agent SPECIALIZATIONS of a shared skill (and
+    # agent-private skills). A second scope rather than a composite key in `skills`,
+    # so the shared records are untouched by the agent dimension arriving — no
+    # migration, and a live deployment keeps serving exactly what it served.
+    SCOPES = %w[agents settings llm_providers mcp agent_files skills agent_skills
+                system_files tools goldens baselines].freeze
 
     class UnknownScope < Insika::Error; end
 

data/lib/insika/context/builder.rb

@@ -19,7 +19,7 @@ module Insika
     def initialize(providers:, event_stream:, hooks: Hooks.new, estimator: TokenEstimator)
       @providers = providers
       @event_stream = event_stream
-      @hooks = hooks # :prompt pair (task 16); empty Hooks = no-op
+      @hooks = hooks # prompt pair; empty Hooks = no-op
       @estimator = estimator
     end
 
@@ -97,7 +97,7 @@ module Insika
     def estimable_text(content)
       case content
       when String then content
-      # An eviction unit (§11 R1): a cycle of message Hashes -> sum their text.
+      # An eviction unit (R1): a cycle of message Hashes -> sum their text.
       when Array then content.map { |c| estimable_text(c) }.join(" ")
       when Hash then content.values.map(&:to_s).join(" ")
       else content.to_s

data/lib/insika/context/fragment.rb

@@ -8,12 +8,36 @@ module Insika
   #   tokens:    Integer | nil; estimated by the Builder when nil
   #   source:    String — provider id (audit)
   #   pinned:    true -> uncuttable in the budget (e.g. identity)
+  #   labels:    [{ "name" =>, "reason" => }] — WHAT this fragment carries and WHY,
+  #              as ids. Content-FREE by contract, so the context trace can report
+  #              which skills a turn injected without storing a byte of the bodies.
+  #              [] = nothing to name (the default for every provider that has no
+  #              natural id, e.g. the identity prompt).
+  #
+  #              The REASON is the point. A name alone answers "was something
+  #              injected"; the operator's actual question is "which skill did I
+  #              trigger, and why is it here" — `eager` (the agent always wants it),
+  #              `trigger:<matched phrase>` (this message asked for it), or absent
+  #              for a body a plugin supplied. String keys because these labels are
+  #              written to the context trace and to events as JSON: the round-trip
+  #              is then the identity, and no reader has to defend against both.
   ContextFragment = Data.define(:content, :placement, :priority, :tokens,
-                                :source, :pinned) do
+                                :source, :pinned, :labels) do
     def self.build(content:, placement:, source:, priority: 50, tokens: nil,
-                   pinned: false)
+                   pinned: false, labels: [])
       new(content: content, placement: placement, priority: priority,
-          tokens: tokens, source: source, pinned: pinned)
+          tokens: tokens, source: source, pinned: pinned,
+          labels: Array(labels).map { |l| label(l) })
+    end
+
+    # A bare String is still a valid label (a provider that has an id but no reason
+    # to give) — it normalizes to a reason-less entry rather than being rejected.
+    def self.label(raw)
+      return { "name" => raw.to_s }.freeze unless raw.is_a?(Hash)
+
+      name = (raw[:name] || raw["name"]).to_s
+      reason = raw[:reason] || raw["reason"]
+      { "name" => name, "reason" => reason&.to_s }.compact.freeze
     end
   end
 end

data/lib/insika/context/priority.rb

@@ -3,12 +3,12 @@
 module Insika
   module Context
     # Precedence ladder for context fragments — SINGLE SOURCE of the order
-    # (Phase 6/D5, trust boundary). Higher = more authority: appears earlier
+    # (trust boundary). Higher = more authority: appears earlier
     # in the system prompt and survives budget cuts. Providers reference these
     # constants instead of loose numbers, so the boundary is an auditable
     # contract in a single place (trust_boundary_spec locks the order).
     #
-    # Contract (NF3/D5): identity and guardrails go PINNED at the top; TURN
+    # Contract: identity and guardrails go PINNED at the top; TURN
     # injections (request_context — the consumer's tenant/vars) sit at the
     # BOTTOM and are sacrificed FIRST under budget. Identity (pinned) is NEVER
     # truncated. A prompt injection riding in via turn data is DATA, not
@@ -18,6 +18,7 @@ module Insika
     module Priority
       IDENTITY     = 100 # IDENTITY/SOUL (Prompt) — pinned
       PROMPT_REF   = 90  # Prompt Catalog guardrails/refs (Prompt) — pinned
+      SKILL_BODY   = 85  # <active_skill> trigger-matched body (SkillTrigger)
       SKILL        = 80  # <available_skills> level 1 (Skill)
       MEMORY       = 75  # <memory> read path (Memory)
       TOOL_SEARCH  = 70  # <available_tools> level 1 (ToolSearch)

data/lib/insika/context/providers/memory.rb

@@ -33,7 +33,7 @@ module Insika
 
         private
 
-        # Engine memory scope (D3): an EXPLICIT tenant from the Command wins
+        # Engine memory scope: an EXPLICIT tenant from the Command wins
         # (multi-merchant override); otherwise the SESSION (=chat) — engine-owner
         # memory is per-chat. No session (one-shot) and no tenant -> nil (MemoryStore
         # applies _default). Symmetric to the write path (`state.tenant` in the Executor).

data/lib/insika/context/providers/request.rb

@@ -13,7 +13,7 @@ module Insika
           # "history" is transcript (consumed by the Session provider), not turn
           # metadata — it does not leak into the system's request_context. Keys
           # prefixed with "__" are INTERNAL slots (e.g. the per-chat model pin
-          # "__llm__", §10) — reserved, never rendered to the model.
+          # "__llm__") — reserved, never rendered to the model.
           request.vars.to_h.each do |k, v|
             next if k.to_s == "history" || k.to_s.start_with?("__")
 

data/lib/insika/context/providers/session.rb

@@ -17,7 +17,13 @@ module Insika
           messages = transcript_for(request)
           return [] if messages.nil? || messages.empty?
 
-          # 1 fragment per EVICTION UNIT (§11 R1): a plain message, OR an
+          # A3/C3 opt-in: identical tool results in the transcript collapse to a
+          # back-reference (the cheap half of compaction). CHANGES WHAT THE MODEL
+          # SEES — hence the profile flag, never a default. Applied BEFORE the
+          # eviction-unit grouping so a cycle's results are already slim.
+          messages = compress_history(messages, request)
+
+          # 1 fragment per EVICTION UNIT (R1): a plain message, OR an
           # assistant-with-tool_calls together with its tool results. Grouping at
           # the fragment level means the budget cut (apply_budget) drops a whole
           # tool cycle atomically — a tool_use is NEVER seeded without its result
@@ -72,7 +78,16 @@ module Insika
           h
         end
 
-        def tool_calls?(msg) = msg[:tool_calls] && !Array(msg[:tool_calls]).empty?
+                def tool_calls?(msg) = msg[:tool_calls] && !Array(msg[:tool_calls]).empty?
+
+        # The compression is opt-in per agent (profile data, config-over-code):
+        # absent/off -> the transcript passes through byte-identical (parity).
+        def compress_history(messages, request)
+          profile = request.respond_to?(:profile) ? request.profile : nil
+          return messages unless profile&.tool_output_compression
+
+          ToolOutputCompressor.compress_transcript(messages)
+        end
 
         # Precedence: checkpoint -> explicit history -> store.
         # The first present source wins; no merge.

data/lib/insika/context/providers/skill.rb

@@ -13,7 +13,11 @@ module Insika
 
         private
 
-        def entries(request) = @catalog.effective(request.profile.skills)
+        # Only the skills the model still has to ASK for. An eager skill is already in
+        # the prompt in full, so advertising it here would invite a `load_skill` call
+        # that buys a duplicate — and the catalog's whole job is to describe what is
+        # NOT yet loaded. Nothing lazy left -> CatalogProvider emits no fragment.
+        def entries(request) = @catalog.lazy_for(request.profile)
       end
     end
   end