insika 0.1.0 → 0.2.0

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

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Insika
+  module Context
+    module Providers
+      # Level-2 skill BODIES in the prompt, with two selection modes — both
+      # deterministic, neither asks the model:
+      #
+      #   profile.skills_eager  -> the agent's eager set (all, or a named list),
+      #                            every turn. No decision at all, so no miss rate.
+      #                            Costs the bodies' tokens.
+      #   `triggers:` in the    -> only the skills whose trigger matches this
+      #   frontmatter              message (whole word, accent- and case-insensitive).
+      #
+      # Model-invoked loading (load_skill) stays the fallback for everything else.
+      #
+      # A trigger only belongs on a skill that can COMPLETE the turn by itself.
+      # Injecting a reference table whose companion skill holds the procedure is
+      # worse than injecting nothing: the model has a plausible half-recipe in the
+      # prompt, so it never calls load_skill for the other half. Measured on a real
+      # pack — the line map arrived, the query-construction rules did not, and the
+      # searches came out malformed.
+      # Activation here is NOT a tool call, so nothing in the transcript would show
+      # it. The fragment's `labels` carry the name AND THE REASON, and the EXECUTOR
+      # announces them (:skill_activated) — not this provider. A provider only has the
+      # ContextRequest, which has no task, and the Studio's SSE drops an event whose
+      # meta lacks `task_id` when the subscriber is task-scoped (Subscription#matches?):
+      # emitting from here produced an event that was correct and never arrived.
+      class SkillTrigger < ContextProvider
+        def initialize(catalog:)
+          @catalog = catalog
+        end
+
+        def call(request)
+          matched = select(request)
+          return [] if matched.empty?
+
+          content = matched.map do |skill, _reason|
+            %(<active_skill name="#{skill.name}">\n#{skill.body}\n</active_skill>)
+          end.join("\n\n")
+
+          labels = matched.map { |skill, reason| { "name" => skill.name, "reason" => reason } }
+          [ContextFragment.build(content: content, placement: :system,
+                                 priority: Context::Priority::SKILL_BODY, source: id,
+                                 labels: labels)]
+        end
+
+        private
+
+        # -> [[skill, reason]]. Two independent reasons a body lands here: the AGENT
+        # marked it eager (always), or a `triggers:` entry matched THIS message.
+        # The union is injected; everything else stays at level 1 for load_skill, where
+        # the model's call is the only record of what it reached for.
+        #
+        # The reason travels with the skill from here to the activation card, because
+        # "which skills were active" without "why each one was" is the information the
+        # deterministic paths destroyed when they replaced the load_skill call.
+        def select(request)
+          eager = @catalog.eager_for(request.profile).map { |skill| [skill, "eager"] }
+          # `triggered` reads the LAZY set, which excludes the eager one — so a skill
+          # cannot arrive twice. uniq_by name anyway: the invariant is worth not
+          # depending on from here.
+          selected = (eager + triggered(request)).uniq { |skill, _reason| skill.name }
+          (selected + companions(selected, request)).uniq { |skill, _reason| skill.name }
+        end
+
+        # Declared `companions:` travel with whatever brought them, so the half-recipe
+        # state cannot be assembled: the line map that arrived by trigger takes its
+        # query-construction rules with it. ONE LEVEL, deliberately — a transitive walk
+        # would make a cycle a hang and a chain a budget blowout, and "cannot work
+        # without" is a direct relationship.
+        #
+        # Restricted to the agent's own allowed set: a companion the agent cannot see
+        # is not injectable, and `doctor` flags that declaration rather than the engine
+        # quietly widening the allowlist.
+        def companions(selected, request)
+          wanted = selected.flat_map { |skill, _reason| Array(skill.companions).map { |c| [c.to_s, skill.name] } }
+          return [] if wanted.empty?
+
+          by_name = @catalog.effective(request.profile.skills, agent: request.profile.id)
+                            .each_with_object({}) { |s, acc| acc[s.name] = s }
+          wanted.filter_map do |name, of|
+            skill = by_name[name]
+            [skill, "companion:#{of}"] if skill
+          end
+        end
+
+        def triggered(request)
+          message = fold(request.message)
+          return [] if message.empty?
+
+          @catalog.lazy_for(request.profile).filter_map do |skill|
+            phrase = matched_trigger(skill, message)
+            [skill, "trigger:#{phrase}"] if phrase
+          end
+        end
+
+        # The trigger phrase that fired, or nil. AS AUTHORED, never as typed: the
+        # reason lands on the activation card, and what an operator needs there is the
+        # config line they can go and edit — not an echo of the customer's message
+        # (which also keeps the label content-free, like the rest of the trace).
+        #
+        # Two hygiene rules, and both are tokenization rather than the semantic
+        # matching this feature deliberately does not do:
+        #
+        #   whole word — bare substring made `triggers: presente` fire inside
+        #   *apresente*, and the card now PRINTS the matched phrase: `trigger:presente`
+        #   on a turn about *apresentação* would discredit the card on day one.
+        #
+        #   folded accents — the corpus is Portuguese and customers type *maquiagem*
+        #   and *maquiágem* unpredictably, so both sides are folded before comparing.
+        def matched_trigger(skill, folded_message)
+          skill.triggers.find do |trigger|
+            needle = fold(trigger)
+            next false if needle.empty?
+
+            /(?<![[:alnum:]])#{Regexp.escape(needle)}(?![[:alnum:]])/.match?(folded_message)
+          end
+        end
+
+        # NFD splits an accented letter into letter + combining mark; dropping the
+        # marks (\p{Mn}) leaves the bare letter, so "maquiágem" and "maquiagem" fold
+        # to the same string.
+        def fold(text) = text.to_s.unicode_normalize(:nfd).gsub(/\p{Mn}/, "").downcase
+      end
+    end
+  end
+end

data/lib/insika/context_trace_store.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Insika
+  # Per-session CONTEXT trace, for the Studio's breakdown-by-category card
+  # One record per session in the raw backend (scope
+  # "context_traces") — RUNTIME data, next to sessions/tasks, like the
+  # ToolTraceStore it mirrors. A capped LIST of entries, ONE PER TURN, written
+  # by the Executor after tool assembly.
+  #
+  # Unlike the tool trace there is NO security machinery here by construction:
+  # the entry is counts and provider ids only (category -> tokens/fragments/
+  # pinned, the tools estimate, the budget verdict) — never fragment content,
+  # so there is nothing to mask. `record` still rescues everything: the trace
+  # NEVER breaks the turn.
+  class ContextTraceStore
+    SCOPE = "context_traces"
+    MAX_PER_SESSION = 50 # one per turn; turns are the unit, not tool calls
+
+    def initialize(store:)
+      @store = store
+    end
+
+    # Writes an entry into the session — UPSERT by (task_id, turn): a turn that
+    # suspends (approval) and resumes re-runs the context stage, and the
+    # re-record replaces the first one instead of duplicating it. (`turn` is
+    # 1-based PER TASK, so the task is part of the key.) Missing session_id ->
+    # no-op.
+    def record(session_id:, entry:)
+      sid = session_id.to_s
+      return if sid.empty?
+
+      e = sanitize(entry)
+      key = [e["task_id"], e["turn"]]
+      list = (@store.get(SCOPE, sid) || []).reject { |x| [x["task_id"], x["turn"]] == key } + [e]
+      @store.set(SCOPE, sid, list.last(MAX_PER_SESSION))
+    rescue StandardError
+      nil
+    end
+
+    # -> [Hash] session entries in chronological order. [] if none.
+    def for_session(session_id) = @store.get(SCOPE, session_id.to_s) || []
+
+    # Discards a session's trace (cleanup). -> bool (did it exist?).
+    def clear(session_id) = @store.delete(SCOPE, session_id.to_s)
+
+    private
+
+    # Keeps only the known shape; coerces numbers and strings so a caller bug
+    # degrades the card instead of poisoning the record.
+    def sanitize(entry)
+      e = entry.is_a?(Hash) ? entry : {}
+      categories = e[:categories] || e["categories"] || {}
+      tools = e[:tools] || e["tools"] || {}
+      {
+        "task_id" => (e[:task_id] || e["task_id"]).to_s,
+        "turn" => int(e[:turn] || e["turn"]),
+        "at" => (e[:at] || e["at"]).to_s,
+        "cap" => int(e[:cap] || e["cap"]),
+        "used" => int(e[:used] || e["used"]),
+        "evicted" => Array(e[:evicted] || e["evicted"]).map(&:to_s),
+        "categories" => categories.each_with_object({}) do |(name, c), acc|
+          c = {} unless c.is_a?(Hash)
+          cat = { "tokens" => int(c[:tokens] || c["tokens"]),
+                  "fragments" => int(c[:fragments] || c["fragments"]),
+                  "pinned" => int(c[:pinned] || c["pinned"]) }
+          # WHAT the category carried and WHY ({name, reason}) — still ids only, so
+          # the no-masking-needed contract above holds. Omitted when empty: most
+          # categories have nothing to name and an empty key is just noise.
+          labels = normalize_labels(c[:labels] || c["labels"])
+          cat["labels"] = labels unless labels.empty?
+          acc[name.to_s] = cat
+        end,
+        "tools" => { "count" => int(tools[:count] || tools["count"]),
+                     "tokens" => int(tools[:tokens] || tools["tokens"]) }
+      }
+    end
+
+    # Labels are {name, reason} in string keys (ContextFragment.label). A bare string
+    # still reads as a nameless-reason label: an entry recorded before reasons existed,
+    # or a caller that only has the id, degrades the card instead of poisoning it.
+    def normalize_labels(raw)
+      Array(raw).filter_map do |label|
+        name, reason = label.is_a?(Hash) ? [label[:name] || label["name"], label[:reason] || label["reason"]] : [label, nil]
+        next if name.to_s.empty?
+
+        { "name" => name.to_s, "reason" => reason&.to_s }.compact
+      end.uniq
+    end
+
+    def int(value) = Integer(value || 0)
+  end
+end

data/lib/insika/delegation_store.rb

@@ -4,8 +4,8 @@ require "securerandom"
 require "time"
 
 module Insika
-  # Durable record of an ASYNC delegation (RFC-0010 §5, item 21 Phase 2, hermes
-  # "delegation durability"). The synchronous subagent (Phase 1) needs no
+  # Durable record of an ASYNC delegation (hermes
+  # "delegation durability"). The synchronous subagent needs no
   # record — it lives and dies inside the parent's turn. The ASYNC subagent does:
   # the parent DISPATCHES and its turn ends; the child runs independently; when the
   # child finishes, its result is delivered to the parent as a NEW turn (never

data/lib/insika/doctor.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Insika
-  # `insika doctor` (item 23 / §8.1 — OpenClaw's "strict config + doctor --fix",
+  # `insika doctor` (— OpenClaw's "strict config + doctor --fix",
   # "the repo's best productization discipline"). A read-only diagnosis of a
   # deployment's configuration that turns the scattered, silent boot warnings into
   # ONE structured report — and, with `--fix`, applies the safe autofixes.
@@ -58,12 +58,16 @@ module Insika
     end
 
     def initialize(env: ENV, settings_store: nil, llm_provider_store: nil, tool_store: nil,
-                   agent_file_store: nil, backend: nil, extra_env_specs: [])
+                   agent_file_store: nil, skill_store: nil, skill_catalog: nil,
+                   profile_source: nil, backend: nil, extra_env_specs: [])
       @env = env
       @settings_store = settings_store
       @llm_provider_store = llm_provider_store
       @tool_store = tool_store
       @agent_file_store = agent_file_store
