insika 0.2.0 → 0.3.0

data/lib/insika/memory_store.rb

@@ -10,6 +10,14 @@ module Insika
   # `PendingActionStore` (normalizes symbol→string on write, O(n) scan on
   # read, records with a timestamp).
   #
+  # the record gains `origin`/`created_at`/`expires_at`, the
+  # (tenant, customer) pair becomes first-class at the API (`customer:`
+  # builds the same "memory:<tenant>:<customer>" scope the Executor derives),
+  # and the store enumerates its cells (the Studio drill, the doctor, the
+  # retention sweep). Migration is lazy: tolerant reads, materialized on the
+  # first write. The audit trail lives in `MemoryAuditStore` (C2), NOT here —
+  # this stays a dumb domain store.
+  #
   # NOT to be confused with `Insika::Stores::Memory` (in-memory KV backend):
   # this is the domain store; that one is one of the backends this writes to.
   class MemoryStore
@@ -18,52 +26,246 @@ module Insika
     NOTE_PREFIX  = "note:"
     DEFAULT_TENANT = "_default"   # no tenant in the Command
 
-    Fact = Data.define(:key, :value, :updated_at)
+    # the record's provenance. A closed string set: "legacy"
+    # (migrated, unknown writer), "engine" (the remember tool / an
+    # integration write), "operator" (Studio edit), "distilled"
+    # reserved).
+    ORIGIN_LEGACY = "legacy"
+
+    # the per-SESSION cell marker. Engine-owner memory with no
+    # customer and no explicit tenant falls back to the session (executor
+    # parity) — the cell is MARKED "memory:chat:<session id>" so the drill and
+    # the doctor never read a conversation as a customer (a bare
+    # "memory:<session id>" cell is indistinguishable from a single-tenant
+    # customer ref). A real tenant NAMED "chat" would collide with the marker
+    # (its customer cells would read as session cells) — accepted, merchant
+    # ids live in a different namespace in practice.
+    SESSION_TAG = "chat"
+
+    Fact = Data.define(:key, :value, :origin, :created_at, :updated_at, :expires_at)
     Note = Data.define(:id, :text, :created_at)
 
-    def initialize(store:)
+    def initialize(store:, clock: nil)
       @store = store
+      @clock = clock # -> Time, injectable for specs
     end
 
-    # Upsert (last-write-wins, Store contract). -> Fact
-    def put_fact(tenant:, key:, value:)
-      record = { "key" => key.to_s, "value" => stringify(value), "updated_at" => timestamp }
-      @store.set(scope_for(tenant), FACT_PREFIX + key.to_s, record)
+    # Upsert (last-write-wins, Store contract). `customer:` PRESENT moves the
+    # scope to the [tenant:]customer cell (WS8's rule — nil tenant + customer
+    # -> bare "memory:<customer>", NEVER _default). `origin` defaults to
+    # "engine" (the remember tool's write). `expires_at` (ISO8601 String) is
+    # normalized and validated here — an invalid value raises ValidationError
+    # (a silently dropped LGPD expiry date is the defect). Preserves the
+    # existing record's created_at; rewrites a legacy record in the full
+    # shape. -> Fact
+    def put_fact(tenant:, key:, value:, customer: nil, origin: "engine", expires_at: nil)
+      scope = scope_for(tenant, customer)
+      current = @store.get(scope, FACT_PREFIX + key.to_s)
+      prev = current.is_a?(Hash) ? current : {}
+      stamp = timestamp
+      record = {
+        "key" => key.to_s, "value" => stringify(value),
+        "origin" => Coercion.presence(origin) || "engine",
+        "created_at" => Coercion.presence(prev["created_at"]) || Coercion.presence(prev["updated_at"]) || stamp,
+        "updated_at" => stamp,
+        "expires_at" => normalize_expiry(expires_at)
+      }
+      @store.set(scope, FACT_PREFIX + key.to_s, record)
       to_fact(record)
     end
 
