insika 0.2.0 → 0.3.0

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

@@ -22,6 +22,9 @@ module Insika
       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

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

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Insika
+  module Context
+    module Providers
+      # Read path for the session briefing: the per-session
+      # working-state the agent keeps and asks for. Thin adapter over the
+      # SessionStore, same pattern as Memory: one `:system` fragment,
+      # deterministic. The MISSING list is rendered, never implied — that list
+      # is what stops the model re-asking for a field already given.
+      class Briefing < ContextProvider
+        def initialize(session_store:)
+          @session_store = session_store
+        end
+
+        # Stable id -> the context-trace category "briefing".
+        def id = "briefing"
+
+        # Pack-declared: no briefing_fields -> no provider (the Builder still
+        # applies the `context_providers` allowlist on top — two gates, like Memory).
+        def enabled_for?(profile)
+          fields = profile.respond_to?(:briefing_fields) ? profile.briefing_fields : nil
+          !Array(fields).empty?
+        end
+
+        # required? == false (default): a store failure degrades via the Builder's
+        # warning path, never aborts the turn.
+        def call(request)
+          session = request.respond_to?(:session) ? request.session : nil
+          return [] if session.nil? # one-shot turns have no briefing
+
+          briefing = briefing_for(session)
+          fields = briefing["fields"] || {}
+          declared = Array(request.profile.briefing_fields)
+          return [] if declared.empty? # defensive; enabled_for? already gates
+
+          block = format_block(declared, fields, briefing["next_step"])
+          return [] if block.nil?
+
+          [ContextFragment.build(content: block, placement: :system,
+                                 priority: Context::Priority::BRIEFING,
+                                 source: id)]
+        end
+
+        private
+
+        # Re-reads the briefing from the store, like the Session provider: the
+        # persisted record is the source of truth, not the request's turn-start
+        # snapshot. A read failure propagates to the Builder, which degrades it
+        # to a :provider_warning (required? == false).
+        def briefing_for(session)
+          @session_store.find(session.id)&.briefing || {}
+        end
+
+        # Byte contract (the specs assert this shape):
+        #   <briefing>
+        #   known:
+        #     size: M
+        #   still missing: delivery_day
+        #   next step: send the payment link tomorrow at 10
+        #   </briefing>
+        # Rules: `known` renders only when at least one declared field has a
+        # stored value; `still missing` renders every declared field with no
+        # stored value (including the all-missing case — that is the block's
+        # job); `next step` renders only when non-nil; stored keys NOT in the
+        # declaration are never rendered (they stay in the store and reappear if
+        # the pack re-declares them).
+        def format_block(declared, fields, next_step)
+          known = declared.filter_map do |name|
+            "  #{name}: #{flatten(fields[name])}" if Coercion.present?(fields[name])
+          end
+          missing = declared.reject { |name| Coercion.present?(fields[name]) }
+
+          lines = []
+          lines << "known:" unless known.empty?
+          lines.concat(known)
+          lines << "still missing: #{missing.join(', ')}" unless missing.empty?
+          lines << "next step: #{flatten(next_step)}" if Coercion.present?(next_step)
+          return nil if lines.empty?
+
+          <<~BLOCK.strip
+            <briefing>
+            #{lines.join("\n")}
+            </briefing>
+          BLOCK
+        end
+
+        # utf8 the value and flatten newlines/whitespace so a value can never
+        # break the block's line structure.
+        def flatten(value)
+          Coercion.utf8(value.to_s).gsub(/\s+/, " ").strip
+        end
+      end
+    end
+  end
+end

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

@@ -20,7 +20,7 @@ module Insika
         # required? == false (default): a failure (store unavailable) becomes a
         # :provider_warning + graceful degradation — never aborts the turn.
         def call(request)
-          tenant = memory_tenant(request)
+          tenant = memory_scope(request)
           facts = @store.facts(tenant: tenant)
           notes = @store.notes(tenant: tenant, limit: @notes_limit)
           return [] if facts.empty? && notes.empty?
