insika 0.1.0 → 0.3.0

data/lib/insika/loop_detector.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module Insika
+  # loop detection by (tool, args) hash, with a ONE-SHOT intervention.
+  #
+  # `max_tool_calls` bounds how MANY tool calls a turn makes, not how useful they
+  # are: a model retrying the exact same call — same tool, identical arguments —
+  # after an empty or error result burns the whole budget doing something that
+  # was settled on the first repeat. This detector is the engine saying so, once.
+  #
+  # The streak is CONSECUTIVE and turn-scoped, like the max_tool_calls counter it
+  # sits next to in ChatBuilder#wire_callbacks: a call revisited much later in a
+  # long turn is not the pathology being caught, and semantic ("nearly the same")
+  # matching is how a guard-rail starts eating legitimate retries.
+  #
+  # Two invariants, both borrowed from SteerInjector, because the
+  # intervention is a `user` message appended mid-loop:
+  #
+  # · **Batch boundary only.** The append happens after the LAST tool result of a
+  #   batch closes — a `user` message between two tool results is rejected by
+  #   Anthropic outright. Same arithmetic: an assistant message opens a batch of
+  #   N, the Nth `role: tool` message closes it.
+  # · **A halted batch receives nothing.** With `halt_when` there is no next
+  #   model step; a warning appended there would sit unanswered forever.
+  #
+  # The repeated call itself STILL RUNS — fabricating a synthetic result would
+  # teach the model that tools lie (the failure refuses). The
+  # warning rides after the truth; only a repeat that arrives AFTER the warning
+  # was spent aborts, through the existing TimeoutError(stage: :tool_limit) path.
+  class LoopDetector
+    # The one intervention text, verbatim — a fixed engine sentence, so a report
+    # can identify it without an origin stamp (chat messages carry none).
+    def self.intervention(name, streak)
+      "You have called `#{name}` with identical arguments #{streak} times in a row and " \
+      "received the same result every time. Repeating it will not produce new information. " \
+      "Do not call it again with the same arguments — answer with what you already have, " \
+      "or change your approach."
+    end
+
+    # chat:  the turn's chat — must answer #add_message (the boundary append).
+    # limit: the streak that triggers the intervention (profile's
+    #        max_tool_repeat). Values < 2 mean OFF: a "streak of 1" is every
+    #        call, which is meaningless.
+    # emit:  ->(type, data) — the Executor's emitter, bound to the task.
+    def initialize(chat:, limit:, emit:)
+      @chat = chat
+      @limit = limit
+      @emit = emit
+      @last = nil          # fingerprint of the previous call (nil = none yet)
+      @streak = 0
+      @intervened = false  # the ONE warning of this turn has been delivered
+      @pending = false     # detection fired; waiting for the batch boundary
+      @expected = nil      # tool calls announced by the batch in flight
+      @seen = 0
+      @halted = false
+    end
+
+    # From ChatBuilder's before_tool_call. Raises BEFORE the call executes once
+    # the warning is spent — bounded spend is the point of aborting here.
+    def tool_call(name, arguments)
+      fingerprint = [name.to_s, canonical(arguments)]
+      if fingerprint == @last
+        @streak += 1
+      else
+        # A different call broke the run: the loop resolved itself, so a warning
+        # armed earlier is moot — it must not fire later naming the WRONG call.
+        @streak = 1
+        @pending = false
+      end
+      @last = fingerprint
+      return if @streak < @limit
+
+      if @intervened
+        raise Insika::TimeoutError.new(
+          "tool loop detected (#{name} repeated with identical arguments after a warning)",
+          stage: :tool_limit)
+      end
+      @pending = true
+    end
+
+    # From ChatBuilder's after_tool_result, with the RAW result — the only place
+    # a Tool::Halt is still recognizable (SteerInjector's comment applies here).
+    def tool_result(result)
+      @halted = true if defined?(RubyLLM::Tool::Halt) && result.is_a?(RubyLLM::Tool::Halt)
+    end
+
+    # RubyLLM after_message. An assistant message carrying tool calls OPENS a
+    # batch; the Nth tool result CLOSES it — the one boundary where appending
+    # is valid.
+    def message_ended(message)
+      role = field(message, :role).to_s
+      return open_batch(message) if role == "assistant"
+      return unless role == "tool" && @expected
+
+      @seen += 1
+      intervene! if @seen >= @expected
+    end
+
+    private
+
+    def open_batch(message)
+      calls = field(message, :tool_calls)
+      size = calls.respond_to?(:size) ? calls.size : 0
+      # No tool call = the model talking; the turn is ending and a pending
+      # warning is moot — the loop resolved itself.
+      return @expected = nil if size.zero?
+
+      @expected = size
+      @seen = 0
+      @halted = false
+    end
+
+    def intervene!
+      @expected = nil
+      return unless @pending
+      @pending = false
+      return if @halted # nothing will read it (halt_when): drop, never deliver
+
+      @intervened = true
+      name, = @last
+      @chat.add_message(role: :user, content: self.class.intervention(name, @streak))
+      # Counts and the tool name, never the arguments — order numbers are PII.
+      @emit.call(:tool_loop_intervened, { name: name, streak: @streak })
+    end
+
+    # (name, args) hash: symbols vs strings and key order must not split an
+    # identical call into two fingerprints. Compared with ==, never hashed.
+    def canonical(value)
+      case value
+      when Hash then value.map { |k, v| [k.to_s, canonical(v)] }.sort_by(&:first)
+      when Array then value.map { |v| canonical(v) }
+      else value
+      end
+    end
+
+    def field(message, name)
+      return message.public_send(name) if message.respond_to?(name)
+      return message[name] || message[name.to_s] if message.respond_to?(:[])
+
+      nil
+    end
+  end
+end