-    # -> Fact | nil
-    def get_fact(tenant:, key:)
-      record = @store.get(scope_for(tenant), FACT_PREFIX + key.to_s)
+    # -> Fact | nil (tolerant read: missing origin -> "legacy", created_at ->
+    # updated_at, expires_at -> nil).
+    def get_fact(tenant:, key:, customer: nil)
+      record = @store.get(scope_for(tenant, customer), FACT_PREFIX + key.to_s)
       record && to_fact(record)
     end
 
-    # -> [Fact] sorted by key (list is lexicographic).
-    def facts(tenant:)
-      scope = scope_for(tenant)
+    # -> [Fact] sorted by key. Facts whose expires_at <= now are EXCLUDED
+    # (D5: an expired fact is never injected nor shown, even before the
+    # sweep runs).
+    def facts(tenant:, customer: nil)
+      scope = scope_for(tenant, customer)
       @store.list(scope, FACT_PREFIX).filter_map do |k|
         record = @store.get(scope, k)
-        record && to_fact(record)
+        next unless record
+
+        fact = to_fact(record)
+        next if expired?(fact)
+
+        fact
       end
     end
 
     # -> bool (did it exist?)
-    def forget_fact(tenant:, key:)
-      @store.delete(scope_for(tenant), FACT_PREFIX + key.to_s)
+    def forget_fact(tenant:, key:, customer: nil)
+      @store.delete(scope_for(tenant, customer), FACT_PREFIX + key.to_s)
+    end
+
+    # CAS write (WS8): only writes when the STORED fact's updated_at still
+    # equals the caller's revision — a fact a concurrent writer already moved
+    # is refused instead of clobbered (last-write-wins is the default; this is
+    # the opt-in optimistic path). -> Fact (written) | nil (lost the race — the
+    # caller must re-read and retry). The read-compare-write rides
+    # `@store.transaction` (the repo rule) — `next`, never `return`, inside.
+    def replace_if_revision(tenant:, key:, value:, expected_revision:,
+                            customer: nil, origin: "engine", expires_at: nil)
+      @store.transaction do
+        current = @store.get(scope_for(tenant, customer), FACT_PREFIX + key.to_s)
+        next nil if current.nil? || current["updated_at"] != expected_revision
+
+        put_fact(tenant: tenant, key: key, value: value, customer: customer,
+                 origin: origin, expires_at: expires_at)
+      end
+    end
+
+    # Purges the WHOLE scope (WS8 — forget_customer / delete_tenant_data). The
+    # scope string is the isolation boundary: one cell per
+    # (tenant-or-customer), so zeroing the cell cannot touch another's.
+    # The list-then-delete rides `@store.transaction` (the repo rule): an erasure
+    # that is half-applied is the LGPD defect, and a fact written between the
+    # list and the deletes would survive a purge that reported success.
+    # -> count of records purged.
+    def purge(tenant:, customer: nil)
+      scope = scope_for(tenant, customer)
+      @store.transaction do
+        keys = @store.list(scope)
+        keys.each { |k| @store.delete(scope, k) }
+        keys.size
+      end
+    end
+
+    # Purges a TENANT and every customer cell under it (WS8 phase 2 —
+    # delete_tenant_data). The tenant's own cell ("memory:<tenant>") plus each
+    # cell whose scope starts with "memory:<tenant>:" (the customer cells),
+    # plus the tenant's SESSION-marked cells ("memory:chat:<tenant>:*" — in
+    # multi-tenant a session id is "<tenant>:<id>", so its memory cell is
+    # "memory:chat:<tenant>:<id>"). The scope enumeration is the Store's — no
+    # session-derived list, so a customer cell whose session was already
+    # deleted is still purged. ONE transaction for the whole tenant (the repo
+    # rule): the scope enumeration and every delete see the same snapshot, so a
+    # customer cell born mid-purge cannot slip through a deletion that reported
+    # success. -> count of records purged.
+    def purge_tenant(tenant)
+      cell = scope_for(tenant)
+      @store.transaction do
+        scopes = [cell] + @store.scopes("#{cell}:") +
+                 @store.scopes("#{SCOPE_PREFIX}:#{SESSION_TAG}:#{tenant}:")
+        scopes.sum do |scope|
+          keys = @store.list(scope)
+          keys.each { |k| @store.delete(scope, k) }
+          keys.size
+        end
+      end
+    end
+
+    # Age-based prune (WS8 retention). New : `scope:` limits the pass
+    # to ONE cell; a fact with an explicit expires_at is SKIPPED (D5 — the
+    # explicit override owns that fact's life). -> count removed.
+    def prune_older_than(time, scope: nil)
+      cutoff = time.utc.iso8601
+      removed = 0
+      scopes = scope ? [scope] : @store.scopes("#{SCOPE_PREFIX}:")
+      scopes.each do |sc|
+        @store.list(sc).each do |k|
+          rec = @store.get(sc, k)
+          next if rec && rec["expires_at"] # the override owns this fact's life
+
+          stamp = rec && (rec["updated_at"] || rec["created_at"])
+          next unless stamp && stamp.to_s < cutoff
+
+          @store.delete(sc, k)
+          removed += 1
+        end
+      end
+      removed
+    end
+
+    # Removes facts whose expires_at <= now (default clock), EVERY cell.
+    # -> count removed.
+    def prune_expired(now = nil)
+      cutoff = (now || self.now).utc
+      removed = 0
+      @store.scopes("#{SCOPE_PREFIX}:").each do |scope|
+        @store.list(scope).each do |k|
+          rec = @store.get(scope, k)
+          next unless rec && rec["expires_at"]
+
+          begin
+            next unless Time.iso8601(rec["expires_at"]) <= cutoff
+          rescue ArgumentError
+            next
+          end
+
+          @store.delete(scope, k)
+          removed += 1
+        end
+      end
+      removed
+    end
+
+    # --- enumeration (the drill / doctor / retention inputs) -----------
+
+    # -> [{scope:, tenant: String|nil, customer: String|nil}] — every "memory:*"
+    # scope, classified by SHAPE (D6). _default -> {tenant: nil, customer: nil}.
+    def cells
+      @store.scopes("#{SCOPE_PREFIX}:").map { |scope| self.class.parse_cell(scope) }
+    end
+
+    # -> [{scope:, tenant:, customer:}] — the cells that hold CUSTOMER memory:
+    # 2+-segment scopes always (except the SESSION-marked cells — a session is
+    # never a customer); 1-segment scopes whose name is not _default and not in
+    # `reserved` (the caller's agent ids / tenant cells). Sorted by scope.
+    def customer_cells(reserved: [])
+      excluded = Array(reserved).map(&:to_s)
+      cells.reject do |c|
+        self.class.session_cell?(c) ||
+          (c[:tenant].nil? && (c[:customer].nil? || excluded.include?(c[:customer])))
+      end.sort_by { |c| c[:scope] }
+    end
+
+    # Is this a classified cell the engine's per-SESSION cell
+    # ("memory:chat:<session id>")? The one classification both the drill and
+    # the doctor share — a session-derived cell must never read as a customer.
+    def self.session_cell?(cell) = cell[:tenant] == SESSION_TAG
+
+    # The public cell string for a pair (the commands and the Studio build URLs
+    # and audit keys with this — the same string the Executor derives).
+    def cell_for(tenant, customer = nil) = scope_for(tenant, customer)
+
+    # The shared classification (public — the Studio/commands split audit
+    # fields): "memory:acme:c-123" -> {scope:, tenant: "acme", customer: "c-123"};
+    # "memory:c-123" -> {scope:, tenant: nil, customer: "c-123"};
+    # "memory:_default" -> {scope:, tenant: nil, customer: nil}.
+    def self.parse_cell(scope)
+      rest = scope.to_s.sub(/\A#{SCOPE_PREFIX}:/, "")
+      base, tail = rest.split(":", 2)
+      if base == DEFAULT_TENANT && tail.nil?
+        { scope: scope, tenant: nil, customer: nil }
+      elsif tail
+        { scope: scope, tenant: base, customer: tail }
+      else
+        { scope: scope, tenant: nil, customer: base }
+      end
     end
 
     # Append. `at` (ISO8601) goes at the START of the key so `list` returns the notes in
     # chronological order; `id`/`at` injectable for deterministic tests. -> Note
-    def add_note(tenant:, text:, id: SecureRandom.uuid, at: nil)
+    def add_note(tenant:, text:, id: SecureRandom.uuid, at: nil, customer: nil)
       at ||= timestamp
       record = { "id" => id.to_s, "text" => text.to_s, "created_at" => at }
-      @store.set(scope_for(tenant), NOTE_PREFIX + "#{at}:#{id}", record)
+      @store.set(scope_for(tenant, customer), NOTE_PREFIX + "#{at}:#{id}", record)
       to_note(record)
     end
 
+    # Cheap fact count for the drill index (keys only, no payload reads). -> Integer
+    def fact_count(tenant:, customer: nil)
+      @store.list(scope_for(tenant, customer), FACT_PREFIX).size
+    end
+
     # -> [Note] MOST RECENT first, capped by `limit`.
-    def notes(tenant:, limit: nil)
-      scope = scope_for(tenant)
+    def notes(tenant:, limit: nil, customer: nil)
+      scope = scope_for(tenant, customer)
       keys = @store.list(scope, NOTE_PREFIX).reverse # list is chronological -> reverse = most recent first
       keys = keys.first(limit) if limit
       keys.filter_map do |k|
@@ -74,12 +276,51 @@ module Insika
 
     private
 
-    def scope_for(tenant) = "#{SCOPE_PREFIX}:#{tenant.nil? || tenant.to_s.empty? ? DEFAULT_TENANT : tenant}"
+    # WS8's rule (executor.rb:1679 parity): customer present -> the
+    # [tenant:]customer cell; nil tenant + customer -> the bare customer cell,
+    # NEVER memory:_default:<customer>.
+    def scope_for(tenant, customer = nil)
+      base = Coercion.blank?(tenant) ? DEFAULT_TENANT : tenant
+      cust = Coercion.presence(customer)
+      return "#{SCOPE_PREFIX}:#{cust}" if cust && Coercion.blank?(tenant)
+
+      cust ? "#{SCOPE_PREFIX}:#{base}:#{cust}" : "#{SCOPE_PREFIX}:#{base}"
+    end
+
+    def to_fact(record)
+      Fact.new(key: record["key"], value: record["value"],
+               origin: Coercion.presence(record["origin"]) || ORIGIN_LEGACY,
+               created_at: Coercion.presence(record["created_at"]) || Coercion.presence(record["updated_at"]),
+               updated_at: record["updated_at"], expires_at: record["expires_at"])
+    end
 
-    def to_fact(record) = Fact.new(key: record["key"], value: record["value"], updated_at: record["updated_at"])
     def to_note(record) = Note.new(id: record["id"], text: record["text"], created_at: record["created_at"])
 
-    def timestamp = Time.now.utc.iso8601
+    def expired?(fact)
+      return false if fact.expires_at.nil?
+
+      Time.iso8601(fact.expires_at) <= now
+    rescue ArgumentError
+      false
+    end
+
+    def now = (@clock ? @clock.call : Time.now.utc).utc
+
+    # Microsecond precision ON PURPOSE: updated_at is the CAS revision
+    # (replace_if_revision) — second-precision collides for two writes in the
+    # same second (WS8).
+    def timestamp = now.iso8601(6)
+
+    # nil | canonical ISO8601(6); invalid -> ValidationError (fail-fast on an
+    # LGPD field — a silently dropped expiry date is the defect).
+    def normalize_expiry(expires_at)
+      return nil if expires_at.nil? || expires_at.to_s.strip.empty?
+
+      Time.iso8601(expires_at.to_s).utc.iso8601(6)
+    rescue ArgumentError
+      raise Insika::ValidationError,
+            "expires_at must be an ISO8601 timestamp (got #{expires_at.inspect})"
+    end
 
     def stringify(obj)
       case obj
@@ -90,4 +331,4 @@ module Insika
       end
     end
   end
-end
+end

data/lib/insika/message_origin.rb

@@ -33,8 +33,13 @@ module Insika
     AGENT    = "agent"    # the model (the default for `assistant`)
     ENGINE   = "engine"   # Insika itself, or the consumer composing on its behalf
     OPERATOR = "operator" # a HUMAN on the assistant side (a handoff; set by importers)
+    # the FollowupEngine's synthetic turn — the engine's own kick,
+    # never the customer. RESERVED: a consumer cannot declare it (the
+    # SendMessage edge refuses the spelling — only the engine creates those
+    # turns, D5).
+    SCHEDULED = "scheduled"
 
-    ALL = [CUSTOMER, AGENT, ENGINE, OPERATOR].freeze
+    ALL = [CUSTOMER, AGENT, ENGINE, OPERATOR, SCHEDULED].freeze
 
     module_function
 

data/lib/insika/model_visible.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Insika
+  #   — the model-visible payload of ONE ask: the system text,
+  # the tool schemas, and the full message stream — exactly what the provider
+  # serializes. Captured AT the RubyLLM boundary (the chat object the executor
+  # hands to `ask`), never re-derived: re-derivation would re-run volatile
+  # context providers (LLM moderation, timestamps) and could drift from the
+  # bytes actually sent.
+  #
+  # "Model-visible means logged": the durable reconstruction of a turn is the
+  # checkpoint (messages — the transcript half) + this record (instructions +
+  # tool schemas — the half the checkpoint lacks). The conformance suite
+  # (spec/insika/conformance/model_visible_spec.rb) asserts the three-way byte
+  # identity: capturing chat == checkpoint == trace.
+  #
+  # Pure reads off the chat object with respond_to? guards — a chat lacking a
+  # reader contributes nil/[], never raises (the trace discipline).
+  ModelVisible = Data.define(:instructions, :tools, :messages) do
+    # -> ModelVisible. `chat` is the RubyLLM chat at the boundary (instructions,
+    # tools, messages are exactly the three parts the provider serializes).
+    def self.capture(chat)
+      new(
+        instructions: chat.respond_to?(:instructions) ? chat.instructions : nil,
+        tools: chat.respond_to?(:tools) ? Array(chat.tools).map { |t| tool_schema(t) } : [],
+        messages: chat.respond_to?(:messages) ? Array(chat.messages) : []
+      )
+    end
+
+    # -> Hash: the JSON-safe schema of ONE tool. Reads `parameters` then
+    # `schema` (the two reader shapes the house FakeChat and the gem's tools
+    # answer); a tool answering none degrades to nil, never raises.
+    def self.tool_schema(tool)
+      params = if tool.respond_to?(:parameters)
+                 tool.parameters
+               elsif tool.respond_to?(:schema)
+                 tool.schema
+               end
+      {
+        "name" => (tool.name.to_s if tool.respond_to?(:name)),
+        "description" => (tool.description.to_s if tool.respond_to?(:description)),
+        "parameters" => params && json_safe(params)
+      }.compact
+    end
+
+    # -> JSON-safe projection of an arbitrary schema value. The gem's tools
+    # answer parameters as Hash with RubyLLM::Parameter values (a class whose
+    # readers are name/type/description/required) — the trace must persist the
+    # schema, so it projects that shape instead of raising on the object (the
+    # record never breaks the turn). Anything unprojectable degrades to its
+    # string form, never raises.
+    def self.json_safe(value)
+      case value
+      when Hash
+        value.each_with_object({}) { |(k, v), acc| acc[k.to_s] = json_safe(v) }
+      when Array
+        value.map { |v| json_safe(v) }
+      when String, Integer, Float, TrueClass, FalseClass, NilClass
+        value
+      else
+        if %i[name type description required].all? { |m| value.respond_to?(m) }
+          { "name" => value.name.to_s, "type" => value.type.to_s,
+            "description" => value.description.to_s, "required" => value.required }
+        elsif value.respond_to?(:to_h)
+          json_safe(value.to_h)
+        else
+          value.to_s
+        end
+      end
+    end
+
+    # The store round-trip: a plain Hash (string keys) -> ModelVisible.
+    def self.from_h(hash)
+      h = hash || {}
+      new(
+        instructions: h["instructions"],
+        tools: Array(h["tools"]),
+        messages: Array(h["messages"])
+      )
+    end
+
+    # JSON-safe (string keys), the shape the store persists.
+    def to_h
+      { "instructions" => instructions, "tools" => tools, "messages" => messages }
+    end
+  end
+end

data/lib/insika/model_visible_trace_store.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Insika
+  #   — the durable half of the conformance claim: what the model
+  # received, per (task, turn), captured at the RubyLLM boundary and persisted.
+  #
+  # One record per (task, turn, part) under the scope "model_visible_traces",
+  # key "model_visible:<task_id>:turn:<n>:<part>" — `part` separates the
+  # turn's own ask ("turn") from engine-internal asks that are model-visible
+  # too (the WS4 routing classifier, "routing").
+  #
+  # A TRACE, best-effort by construction: `record` rescues everything -> nil
+  # (a log must never break a turn — the house rule, tool_trace_store.rb).
+  # The record is an UPSERT by (task, turn, part): a resumed turn re-records
+  # its ask in place (the ContextTraceStore idiom), never duplicates.
+  class ModelVisibleTraceStore
+    SCOPE = "model_visible_traces"
+
+    def initialize(store:)
+      @store = store
+    end
+
+    # -> ModelVisible | nil (nil = the record failed — the turn proceeds).
+    def record(task_id:, turn:, part: "turn", payload:)
+      return nil if payload.nil?
+
+      @store.set(SCOPE, key(task_id, turn, part), payload.to_h)
+      payload
+    rescue StandardError
+      nil
+    end
+
+    # -> ModelVisible | nil.
+    def find(task_id, turn:, part: "turn")
+      raw = @store.get(SCOPE, key(task_id, turn, part))
+      raw && ModelVisible.from_h(raw)
+    end
+
+    # -> [ModelVisible] the task's records for `part`, ordered by turn.
+    def for_task(task_id, part: "turn")
+      @store.list(SCOPE, key_prefix(task_id)).filter_map do |k|
+        next unless k.end_with?(":#{part}")
+
+        n = k[/:turn:(\d+):/, 1]
+        n && [Integer(n), ModelVisible.from_h(@store.get(SCOPE, k))]
+      end.sort_by(&:first).map(&:last)
+    end
+
+    # Removes every record for a task (retention/LGPD). -> Integer (removed).
+    def purge(task_id)
+      keys = @store.list(SCOPE, key_prefix(task_id))
+      keys.each { |k| @store.delete(SCOPE, k) }
+      keys.size
+    end
+
+    private
+
+    def key(task_id, turn, part)
+      "model_visible:#{task_id}:turn:#{Integer(turn)}:#{part}"
+    end
+
+    def key_prefix(task_id)
+      "model_visible:#{task_id}:turn:"
+    end
+  end
+end

data/lib/insika/onboarding.rb

@@ -54,8 +54,13 @@ module Insika
       "observability" => "docs/OBSERVABILITY.md",
       "evals" => "docs/EVALS.md",
       "refinement" => "docs/REFINEMENT.md",
+      "facts" => "docs/FACTS.md",
+      "harvest" => "docs/HARVEST.md",
       "loadtest" => "docs/LOADTEST.md",
-      "releasing" => "docs/RELEASING.md"
+      "releasing" => "docs/RELEASING.md",
+      # the /v1 compatibility contract and the domain-free map.
+      "api" => "docs/API.md",
+      "domain" => "docs/domain.md"
     }.freeze
 
     # Repo-relative path to the start.md template.