@@ -33,15 +33,24 @@ module Insika
 
         private
 
-        # Engine memory scope: an EXPLICIT tenant from the Command wins
-        # (multi-merchant override); otherwise the SESSION (=chat) — engine-owner
-        # memory is per-chat. No session (one-shot) and no tenant -> nil (MemoryStore
-        # applies _default). Symmetric to the write path (`state.tenant` in the Executor).
-        def memory_tenant(request)
+        # Engine memory scope (WS8): the request's CUSTOMER-scoped cell
+        # ("[tenant:]customer" — engine-owner memory is per customer, never per
+        # tenant) wins; otherwise an EXPLICIT tenant from the Command (the
+        # multi-merchant override); otherwise the SESSION (=chat), MARKED like
+        # the write path ("chat:<session id>" —  : a session cell is
+        # never a bare cell, so the drill cannot read a conversation as a
+        # customer). No session (one-shot) and no tenant -> nil (MemoryStore
+        # applies _default). Symmetric to the write path (`state.tenant` in the
+        # Executor).
+        def memory_scope(request)
+          scoped = request.respond_to?(:memory_scope) ? request.memory_scope : nil
+          return scoped if scoped
+
           explicit = request.respond_to?(:tenant) ? request.tenant : nil
           return explicit if explicit
 
-          request.respond_to?(:session) ? request.session&.id : nil
+          session = request.respond_to?(:session) ? request.session : nil
+          session && session.id ? "#{Insika::MemoryStore::SESSION_TAG}:#{session.id}" : nil
         end
 
         # Passive <memory> (no instruction — the HOW of writing lives in the `remember` tool).

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

@@ -10,11 +10,26 @@ module Insika
       #
       # PER-AGENT identity. `profile.prompt_files` (file names)
       # wins over the wiring's `files:` — this fixes the limitation of a new
-      # agent inheriting Bia's prompt. The content comes from `agent_files`
+      # agent inheriting the previous persona's prompt. The content comes from `agent_files`
       # (AgentFileStore, lives in the Store), with a File.read fallback
       # for on-disk paths (compat/seed). Without prompt_files -> uses the wiring's
       # `files:` (deployment default; byte-for-byte parity).
       class Prompt < ContextProvider
+        # Engine-owned execution discipline, appended AFTER the agent's identity.
+        # The one behavior every reference harness bakes into its base prompt
+        # (OpenClaw's "Execution Bias") and this engine was missing: a weak tool
+        # result read as final. A constant — byte-identical every turn, so
+        # prompt_caching pays ONE write on the deploy that introduces it, never
+        # per turn. Opt-out per profile (`tool_persistence false`), the single
+        # default-ON profile flag: the proven-good behavior is the default, the
+        # exception is the thing an operator declares.
+        TOOL_PERSISTENCE = "## Tool discipline\n" \
+          "- Weak or empty tool result: try again with a different approach — rephrase the " \
+          "query, use a synonym or broader term, drop a secondary filter — before telling " \
+          "the user you found nothing. Do not narrate the retries. Then conclude.\n" \
+          "- Tool error: read the error, fix the arguments or try another path; never " \
+          "repeat the exact same call."
+
         def initialize(base: "", files: [], catalog: nil, agent_files: nil, system_files: nil)
           @base = base
           @files = Array(files)
@@ -24,6 +39,8 @@ module Insika
         end
 
         def required? = true
+        # identity (config/agent-file derived — already pinned).
+        def layer = :identity
 
         def call(request)
           fragments = []
@@ -62,7 +79,18 @@ module Insika
           else
             sources.each { |src| parts << read_source(profile&.id, src.to_s) }
           end
-          parts.reject { |p| p.nil? || p.strip.empty? }.join("\n\n")
+          identity = parts.reject { |p| p.nil? || p.strip.empty? }.join("\n\n")
+          # Discipline rides an EXISTING identity, never substitutes one: an
+          # agent with no identity at all must stay detectably empty.
+          return identity if identity.empty? || !tool_persistence?(profile)
+
+          "#{identity}\n\n#{TOOL_PERSISTENCE}"
+        end
+
+        # nil/absent/true = ON (the engine default); only an explicit `false`
+        # turns it off. Defensive respond_to?: a minimal profile stub reads ON.
+        def tool_persistence?(profile)
+          !(profile.respond_to?(:tool_persistence) && profile.tool_persistence == false)
         end
 
         # GLOBAL system files: apply to every agent,

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