+      @skill_store = skill_store
+      @skill_catalog = skill_catalog
+      @profile_source = profile_source
       @backend = backend
       @extra_env_specs = extra_env_specs
     end
@@ -84,7 +88,7 @@ module Insika
 
     def checks = %i[check_env check_settings_schema check_default_model check_db check_llm_provider
                     check_admin_token check_data_tools check_prompt_files check_relay_channel
-                    check_web_widget]
+                    check_web_widget check_skill_eager check_skill_drift]
 
     def safe(check)
       Array(send(check))
@@ -155,7 +159,7 @@ module Insika
                    message: "ADMIN_TOKEN unset — /studio is fail-closed (login denied) and the gateway has no fallback token", fix: nil)]
     end
 
-    # A half-configured relay is the silent kind of broken (RFC-0011 §6): with only
+    # A half-configured relay is the silent kind of broken: with only
     # the deliver URL set, nothing is mounted and every inbound POST 404s; with only
     # the token, the engine accepts turns it can never answer and the customer waits
     # forever on a reply that is sitting in the outbox. Both halves or neither.
@@ -176,7 +180,7 @@ module Insika
     end
 
     # The widget is the one PUBLIC channel, so its misconfigurations are the ones that
-    # cost money rather than just failing (RFC-0011 §5.3/§5.4). Three of them, in the
+    # cost money rather than just failing. Three of them, in the
     # order they bite: half the switch set (mounted nowhere, or mounted addressing
     # nothing), and a mount with no chat rate limit anywhere — which the channel
     # refuses with a 503 rather than opening, but which reads to an operator as "the
