insika 0.3.0 → 0.8.0

data/lib/insika/executor.rb

@@ -22,7 +22,8 @@ module Insika
                     delegation_store: nil, channel_delivery: nil, llm: nil,
                     context_trace_store: nil, reliability: nil, media: nil, media_output: nil,
                     grounding_enforcer: nil, cache_series_store: nil,
-                    contact_store: nil, followup_store: nil, model_visible_trace_store: nil)
+                    contact_store: nil, followup_store: nil, model_visible_trace_store: nil,
+                    knowledge_store: nil)
       @context_builder = context_builder
       @policy_engine = policy_engine
       @middleware = middleware
@@ -98,6 +99,10 @@ module Insika
       # the platform layer of the queue policy (nil = per-agent and
       # defaults only, which is `followup` with no window — today's behavior).
       @settings_store = settings_store
+      # LEARNED concepts, extracted from a turn's transcript after it
+      # completes. nil = the loop is off (parity — every write path below is
+      # skipped, zero allocations). Gated per-agent by `profile.knowledge`.
+      @knowledge_store = knowledge_store
       # RubyLLM glue (stages 5-7): chat assembly delegated to ChatBuilder. Its
       # optional deps tool_catalog (Tool Search) and memory_store (cross-session
       # memory) matter only to it — nil = parity (deferred
@@ -123,7 +128,11 @@ module Insika
         # tools gated by a parsed policy AND both stores present. nil = never
         # wired (parity).
         contact_store: contact_store,
-        followup_store: followup_store
+        followup_store: followup_store,
+        # the builder wires the load_knowledge system tool gated by
+        # @knowledge_store + profile.knowledge["retrieve"]. nil = never
+        # wired (parity — the write path above stays unaffected either way).
+        knowledge_store: knowledge_store
       )
       # Stage-3-tail tool assembly (capability resolution, instantiation,
       # injection, dedup join, ToolEnvelope wrap) — extracted collaborator.
@@ -175,6 +184,20 @@ module Insika
     # scans, nothing mines).
     attr_accessor :harvest_engine
 
+    # Forces the long-lived turn supervisor (and its tick/alert/distill/harvest
+    # children — see #turn_parent) to start NOW instead of lazily on the first
+    # served turn. Without this, a deployment whose only agents are scheduled
+    # (no live chat) never fires the tick until some unrelated turn happens to
+    # land first — observed live as 16+ minutes of silence after a clean boot.
+    # Call once, right after `supervised = true`, from the composition root
+    # (Server::Boot / config.ru / DSL::ServerBoot). A no-op outside a live
+    # reactor (nothing to bind the supervisor to yet) — the lazy path in
+    # #turn_parent still covers that case, e.g. specs that never enter Async.
+    def start_supervisor!
+      turn_parent if @supervised && Async::Task.current?
+      nil
+    end
+
     # closes the TURN intake for shutdown. Armed by Insika::Shutdown
     # when the process is asked to stop: from here on a new top-level turn is left
     # `:queued` (durable — the next boot's recovery replays it) instead of
@@ -1015,6 +1038,11 @@ module Insika
                          tokens: estimate_tools_tokens(state.allowed_tools) },
                 fingerprints: fingerprints,
                 cache: { invalidation_reason: reason } }
+      # the compaction state this turn was BUILT over (RFC-0044) —
+      # {upto, runs}, counts only; the summary fragment itself already shows
+      # as the trace's own "compaction" category via its fragment source.
+      compaction = state.session.respond_to?(:compaction) ? state.session.compaction : nil
+      entry[:compaction] = { upto: compaction["upto"], runs: compaction["runs"] } if compaction
       # Park the SANITIZED entry (string keys) — the stage-8 stamp merges into
       # it and re-records the same key; a raw entry would add a SECOND "cache"
       # key that sanitize would then ignore (the symbol one wins).
@@ -1262,6 +1290,13 @@ module Insika
         response = @hooks.around(:agent, state) do |s|
           result = @reliability ? run_reliable_ask(task, s, filter, timing)
                                 : run_single_ask(task, s, filter, timing)