@@ -10,6 +10,8 @@ module Insika
       class Skill < CatalogProvider
         # priority 80: above deferred tools (70), below pinned identity.
         def priority = Context::Priority::SKILL
+        # catalog + allowlist — config only.
+        def layer = :identity
 
         private
 

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

@@ -10,6 +10,8 @@ module Insika
       class ToolSearch < CatalogProvider
         # priority 70: below skills (80) in the sacrifice order.
         def priority = Context::Priority::TOOL_SEARCH
+        # tool registry + tools_deferred — config only.
+        def layer = :identity
 
         private
 

data/lib/insika/context_trace_store.rb

@@ -24,7 +24,8 @@ module Insika
     # 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.
+    # no-op. -> the sanitized entry (parks it on TurnState for the
+    # stage-8 cache merge).
     def record(session_id:, entry:)
       sid = session_id.to_s
       return if sid.empty?
@@ -33,6 +34,7 @@ module Insika
       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))
+      e
     rescue StandardError
       nil
     end
@@ -63,6 +65,11 @@ module Insika
           cat = { "tokens" => int(c[:tokens] || c["tokens"]),
                   "fragments" => int(c[:fragments] || c["fragments"]),
                   "pinned" => int(c[:pinned] || c["pinned"]) }
+          # which cache layer the category belongs to ("identity" |
+          # "volatile"). Absent for a category recorded before the contract (or
+          # one that never learned it) — the view guards on nil.
+          layer = c[:layer] || c["layer"]
+          cat["layer"] = layer.to_s if layer
           # 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.
@@ -71,8 +78,36 @@ module Insika
           acc[name.to_s] = cat
         end,
         "tools" => { "count" => int(tools[:count] || tools["count"]),
-                     "tokens" => int(tools[:tokens] || tools["tokens"]) }
+                     "tokens" => int(tools[:tokens] || tools["tokens"]) },
+        "fingerprints" => fingerprints_of(e[:fingerprints] || e["fingerprints"]),
+        "cache" => cache_of(e[:cache] || e["cache"])
+      }.compact
+    end
+
+    # { name => sha256-hex }; names stringified, non-strings
+    # dropped. Absent when the caller passed nothing (a trace recorded before
+    # this feature has no key and the view guards on nil).
+    def fingerprints_of(raw)
+      return nil unless raw.is_a?(Hash) && !raw.empty?
+
+      raw.each_with_object({}) do |(name, hex), acc|
+        acc[name.to_s] = hex.to_s if hex.is_a?(String)
+      end.then { |h| h.empty? ? nil : h }
+    end
+
+    # { hit_pct, cached_tokens, prompt_tokens, invalidation_reason }.
+    # Unknown keys dropped. Present only when the caller passed it.
+    def cache_of(raw)
+      return nil unless raw.is_a?(Hash)
+
+      c = {
+        "hit_pct" => int_or_nil(raw[:hit_pct] || raw["hit_pct"]),
+        "cached_tokens" => int(raw[:cached_tokens] || raw["cached_tokens"]),
+        "prompt_tokens" => int(raw[:prompt_tokens] || raw["prompt_tokens"]),
+        "invalidation_reason" => raw[:invalidation_reason] || raw["invalidation_reason"]
       }
+      c["invalidation_reason"] = c["invalidation_reason"].to_s unless c["invalidation_reason"].nil?
+      c
     end
 
     # Labels are {name, reason} in string keys (ContextFragment.label). A bare string
@@ -88,5 +123,6 @@ module Insika
     end
 
     def int(value) = Integer(value || 0)
+    def int_or_nil(value) = value.nil? ? nil : Integer(value)
   end
 end