@@ -202,6 +206,247 @@ module Insika
                             "INSIKA_WIDGET_AGENTS sets limits.chat_rate_limit (a public channel with no ceiling is not served)", fix: nil)]
     end
 
+    # Eagerness moved from the SKILL.md frontmatter to `profile.skills_eager`, because
+    # skills are SHARED and a flag on the skill forced one decision onto every agent
+    # holding it. The parser now ignores `eager:` — which is the quiet kind of upgrade:
+    # nothing crashes, the body simply stops being in the prompt. This check is the
+    # only thing that says so. Its sibling half is the opposite mistake: a name in
+    # `skills_eager` that the agent's `skills` allowlist does not contain is
+    # intersected away at runtime, so the operator's intent evaporates in silence.
+    def check_skill_eager
+      findings = stale_eager_frontmatter + unreachable_eager_names
+      return findings if findings.any?
+      return [] unless @skill_store || @skill_catalog || @profile_source
+
+      [ok("skill-eager", "skill eagerness: per-agent (profile.skills_eager), no stale frontmatter")]
+    end
+
+    def stale_eager_frontmatter
+      skill_sources.filter_map do |name, content|
+        next unless frontmatter_of(content).key?("eager")
+
+        Finding.new(check: "skill-eager", severity: :warn, fix: nil,
+                    message: "skill '#{name}' still declares `eager:` in its frontmatter — the key is IGNORED. " \
+                             "Eagerness is per-agent now: put the name in that agent's `skills_eager` " \
+                             "(Studio > Skills, or `skills_eager \"#{name}\"` in the DSL).")
+      end
+    end
+
+    def unreachable_eager_names
+      return [] unless @profile_source
+
+      @profile_source.all.flat_map do |profile|
+        eager = profile.skills_eager
+        next [] unless eager.is_a?(Array)
+        next [] if profile.skills.nil? # nil = every skill allowed, so nothing is unreachable
+
+        allowed = Array(profile.skills).map(&:to_s)
+        (eager.map(&:to_s) - allowed).map do |name|
+          Finding.new(check: "skill-eager", severity: :warn, fix: nil,
+                      message: "agent '#{profile.id}' marks skill '#{name}' eager but does not allow it — " \
+                               "the name is a no-op. Add it to the agent's skills, or drop it from skills_eager.")
+        end
+      end
+    end
+
+    # { name => raw SKILL.md } across BOTH sources the runtime reads: the disk roots
+    # (seed, via the catalog) and the authored store (wins — same precedence as
+    # SkillCatalog). The checks parse frontmatter the catalog deliberately drops
+    # (`eager:`), so they need the raw text; for a disk skill that is the file itself,
+    # and a store-overlaid skill carries a sentinel path that is not a file.
+    def skill_sources
+      @skill_sources ||= disk_skill_sources.merge(@skill_store ? @skill_store.all : {})
+    end
+
+    def disk_skill_sources
+      return {} unless @skill_catalog
+
+      @skill_catalog.all.each_with_object({}) do |skill, acc|
+        acc[skill.name] = File.read(skill.path, encoding: "UTF-8") if File.file?(skill.path.to_s)
+      end
+    end
+
+    # The frontmatter block only; a `eager:` line in the BODY is prose, not config.
+    def frontmatter_of(content)
+      match = content.to_s.match(/\A---\s*\n(.*?)\n---\s*\n/m)
+      match ? Insika::Frontmatter.parse(match[1]) : {}
+    end
+
+    # Drift between a pack's PROSE and the catalog. Three ways it happened on the
+    # pilot, all silent, all found by reading a customer conversation afterwards.
+    #
+    # Every check here takes MECHANICAL inputs only — skill names, allowlists, agent
+    # identities. A check that has to parse prose ("this paragraph declares a count of
+    # six") false-positives on the first real pack and takes the doctor's credibility
+    # with it, which costs more than the drift it caught.
+    def check_skill_drift
+      return [] unless (@skill_store || @skill_catalog) && @profile_source
+
+      findings = prompt_files_naming_unallowed_skills + shared_skills_naming_a_holder + broken_companions
+      return findings if findings.any?
+
+      [ok("skill-drift", "skill references: prompt files, shared bodies and companions all consistent")]
+    end
+
+    # D1 residue. The routing table is GENERATED now (SkillCatalog#format_for_prompt
+    # renders each skill with its triggers), so the hand-written companion has no
+    # reason to exist — but a pack that still carries one keeps instructing the model
+    # about skills the agent cannot load. Skill names are known ids, so this is a grep.
+    def prompt_files_naming_unallowed_skills
+      return [] unless @agent_file_store
+
+      catalog = skill_sources.keys
+      @profile_source.all.flat_map do |profile|
+        next [] if profile.skills.nil? # nil = everything allowed, nothing to be outside of
+
+        allowed = Array(profile.skills).map(&:to_s)
+        orphans = catalog - allowed
+        next [] if orphans.empty?
+
+        @agent_file_store.list(profile.id).flat_map do |file|
+          body = @agent_file_store.read(profile.id, file).to_s
+          orphans.select { |name| mentions?(body, name) }.map do |name|
+            Finding.new(check: "skill-drift", severity: :warn, fix: nil,
+                        message: "agent '#{profile.id}' file '#{file}' names skill '#{name}', which is NOT in its " \
+                                 "skills allowlist — the model is being told to use something it cannot load. " \
+                                 "Allow the skill, or drop the reference (the skill table is generated).")
+          end
+        end
+      end
+    end
+
+    # D2. A skill in more than one allowlist that names one of its OWN holders in its
+    # text is specialized text in shared clothing — the pilot served the Cacau Show
+    # agent three shared skills that each said "na Natura". Specialize it per agent
+    # (write_skill with `agent:`) instead of leaving one store's policy in a shared body.
+    #
+    # Merchant vocabulary beyond the holders' identities is deliberately out of scope:
+    # there is no mechanical source for it.
+    def shared_skills_naming_a_holder
+      holders = skill_holders
+      specialized = specialized_by
+      skill_sources.flat_map do |name, content|
+        owners = holders[name].to_a
+        next [] if owners.length < 2
+
+        # Who still READS this shared body: a holder with its own version reads that
+        # instead, so it stops being a victim — but its identity in the shared text
+        # keeps poisoning whoever is left. Identity comes from ALL holders; only the
+        # readers shrink as specializations land, so the finding clears when the last
+        # victim stops reading, never merely because the named holder moved out.
+        readers = owners - specialized[name].to_a
+        owners.flat_map do |owner|
+          victims = (readers - [owner]).sort
+          next [] if victims.empty?
+
+          identity_terms(owner).select { |term| mentions?(content, term) }.map do |term|
+            Finding.new(check: "skill-drift", severity: :warn, fix: nil,
+                        message: "shared skill '#{name}' names '#{term}', the identity of '#{owner}' — " \
+                                 "#{victims.join(', ')} read(s) #{owner}'s text as their own. Specialize " \
+                                 "'#{owner}' if it needs that text, and remove it from the shared body.")
+          end
+        end
+      end
+    end
+
+    # D3 residue, the half `companions:` cannot prevent: a body that points at another
+    # catalog skill without declaring it (so the pair can still break apart), and a
+    # declared companion an agent is not allowed to load (so the pair breaks for THAT
+    # agent, silently, since the engine will not widen an allowlist on its own).
+    def broken_companions
+      names = skill_sources.keys
+      undeclared = skill_sources.flat_map do |name, content|
+        declared = declared_companions(content)
+        (names - [name] - declared).select { |other| mentions?(body_of(content), other) }.map do |other|
+          Finding.new(check: "skill-drift", severity: :warn, fix: nil,
+                      message: "skill '#{name}' references skill '#{other}' in its body without declaring it a " \
+                               "companion — the two can arrive apart, and half a recipe is worse than none. " \
+                               "Add `companions: [#{other}]` to '#{name}'.")
+        end
+      end
+      undeclared + companions_outside_allowlists
+    end
+
+    # Same lenient reading as SkillCatalog#parse_list: a YAML list, or the whole value
+    # as one comma-separated String when the tolerant parser had to fall back.
+    def declared_companions(content)
+      raw = frontmatter_of(content)["companions"]
+      Array(raw).flat_map { |c| c.to_s.split(",") }.map(&:strip).reject(&:empty?)
+    end
+
+    def companions_outside_allowlists
+      declared = skill_sources.each_with_object({}) do |(name, content), acc|
+        list = declared_companions(content)
+        acc[name] = list unless list.empty?
+      end
+      return [] if declared.empty?
+
+      @profile_source.all.flat_map do |profile|
+        next [] if profile.skills.nil?
+
+        allowed = Array(profile.skills).map(&:to_s)
+        declared.flat_map do |name, companions|
+          next [] unless allowed.include?(name)
+
+          (companions - allowed).map do |missing|
+            Finding.new(check: "skill-drift", severity: :warn, fix: nil,
+                        message: "agent '#{profile.id}' allows skill '#{name}' but not its companion '#{missing}' — " \
+                                 "the pair cannot travel together for this agent. Allow '#{missing}' too.")
+          end
+        end
+      end
+    end
+
+    # { skill name => [agent ids that have their OWN version] }.
+    def specialized_by
+      return {} unless @skill_store.respond_to?(:agents)
+
+      @skill_store.agents.each_with_object({}) do |agent, acc|
+        @skill_store.names(agent: agent).each { |name| (acc[name] ||= []) << agent }
+      end
+    end
+
+    # { skill name => Set(agent ids that allow it explicitly) }. An agent with
+    # skills=nil allows everything and is not a "holder": it says nothing about which
+    # skills were meant to be shared.
+    def skill_holders
+      @profile_source.all.each_with_object({}) do |profile, acc|
+        next if profile.skills.nil?
+
+        Array(profile.skills).each { |name| (acc[name.to_s] ||= []) << profile.id }
+      end
+    end
+
+    # An agent's identity as WORDS: the distinctive tokens of its id plus whatever it
+    # calls itself in metadata. Structural tokens (agent/store/bot/…) are dropped and
+    # short ones ignored — "store" appears in every retail skill ever written, and one
+    # false positive is enough for an operator to stop reading the doctor.
+    IDENTITY_STOPWORDS = %w[agent agente store shop loja bot assistant assistente atendimento
+                            prod staging demo test main default].freeze
+
+    def identity_terms(agent_id)
+      profile = @profile_source.fetch(agent_id)
+      meta = profile ? (profile.metadata || {}) : {}
+      raw = [agent_id.to_s.split(/[-_.\s]+/), meta["name"], meta["display_name"], meta["store_name"]]
+      raw.flatten.compact.map { |t| t.to_s.strip }
+         .reject { |t| t.length < 4 || IDENTITY_STOPWORDS.include?(t.downcase) }
+         .uniq
+    end
+
+    # Whole-word, case- and accent-insensitive — the same reading the trigger matcher
+    # uses, for the same reason: a substring hit inside a longer word is a false
+    # positive, and one of those is enough to lose the operator.
+    def mentions?(text, term)
+      needle = fold(term)
+      return false if needle.empty?
+
+      /(?<![[:alnum:]])#{Regexp.escape(needle)}(?![[:alnum:]])/.match?(fold(text))
+    end
+
+    def fold(text) = text.to_s.unicode_normalize(:nfd).gsub(/\p{Mn}/, "").downcase
+
+    def body_of(content) = content.to_s.sub(/\A---\s*\n.*?\n---\s*\n/m, "")
+
     def platform_chat_rate_limit
       value = ((@settings_store&.get || {})["edge"] || {})["chat_rate_limit"]
       value.to_i.positive?