+          # A steered message that no tool batch absorbed (a text-only turn: the
+          # injector only drains at a tool boundary) is still in the mailbox when
+          # RubyLLM's loop returns. ONE extra round, in the SAME turn, answers the
+          # burst coherently -- without it the release would spawn a follow-up
+          # whose answer has no delivery channel under request/response.
+          # Read AFTER it: the extra round replaces both the response and `asked`.
+          absorb_steer_overflow(task, s, timing, result)
           output = result[:output]
           asked = result[:asked]
           result[:response]
@@ -1369,10 +1404,11 @@ module Insika
     #
     # Content parts on the command -> a turn: audio parts are transcribed (the
     # text enters the message marked `source: :voice` — the consumer's signal
-    # the person SPOKE), image parts become the ask's attachments (the model
-    # sees them; the provider bills them — usage flows) and the first URL is
-    # deposited as `ctx.image_url` for data/HTTP tools. The engine transports
-    # media, never meaning: no speech/vision logic beyond the call itself.
+    # the person SPOKE), image and document parts become the ask's attachments
+    # (the model sees them; the provider bills them — usage flows) and the
+    # first URL of each kind is deposited as `ctx.image_url` / `ctx.document_url`
+    # for data/HTTP tools. The engine transports media, never meaning: no
+    # speech/vision logic beyond the call itself.
     def run_media_stage(task, state)
       # a consumer that pre-transcribed voice text labels it `source: voice`;
       # the marker rides the turn even when there are no audio PARTS left.
@@ -1383,20 +1419,33 @@ module Insika
 
       voice = Insika::Media.audio_parts(parts)
       if voice.any?
-        text = voice.map { |p| media_transcribe(p.url) }.reject(&:empty?).join(" ")
+        text = voice.map { |p| media_transcribe(p.url, state) }.reject(&:empty?).join(" ")
         state.message = [state.message.to_s, text].reject(&:empty?).join("\n")
         state.message_source = :voice
       end
 
       images = Insika::Media.image_parts(parts)
       if images.any?
-        state.media_attachments = images.map { |p| media_attachment(p.url) }
+        state.image_attachments = images.map { |p| media_attachment(p.url) }
+        state.media_attachments = state.image_attachments
         # First image URL for data tools (`{{ctx.image_url}}`) — photo analysis
         # outside the prompt. The model still sees the attachment; the tool
         # gets the original URL (its own egress applies when it fetches).
         state.turn_context = (state.turn_context || {}).merge(image_url: images.first.url)
       end
 
+      # Documents (a prescription, a recipe, an invoice) ride the SAME
+      # attachments array as images — RubyLLM's `ask(with:)` takes both, and
+      # the attachment content-sniffs PDF magic bytes when the URL has no
+      # extension — capped separately (MAX_DOCUMENT_BYTES) since a document
+      # is not a photo.
+      documents = Insika::Media.document_parts(parts)
+      if documents.any?
+        doc_attachments = documents.map { |p| media_attachment(p.url, max_bytes: Insika::Media::MAX_DOCUMENT_BYTES) }
+        state.media_attachments = Array(state.media_attachments) + doc_attachments
+        state.turn_context = (state.turn_context || {}).merge(document_url: documents.first.url)
+      end
+
       # A media-only turn (a voice note with no caption) is legitimate — the
       # surfaces admit it — but it must leave this stage with something to ask
       # about. Empty text AND no attachment means the parts carried nothing the
@@ -1410,41 +1459,30 @@ module Insika
     # The STT seam: the injected transcriber (specs), else the default
     # (fetch + RubyLLM::Transcription — lazy require). A failed transcription
     # fails the turn loudly (MediaError -> :media): a voice message that was
-    # not heard must not become a hallucinated one.
-    def media_transcribe(url)
-      transcriber = @media || (@default_transcriber ||= Insika::Media.default_transcriber(
+    # not heard must not become a hallucinated one. The default is rebuilt
+    # PER CALL (never memoized) because its vocabulary `prompt:` is resolved
+    # from THIS turn's profile — a memoized seam would freeze the first
+    # agent's prompt (or its absence) for every agent sharing the executor.
+    def media_transcribe(url, state)
+      transcriber = @media || Insika::Media.default_transcriber(
         stt_model: Insika::EnvSchema.read("INSIKA_STT_MODEL"),
-        stt_language: Insika::EnvSchema.read("INSIKA_STT_LANGUAGE")
-      ))
+        stt_language: Insika::EnvSchema.read("INSIKA_STT_LANGUAGE"),
+        stt_prompt: resolved_stt_prompt(state.profile)
+      )
       transcriber.call(url)
     end
 