data/lib/insika/mcp_http_client.rb

@@ -3,19 +3,19 @@
 require "json"
 
 module Insika
-  # MINIMAL MCP client over HTTP JSON-RPC (Phase 7, Stage E). Discovers the tools
+  # MINIMAL MCP client over HTTP JSON-RPC. Discovers the tools
   # of an MCP instance with HTTP transport by making a JSON-RPC 2.0 `tools/list`
   # POST to the instance endpoint, behind the EgressGuard (SSRF — the url comes
-  # from editable config, NF4). It is the DEFAULT client injected into the
+  # from editable config). It is the DEFAULT client injected into the
   # McpToolIngestor; tests pass a Fake (duck-typed) in its place.
   #
   # Contract (MCP client duck-type): `#list_tools -> [{name, description,
   # inputSchema}]` — the same MCP envelope that the ToolManifest adapter normalizes.
   #
-  # SCOPE (bounded, D8): only the minimal handshake of ONE stateless `tools/list`
+  # SCOPE (bounded): only the minimal handshake of ONE stateless `tools/list`
   # POST. Does NOT implement the full MCP session lifecycle (initialize/protocol
   # negotiation/session-id/notifications) nor the stdio transport — that is the
-  # "real MCP transport", later work (out-of-scope, see spec §4 D8). It serves
+  # "real MCP transport", later work (out-of-scope, see spec). It serves
   # simple HTTP MCP servers (direct JSON-RPC) and proves the ingestion seam.
   class McpHttpClient
     JSONRPC_VERSION = "2.0"

data/lib/insika/mcp_tool_ingestor.rb

@@ -3,16 +3,16 @@
 require "json"
 
 module Insika
-  # LIVE MCP ingestion (Phase 7, Stage E / spec §4 D8): discovers the tools of an
+  # LIVE MCP ingestion (/ spec): discovers the tools of an
   # MCP instance at RUNTIME (no hand-written manifest) and ingests them as
   # data-tools. Given an McpStore instance + an INJECTABLE MCP client
   # (duck-typed: `#list_tools -> [{name, description, inputSchema}]`), it builds a
-  # ToolManifest and REUSES the Stage B ingestion path (the :import_tools Command:
+  # ToolManifest and REUSES the ingestion path (the:import_tools Command:
   # batch upsert into the ToolStore + hot reload + per-tool report + partial-
   # failure isolation R4). The ToolManifest MCP adapter (`inputSchema`) is reused
   # — no schema parsing here.
   #
