insika 0.2.0 → 0.7.0

data/lib/insika/commands/seed_demo_data.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Studio/CLI-facing adapter over Insika::Demo::Seeder — the one path both
+    # `insika demo:seed` and the Studio's "Seed demo data" button use (same
+    # discipline as RunDistillation: one object, two front doors).
+    class SeedDemoData
+      def initialize(seeder:, event_stream:)
+        @seeder = seeder
+        @event_stream = event_stream
+      end
+
+      # payload: { force: bool } -> the seeder's result Hash.
+      def call(command)
+        force = Coercion.truthy?(command.payload[:force] || command.payload["force"])
+        result = @seeder.seed!(force: force)
+        if result[:seeded]
+          @event_stream.emit(Insika::Event.new(
+                               type: :demo_data_seeded,
+                               data: { agent: result[:agent], counts: result[:counts] },
+                               meta: { at: Time.now.utc.iso8601 }
+                             ))
+        end
+        result
+      end
+    end
+  end
+end

data/lib/insika/commands/send_message.rb

@@ -20,12 +20,22 @@ module Insika
       # 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.
-      def initialize(profiles:, session_store:, task_store:, executor:, inbound_log: nil)
+      #
+      # `contact_store`/`followup_store` : the contact-state hook —
+      # a customer message reopens the contact cell and a cancellation keyword
+      # revokes it + falls the pending records. nil = the hook is off (parity).
+      # `store` is the SHARED backend the two stores ride — the keyword revoke
+      # commits in ONE transaction (D2). nil = best-effort separate writes.
+      def initialize(profiles:, session_store:, task_store:, executor:, inbound_log: nil,
+                     contact_store: nil, followup_store: nil, store: nil)
         @profiles = ProfileSource.coerce(profiles)
         @session_store = session_store
         @task_store = task_store
         @executor = executor
         @inbound_log = inbound_log
+        @contact_store = contact_store
+        @followup_store = followup_store
+        @store = store
       end
 
       def call(command)
@@ -37,8 +47,15 @@ module Insika
         profile = @profiles[agent] ||
                   (raise Insika::NotFoundError, "agent '#{agent}' not configured")
 
+        # A turn is text OR media. The media half (WS9) is what a voice note
+        # with no caption looks like on the wire — `{ parts: [{type: "audio",
+        # url: …}] }` and nothing else — and demanding a message here made the
+        # anchor use case unreachable end to end: the audio becomes the message
+        # at the :media stage, one step later.
         message = p[:message]
-        raise Insika::ValidationError, "message is required and non-empty" if message.to_s.strip.empty?
+        if message.to_s.strip.empty? && !media?(p[:parts])
+          raise Insika::ValidationError, "message is required and non-empty (or a media part)"
+        end
 
         # session_id XOR history (both -> error; neither -> one-shot).
         if p[:session_id] && p[:history]
@@ -50,7 +67,14 @@ module Insika
         # is what a turn has always meant. Refused here rather than downstream: a
         # typo'd origin would read as absent, and a marker that silently means
         # "unmarked" is worse than none — it looks like the filtering is on.
-        Insika::MessageOrigin.parse!(p[:origin])
+        origin = Insika::MessageOrigin.parse!(p[:origin])
+        # `scheduled` is ENGINE-RESERVED — the FollowupEngine's
+        # synthetic turn stamps it, and the edge must not let a consumer
+        # impersonate the engine's kick (a spoofed follow-up is the spam bug).
+        if origin == Insika::MessageOrigin::SCHEDULED
+          raise Insika::ValidationError,
+                "origin 'scheduled' is engine-reserved: it is stamped by the follow-up engine only"
+        end
         if p[:session_id]
           @session_store.find(p[:session_id]) ||
             (raise Insika::NotFoundError, "session '#{p[:session_id]}' not found")
@@ -66,6 +90,14 @@ module Insika
           return { task_id: prior, duplicate: true }
         end
 
+        # the contact-state hook — the ONLY path that sees every
+        # customer message. A real customer message reopens the contact cell; a
+        # cancellation keyword revokes it and falls the pending records in ONE
+        # transaction. Runs AFTER validation and dedup: a refused or duplicated
+        # message must not touch contact state. Nil-safe and policy-gated: no
+        # profile declaration = the hook is off (parity).
+        touch_contact(p, profile, command, origin)
+
         result = start_turn(command, p, profile)
         @inbound_log.record(key, result[:task_id]) if key
         result