-    # An image part -> the ask's attachment. RubyLLM required lazily (load-guard).
-    #
-    # The bytes come through OUR fetch (`Media.fetch_binary`), which is
-    # egress-guarded — the URL is CONSUMER input, so a private/metadata target
-    # fails the turn loudly at :media — and SIZE-CAPPED. Handing the raw URL to
-    # `RubyLLM::Attachment` instead left the fetch to the gem, whose
-    # `fetch_content` reads the whole response with no ceiling: a hostile URL
-    # answering an endless body grows this process until it dies. An io-like
-    # source (StringIO) is the branch of Attachment that takes bytes we already
-    # hold; the provider then gets base64 rather than the URL, which every
-    # vision provider accepts.
-    def media_attachment(url)
-      require "ruby_llm"
-      require "stringio"
-
-      bytes = Insika::Media.fetch_binary(url, max_bytes: Insika::Media::MAX_IMAGE_BYTES)
-      RubyLLM::Attachment.new(StringIO.new(bytes), filename: media_filename(url))
+    # Resolution order: the agent profile's own vocabulary hint
+    # (it knows its catalog) beats the deployment-wide default, which beats
+    # nothing (no prompt: kwarg at all).
+    def resolved_stt_prompt(profile)
+      Insika::Coercion.presence(profile&.stt_prompt) || Insika::EnvSchema.read("INSIKA_STT_PROMPT")
     end
 
-    # The URL's basename, for the attachment's mime sniff (".png" -> image/png;
-    # a URL with no filename falls back to the content sniff RubyLLM does).
-    def media_filename(url)
-      name = File.basename(URI.parse(url).path.to_s)
-      name.empty? ? nil : name
-    rescue URI::InvalidURIError
-      nil
+    # An image/document part -> the ask's attachment (Insika::Media.url_attachment
+    # — egress-guarded, size-capped fetch; the caller picks the ceiling).
+    def media_attachment(url, max_bytes: Insika::Media::MAX_IMAGE_BYTES)
+      Insika::Media.url_attachment(url, max_bytes: max_bytes)
     end
 
     # --- WS4 intent routing --------------------------------------------
@@ -1634,7 +1672,39 @@ module Insika
     def wire_chat_output(task, state, output)
       chat = state.chat
       chat.after_message { |message| output.message_ended(message) } if chat.respond_to?(:after_message)
-      install_steer_injector(task, state)
+      state.steer_injector = install_steer_injector(task, state)
+    end
+
+    # The extra round for a steered message that never met a tool boundary (a
+    # text-only turn closes no batch, so `SteerInjector` never got its cue). The
+    # burst is appended to the history and the model answers ALL of it in one go,
+    # inside the SAME turn — without this the release would spawn a follow-up whose
+    # answer has no delivery channel under request/response.
+    #
+    # Skipped when the turn HALTED: there is no next model step by construction.
+    # `release_steered` (execute's ensure) stays the fallback there, as it is for a
+    # failed or cancelled turn, and for a transport that cannot `complete`.
+    #
+    # At most one extra round: if the model ignores the burst, the turn ends anyway.
+    def absorb_steer_overflow(task, state, timing, result)
+      injector = state.steer_injector
+      return unless injector && state.chat.respond_to?(:complete)
+      return unless state.actor&.user_messages_posted&.positive?
+      return if halted?(result[:response])
+      return if injector.absorb_pending!.zero?
+
+      # TWO provider round trips now. Bank the first one's tokens BEFORE the response
+      # is replaced — stage 6's merge only sees whatever `result[:response]` ends up
+      # being, so without this the extra round silently erases the first round's cost
+      # from the terminal usage and from the EdgeLimiter's budget.
+      state.usage = merge_usage(with_model_source(usage_of(result[:response]), state.model_selection),
+                                state.usage)
+      # COMPLETE, not `ask(nil)`: the messages are already in the history, and an
+      # ask with no text appends an EMPTY user message after them — which is both a
+      # duplicate turn-opener and something providers refuse outright.
+      extra = state.chat.complete(&turn_chunk_handler(task, state, result[:output], timing))
+      result[:response] = extra
+      result[:asked] = extra
     end
 
     # The ask itself, chunk-by-chunk (WS3 attempts and the plain path share it).