data/lib/insika/dsl/runtime.rb

@@ -26,16 +26,16 @@ module Insika
       # the runtime does not care how many agents it hosts, only that each one
       # arrives as an ordinary Pack.
       #
-      # `backend`: the store this graph owns (RFC-0017 A1). nil = the historic
+      # `backend`: the store this graph owns. nil = the historic
       # path, `INSIKA_DB` or memory — ENV is a default, never a requirement (the
-      # embed contract, item 5). An injected backend wins and is never widened
+      # embed contract). An injected backend wins and is never widened
       # back to the environment.
       def initialize(definition, backend: nil)
         @definition = definition
         @injected_backend = backend
         @packs = (definition.respond_to?(:packs) ? Array(definition.packs) : [definition.pack]).freeze
         @pack = @packs.first
-        # RFC-0017 A2: the graph's OWN RubyLLM config, built before the graph so
+        # the graph's OWN RubyLLM config, built before the graph so
         # every collaborator that talks to a provider is handed it at wiring time
         # rather than reading a process-wide singleton at call time.
         @llm = build_llm_context
@@ -44,7 +44,7 @@ module Insika
         import_packs
       end
 
-      # The graph's RubyLLM context (RFC-0017 A2) — an isolated config dup that
+      # The graph's RubyLLM context — an isolated config dup that
       # answers #chat. nil only under the test stub, where the fallback is the
       # RubyLLM constant itself. Read by the specs and by anything a host wires
       # alongside this graph.