data/lib/insika/outbox_store.rb

@@ -23,7 +23,7 @@ module Insika
   #               a third party that refused N times is an operator problem, not
   #               something to replay forever.
   #
-  # `failed` and `delivering` are a deliberate widening of the RFC's two-status
+  # `failed` and `delivering` are a deliberate widening of the two-status
   # sketch (`pending -> delivered`): without them a crashed claim and an
   # exhausted retry are indistinguishable from a fresh record, and the sweep
   # would redeliver both.
@@ -38,7 +38,7 @@ module Insika
 
     Delivery = Data.define(
       :id, :channel, :to, :task_id, :session_id, :payload,
-      :status, :attempts, :last_error, :created_at, :updated_at
+      :status, :attempts, :last_error, :index, :created_at, :updated_at
     )
 
     def initialize(store:)
@@ -47,7 +47,9 @@ module Insika
 
     # -> Delivery (:pending). `payload` is the body the channel will send; it is
     # DATA (string keys, JSON types) and the store never interprets it.
-    def create(channel:, to:, task_id:, session_id:, payload:, id: SecureRandom.uuid)
+    # `index`  is the balloon's position inside its turn — 0 for a
+    # plain `:at_end` delivery, written by a progressive flush.
+    def create(channel:, to:, task_id:, session_id:, payload:, index: 0, id: SecureRandom.uuid)
       record = {
         "id" => id.to_s,
         "channel" => channel.to_s,
@@ -58,6 +60,7 @@ module Insika
         "status" => "pending",
         "attempts" => 0,
         "last_error" => nil,
+        "index" => index.to_i,
         "created_at" => timestamp,
         "updated_at" => timestamp
       }