@@ -1644,9 +1714,27 @@ module Insika
     # :ttft on EVERY content chunk (3 chunks = 3 insika.ttft frames); the spec
     # passed because FakeChat emits a single chunk.
     def ask_on(task, state, chat, output, timing)
+      each_chunk = turn_chunk_handler(task, state, output, timing)
+      # WS9: image parts ride the ask as attachments (only then — a chat whose
+      # ask has no `with:` keeps working, and the plain path is byte-identical).
+      # An image with no caption asks with NIL, not "": an empty text part is a
+      # thing some providers refuse, and nil is how RubyLLM says "attachments
+      # only".
+      if state.media_attachments
+        text = state.message.to_s.empty? ? nil : state.message
+        chat.ask(text, with: state.media_attachments, &each_chunk)
+      else
+        chat.ask(state.message, &each_chunk)
+      end
+    end
+
+    # The per-round chunk sink. Built FRESH per round: `ttft_sent` is that round's
+    # own bookkeeping, and the steer overflow round is a second round on the same
+    # chat.
+    def turn_chunk_handler(task, state, output, timing)
       public_thinking = state.profile.stream_public?(:thinking)
       ttft_sent = false
-      each_chunk = lambda do |chunk|
+      lambda do |chunk|
         emit_thinking(chunk, task, public: public_thinking)
         next unless chunk.content
 
@@ -1657,17 +1745,6 @@ module Insika
         end
         output.push(chunk.content)
       end
-      # WS9: image parts ride the ask as attachments (only then — a chat whose
-      # ask has no `with:` keeps working, and the plain path is byte-identical).
-      # An image with no caption asks with NIL, not "": an empty text part is a
-      # thing some providers refuse, and nil is how RubyLLM says "attachments
-      # only".
-      if state.media_attachments
-        text = state.message.to_s.empty? ? nil : state.message
-        chat.ask(text, with: state.media_attachments, &each_chunk)
-      else
-        chat.ask(state.message, &each_chunk)
-      end
     end
 
     # The provider's TTFB as a live event (data: ttft_ms) — only under
@@ -1950,10 +2027,17 @@ module Insika
         # the memory scope carries a customer — the backend identifies the store,
         # not the shopper (WS8 keeps the two scopes separate).
         tenant: command_tenant(task) || task.session_id,
+        # the DECLARED tenant alone (nil in single-tenant). Distinct from
+        # `tenant` for the ownership-binding tools (save_artifact): a report
+        # belongs to the AGENT's tenant — the deployment's tenant in
+        # single-tenant, never the chat that happened to run it.
+        command_tenant: command_tenant(task),
         store_id: profile.store_id,
-        # current delegation depth (0 for a top-level turn). Carried in
-        # the child command's payload by run_subagent; read here so the child's OWN
-        # spawn_subagent tool sees depth+1 and the runtime cap holds down the chain.
+        # the current task id — the save_artifact binding (which run produced
+        # this report), same turn-origin discipline as the rest of ctx.*.
+        task_id: task.id,
+        # current delegation depth (0 for a top-level turn). Set by run_subagent
+        # for children.
         delegation_depth: delegation_depth(task)
       }
     end
@@ -2391,6 +2475,18 @@ module Insika
       # has to travel out of band. Same terminal hook, next door to the delegation
       # one, for the same reason: it fires for a fresh turn and a recovered one.
       finalize_channel_delivery(task, content, state, timing)
+
+      # extracts durable concepts from this turn, off the critical
+      # path — the user already has the answer above. Same terminal hook,
+      # next door to the other two, for the same reason: it fires for a fresh
+      # turn and a recovered one.
+      finalize_knowledge_extraction(task, profile, new_messages)
+
+      # in-session compaction (RFC-0044): when the uncompacted
+      # transcript crossed the threshold this turn, summarize the old prefix
+      # with the cheap model and move the boundary — off the critical path,
+      # same terminal hook, same best-effort discipline as the other three.
+      finalize_compaction(task, profile)
     end
 
     # Records the answer in the outbox and dispatches it. The discriminator is the