@@ -178,7 +178,7 @@ module Insika
           guardrails: c[:guardrails], context_providers: context_providers(spine, c),
           edge_limiter: c[:edge_limiter],
           executor_extra: { settings_store: c[:settings_store], tool_trace_store: c[:tool_trace_store],
-                            llm: @llm }
+                            context_trace_store: c[:context_trace_store], llm: @llm }
         )
         register_authoring_commands(graph, c)
         register_workflows(graph)
@@ -228,17 +228,19 @@ module Insika
           system_file_store: Insika::SystemFileStore.new(config_store: config_store),
           mcp_store: Insika::McpStore.new(config_store: config_store),
           tool_trace_store: Insika::ToolTraceStore.new(store: backend),
+          context_trace_store: Insika::ContextTraceStore.new(store: backend),
           tool_registry: tool_registry,
           tool_catalog: Insika::ToolCatalog.new(tool_registry: tool_registry),
           skill_catalog: Insika::SkillCatalog.new([], store: skill_store),
           prompt_catalog: Insika::PromptCatalog.new([]),
           profile_source: Insika::StoredProfileSource.new(config_store: config_store),
-          # A2: the moderator/validator tiers ask a model too. A graph reading its
+          # the moderator/validator tiers ask a model too. A graph reading its
           # own key for the turn but the global one for a guardrail would be a
           # credential leak wearing the look of isolation.
           guardrails: Insika::Safety::Factory.new(settings_store: settings_store, llm: @llm),
           edge_limiter: Insika::EdgeLimiter.new(
-            ledger: Insika::UsageLedger.new(store: backend), settings_store: settings_store
+            ledger: Insika::UsageLedger.new(store: backend), settings_store: settings_store,
+            budget_ledger: spine.budget_ledger, event_stream: spine.event_stream
           )
         }
       end
