insika 0.1.0 → 0.3.0

data/lib/insika/commands/session_purge.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Insika
+  module Commands
+    # The CONVERSATION footprint of a session, purged (WS8/LGPD). Shared by
+    # `forget_customer` and `delete_tenant_data` because "erase this person"
+    # and "erase this tenant" differ only in WHICH sessions they name — what a
+    # session leaves behind is the same list, and a second copy of that list is
+    # a second thing to forget to update.
+    #
+    # Deleting the session record alone is NOT erasure: the customer's own text
+    # lives in the task's persisted command payload, the whole transcript lives
+    # in the turn's checkpoints, and the answer as it was handed to the channel
+    # lives in the outbox record's payload. All four go together or none of them
+    # counts.
+    #
+    # A task is deleted whatever its status — this is a deletion order, not the
+    # retention sweep (which spares live tasks on purpose). The stores it needs
+    # beyond the session are optional (deployment components): a graph without
+    # them purges what it has and reports zero for the rest.
+    module SessionPurge
+      # ids: the session ids to erase. -> { tasks:, checkpoints:, deliveries:, pairs: }
+      def purge_sessions(ids)
+        ids = Array(ids).map(&:to_s)
+        return { tasks: 0, checkpoints: 0, deliveries: 0, pairs: 0 } if ids.empty?
+
+        tasks, checkpoints, model_visible = purge_tasks_of(ids)
+        deliveries = @outbox_store ? @outbox_store.purge_sessions(ids) : 0
+        pairs = @shadow_pairs ? @shadow_pairs.purge_sessions(ids) : 0
+        ids.each do |id|
+          @tool_trace_store&.clear(id)
+          @context_trace_store&.clear(id)
+          @session_store.delete(id)
+        end
+        { tasks: tasks, checkpoints: checkpoints, model_visible: model_visible,
+          deliveries: deliveries, pairs: pairs }
+      end
+
+      private
+
+      # -> [tasks removed, checkpoint records removed, model-visible records removed].
+      # the model-visible traces are transcripts — they die next to
+      # their checkpoints (the same single list, so "erase this person" cannot
+      # forget one half). The id list is SNAPSHOTTED (`to_a`) before the deletes:
+      # `each_id` enumerates the backend's keys lazily, and deleting under it
+      # would skip records.
+      def purge_tasks_of(ids)
+        return [0, 0, 0] unless @task_store
+
+        wanted = ids.each_with_object({}) { |id, acc| acc[id] = true }
+        tasks = 0
+        checkpoints = 0
+        model_visible = 0
+        @task_store.each_id.to_a.each do |task_id|
+          task = @task_store.find(task_id)
+          next unless task && wanted[task.session_id.to_s]
+
+          checkpoints += @checkpoint_store ? @checkpoint_store.purge(task_id) : 0
+          model_visible += @model_visible_trace_store ? @model_visible_trace_store.purge(task_id) : 0
+          @task_store.delete(task_id)
+          tasks += 1
+        end
+        [tasks, checkpoints, model_visible]
+      end
+    end
+  end
+end

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/contact_store.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  # the durable CONTACT STATE cell per (tenant, customer)— ONE
+  # derived cell, never a transition log (D2): `granted | revoked |
+  # unavailable`, the sends-without-reply counter and the last outbound
+  # timestamp. Dumb domain store: it holds no policy and no follow-up records
+  # (the firer and the inbound hook own those transformations).
+  #
+  # Invariants (the firer enforces them, the store only records):
+  #   · only `granted` may be messaged; absent = never messaged (:consent block);
+  #   · `revoked` is immediate and permanent until the customer speaks;
+  #   · `unavailable` means silence ≠ refusal — set when sends_without_reply
+  #     reaches the policy's ceiling; further fires block until the customer
+  #     speaks; any customer message reopens (sets granted + zeroes the counter).
+  #
+  # The customer identifier is the SAME string the message contract carries
+  # (`customer:` on /v1/messages, WS8).
+  class ContactStore
+    SCOPE = "contacts"
+    STATES = %w[granted revoked unavailable].freeze
+
+    Cell = Data.define(:state, :sends_without_reply, :last_outbound_at, :updated_at)
+
+    def initialize(store:)
+      @store = store
+    end
+
+    # -> [Cell] | nil (absent = never messaged — the :consent block). nil
+    # customer -> nil (an untagged conversation has no cell).
+    def get(tenant:, customer:)
+      return nil if customer.to_s.empty?
+
+      record = @store.get(SCOPE, key(tenant, customer))
+      record && to_cell(record)
+    end
+
+    # -> { "<tenant>:<customer>" => raw record } — the whole scope, for the
+    # doctor's contact summary and the Studio (read-only folds; the mutations
+    # go through the commands, D10).
+    def cells
+      @store.list(SCOPE).each_with_object({}) do |k, acc|
+        record = @store.get(SCOPE, k)
+        acc[k] = record if record
+      end
+    end
+
+    # The ONLY writers. Each is a read-check-write on the cell (#transaction —
+    # two processes flipping the state in the same second serialize).
+
+    # Any customer message reopens the conversation: `granted` + the counter
+    # reset. The consent record itself (D2/D7) is the `schedule` tool call.
+    def set_granted(tenant:, customer:, now: Time.now.utc)
+      write(tenant, customer, now) do |record|
+        record["state"] = "granted"
+        record["sends_without_reply"] = 0
+      end
+    end
+
+    # D7: the schedule tool's consent write. The customer agreeing
+    # in-conversation IS the consent — but ONLY a customer message reopens
+    # (D2): this NEVER lifts `:unavailable` and NEVER resets
+    # sends_without_reply, so a re-booking inside the scheduled turn cannot
+    # clear the silence protection. Creates the cell when absent (the first
+    # consent). Raises Insika::ValidationError on `:revoked` — an opt-out is
+    # permanent; the caller refuses.
+    def consent(tenant:, customer:, now: Time.now.utc)
+      raise Insika::ValidationError, "customer is required" if customer.to_s.empty?
+
+      @store.transaction do
+        record = @store.get(SCOPE, key(tenant, customer)) ||
+                 { "state" => "granted", "sends_without_reply" => 0,
+                   "last_outbound_at" => nil, "updated_at" => nil }
+        if record["state"] == "revoked"
+          raise Insika::ValidationError,
+                "this customer opted out — you cannot schedule a follow-up"
+        end
+
+        record["state"] ||= "granted"
+        record["updated_at"] = now.iso8601
+        @store.set(SCOPE, key(tenant, customer), record)
+        to_cell(record)
+      end
+    end
+
+    # Keyword / channel opt-out / operator: immediate and permanent until the
+    # customer speaks. Nothing auto-revokes.
+    def set_revoked(tenant:, customer:, now: Time.now.utc)
+      write(tenant, customer, now) do |record|
+        record["state"] = "revoked"
+      end
+    end
+
+    # Silence reached the policy's ceiling (the firer counts sends without a
+    # reply); further fires block until the customer speaks.
+    def mark_unavailable(tenant:, customer:, now: Time.now.utc)
+      write(tenant, customer, now) do |record|
+        record["state"] = "unavailable"
+      end
+    end
+
+    # The firer's call: sends_without_reply += 1, last_outbound_at = now.
+    # Creates the cell when absent (granted — the firer checks the GO before
+    # bumping, so a bump only happens after the consent gate).
+    def bump_outbound(tenant:, customer:, now: Time.now.utc)
+      write(tenant, customer, now) do |record|
+        record["state"] ||= "granted"
+        record["sends_without_reply"] = record["sends_without_reply"].to_i + 1
+        record["last_outbound_at"] = now.iso8601
+      end
+    end
+
+    # Purge paths (C11 — the LGPD footprint): one cell; a whole tenant's
+    # (prefix scan); age-based. All nil-safe.
+
+    # -> true | false (did the cell exist?)
+    def delete(tenant:, customer:)
+      return false if customer.to_s.empty?
+
+      @store.delete(SCOPE, key(tenant, customer))
+    end
+
+    # -> count removed.
+    def purge(tenant:)
+      prefix = "#{tenant_id(tenant)}:"
+      keys = @store.list(SCOPE).select { |k| k.start_with?(prefix) }
+      keys.each { |k| @store.delete(SCOPE, k) }
+      keys.size
+    end
+
+    # Cells untouched past the cutoff (WS8 retention). -> count removed.
+    def delete_older_than(time)
+      cutoff = time.utc.iso8601
+      removed = 0
+      @store.list(SCOPE).each do |k|
+        record = @store.get(SCOPE, k)
+        next unless record && record["updated_at"].to_s < cutoff
+
+        @store.delete(SCOPE, k)
+        removed += 1
+      end
+      removed
+    end
+
+    private
+
+    # One cell per (tenant, customer); blank tenant -> the literal "platform"
+    # (outcome_store.rb's rule — contact, follow-up and outcome keys share one
+    # tenant segment so the purge prefix scans line up).
+    def key(tenant, customer)
+      "#{tenant_id(tenant)}:#{customer}"
+    end
+
+    def tenant_id(tenant)
+      t = tenant.to_s
+      t.empty? ? "platform" : t
+    end
+
+    # Read-check-write inside the backend transaction (the budget_ledger.rb:38
+    # discipline): two writers racing the same cell serialize on the backend
+    # lock and the loser re-reads.
+    def write(tenant, customer, now, &block)
+      raise Insika::ValidationError, "customer is required" if customer.to_s.empty?
+
+      @store.transaction do
+        record = @store.get(SCOPE, key(tenant, customer)) ||
+                 { "state" => "granted", "sends_without_reply" => 0,
+                   "last_outbound_at" => nil, "updated_at" => nil }
+        block.call(record)
+        record["updated_at"] = now.iso8601
+        @store.set(SCOPE, key(tenant, customer), record)
+        to_cell(record)
+      end
+    end
+
+    def to_cell(record)
+      Cell.new(state: record["state"], sends_without_reply: record["sends_without_reply"].to_i,
+               last_outbound_at: record["last_outbound_at"], updated_at: record["updated_at"])
+    end
+  end
+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
 
