insika 0.9.0 → 1.0.1

data/lib/insika/shared_conversations.rb

@@ -0,0 +1,305 @@
+# frozen_string_literal: true
+require 'json'
+require 'securerandom'
+require 'digest'
+
+module Insika
+  # Required HTTP persistence. The native backend owns the execution outbox;
+  # the central service alone owns settled conversation history.
+  class SharedConversations
+    class Recovered < StandardError
+      attr_reader :content, :output_parts, :attachments
+      def initialize(content, output_parts: [], attachments: [])
+        @content, @output_parts, @attachments = content, output_parts, attachments
+        super('recorded shared result recovered')
+      end
+    end
+    UUID = /\A[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\z/i
+    SCOPE = 'shared_conversations'
+
+    def initialize(url:, token:, store:)
+      require 'uri'
+      @url = URI(url)
+      unless %w[http https].include?(@url.scheme) && @url.host && !@url.userinfo && !@url.query && !@url.fragment
+        raise StoreError, 'invalid shared conversation URL'
+      end
+      raise StoreError, 'shared conversation token missing' if token.to_s.empty?
+      raise StoreError, 'shared conversations require a durable native backend' unless Stores.durable?(store)
+      @token, @store = token, store
+    end
+
+    def begin_turn(task:, profile:)
+      data, payload = identity(task)
+      acquire = !payload.fetch('shared_conversation').key?('generation')
+      path = path_for(data)
+      conversation = request('GET', path)
+      key = key_for(data)
+      old = @store.get(SCOPE,key)
+      check_identity!(data, conversation, ownership: !acquire || !!old)
+      if old
+        raise StoreError, 'shared turn input differs' unless old['input_digest'] == input_digest(payload)
+        raise StoreError, 'shared turn requires native reconciliation' unless old['messages']
+        flush(data, old)
+        raise Recovered.new(old['messages'].last['content'].filter_map { _1['text'] }.join("\n"), output_parts: old.fetch('output_parts', []), attachments: old.fetch('delivery_attachments', []))
+      end
+      raise StoreError, 'shared turn requires native reconciliation' if conversation['active_turn']
+      data = data.merge('generation'=>conversation['generation'] + (conversation['assigned_harness'] == 'insika' ? 0 : 1)) if acquire
+      history = history_at(path, conversation.fetch('last_sequence'))
+      request('PUT', path+'/bindings/insika', {'generation'=>data['generation'], 'native_session_id'=>task.session_id || task.id,
+        'synchronized_sequence'=>conversation['last_sequence']}) unless acquire
+      input = canonical(task, {'role'=>'user','content'=>payload.fetch('user_text')}, id: data['message_id'])
+      input['origin'] = payload['origin'] || 'customer'
+      input['content'] = data['content'] if data['content']
+      record = {'native_run_id'=>task.id, 'input_digest'=>input_digest(payload), 'sequence'=>conversation['last_sequence'] + 1, 'generation'=>data['generation']}
+      # Write first: an ambiguous admission or registration must never authorize
+      # another execution. Only a recorded result can be flushed automatically.
+      @store.transaction do
+        raise StoreError, 'shared turn requires native reconciliation' if @store.get(SCOPE,key)
+        @store.set(SCOPE,key,record)
+      end
+      admission = {'id'=>data['turn_id'],'generation'=>data['generation'],
+        'expected_sequence'=>conversation['last_sequence'],'message'=>input}
+      admission.merge!('acquire'=>true, 'generation'=>conversation['generation'], 'native_session_id'=>task.session_id || task.id) if acquire
+      turn = request('POST', path+'/turns', admission)
+      raise StoreError, 'shared acquired generation differs' if acquire && turn['generation'] != data['generation']
+      raise StoreError, 'shared turn requires native reconciliation' if turn['native_run_id'] || turn['state'] != 'running'
+      request('PUT', path+"/turns/#{data['turn_id']}/native-run", {'generation'=>data['generation'],'native_run_id'=>task.id})
+      project(history, path)
+    end
+
+    def resume_turn(task:, profile:, checkpoint:)
+      data, = identity(task)
+      path = path_for(data)
+      conversation = request('GET',path)
+      check_identity!(data,conversation)
+      active = conversation['active_turn']
+      record = @store.get(SCOPE,key_for(data))
+      valid = task.status == :waiting && checkpoint.task_id == task.id && checkpoint.continuation &&
+        active && active.values_at('id','native_run_id','state') == [data['turn_id'],task.id,'running'] &&
+        record && record['native_run_id'] == task.id
+      raise StoreError, 'shared turn requires native reconciliation' unless valid
+      project(history_at(path,record['sequence'] - 1),path)
+    end
+
+    def complete(task:, messages:, pending_approval: false, output_parts: [], attachments: [])
+      data, = identity(task)
+      record = @store.get(SCOPE,key_for(data)) || raise(StoreError, 'shared admission missing')
+      raise StoreError, 'shared native execution differs' unless record['native_run_id'] == task.id
+      unless record['messages']
+        output = messages.drop_while { _1['role'] == 'user' }
+        raise StoreError, 'shared final answer missing' unless output.last && output.last['role'] == 'assistant'
+        record['pending_approval'] = pending_approval
+        record['messages'] = output.map do |message|
+          full = record.fetch('tool_results', {})[message['tool_call_id']]
+          if message['role'] == 'tool' && !full.nil?
+            text = full.is_a?(String) ? full : JSON.generate(full)
+            message = message.merge('content'=>text)
+          end
+          canonical(task, message)
+        end
+        record['output_parts'] = Array(output_parts)
+        record['delivery_attachments'] = Array(attachments)
+        record['uploads'] = Array(output_parts).map do |part|
+          require 'base64'
+          raise StoreError, 'invalid shared output media' unless %w[image audio].include?(part['type']) && part['base64'].is_a?(String)
+          bytes = Base64.strict_decode64(part['base64'])
+          raise StoreError, 'shared output exceeds 10 MiB' if bytes.bytesize > 10*1024*1024
+          id = SecureRandom.uuid
+          record['messages'].last['content'] << {'type'=>part['type'],'attachment_id'=>id}
+          {'id'=>id,'base64'=>part['base64'],'mime_type'=>part.fetch('mime_type'),'sha256'=>Digest::SHA256.hexdigest(bytes)}
+        end
+        @store.set(SCOPE,key_for(data),record)
+      end
+      flush(data,record)
+    end
+
+    def input_attachments(task:)
+      data, = identity(task)
+      return [] unless data['content']
+      project([{'role'=>'user', 'content'=>data['content']}],path_for(data)).first['attachments'].map { Media.hydrate_attachment(_1) }
+    end
+
+    def record_tool_result(task:, call_id:, result:)
+      raise StoreError, 'shared tool correlation missing' if call_id.to_s.empty?
+      data, = identity(task)
+      @store.transaction do
+        record = @store.get(SCOPE,key_for(data)) || raise(StoreError, 'shared admission missing')
+        results = (record['tool_results'] ||= {})
+        # The first capture precedes prompt-only evidence reshaping and clipping.
+        results[call_id.to_s] ||= ToolTraceStore.mask(result.respond_to?(:content) ? result.content : result)
+        @store.set(SCOPE,key_for(data),record)
+      end
+    end
+
+    def identity(task)
+      payload = task.command.fetch('payload')
+      data = payload['shared_conversation']
+      raise StoreError, 'explicit shared conversation identity required' unless data.is_a?(Hash)
+      %w[tenant_id user_id agent_id conversation_id turn_id message_id].each do |name|
+        raise StoreError, "invalid shared #{name}" unless data[name].is_a?(String) && UUID.match?(data[name])
+      end
+      if data.key?('generation')
+        raise StoreError, 'invalid shared generation' unless data['generation'].is_a?(Integer) && data['generation'].positive?
+      else
+        record = @store.get(SCOPE,key_for(data))
+        data = data.merge('generation'=>record.fetch('generation')) if record
+      end
+      raise StoreError, 'original user_text required' unless payload['user_text'].is_a?(String)
+      content = data['content']
+      if content
+        valid = content.is_a?(Array) && content.all? do |part|
+          part.is_a?(Hash) && (part['type'] == 'text' ? part['text'].is_a?(String) :
+            %w[image audio document].include?(part['type']) && part['attachment_id'].is_a?(String) && UUID.match?(part['attachment_id']))
+        end
+        raise StoreError, 'invalid shared content' unless valid
+        raise StoreError, 'shared content differs from original speech' unless content.filter_map { _1['text'] }.join("\n") == payload['user_text']
+      end
+      if Media.parts(payload['parts']).any? { !_1.text? } && !Array(content).any? { _1['type'] != 'text' }
+        raise StoreError, 'upload media to central storage before admission'
+      end
+      tenant = task.command.fetch('meta')['tenant']
+      raise StoreError, 'shared tenant identity differs' unless tenant.to_s == data['tenant_id']
+      [data,payload]
+    end
+
+    def memory_context(task:, profile:)
+      data, payload = identity(task)
+      result = {}
+      if profile.memory
+        refs = request('GET', "/v1/memories/user/#{data['user_id']}?limit=50")['memories']
+        result['facts'] = refs.filter_map { memory_get(task:task,id:_1['id']) }
+        path = "/v1/memories/conversation/#{data['conversation_id']}"
+        request('GET',path+'?limit=50')['memories'].each do |ref|
+          record = request('GET',path+'/'+URI.encode_www_form_component(ref['id']),missing:true)
+          result['facts'] << record.merge('id'=>"conversation.#{record['id']}") if record
+        end
+      end
+      if Coercion.truthy?(profile.knowledge&.dig('retrieve'))
+        query = URI.encode_www_form_component(payload['user_text'][0, 200])
+        result['knowledge'] = request('GET', "/v1/memories/agent/#{data['agent_id']}?limit=5&query=#{query}")['memories']
+      end
+      result
+    end
+
+    def memory_get(task:, id:, kind: 'fact', include_proposed: false)
+      data, = identity(task)
+      scope, owner = kind == 'knowledge' ? ['agent',data['agent_id']] : ['user',data['user_id']]
+      path = "/v1/memories/#{scope}/#{owner}/#{URI.encode_www_form_component(id)}"
+      path += '?include_proposed=true' if include_proposed
+      request('GET', path, missing:true)
+    end
+
+    def propose_memory(task:, id:, value:, kind: 'fact')
+      data, = identity(task)
+      scope, owner = kind == 'knowledge' ? ['agent',data['agent_id']] : ['user',data['user_id']]
+      current = memory_get(task:task,id:id,kind:kind,include_proposed:true)
+      recorded = @store.get(SCOPE,key_for(data))
+      source_ids = [data['message_id']] + Array(recorded && recorded['messages']).map { _1['id'] }
+      clean = value.is_a?(String) ? Safety::Detectors.redact(value).first : ToolTraceStore.mask(value)
+      request('PUT', "/v1/memories/#{scope}/#{owner}/#{URI.encode_www_form_component(id)}",
+        {'value'=>clean,'kind'=>kind,'origin'=>'insika','status'=>'proposed','expected_revision'=>current ? current['revision'] : 0,
+         'sources'=>source_ids.uniq.map { {'conversation_id'=>data['conversation_id'],'message_id'=>_1} }})
+    end
+
+    private
+
+    def check_identity!(data, conversation, ownership: true)
+      unless conversation.values_at('tenant_id','user_id','agent_id') == data.values_at('tenant_id','user_id','agent_id') &&
+             (!ownership || conversation.values_at('assigned_harness','generation') == ['insika',data['generation']])
+        raise StoreError, 'shared conversation identity or generation mismatch'
+      end
+    end
+
+    def key_for(data) = data.values_at('tenant_id','conversation_id','turn_id').join(':')
+    def path_for(data) = "/v1/conversations/#{data['conversation_id']}"
+    def input_digest(payload) = Digest::SHA256.hexdigest(JSON.generate(payload.slice('shared_conversation','user_text','origin')))
+
+    def canonical(task, message, id: SecureRandom.uuid)
+      result = {'schema_version'=>1,'id'=>id,'role'=>message.fetch('role'),
+        'content'=>[{'type'=>'text','text'=>message.fetch('content').to_s}],
+        'source'=>{'harness'=>'insika','session_id'=>task.session_id || task.id}}
+      result.merge!(ToolTraceStore.mask(message.slice('tool_calls','tool_call_id','origin','outcome')))
+      result
+    end
+
+    def flush(data, record)
+      require 'base64'
+      record.fetch('uploads',[]).each do |upload|
+        request('PUT',path_for(data)+"/attachments/#{upload['id']}",Base64.strict_decode64(upload['base64']),
+          headers: {'Content-Type'=>upload['mime_type'],'X-Filename'=>upload['id'],
+            'X-Content-SHA256'=>upload['sha256'],'X-Conversation-Generation'=>data['generation'].to_s})
+      end
+      path = path_for(data)+"/turns/#{data['turn_id']}"
+      prefix = record.fetch('messages')[0...-1]
+      prefix.each_with_index do |message, index|
+        request('POST', path+'/messages', {'generation'=>data['generation'],'expected_sequence'=>record['sequence']+index,'messages'=>[message]})
+      end
+      request('POST', path+'/complete', {'generation'=>data['generation'],
+        'expected_sequence'=>record['sequence']+prefix.length,'message'=>record['messages'].last,'pending_approval'=>record.fetch('pending_approval',false)})
+    end
+
+    def history_at(path, sequence)
+      messages, cursor = [], 0
+      while cursor < sequence
+        page = request('GET', path+"/messages?after_sequence=#{cursor}&through_sequence=#{sequence}&limit=10")
+        raise StoreError, 'shared history cursor did not advance' unless page['next_sequence'].is_a?(Integer) && page['next_sequence'] > cursor
+        messages.concat(page.fetch('messages'))
+        cursor = page['next_sequence']
+      end
+      messages
+    end
+
+    def project(messages, path)
+      messages.map do |message|
+        text, attachments = [], []
+        message.fetch('content').each do |part|
+          if part['type'] == 'text'
+            text << part.fetch('text')
+          else
+            id = part.fetch('attachment_id')
+            raise StoreError, 'invalid shared attachment ID' unless UUID.match?(id)
+            bytes, headers = request('GET', path+"/attachments/#{id}", raw: true)
+            raise StoreError, 'shared attachment hash mismatch' unless Digest::SHA256.hexdigest(bytes) == headers['x-content-sha256']
+            require 'base64'
+            extension = {'image/png'=>'png','image/jpeg'=>'jpg','image/webp'=>'webp','image/gif'=>'gif',
+              'application/pdf'=>'pdf','audio/mpeg'=>'mp3','audio/wav'=>'wav','audio/ogg'=>'ogg','audio/webm'=>'webm','text/plain'=>'txt'}.fetch(headers['content-type'],'bin')
+            attachments << {'base64'=>Base64.strict_encode64(bytes),'filename'=>"#{id}.#{extension}"}
+          end
+        end
+        projected = message.slice('role','origin').merge('content'=>text.join("\n"),'attachments'=>attachments)
+        # RubyLLM checks answered call IDs across its entire chat, not per turn.
+        call_id = ->(id) { "history_#{Digest::SHA256.hexdigest("#{message.fetch('turn_id')}:#{id}")[0, 48]}" }
+        projected['tool_calls'] = message['tool_calls'].map { _1.merge('id'=>call_id.call(_1['id'])) } if message['tool_calls']
+        projected['tool_call_id'] = call_id.call(message['tool_call_id']) if message['tool_call_id']
+        projected
+      end
+    end
+
+    def request(method, path, data = nil, raw: false, headers: {}, missing: false)
+      require 'net/http'
+      uri = @url.dup
+      uri.path = @url.path.delete_suffix('/') + path.split('?',2).first
+      uri.query = path.split('?',2)[1]
+      body = data.is_a?(String) ? data : data && JSON.generate(data)
+      raise StoreError, 'shared request exceeds 1 MiB' if body && !data.is_a?(String) && body.bytesize > 1_048_576
+      request = Net::HTTPGenericRequest.new(method, !body.nil?, true, uri.request_uri,
+        {'Authorization'=>"Bearer #{@token}", 'Content-Type'=>'application/json'}.merge(headers))
+      request.body = body if body
+      Net::HTTP.start(uri.host, uri.port, nil, use_ssl: uri.scheme == 'https', open_timeout: 5, read_timeout: 10, write_timeout: 10) do |http|
+        http.max_retries = 0
+        http.request(request) do |response|
+          return nil if missing && response.code == '404'
+          raise StoreError, "shared conversation HTTP #{response.code}" unless response.code == '200'
+          bytes = +''.b
+          response.read_body do |chunk|
+            bytes << chunk
+            raise StoreError, 'shared response too large' if bytes.bytesize > (raw ? 10 : 16)*1024*1024
+          end
+          return raw ? [bytes,response.to_hash.transform_values(&:first)] : JSON.parse(bytes)
+        end
+      end
+    rescue JSON::ParserError, IOError, SystemCallError, Timeout::Error, SocketError => error
+      raise StoreError, "shared conversation transport failed (#{error.class})"
+    end
+  end
+end

data/lib/insika/skill_catalog.rb

@@ -28,10 +28,17 @@ module Insika
     # store (optional): a SkillStore with the skills AUTHORED in the Studio.
     # They overlay the on-disk ones (seed) — the Store wins, it is the source of truth.
     # Nil = disk-only behavior, zero regression.
-    def initialize(roots, store: nil)
+    #
+    # recheck/clock: another worker may write a skill (pack import, Studio edit) and
+    # `reload` only runs in the process that handled the write. At most every
+    # `recheck` seconds the catalog compares the config version token and reloads
+    # when it moved — the same rule as OverlayToolRegistry for data-tools.
+    def initialize(roots, store: nil, recheck: 2, clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
       @roots = Array(roots)
       @store = store
-      @skills, @agent_skills = load_all
+      @recheck = recheck
+      @clock = clock
+      reload
     end
 
     # The SkillStore the catalog overlays — the composition root hands it to
@@ -49,6 +56,7 @@ module Insika
     # Without `agent` the shared scope is all there is, which is what every caller
     # that has no agent in hand (the Studio's shared editor, a bare catalog) means.
     def all(agent: nil)
+      reload if stale?
       shared = @skills
       overrides = agent_scope(agent)
       return shared.values if overrides.empty?
@@ -57,6 +65,7 @@ module Insika
     end
 
     def find(name, agent: nil)
+      reload if stale?
       agent_scope(agent)[name.to_s] || @skills[name.to_s]
     end
 
@@ -64,6 +73,8 @@ module Insika
     # authored/edited skill takes effect without a restart. A turn in progress
     # captured @skills at dispatch, so it does not see the swap mid-flight.
     def reload
+      @token = version_token
+      @checked_at = @clock.call
       @skills, @agent_skills = load_all
       self
     end
@@ -155,6 +166,21 @@ module Insika
     # AgentProfile#stream_public?. Anything else (a list, nil, false) is not blanket.
     def blanket?(spec) = Coercion.truthy?(spec)
 
+    # The token moves on any config write, so a reload may find nothing new. Read
+    # BEFORE load_all in `reload`: a write landing in between leaves the old token,
+    # and the next check reloads again instead of missing it.
+    def stale?
+      return false unless @store.respond_to?(:version_token)
+
+      now = @clock.call
+      return false if now - @checked_at < @recheck
+
+      @checked_at = now
+      version_token != @token
+    end
+
+    def version_token = @store.respond_to?(:version_token) ? @store.version_token : nil
+
     # An agent's override index; {} for a nil agent or one that specialized nothing.
     def agent_scope(agent) = agent.nil? ? {} : (@agent_skills[agent.to_s] || {})
 

data/lib/insika/skill_store.rb

@@ -55,6 +55,9 @@ module Insika
       names(agent: agent).each_with_object({}) { |n, acc| acc[n] = get(n, agent: agent) }
     end
 
+    # Changes whenever any config is written, in any process (ConfigStore#version_token).
+    def version_token = @cs.version_token
+
     # -> [String] every agent that has specialized at least one skill. What the
     # catalog overlays and `doctor` sweeps.
     def agents = @cs.keys(AGENT_SCOPE).sort
@@ -86,6 +89,9 @@ module Insika
     # -> [ { "content" =>, "at" => } ] most recent first.
     def versions(name, agent: nil) = record(name, agent)&.fetch("history", []) || []
 
+    # -> iso8601 of the current content's write, nil for an unknown skill.
+    def updated_at(name, agent: nil) = record(name, agent)&.fetch("updated_at", nil)
+
     # Restores version `index` as the current content (a new write). -> Hash.
     def restore(name, index, agent: nil)
       hist = versions(name, agent: agent)

data/lib/insika/soak/runner.rb

@@ -182,7 +182,7 @@ module Insika
       end
 
       def target_url
-        (@env["INSIKA_URL"] || @env["HARNESS_URL"] || "http://localhost:9292").sub(%r{/$}, "")
+        (@env["INSIKA_URL"] || "http://localhost:9292").sub(%r{/$}, "")
       end
 
       def corpus

data/lib/insika/steer_injector.rb

@@ -6,17 +6,9 @@ module Insika
   #
   # A customer who corrects themselves while the agent is calling tools ("1234567",
   # three seconds after "queria saber do pedido") should have that land before the
-  # model's next reasoning step, not after the whole run. RubyLLM runs the entire tool
-  # loop inside `chat.ask`, so the only place to append is from inside its callbacks —
-  # which is enough, because they are public and additive:
-  #
-  #   complete_once
-  #     ├─ provider_completion         → assistant message announcing N tool_calls
-  #     ├─ after_message(assistant)    ← N is read here
-  #     └─ handle_tool_calls
-  #          ├─ add_tool_result_message ×N
-  #          │    └─ after_message(tool)  ← counted; the Nth is THE BOUNDARY
-  #          └─ halt_result || complete   ← the next model step sees what we appended
+  # model's next reasoning step, not after the whole run. RubyLLM emits message
+  # callbacks during both `chat.ask` and native steps. ToolBatch finds the last
+  # sibling result so steering lands before the next model step.
   #
   # Counting to N is not an optimization, it is the correctness condition. A `user`
   # message inserted BETWEEN tool results is rejected outright by Anthropic (all tool
@@ -41,9 +33,7 @@ module Insika
       @actor = actor
       @policy = policy
       @emit = emit
-      @expected = nil # tool calls announced by the batch in flight (nil = not in one)
-      @seen = 0
-      @halted = false
+      @batch = ToolBatch.new
       @injected = 0
     end
 
@@ -53,20 +43,13 @@ module Insika
     # RubyLLM `after_tool_result`, with the RAW result — the only place a `Tool::Halt`
     # is still recognizable. By the time it becomes a `role: tool` message its content
     # is the payload, indistinguishable from an ordinary result.
-    def tool_result(result)
-      @halted = true if halt?(result)
-    end
+    def tool_result(result) = @batch.halt!(result)
 
     # RubyLLM `after_message`. An assistant message carrying tool calls OPENS a batch;
     # the Nth tool result CLOSES it, and that is 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
-      inject! if @seen >= @expected
+      inject! if @batch.closed?(message)
     end
 
     # Tail-appends whatever is in the mailbox right now and reports how many. Called
@@ -88,34 +71,10 @@ module Insika
 
     private
 
-    def open_batch(message)
-      calls = field(message, :tool_calls)
-      size = calls.respond_to?(:size) ? calls.size : 0
-      # A message with no tool call is the model talking, not a batch: leave any
-      # pending message where it is. The turn is about to end, and the Executor
-      # absorbs it there in ONE extra round (#absorb_pending!) — a text-only turn
-      # closes no batch, and answering it half-way is not an option.
-      return @expected = nil if size.zero?
-
-      @expected = size
-      @seen = 0
-      @halted = false
-    end
-
     def inject!
-      @expected = nil
-      return if @halted # nothing will read it: leave it in the mailbox
+      return if @batch.halted? # nothing will read it: leave it in the mailbox
 
       absorb_pending!
     end
-
-    def halt?(result) = defined?(RubyLLM::Tool::Halt) && result.is_a?(RubyLLM::Tool::Halt)
-
-    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/store.rb

@@ -25,7 +25,9 @@ module Insika
   #
   # Backends `include Store` and override the six methods; any forgotten
   # method raises NotImplementedError (fail-fast, better than a distant
-  # NoMethodError).
+  # NoMethodError). #entries, #recent and #amend have defaults; a backend that
+  # knows its write order overrides #recent and #amend together (the contract
+  # suite checks that an amended key keeps its place in #recent).
   module Store
     # -> Object | nil (deserialized)
     def get(scope, key)
@@ -37,6 +39,13 @@ module Insika
       raise NotImplementedError, "#{self.class}#set"
     end
 
+    # -> value. Like #set, but an existing key keeps its place in #recent: an edit
+    # that is not new activity (a review on a session). This default is #set,
+    # exact only for a backend whose #recent reads the value's "updated_at".
+    def amend(scope, key, value)
+      set(scope, key, value)
+    end
+
     # -> true | false (did it exist?)
     def delete(scope, key)
       raise NotImplementedError, "#{self.class}#delete"
@@ -53,6 +62,25 @@ module Insika
       raise NotImplementedError, "#{self.class}#scopes"
     end
 
+    # -> [[key, value], ...] sorted by key, filtered like #list. The bulk read for
+    # a caller that lists keys and reads each one. This default is exactly that;
+    # a backend overrides it to answer in one query (no lock taken, like #list).
+    def entries(scope, prefix = nil)
+      list(scope, prefix).filter_map do |key|
+        value = get(scope, key)
+        [key, value] unless value.nil?
+      end
+    end
+
+    # -> [[key, value], ...] the `limit` most recently WRITTEN keys of the scope
+    # (filtered like #list), newest first: a "recent" list without reading the
+    # whole scope. A backend that knows its write order answers it directly;
+    # this default approximates it by each value's "updated_at", when it has one.
+    # `offset` skips that many of the newest (the next page).
+    def recent(scope, prefix, limit, offset = 0)
+      entries(scope, prefix).sort_by { |_, v| v.is_a?(Hash) ? v["updated_at"].to_s : "" }.reverse.drop(offset).first(limit)
+    end
+
     # -> the block's result; atomic if the backend supports it
     def transaction(&blk)
       raise NotImplementedError, "#{self.class}#transaction"

data/lib/insika/stores/json_value.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Insika
+  module Stores
+    # The type model every backend shares: JSON types plus Symbol (stored as
+    # String). Anything else is refused at the write (fail-fast), so no backend
+    # ever stores garbage.
+    #
+    # Does not use `JSON.generate(strict: true)`: under older json versions
+    # `strict` rejects Symbol, which would break the Symbol coercion. The
+    # explicit check is independent of the json version.
+    module JsonValue
+      JSONABLE = [NilClass, TrueClass, FalseClass, Integer, Float, String, Symbol].freeze
+
+      private
+
+      def serialize(value)
+        ensure_jsonable!(value)
+        JSON.generate(value)
+      rescue JSON::GeneratorError => e
+        raise Insika::StoreError, "value not serializable: #{e.message}"
+      end
+
+      def ensure_jsonable!(value)
+        case value
+        when *JSONABLE then nil
+        when Array then value.each { |v| ensure_jsonable!(v) }
+        when Hash then value.each { |k, v| ensure_jsonable!(k); ensure_jsonable!(v) }
+        else
+          raise Insika::StoreError, "value not serializable: #{value.class} not allowed in JSON"
+        end
+      end
+    end
+  end
+end