@@ -2433,6 +2529,148 @@ module Insika
       nil
     end
 
+    # Turns whose combined transcript slice is this trivially short skip
+    # extraction entirely ("ok thanks" exchanges) — no new config surface,
+    # just avoids a wasted utility-model call.
+    KNOWLEDGE_MIN_CHARS = 200
+
+    # No-op without a knowledge store, without the profile's opt-in
+    # (`knowledge.extract`), without a usable model, or for a trivially short
+    # turn. Otherwise dispatches the extraction off the critical path — the
+    # SAME `dispatch_chain` shape: inline when non-supervised (tests, CLI,
+    # boot sweep), a child of the turn supervisor when serving (survives the
+    # request's own disconnect). Best-effort: any failure is swallowed here,
+    # never re-fails an already-committed turn.
+    def finalize_knowledge_extraction(task, profile, new_messages)
+      return unless @knowledge_store
+
+      config = Coercion.deep_stringify(profile.knowledge)
+      return unless config && Coercion.truthy?(config["extract"])
+      return if knowledge_transcript(new_messages).length < KNOWLEDGE_MIN_CHARS
+
+      extractor = Knowledge::ExtractorFactory.build(config, utility_model: utility_model)
+      return unless extractor
+
+      # Same resolved model as the extractor — a deployment names one
+      # knowledge model, not two. nil consolidator (no model resolvable) is
+      # still meaningful: write_concept's conservative default.
+      consolidator = Knowledge::ConsolidatorFactory.build(config, utility_model: utility_model)
+
+      run = lambda { run_knowledge_extraction(task, profile, config, new_messages, extractor, consolidator) }
+      return run.call unless @supervised
+
+      turn_parent.async do |t|
+        t.annotate("knowledge:#{task.id}")
+        run.call
+      end
+    end
+
+    def run_knowledge_extraction(task, profile, config, new_messages, extractor, consolidator)
+      prompt = knowledge_prompt(config, new_messages)
+      result = extractor.extract(prompt: prompt)
+      result[:concepts].each do |concept|
+        outcome = Knowledge.write_concept(
+          store: @knowledge_store, agent_id: profile.id, concept: concept, session_id: task.session_id,
+          tenant: task_tenant(task), consolidator: consolidator
+        )
+        emit_knowledge_event(outcome, profile, task)
+      end
+    rescue StandardError
+      nil # best-effort: extraction never re-fails an already-committed turn.
+    end
+
+    # :new/:related taught the agent something; :contradicting needs a
+    # human; :same is a silent reinforcement (no event — a popular concept
+    # would otherwise spam the stream every time it's confirmed).
+    def emit_knowledge_event(outcome, profile, task)
+      case outcome[:verdict]
+      when :new, :related
+        emit(:knowledge_learned, { name: outcome[:name], type: outcome[:type], agent: profile.id }, task: task)
+      when :contradicting
+        emit(:knowledge_conflict, { name: outcome[:name], agent: profile.id }, task: task)
+      end
+    end
+
+    def knowledge_prompt(config, new_messages)
+      base = Coercion.presence(config["prompt"]) || Knowledge::DEFAULT_PROMPT
+      <<~PROMPT
+        #{base.rstrip}
+
+        ## The conversation
+
+        #{knowledge_transcript(new_messages)}
+      PROMPT
+    end
+
+    # Redacted (RFC's PII rule applies to what reaches the model too, not
+    # just what gets persisted).
+    def knowledge_transcript(new_messages)
+      redacted, = Insika::Safety::Detectors.redact(
+        new_messages.each_with_index.map { |m, i| "[#{i}] #{m['role'] || m[:role]}: #{m['content'] || m[:content]}" }
+                    .join("\n")
+      )
+      redacted
+    end
+
+    def utility_model
+      return nil unless @settings_store
+
+      @settings_store.get["utility_model"]
+    end
+
+    # in-session compaction (RFC-0044). Platform-gated
+    # (Settings compaction.enabled — parity when off), planned over the
+    # POST-append transcript (persist_turn already wrote this turn's messages),
+    # dispatched off the critical path — the SAME shape as
+    # finalize_knowledge_extraction: inline when non-supervised, a child of the
+    # turn supervisor when serving. Best-effort: any failure leaves the session
+    # record untouched and the next turn re-plans.
+    def finalize_compaction(task, profile)
+      return unless task.session_id && @settings_store
+
+      config = Coercion.deep_stringify(@settings_store.get["compaction"])
+      return unless config && Coercion.truthy?(config["enabled"])
+
+      session = @session_store.find(task.session_id)
+      return unless session
+
+      state = session.respond_to?(:compaction) ? session.compaction : nil
+      plan = Insika::Compaction.plan(messages: session.messages, state: state, config: config)
+      return unless plan
+
+      # compaction.model -> platform utility_model -> inert (never a guess);
+      # `insika doctor` warns on enabled-with-no-model. @llm rides along so a
+      # deployment (or spec) that injects its LLM seam covers this call too.
+      summarizer = Compaction::SummarizerFactory.build(config, utility_model: utility_model, llm: @llm)
+      return unless summarizer
+
+      run = lambda { run_compaction(task, profile, session, state, plan, config, summarizer) }
+      return run.call unless @supervised
+
+      turn_parent.async do |t|
+        t.annotate("compaction:#{task.id}")
+        run.call
+      end
+    end
+
+    def run_compaction(task, profile, session, state, plan, config, summarizer)
+      prompt = Insika::Compaction.prompt(messages: session.messages, plan: plan,
+                                         previous: state && state["summary"],
+                                         base: config["prompt"])
+      result = summarizer.summarize(prompt: prompt)
+      updated = @session_store.set_compaction(task.session_id, summary: result[:summary],
+                                              upto: plan.upto, model: summarizer.model)
+      # counts and ids only — the summary text never enters the stream. Feeds
+      # the insika.context.compacted counter (Telemetry::Recorder).
+      emit(:context_compacted,
+           { task_id: task.id, agent: profile.id, from: plan.from, upto: plan.upto,
+             messages: plan.count, runs: updated.compaction && updated.compaction["runs"],
+             model: summarizer.model, cost: result[:cost] },
+           task: task)
+    rescue StandardError
+      nil # best-effort: compaction never re-fails an already-committed turn.
+    end
+
     # ONE supervisor fiber for the whole chain. Sequential deliver
     # calls, so balloon N+1 cannot overtake balloon N on the wire. Still off the
     # session's FIFO — the customer's next message does not wait on this turn's