@@ -66,7 +66,14 @@ module Insika
 
       fragments = []
       tasks.each do |provider, child|
-        fragments.concat(Array(child.wait))
+        # stamp the layer at PRODUCTION from the PROVIDER's
+        # declaration — authoritative, so a fragment that arrives pre-stamped
+        # cannot sneak above the boundary (a :volatile provider emitting a
+        # fragment with layer :identity would otherwise bypass the doctor's
+        # class-level check). A custom provider that never learned the contract
+        # leaves :volatile.
+        layer = provider.respond_to?(:layer) ? provider.layer : :volatile
+        Array(child.wait).each { |f| fragments << f.with(layer: layer) }
       rescue StandardError => e # Async::TimeoutError is a StandardError; Async::Stop is NOT (propagates)
         handle_provider_failure(provider, e, request)
       end
@@ -97,7 +104,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
@@ -135,10 +142,14 @@ module Insika
       [survivors, evicted_sources]
     end
 
-    # Step 6: assembly in DETERMINISTIC canonical order.
+    # Step 6: assembly in DETERMINISTIC canonical order. The
+    # identity-first partition — nothing volatile renders above the cache
+    # boundary. Each partition keeps the existing canonical sort; the partition
+    # is by LAYER only.
     def assemble(fragments, cap, evicted)
       system_frags = fragments.select { |f| f.placement == :system }