-  # GENERIC (NF1): nothing here mentions achei/openclaw. The MCP instance is DATA in the store.
+  # GENERIC: nothing here mentions a consumer/gateway. The MCP instance is DATA in the store.
   #
   # BINDING STRATEGY (this stage's choice, bounded):
   #   Each discovered tool becomes an HTTP data-tool that makes a JSON-RPC 2.0
@@ -23,10 +23,10 @@ module Insika
   #   runs through the SAME HTTP path as the other data-tools (egress guard, secret
   #   headers, hot reload) — no new execution code.
   #
-  #   Each tool gets `group: "mcp:<instance>"` so the Stage C per-group gating
+  #   Each tool gets `group: "mcp:<instance>"` so the per-group gating
   #   (tools_allow_groups) works for free.
   #
-  # DEFERRED / OUT-OF-SCOPE (documented — spec §4 D8):
+  # DEFERRED / OUT-OF-SCOPE (documented — spec):
   #   - Real MCP transport: only instances with a `url` (http transport) are ingestible;
   #     stdio has no HTTP endpoint -> raises a clear error (later work).
   #   - MCP session lifecycle (initialize/negotiation/session-id/notifications) and the
@@ -65,7 +65,7 @@ module Insika
       if url.nil?
         raise Insika::ValidationError,
               "MCP instance '#{name}' has no url: live ingestion requires HTTP transport " \
-              "(stdio is later work — D8)"
+              "(stdio is later work)"
       end
 
       tools = Array((client || @client_factory.call(record)).list_tools)

data/lib/insika/media.rb