@@ -2546,11 +2784,13 @@ module Insika
 
     # Stage 6 (factory): the ONLY point that touches the gem. lazy require,
     # confined — not covered by unit (factory line). It also loads the system
-    # builtins (load_skill/tool_search/remember) that the ChatBuilder assembles at
-    # stage 5 — lazy, so the core installs without ruby_llm.
+    # builtins (load_skill/load_knowledge/tool_search/remember) that the
+    # ChatBuilder assembles at stage 5 — lazy, so the core installs without
+    # ruby_llm.
     def create_chat(profile, state)
       require "ruby_llm"
       require_relative "tools/load_skill"
+      require_relative "tools/load_knowledge"
       require_relative "tools/tool_search"
       require_relative "tools/remember"
       require_relative "tools/subagent"

data/lib/insika/followup_policy.rb

@@ -70,7 +70,7 @@ module Insika
     def quiet?(time)
       return false unless @quiet_hours
 
-      local = in_zone(@quiet_hours.timezone, time) { |t| t.getlocal }
+      local = Insika::Timezone.in_zone(@quiet_hours.timezone, time) { |t| t.getlocal }
       minutes = local.hour * 60 + local.min
       start_min = minutes_of(@quiet_hours.start)
       end_min = minutes_of(@quiet_hours.end)
@@ -136,7 +136,7 @@ module Insika
       # a bogus IANA zone is a malformed policy — refused HERE, where the
       # doctor can name it. An unknown ENV["TZ"] silently behaves as UTC, so
       # existence is checked against the OS tz database, not by asking Time.