-                              .sort_by.with_index { |f, i| [-f.priority, f.source.to_s, i] }
+      identity, volatile = system_frags.partition { |f| (f.layer || :volatile) == :identity }
+      system_frags = sort_canonical(identity) + sort_canonical(volatile)
       history_frags = fragments.select { |f| f.placement == :history } # production order (chronological)
       tool_frags = fragments.select { |f| f.placement == :tool_context }
 
@@ -153,6 +164,13 @@ module Insika
       )
     end
 
+    # The canonical system sort (priority DESC, source ASC, production index) —
+    # applied WITHIN each layer partition, so the prior order survives inside
+    # it and the boundary is the only thing that moved.
+    def sort_canonical(frags)
+      frags.sort_by.with_index { |f, i| [-f.priority, f.source.to_s, i] }
+    end
+
     # :provider_warning. The Builder does not know task_id/seq (correlation is
     # the Executor's job) — emits with what it has; Event#to_h does meta.compact.
     def emit_warning(provider_id, message, request)

data/lib/insika/context/fragment.rb

@@ -8,12 +8,40 @@ 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)
+  #   layer:     :identity | :volatile | nil. Stamped by the Builder
+  #              at production from the provider's declaration; nil (a fragment
+  #              built outside the Builder) reads as :volatile everywhere it is
+  #              consumed — parity, never a crash.
+  #   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, :layer) do
     def self.build(content:, placement:, source:, priority: 50, tokens: nil,
-                   pinned: false)
+                   pinned: false, labels: [], layer: nil)
       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) }, layer: layer)
+    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,9 +18,13 @@ 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)
+      BRIEFING     = 65  # <briefing> session working state (Briefing) — D5:
+                         #   below every identity/skill/memory block (never breaks the
+                         #   pinned prefix), above the turn's own <request_context>.
       HISTORY_MAX  = 79  # history ceiling by recency (Session)
       HISTORY_BASE = 60  # history base; +idx up to the ceiling (Session)
       REQUEST      = 40  # <request_context> — turn injection, the most cuttable

data/lib/insika/context/provider.rb

@@ -9,11 +9,25 @@ module Insika
     def required? = false          # true -> failure aborts the turn
     def enabled_for?(_profile) = true
     def call(_request) = []        # -> [ContextFragment]; may do IO
+    # which cache layer the output belongs to.
+    #   :identity -> changes only on deploy/config edit (the cacheable prefix);
+    #   :volatile -> may change per turn (the Builder renders identity first).
+    # :volatile is the conservative default — nothing gets pinned by accident.
+    def layer = :volatile
   end
 
   # Input for the provider contract.
-  #   session:    SessionStore::Session | nil
-  #   checkpoint: Checkpoint | nil (present on ResumeTask — history comes from it)
+  #   session:      SessionStore::Session | nil
+  #   checkpoint:   Checkpoint | nil (present on ResumeTask — history comes from it)
+  #   memory_scope: the CUSTOMER-scoped memory cell (WS8): "[tenant:]customer"
+  #                 when the request carries a customer, else nil (the providers
+  #                 fall back to tenant || session). Kept separate from `tenant`
+  #                 (the <request_context> merchant label) on purpose.
   ContextRequest = Data.define(:session, :message, :profile, :tenant, :vars,
-                               :checkpoint)
+                               :checkpoint, :memory_scope) do
+    def initialize(session: nil, message: nil, profile: nil, tenant: nil, vars: {},
+                   checkpoint: nil, memory_scope: nil)
+      super
+    end
+  end
 end