@@ -251,6 +253,7 @@ module Insika
             agent_files: c[:agent_file_store], system_files: c[:system_file_store]
           ),
           Insika::Context::Providers::Skill.new(catalog: c[:skill_catalog]),
+          Insika::Context::Providers::SkillTrigger.new(catalog: c[:skill_catalog]),
           Insika::Context::Providers::ToolSearch.new(catalog: c[:tool_catalog]),
           Insika::Context::Providers::Memory.new(store: spine.memory_store),
           Insika::Context::Providers::Session.new(session_store: spine.session_store)
@@ -303,7 +306,7 @@ module Insika
         ([provider_name] + @packs.filter_map { |p| Insika::Coercion.presence(p.config[:provider])&.to_s }).uniq
       end
 
-      # RFC-0017 A2 — the graph's credentials belong to the graph. `RubyLLM.context`
+      # the graph's credentials belong to the graph. `RubyLLM.context`
       # is an isolated dup of the config that answers #chat, so two graphs in one
       # process no longer overwrite each other's keys: the global
       # `RubyLLM.configure` is a single slot PER PROVIDER, and the loser of that
@@ -332,7 +335,7 @@ module Insika
 
       # The LLMConfigurator's target (Studio: edit a provider key, no restart).
       # Scoped to THIS graph's context — a `RubyLLM.configure` here would reach