-      unless zone_known?(timezone.to_s)
+      unless Insika::Timezone.known?(timezone.to_s)
         raise Insika::ValidationError,
               "followup.policy.quiet_hours.timezone is not a valid IANA timezone: #{timezone.inspect}"
       end
@@ -190,29 +190,6 @@ module Insika
       text.to_s.unicode_normalize(:nfd).gsub(/\p{Mn}/, "").downcase
     end
 
-    # Yields `time` interpreted in the given IANA zone (via a save/restore of
-    # ENV["TZ"] — the stdlib-only route to the OS tz database; see #quiet?).
-    def in_zone(zone, time)
-      previous = ENV["TZ"]
-      ENV["TZ"] = zone
-      yield time
-    ensure
-      ENV["TZ"] = previous
-    end
-
-    # The candidate tz-data roots (TZDIR first — Ruby's own lookup env). The
-    # zone name maps to a FILE under the root ("America/Sao_Paulo" ->
-    # "America/Sao_Paulo").
-    TZ_ROOTS = ([ENV["TZDIR"]] +
-                %w[/usr/share/zoneinfo /usr/share/lib/zoneinfo /etc/zoneinfo])
-               .compact.freeze
-
-    def zone_known?(zone)
-      return true if zone == "UTC" || zone == "Etc/UTC"
-
-      TZ_ROOTS.any? { |root| File.directory?(root) && File.exist?(File.join(root, zone)) }
-    end
-
     def minutes_of(hhmm)
       h, m = hhmm.split(":").map(&:to_i)
       h * 60 + m

data/lib/insika/golden_store.rb

@@ -63,6 +63,11 @@ module Insika
     # -> [Evals::Golden] one agent's cases.
     def for_agent(agent_id) = all.select { |g| g.agent == agent_id.to_s }
 
+    # -> [Evals::Golden] one tenant's cases (C3.1's isolation query —
+    # `run_persona_eval` never lists or runs a case outside the calling agent's
+    # own tenant, "platform" being the single-tenant default).
+    def for_tenant(tenant) = all.select { |g| g.tenant == tenant.to_s }
+
     # -> [String] ids whose stored mapping no longer validates (an edit that broke the
     # shape). The Studio shows these; they never silently vanish from a run.
     def invalid
@@ -130,13 +135,23 @@ module Insika
     # in the store as it is on disk — but it is NEVER dropped when present: a case
     # that silently lost its requirements would come back as a failure on every
     # deployment that lacks the tool, which is the exact lie `requires` exists to end.
+    # Same for `persona`: a simulated case that lost its persona would
+    # silently stop being simulated and replay as an empty script.
     def case_hash(golden)
-      h = { "id" => golden.id, "agent" => golden.agent, "turns" => golden.turns }
+      h = if golden.simulated?
+            { "id" => golden.id, "agent" => golden.agent, "persona" => golden.persona.to_h }
+          else
+            { "id" => golden.id, "agent" => golden.agent, "turns" => golden.turns }
+          end
       h["requires"] = golden.requires unless golden.requires.empty?
       # Same rule for `reference`: omitted when absent, never dropped
       # when present. A case that lost its reference in a round-trip would stop being
       # compared against the incumbent and the report would look identical.
       h["reference"] = golden.reference unless golden.reference.empty?
+      # `tenant` follows the same omit-when-default rule: "platform" is the
+      # loader's own default, so leaving it out reproduces the same case; an
+      # explicit tenant is a case's isolation boundary and must never round-trip away.
+      h["tenant"] = golden.tenant unless golden.tenant == "platform"
       h.merge("expect" => golden.expect)
     end
 

data/lib/insika/grounding/matcher.rb

@@ -7,7 +7,7 @@ module Insika
   # The pack's DATA (D7): a `sku` regex for the SKU shape. The engine only
   # APPLIES it — it never guesses what a SKU looks like. No NLP, no LLM, no gem.
   #
-  # REVIEW-DECISION (rfc-0029 v2): grounding is **SKU-only**. The techspec's
+  # REVIEW-DECISION: grounding is **SKU-only**. The techspec's
   # name half (name_keys indexing ledger lines to flag names) cannot flag
   # anything: a name found in the text that also came from the ledger is grounded
   # by construction, and detecting a name that matches NO ledger line needs a