@@ -75,8 +78,12 @@ module Insika
     # `delivering`: that one was claimed by a process that then died, and whether
     # its POST landed is unknowable — replaying it is the duplicate the claim
     # exists to prevent.
+    #
+    # Ordered by [task_id, index] : a crashed progressive turn re-drives
+    # balloon 1 only after balloon 0, never the reverse.
     def pending
       scan.select { |d| d.status == :pending }
+          .sort_by { |d| [d.task_id.to_s, d.index] }
     end
 
     # pending -> delivering, ATOMICALLY — across processes, not just fibers: the
@@ -127,8 +134,38 @@ module Insika
       touch(id, record)
     end
 
+    # WS8 (LGPD): drops every delivery of these sessions, whatever its status.
+    # `payload` is the ANSWER as it was handed to the channel, so a purge that
+    # stops at the session record leaves the conversation readable here forever.
+    # -> count removed.
+    def purge_sessions(session_ids)
+      wanted = Array(session_ids).map(&:to_s)
+      return 0 if wanted.empty?
+
+      delete_where { |d| wanted.include?(d.session_id.to_s) }
+    end
+
+    # WS8 retention: deliveries created before the cutoff. TERMINAL ones only —
+    # a `pending`/`delivering` record older than the window is still somebody's
+    # undelivered answer, and the sweep is not the place to decide it is lost.
+    # -> count removed.
+    def delete_older_than(time)
+      cutoff = time.utc.iso8601
+      delete_where do |d|
+        %i[delivered failed].include?(d.status) && d.created_at.to_s < cutoff
+      end
+    end
+
     private
 
+    # The id list is SNAPSHOTTED before the deletes: `scan` enumerates the
+    # backend's keys lazily and deleting under it would skip records.
+    def delete_where(&match)
+      doomed = scan.select(&match)
+      doomed.each { |d| @store.delete(SCOPE, key_for(d.id)) }
+      doomed.size
+    end
+
     def scan
       return enum_for(:scan) unless block_given?
 
@@ -157,7 +194,8 @@ module Insika
         task_id: record["task_id"], session_id: record["session_id"],
         payload: record["payload"], status: record["status"].to_sym,
         attempts: record["attempts"].to_i, last_error: record["last_error"],
-        created_at: record["created_at"], updated_at: record["updated_at"]
+        index: record["index"].to_i, created_at: record["created_at"],
+        updated_at: record["updated_at"]
       )
     end