-      # into every other graph in the process, which is the leak A2 exists to
+      # into every other graph in the process, which is the leak exists to
       # close. nil = no context (test stub) -> the configurator's own global
       # default, unchanged.
       def llm_configure

data/lib/insika/dsl/server_boot.rb

@@ -25,7 +25,7 @@ module Insika
         # Fixed local token: logs into the Studio (cookie) and gates /v1 (Bearer).
         # Never a real secret — override with `token:` or ADMIN_TOKEN.
         @token = token || ENV.fetch("ADMIN_TOKEN", "local-demo")
-        # RFC-0017 A3: the /v1 app is a value now — the same one a host mounts.
+        # the /v1 app is a value now — the same one a host mounts.
         # This boot adds the Studio and a reactor around it, nothing else.
         @builder = Insika::Server::AppBuilder.new(runtime, token: @token)
       end
@@ -35,13 +35,13 @@ module Insika
         dispatch = Rack::URLMap.new("/studio" => Studio::App, "/" => @builder.app)
         endpoint = Async::HTTP::Endpoint.parse("http://#{@host}:#{@port}")
         middleware = Protocol::Rack::Adapter.new(dispatch)
-        # Item 16 / P4: the OTEL bridge is opt-in but must be reachable from the DSL
+        # the OTEL bridge is opt-in but must be reachable from the DSL
         # front door too — the convention is worthless if only config.ru can export.
         # nil (the default) -> attach is a no-op and no gem is loaded.
         telemetry = Insika::Telemetry.setup(service_name: ENV.fetch("OTEL_SERVICE_NAME", "insika"))
 
         banner(telemetry)