@@ -0,0 +1,298 @@
+# frozen_string_literal: true
+
+module Insika
+  # WS9: the engine transports MEDIA, never meaning. Content parts ride the
+  # message contract — `{ "type": "text", "text": … }`, `{ "type": "image",
+  # "url": … }`, `{ "type": "audio", "url": … }` — and the Executor turns them
+  # into a turn: audio is transcribed (text marked `source: :voice`), images
+  # attach to the model ask and the first URL is `{{ctx.image_url}}` for
+  # data/HTTP tools. This class owns the PURE parts (normalization) and
+  # the STT SEAM (injectable — specs stub it; the default fetches the audio and
+  # transcribes via RubyLLM behind a lazy require, so the core stays gem-free
+  # at load). `Media::Output` is the generated-media half (WS9, saída): the
+  # turn can PRODUCE an image or an audio clip when the agent opted in
+  # (`AgentProfile#outputs`) AND the channel declared it can receive it
+  # (`channel.capabilities`) — nothing leaks by default.
+  module Media
+    # A single content part, normalized.
+    Part = Data.define(:type, :text, :url) do
+      def audio? = type == "audio"
+      def image? = type == "image"
+      def text? = type == "text"
+    end
+
+    # -> [Part]: normalize the raw parts (string|symbol keys), skipping anything
+    # that is not a well-formed text/image/audio part. Lenient on purpose — the
+    # SURFACE validates the contract with `well_formed?` (a malformed part is a
+    # 422 before dispatch); here a stray entry must not break the turn.
+    def self.parts(raw)
+      Array(raw).filter_map do |p|
+        next unless p.is_a?(Hash)
+
+        type = (p[:type] || p["type"]).to_s
+        url = (p[:url] || p["url"]).to_s
+        text = (p[:text] || p["text"]).to_s
+        case type
+        when "text" then text.empty? ? nil : Part.new("text", text, nil)
+        when "image", "audio" then url.empty? ? nil : Part.new(type, nil, url)
+        else nil
+        end
+      end
+    end
+
+    # The SURFACE's contract check (server edge): true when EVERY entry is a
+    # well-formed content part — a Hash whose type is text (with text), image
+    # or audio (with url). The edge raises a 422 on the first offender; the
+    # engine itself stays lenient (`parts` skips strays so a non-HTTP transport
+    # that bypassed the edge cannot break a turn).
+    def self.well_formed?(raw)
+      Array(raw).all? do |p|
+        next false unless p.is_a?(Hash)
+
+        case (p[:type] || p["type"]).to_s
+        when "text" then !(p[:text] || p["text"]).to_s.empty?
+        when "image", "audio" then !(p[:url] || p["url"]).to_s.empty?
+        # a part WITHOUT a type is admitted only as a bare text part (the
+        # shape the input joiner already tolerates) — anything else is refused.
+        when "" then !(p[:text] || p["text"]).to_s.empty?
+        else false
+        end
+      end
+    end
+
+    # The OUTPUT media kinds a channel may declare it can receive
+    # (`channel.capabilities`). The closed list is the "abstraction admits
+    # only what leaks" rule: an unknown value is refused at the edge, never
+    # silently ignored.
+    OUTPUT_CAPABILITIES = %w[image_output audio_output].freeze
+
+    # -> [String]: the capabilities a raw `channel` hash declares. Lenient on
+    # the key spelling (symbol|string) at both boundaries (request parse vs
+    # persisted command payload); [] = the channel declared nothing.
+    def self.channel_capabilities(raw)
+      channel = raw.is_a?(Hash) ? raw : {}
+      Array(channel[:capabilities] || channel["capabilities"]).map(&:to_s)
+    end
+
+    # The ceilings on INBOUND media (a URL a consumer sent us). Both fetches
+    # stream into the cap and refuse past it: the bytes land in THIS process,
+    # so an uncapped one is a hostile URL away from growing it until it dies.
+    MAX_AUDIO_BYTES = 1_000_000 # a voice note, not a warehouse
+    MAX_IMAGE_BYTES = 5_000_000 # a photo, not a poster
+
+    def self.audio_parts(parts) = parts.select(&:audio?)
+    def self.image_parts(parts) = parts.select(&:image?)
+
+    # The STT seam: ->(url) { text } (default: fetch + RubyLLM transcription).
+    # Injected so a spec never touches the network; the default is built lazily
+    # when the turn first carries audio.
+    def self.default_transcriber(stt_model:, stt_language: nil)
+      lambda do |url|
+        fetch_and_transcribe(url, model: stt_model, language: stt_language)
+      end
+    end
+
+    def self.fetch_and_transcribe(url, model:, language:)
+      require "net/http"
+      require "uri"
+      require "ruby_llm" # lazy — the core loads without it (load-guard)
+
+      bytes = fetch_binary(url)
+      audio = RubyLLM::Attachment.new(bytes)
+      options = { model: model, assume_model_exists: true }
+      options[:language] = language if language
+      RubyLLM::Transcription.transcribe(audio, **options).text
+    end
+
+    # Egress-guarded binary fetch of a media URL. Blocked like the webhook: the
+    # url is consumer config/input, so a private/loopback/metadata target is
+    # refused (SSRF) unless the deployment opts out. Size-capped (the caller
+    # picks the ceiling; the default is the audio one).
+    def self.fetch_binary(url, max_bytes: MAX_AUDIO_BYTES)
+      violation = Insika::EgressGuard.violation(url, **egress_opt_out)
+      raise Insika::MediaError, "media egress blocked for #{url}: #{violation}" if violation
+
+      uri = URI.parse(url)
+      opts = { use_ssl: uri.scheme == "https", open_timeout: 30, read_timeout: 60 }
+      Net::HTTP.start(uri.host, uri.port, opts) do |http|
+        buf = +"".b
+        http.request(Net::HTTP::Get.new(uri)) do |resp|
+          raise Insika::MediaError, "media fetch HTTP #{resp.code}" unless resp.is_a?(Net::HTTPSuccess)
+
+          resp.read_body { |chunk| buf << chunk; break if buf.bytesize > max_bytes }
+        end
+        raise Insika::MediaError, "media exceeds #{max_bytes} bytes" if buf.bytesize > max_bytes
+        buf
+      end
+    rescue URI::InvalidURIError
+      raise Insika::MediaError, "invalid media URL"
+    end
+
+    # The opt-out the comment above promises, read from the SAME env the
+    # data-tool guard reads (INSIKA_EGRESS_ALLOW_HTTP / _ALLOW_PRIVATE): without
+    # this, a local run serving media over http:// ALWAYS failed, however the
+    # deployment was configured. INSIKA_EGRESS_HOSTS is deliberately NOT applied:
+    # that allowlist pins the handful of hosts a tool may call, while media URLs
+    # come from the channel's CDN — honouring it here would break every real
+    # deployment that narrows its tools.
+    def self.egress_opt_out
+      { allow_http: Insika::EnvSchema.truthy?(ENV["INSIKA_EGRESS_ALLOW_HTTP"]),
+        allow_private: Insika::EnvSchema.truthy?(ENV["INSIKA_EGRESS_ALLOW_PRIVATE"]) }
+    end
+
+    # WS9 (saída): generated media. The OUTPUT shape is an additive part —
+    # `{ "type": "image"|"audio", "mime_type": …, "base64": …, "model": … }`
+    # — that rides the turn's `output_parts` (terminal event + /v1/responses
+    # envelope), NEVER the answer text: the customer's channel consumes the
+    # bytes, the model's prose stays the answer.
+    #
+    # The GENERATION SEAMS are injectable like the STT seam: each is a
+    # `->(content, config) { [ part_hash, usage_hash ] }` (part_hash already
+    # carries its "type"), specs stub them, and the defaults hit the provider
+    # behind lazy requires:
+    #  · image — RubyLLM.paint (the gem has vision AND painting), billed
+    #    tokens merged into the turn's usage like any ask;
+    #  · tts — RubyLLM still has NO speech API (as of 1.16.0), so the default
+    #    is a thin POST to the OpenAI-compatible `<base>/audio/speech`
+    #    endpoint (base + key from the provider config the chat uses — a
+    #    deployment pointing OpenAI at a gateway keeps TTS pointing there).
+    #    OpenAI's speech API reports no token usage; the part carries the
+    #    model so the consumer can price it, and the turn counts the call.
+    module Output
+      DEFAULT_IMAGE_SIZE = "1024x1024"
+      DEFAULT_TTS_MODEL = "tts-1"
+      DEFAULT_TTS_VOICE = "alloy"
+      DEFAULT_TTS_FORMAT = "mp3"
+      # Base64 inlines into the envelope — a cap so a pathological generation
+      # cannot blow up the SSE frame. A generated 1024x1024 PNG sits well under.
+      MAX_EMBEDDED_BYTES = 8 * 1024 * 1024
+
+      class << self
+        # -> { image: seam, tts: seam } with the DEFAULTS bound to a context
+        # (the graph's RubyLLM::Context when it owns credentials — nil = the
+        # process-wide RubyLLM constant). Built lazily on first generation so
+        # the core loads without ruby_llm (load-guard).
+        def defaults(context:)
+          {
+            image: ->(prompt, config) { generate_image(prompt, config: config, context: context) },
+            tts: ->(text, config) { synthesize_speech(text, config: config, context: context) }
+          }
+        end
+
+        # -> [Part, usage]: paint via RubyLLM. usage is the provider's token
+        # counts ({ input_tokens:, output_tokens: } — merged into the turn's
+        # usage by the Executor); a provider without counts reports nothing.
+        def generate_image(prompt, config:, context:)
+          require "ruby_llm" # lazy — the core loads without it (load-guard)
+
+          cfg = Insika::Coercion.deep_stringify(config || {})
+          model = Insika::Coercion.presence(cfg["model"]) || image_model(context)
+          api = context || RubyLLM
+          image = api.paint(prompt.to_s, model: model, assume_model_exists: true,
+                                          size: presence(cfg["size"]) || DEFAULT_IMAGE_SIZE)
+          data = image.respond_to?(:data) ? image.data : nil
+          raise Insika::MediaError, "image generation returned no embeddable data" if data.to_s.empty?
+
+          enforce_embedded_size!(data, "generated image")
+          mime = image.respond_to?(:mime_type) ? image.mime_type : nil
+          model_id = image.respond_to?(:model_id) ? image.model_id : nil
+          usage = image.respond_to?(:usage) ? token_usage(image.usage) : {}
+          part = { "type" => "image", "mime_type" => presence(mime) || "image/png",
+                   "base64" => data, "model" => presence(model_id) }
+          [part.compact, usage]
+        end
+
+        # -> [Part, {}]: synthesize speech via the OpenAI-compatible
+        # `<base>/audio/speech` endpoint. `context` supplies the base URL + key
+        # (the same config the chat uses — see `speech_endpoint`). The bytes
+        # embed base64 in the part; the usage is empty (no token counts on the
+        # speech API) and the part carries the model for consumer-side pricing.
+        def synthesize_speech(text, config:, context:)
+          require "net/http"
+          require "uri"
+          require "json"
+          require "base64"
+
+          cfg = Insika::Coercion.deep_stringify(config || {})
+          model = presence(cfg["model"]) || DEFAULT_TTS_MODEL
+          voice = presence(cfg["voice"]) || DEFAULT_TTS_VOICE
+          format = presence(cfg["format"]) || DEFAULT_TTS_FORMAT
+          base, key = speech_endpoint(context)
+          if key.to_s.empty?
+            raise Insika::MediaError,
+                  "TTS needs an OpenAI API key (provider config) — set it on the " \
+                  "provider the agent uses, or inject a tts seam"
+          end
+
+          uri = URI.parse("#{base}/audio/speech")
+          req = Net::HTTP::Post.new(uri)
+          req["Authorization"] = "Bearer #{key}"
+          req["Content-Type"] = "application/json"
+          req.body = JSON.generate(model: model, voice: voice, input: text.to_s,
+                                   response_format: format)
+          opts = { use_ssl: uri.scheme == "https", open_timeout: 30, read_timeout: 60 }
+          bytes = Net::HTTP.start(uri.host, uri.port, opts) do |http|
+            resp = http.request(req)
+            raise Insika::MediaError, "TTS HTTP #{resp.code}" unless resp.is_a?(Net::HTTPSuccess)
+
+            # stream into the cap — a rogue/broken endpoint must not grow the
+            # process past MAX_EMBEDDED_BYTES before the refusal.
+            buf = +"".b
+            resp.read_body do |chunk|
+              buf << chunk
+              break if buf.bytesize > MAX_EMBEDDED_BYTES
+            end
+            buf
+          end
+          enforce_embedded_size!(bytes, "synthesized speech")
+          part = { "type" => "audio", "mime_type" => mime_for(format), "base64" => Base64.strict_encode64(bytes), "model" => model }
+          [part.compact, {}]
+        rescue URI::InvalidURIError
+          raise Insika::MediaError, "invalid TTS endpoint"
+        end
+
+        private
+
+        # The OpenAI-compatible base URL + key behind the chat's provider
+        # config. A RubyLLM::Context owns the deployment's credentials; the
+        # global config is the fallback (a graph without its own context).
+        def speech_endpoint(context)
+          config = context.respond_to?(:config) ? context.config : RubyLLM.config
+          base = config.respond_to?(:openai_api_base) ? config.openai_api_base : nil
+          key = config.respond_to?(:openai_api_key) ? config.openai_api_key : nil
+          [presence(base) || "https://api.openai.com/v1", key]
+        end
+
+        def image_model(context)
+          config = context.respond_to?(:config) ? context.config : RubyLLM.config
+          config.respond_to?(:default_image_model) ? config.default_image_model : nil
+        end
+
+        def token_usage(raw)
+          usage = raw.is_a?(Hash) ? raw : {}
+          {
+            input_tokens: usage[:input_tokens] || usage["input_tokens"] || usage["prompt_tokens"],
+            output_tokens: usage[:output_tokens] || usage["output_tokens"] || usage["completion_tokens"]
+          }.compact
+        end
+
+        def mime_for(format)
+          { "mp3" => "audio/mpeg", "opus" => "audio/opus", "aac" => "audio/aac",
+            "wav" => "audio/wav", "flac" => "audio/flac" }[format.to_s] || "audio/mpeg"
+        end
+
+        def enforce_embedded_size!(data, label)
+          size = data.respond_to?(:bytesize) ? data.bytesize : data.to_s.bytesize
+          return if size <= MAX_EMBEDDED_BYTES
+
+          raise Insika::MediaError,
+                "#{label} too large to embed (#{size} bytes > #{MAX_EMBEDDED_BYTES})"
+        end
+
+        def presence(value)
+          Insika::Coercion.presence(value)
+        end
+      end
+    end
+  end
+end