@@ -73,6 +105,41 @@ module Insika
 
       private
 
+      # the contact bookkeeping of a customer message. The
+      # keyword cast IS a revocation: the customer just said the shut-off
+      # words — the pending records must fall with the state (D2, ONE
+      # transaction). The reset-on-origin list: only an origin that is
+      # nil/customer acts — an engine/operator-composed line (even one QUOTING
+      # the customer's words) never touches contact state. Nil collaborators
+      # or no profile declaration = the hook is a no-op (byte-parity).
+      def touch_contact(p, profile, command, origin)
+        return unless @contact_store
+        return unless origin.nil? || origin == Insika::MessageOrigin::CUSTOMER
+
+        policy = Insika::FollowupPolicy.parse(profile.followup)
+        return unless policy
+
+        customer = p[:customer]
+        return if customer.to_s.empty?
+
+        keyword = policy.match_keyword(p[:message].to_s)
+        if keyword
+          # one transaction on the shared backend: the revoke and the pending
+          # fall commit together — a half-cancelled opt-out is the spam bug.
+          if @store
+            @store.transaction do
+              @contact_store.set_revoked(tenant: command.meta[:tenant], customer: customer)
+              @followup_store&.cancel_pending_for(tenant: command.meta[:tenant], customer: customer)
+            end
+          else
+            @contact_store.set_revoked(tenant: command.meta[:tenant], customer: customer)
+            @followup_store&.cancel_pending_for(tenant: command.meta[:tenant], customer: customer)
+          end
+        else
+          @contact_store.set_granted(tenant: command.meta[:tenant], customer: customer)
+        end
+      end
+
       # The turn (or the verdict that this message joined someone else's).
       def start_turn(command, p, profile)
         message = p[:message]
@@ -83,7 +150,10 @@ module Insika
         # boot). Only offered on a surface that can report the verdict back —
         # coalescing a caller that cannot hear `merged` makes it deliver the
         # same answer twice.
-        if coalescable?(command)
+        # A message carrying MEDIA never joins another turn: `collect`/`steer`
+        # move TEXT into a task that is already at the door, and its parts would
+        # be left behind — the customer's photo would silently not exist.
+        if coalescable?(command) && !media?(p[:parts])
           if (joined = @executor.collect_into_pending(p[:session_id], message, profile: profile))
             return { task_id: joined, merged: true }
           end
@@ -101,16 +171,41 @@ 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])
+        # the channel clock starts HERE — the 202-owning request
+        # is accepted, before the SessionActor FIFO and the debounce window.
+        # `first_balloon_ms` is the wait the customer feels, so t0 is not the
+        # moment the turn finally runs; the same object travels with the turn
+        # and `:first_balloon` closes the window at the outbox flush.
         # `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.
         # No-op in every other mode.
         @executor.interrupt_running(p[:session_id], profile: profile, replaced_by: task.id)
-        @executor.spawn_in_session(task, profile: profile)
+        @executor.spawn_in_session(task, profile: profile,
+                                          timing: channel_inbound_timing(command))
         { task_id: task.id }
       end
 
+      # allocate the channel clock at 202 acceptance and stamp
+      # `:inbound` — the window's start. `breakdown: false` when INSIKA_TURN_TIMING
+      # is off, so a channel turn measures ONLY first_balloon_ms (H-latência never
+      # depends on the flag). nil for every non-channel transport: no clock to start.
+      def channel_inbound_timing(command)
+        return nil unless command.meta[:transport].to_s.start_with?("channel:")
+
+        timing = Insika::TurnTiming.new(breakdown: Insika::TurnTiming.enabled?)
+        timing.mark(:inbound)
+        timing
+      end
+
+      # Does the payload carry a part the engine will turn into the turn's
+      # substance — audio (transcribed into the message) or an image (attached
+      # to the ask)? A text part is not media: it is the message, spelled long.
+      def media?(parts)
+        Insika::Media.parts(parts).any? { |p| p.audio? || p.image? }
+      end
+
       def coalescable?(command)
         transport = command.meta[:transport]
         COALESCABLE_TRANSPORTS.include?(transport) || transport.to_s.start_with?("channel:")
@@ -133,7 +228,9 @@ module Insika
           session_id: payload[:session_id] || payload["session_id"],
           history: payload[:history] || payload["history"],
           origin: payload[:origin] || payload["origin"],