-        # RFC-0016 A3: first Ctrl-C/SIGTERM closes the intake and drains in-flight
+        # first Ctrl-C/SIGTERM closes the intake and drains in-flight
         # turns (INSIKA_DRAIN_TIMEOUT, default 20s); a second signal skips the wait.
         Insika::Shutdown.install(executor: @graph.executor)
         Async do
@@ -68,6 +68,7 @@ module Insika
           settings_store: @rt.component(:settings_store), llm_provider_store: @rt.component(:provider_store),
           mcp_store: @rt.component(:mcp_store), system_file_store: @rt.component(:system_file_store),
           tool_trace_store: @rt.component(:tool_trace_store),
+          context_trace_store: @rt.component(:context_trace_store),
           task_store: @graph.task_store, checkpoint_store: @graph.checkpoint_store,
           pending_action_store: @graph.pending_action_store
         )

data/lib/insika/dsl/system.rb

@@ -17,7 +17,7 @@ module Insika
     class System
       attr_reader :definitions, :workflows, :runtime_options
 
-      # `backend`: the store this system's graph owns (RFC-0017 A1). nil = the
+      # `backend`: the store this system's graph owns. nil = the
       # historic path (INSIKA_DB, or memory when unset). Set by `Insika.embed`.
       def initialize(definitions:, workflows: [], runtime: {}, backend: nil)
         @definitions = definitions.freeze