data/lib/insika/memory_audit_store.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "digest/sha2"
+require "json"
+require "time"
+
+module Insika
+  # append-only, per-cell audit of MEMORY mutations. Every
+  # operator mutation of a cell appends a line (who, when, what, old->new
+  # digests). The entry holds DIGESTS of values, never the values — the forget
+  # line records that a deletion happened without the deleted content (the
+  # digest is not invertible, and keys are fact names — provenance, not
+  # payload). Capped per cell (no retention hook, no delete path: the audit
+  # outlives what it describes). `record` rescues EVERYTHING — a failed audit
+  # write never fails the mutation it describes.
+  #
+  # The capped-list RMW caveat (context_trace_store.rb's discipline): one cell
+  # key, written on the command's fiber; a cross-process race loses the loser's
+  # append — a trace-level loss, not a correctness one.
+  class MemoryAuditStore
+    SCOPE = "memory_audit" # store key = the memory cell scope
+    MAX_PER_CELL = 200 # oldest dropped; the cap bounds growth
+
+    Entry = Data.define(:at, :action, :actor, :key, :tenant, :customer,
+                        :old_hash, :new_hash, :note)
+
+    def initialize(store:, clock: nil)
+      @store = store
+      @clock = clock # -> Time, injectable for specs
+    end
+
+    # action: "put" | "forget" | "purge". key = the fact name (provenance,
+    # not payload). Appends + caps. Rescues EVERYTHING -> Entry | nil (the
+    # audit never breaks a command).
+    def record(cell:, action:, actor:, key: nil, tenant: nil, customer: nil,
+               old_hash: nil, new_hash: nil, note: nil)
+      entry = {
+        "at" => timestamp,
+        "action" => action.to_s,
+        "actor" => actor.to_s,
+        "key" => Coercion.presence(key),
+        "tenant" => Coercion.presence(tenant),
+        "customer" => Coercion.presence(customer),
+        "old_hash" => Coercion.presence(old_hash),
+        "new_hash" => Coercion.presence(new_hash),
+        "note" => Coercion.presence(note)
+      }
+      list = (@store.get(SCOPE, cell.to_s) || []) + [entry]
+      @store.set(SCOPE, cell.to_s, list.last(MAX_PER_CELL))
+      to_entry(entry)
+    rescue StandardError
+      nil
+    end
+
+    # -> [Entry] most recent first. [] if none. A broken backend degrades to
+    # [] — the audit is read to RENDER, never to gate.
+    def for_cell(cell, limit: 100)
+      Array(@store.get(SCOPE, cell.to_s)).reverse.first(limit).map { |e| to_entry(e) }
+    rescue StandardError
+      []
+    end
+
+    # The digest the callers share: SHA-256 hexdigest of JSON.generate(value)
+    # (or value.to_s for non-JSON scalars). -> String
+    def self.digest(value)
+      payload = case value
+                when Hash, Array then JSON.generate(value)
+                else value.to_s
+                end
+      Digest::SHA256.hexdigest(payload)
+    end
+
+    private
+
+    def to_entry(record)
+      Entry.new(at: record["at"], action: record["action"], actor: record["actor"],
+                key: record["key"], tenant: record["tenant"], customer: record["customer"],
+                old_hash: record["old_hash"], new_hash: record["new_hash"], note: record["note"])
+    end
+
+    def timestamp = (clock ? clock.call : Time.now.utc).utc.iso8601(6)
+
+    def clock = @clock
+  end
+end