-          event_id: payload[:event_id] || payload["event_id"]
+          event_id: payload[:event_id] || payload["event_id"],
+          parts: payload[:parts] || payload["parts"],
+          customer: payload[:customer] || payload["customer"]
         }
       end
 

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

@@ -8,17 +8,20 @@ module Insika
     # (transport/command/url/enabled + `env` credentials) in the McpStore. The
     # credentials are sentinel-aware per key (__OCULTO__ preserves; "" clears;
     # a new string replaces). Returns the MASKED record (env never comes back in
-    # plaintext). Durable config CRUD — running an MCP client against the
-    # instance is later runtime.
+    # plaintext). Evicts any memoized client for this name (mcp_registry is
+    # optional so a bare CLI/store-only caller need not wire one) so an edited
+    # command/url/env takes effect on the instance's next call — no restart.
     class UpsertMcp
-      def initialize(mcp_store:, event_stream:)
+      def initialize(mcp_store:, event_stream:, mcp_registry: nil)
         @mcp_store = mcp_store
         @event_stream = event_stream
+        @mcp_registry = mcp_registry
       end
 
       def call(command)
         p = AgentPayload.symbolize(command.payload)
         masked = @mcp_store.upsert(p) # validates `name`; returns masked
+        @mcp_registry&.evict(masked["name"])
 
         @event_stream.emit(Insika::Event.new(
                              type: :mcp_upserted,

data/lib/insika/commands/write_concept.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command: writes a concept (complete concept markdown) into the
+    # KnowledgeStore. Validates the frontmatter (a `name` is required) before
+    # writing — same discipline as `WriteSkill`. The STORE POSITION (the
+    # `agent`/`name`/`tenant` triple) is the identity, exactly like a skill:
+    # an operator editing the raw markdown may leave the frontmatter `name:`
+    # unchanged even while promoting `provenance: observed` to `policy` —
+    # that promotion IS this command, no separate "promote" action needed.
+    # -> { name, agent, tenant, updated_at }.
+    class WriteConcept
+      def initialize(knowledge_store:, event_stream:)
+        @knowledge_store = knowledge_store
+        @event_stream = event_stream
+      end
+
+      def call(command)
+        p = AgentPayload.symbolize(command.payload)
+        name = AgentPayload.presence(p[:name])
+        agent = AgentPayload.presence(p[:agent])
+        tenant = AgentPayload.presence(p[:tenant])
+        content = p[:content].to_s
+        raise Insika::ValidationError, "name is required" if name.nil?
+        raise Insika::ValidationError, "agent is required" if agent.nil?
+
+        parsed = validate_frontmatter!(content)
+        rec = @knowledge_store.write(agent, name, content, tenant: tenant)
+        emit(parsed[:type], name, agent)
+        { name: name, agent: agent, tenant: tenant, updated_at: rec["updated_at"] }
+      end
+
+      private
+
+      def emit(type, name, agent)
+        @event_stream.emit(Insika::Event.new(
+                             type: :knowledge_learned, data: { name: name, type: type, agent: agent },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+      end
+
+      # Mirrors WriteSkill's frontmatter guard: without a parseable `name`,
+      # the concept would be unreachable by name once written (the Studio
+      # list keys on the store position, but the editor round-trips the
+      # content) — fail early, in the Command.
+      def validate_frontmatter!(content)
+        parsed = Insika::Knowledge::Concept.parse(content)
+        raise Insika::ValidationError, "concept missing YAML frontmatter (--- ... ---) or a `name`" if parsed.nil?
+
+        parsed
+      end
+    end
+  end
+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

@@ -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
@@ -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,6 +8,10 @@ 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.
@@ -22,12 +26,12 @@ module Insika
   #              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, :labels) do
+                                :source, :pinned, :labels, :layer) do
     def self.build(content:, placement:, source:, priority: 50, tokens: nil,
-                   pinned: false, labels: [])
+                   pinned: false, labels: [], layer: nil)
       new(content: content, placement: placement, priority: priority,
           tokens: tokens, source: source, pinned: pinned,
-          labels: Array(labels).map { |l| label(l) })
+          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

data/lib/insika/context/priority.rb

@@ -20,8 +20,13 @@ module Insika
       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)
+      KNOWLEDGE    = 77  # <knowledge> top-K learned concepts (Knowledge) —
+                         #   below curated skills, above a single conversation's memory
       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