insika 0.2.0 → 0.7.0

data/lib/insika/proposal_store.rb

@@ -0,0 +1,271 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "time"
+
+module Insika
+  # the proposals and the two persisted mechanisms the gates
+  # on — the **latched dedup ledger** (D3: the rows themselves ARE the ledger —
+  # a dismissed/rejected tuple is never proposed again, and an unanswered
+  # proposal is not piled on) and the **per-session distilled marker** (D2:
+  # written only after a pass completes, so a crash mid-pass leaves the marker
+  # unwritten and the next pass re-scans). A dumb domain store — it holds no
+  # policy (which tuple is a fact is the distiller's job), no memory facts and
+  # no model. The scope string (the memory cell) is built by the callers from
+  # the   `MemoryStore::parse_cell` shape; the store keys by
+  # `(tenant, customer)` explicitly.
+  #
+  # Statuses: pending -> approved | rejected | dismissed | stale.
+  # `stale` is the CAS-lost re-present (E3): the proposal carries the fact's
+  # CURRENT value (`current_value`) next to the proposed one, never a silent
+  # overwrite.
+  class ProposalStore
+    SCOPE = "proposals"
+    STATUSES = %w[pending approved rejected dismissed stale].freeze
+    TERMINAL = %w[approved rejected dismissed].freeze
+    PROPOSAL_PREFIX = "p:"
+    MARKER_PREFIX = "s:"
+
+    Proposal = Data.define(:id, :tenant, :customer, :scope, :session_ref, :key,
+                           :value, :confidence, :status, :evidence,
+                           :expected_revision, :expected_existed, :current_value,
+                           :operator, :note, :created_at, :updated_at)
+
+    def initialize(store:)
+      @store = store
+    end
+
+    # -> Proposal (status :pending). The caller (RunDistillation) already ran
+    # the dedup checks; the store writes. `evidence` = message indexes; the
+    # revision baseline (D5) travels with the record.
+    #
+    # The tenant is stored VERBATIM — nil in a single-tenant deployment, so
+    # the scope is the bare `customer` cell and the approval reads/writes the
+    # SAME cell the Memory provider injects (memory_store.rb's
+    # blank-tenant + customer -> "memory:<customer>" rule). Coercing a blank
+    # tenant to a sentinel here would orphan every approved fact in a
+    # phantom "memory:platform:<customer>" cell.
+    def create(tenant:, customer:, session_ref:, key:, value:, confidence: nil,
+               evidence: [], expected_revision: nil, expected_existed: false,
+               id: SecureRandom.uuid, now: Time.now.utc)
+      tenant = tenant_key(tenant)
+      stamp = now.iso8601(6)
+      record = { "id" => id.to_s, "status" => "pending",
+                 "tenant" => tenant, "customer" => customer.to_s,
+                 "scope" => [tenant, customer.to_s].compact.join(":"),
+                 "session_ref" => session_ref.to_s, "key" => key.to_s,
+                 "value" => value.to_s, "confidence" => confidence,
+                 "evidence" => Array(evidence).map(&:to_i),
+                 "expected_revision" => expected_revision,
+                 "expected_existed" => !!expected_existed,
+                 "current_value" => nil, "operator" => nil, "note" => nil,
+                 "created_at" => stamp, "updated_at" => stamp }
+      @store.set(SCOPE, PROPOSAL_PREFIX + id.to_s, record)
+      to_proposal(record)
+    end
+
+    def find(id)
+      record = @store.get(SCOPE, PROPOSAL_PREFIX + id.to_s)
+      record && to_proposal(record)
+    end
+
+    # The wiki's lists. `pending` = pending, oldest first (the operator works
+    # the oldest proposal first — evidence ages).
+    def pending(limit: 100)
+      scan.select { |p| p.status == "pending" }
+          .sort_by { |p| [p.created_at.to_s, p.id] }
+          .first(limit)
+    end
+
+    def stale(limit: 50)
+      scan.select { |p| p.status == "stale" }
+          .sort_by { |p| p.updated_at.to_s }
+          .first(limit)
+    end
+
+    # The wiki's Recent list: every terminal status (approved/rejected/
+    # dismissed), most recent first — the operator's audit trail.
+    def resolved(limit: 20)
+      scan.select { |p| TERMINAL.include?(p.status) }
+          .sort_by { |p| p.updated_at.to_s }
+          .reverse
+          .first(limit)
+    end
+
+    # ---- the latched dedup (D3) ----
+    # true when a dismissed/rejected row exists for the exact tuple — the
+    # latch. Persisted rows ARE the ledger. A *different* value for the same
+    # `name` is a different tuple.
+    def decided?(tenant:, customer:, key:, value:)
+      scan.any? do |p|
+        tenant_key(p.tenant) == tenant_key(tenant) && p.customer == customer.to_s &&
+          p.key == key.to_s && p.value == value.to_s &&
+          %w[dismissed rejected].include?(p.status)
+      end
+    end
+
+    # true when a pending row exists for (scope, key) — no piling.
+    def open_pending?(tenant:, customer:, key:)
+      scan.any? do |p|
+        tenant_key(p.tenant) == tenant_key(tenant) && p.customer == customer.to_s &&
+          p.key == key.to_s && p.status == "pending"
+      end
+    end
+
+    # ---- transitions, each read-check-write on @store.transaction ----
+    # pending -> terminal. ArgumentError for a wrong source state (the
+    # task_store.rb state-machine idiom).
+    def approve(id:, operator: nil, note: nil, now: Time.now.utc)
+      transition(id, "approved", operator: operator, note: note, now: now)
+    end
+
+    def reject(id:, operator: nil, note: nil, now: Time.now.utc)
+      transition(id, "rejected", operator: operator, note: note, now: now)
+    end
+
+    def dismiss(id:, operator: nil, note: nil, now: Time.now.utc)
+      transition(id, "dismissed", operator: operator, note: note, now: now)
+    end
+
+    # pending -> stale, CAS lost; `current_value` = the fact as it stands (the
+    # re-present's second value, E3).
+    def mark_stale(id:, current_value:, operator: nil, now: Time.now.utc)
+      transition(id, "stale", operator: operator, current_value: current_value, now: now)
+    end
+
+    # ---- the per-session marker (D2) ----
+    # Written ONLY after a pass completes (RunDistillation). -> the marker hash.
+    def mark_distilled(session_ref, agent:, proposals:, dropped:, deduped: 0, cost: nil, now: Time.now.utc)
+      marker = { "session_ref" => session_ref.to_s, "agent" => agent.to_s,
+                 "distilled_at" => now.iso8601, "proposals" => proposals.to_i,
+                 "dropped" => dropped, "deduped" => deduped.to_i,
+                 "cost" => cost }
+      @store.set(SCOPE, MARKER_PREFIX + session_ref.to_s, marker)
+      marker
+    end
+
+    def distilled?(session_ref)
+      !@store.get(SCOPE, MARKER_PREFIX + session_ref.to_s).nil?
+    end
+
+    def distilled_sessions(agent_id = nil)
+      keys = agent_id ? marker_keys.select { |k| marker_agent(k) == agent_id.to_s } : marker_keys
+      keys.map { |k| k.delete_prefix(MARKER_PREFIX) }
+    end
+
+    # ---- LGPD / retention (C8) ----
+
+    # One customer's proposals, EVERY status. -> count removed.
+    def purge_customer(tenant:, customer:)
+      removed = 0
+      @store.transaction do
+        proposal_keys.each do |k|
+          record = @store.get(SCOPE, k)
+          next unless record && record["tenant"] == tenant_key(tenant)
+          next unless record["customer"] == customer.to_s
+
+          @store.delete(SCOPE, k)
+          removed += 1
+        end
+      end
+      removed
+    end
+
+    # A tenant's proposals. -> count removed.
+    def purge(tenant:)
+      removed = 0
+      @store.transaction do
+        proposal_keys.each do |k|
+          record = @store.get(SCOPE, k)
+          next unless record && record["tenant"] == tenant_key(tenant)
+
+          @store.delete(SCOPE, k)
+          removed += 1
+        end
+      end
+      removed
+    end
+
+    # Age-based prune (the retention sweep). TERMINAL rows age by their
+    # updated_at; a PENDING row is a zombie past the cutoff (its transcript is
+    # dead). Session MARKERS die WITH their proposals — a marker past the
+    # cutoff is evidence about a dead transcript (the session aged out under
+    # the same retention window), and keeping it would lock an unreviewed
+    # proposal out of re-distillation forever. -> count removed.
+    def delete_older_than(time)
+      cutoff = time.utc.iso8601
+      removed = 0
+      @store.transaction do
+        proposal_keys.each do |k|
+          record = @store.get(SCOPE, k)
+          next unless record
+
+          terminal = TERMINAL.include?(record["status"])
+          stamp = terminal ? record["updated_at"] : record["created_at"]
+          next unless stamp && stamp.to_s < cutoff
+
+          @store.delete(SCOPE, k)
+          removed += 1
+        end
+        marker_keys.each do |k|
+          marker = @store.get(SCOPE, k)
+          next unless marker && marker["distilled_at"].to_s < cutoff
+
+          @store.delete(SCOPE, k)
+          removed += 1
+        end
+      end
+      removed
+    end
+
+    private
+
+    def transition(id, to, operator: nil, note: nil, current_value: nil, now: Time.now.utc)
+      @store.transaction do
+        key = PROPOSAL_PREFIX + id.to_s
+        record = @store.get(SCOPE, key)
+        raise Insika::NotFoundError, "proposal not found: #{id}" if record.nil?
+
+        unless record["status"] == "pending"
+          raise ArgumentError,
+                "proposal #{id}: cannot resolve a #{record['status']} proposal — " \
+                "it resolves once, from pending"
+        end
+
+        record["status"] = to
+        record["operator"] = operator.to_s unless operator.nil?
+        record["note"] = note.to_s unless note.nil?
+        record["current_value"] = current_value unless current_value.nil?
+        record["updated_at"] = now.iso8601(6)
+        @store.set(SCOPE, key, record)
+        to_proposal(record)
+      end
+    end
+
+    def scan
+      proposal_keys.filter_map do |k|
+        record = @store.get(SCOPE, k)
+        record && to_proposal(record)
+      end
+    end
+
+    def proposal_keys = @store.list(SCOPE, PROPOSAL_PREFIX)
+    def marker_keys = @store.list(SCOPE, MARKER_PREFIX)
+
+    # nil stays nil (single-tenant); a present tenant is a String. The
+    # comparisons below use tenant_key on BOTH sides so nil == nil holds.
+    def tenant_key(tenant) = tenant.nil? ? nil : tenant.to_s
+
+    def to_proposal(rec)
+      Proposal.new(id: rec["id"], tenant: rec["tenant"], customer: rec["customer"],
+                   scope: rec["scope"], session_ref: rec["session_ref"],
+                   key: rec["key"], value: rec["value"], confidence: rec["confidence"],
+                   status: rec["status"], evidence: rec["evidence"] || [],
+                   expected_revision: rec["expected_revision"],
+                   expected_existed: rec["expected_existed"] == true,
+                   current_value: rec["current_value"], operator: rec["operator"],
+                   note: rec["note"], created_at: rec["created_at"],
+                   updated_at: rec["updated_at"])
+    end
+  end
+end

data/lib/insika/queue_policy.rb

@@ -85,7 +85,10 @@ module Insika
     def debounce? = @debounce_ms.positive?
 
     # Does this policy merge into a turn that has not started yet?
-    def collect? = @mode == :collect
+    # True for :collect AND :steer — both absorb fragments that land before the
+    # turn starts. Debounce is what actually holds them; without a window a steer
+    # agent still steers mid-run and never waits at the door.
+    def collect? = @mode == :collect || @mode == :steer
 
     # Does this policy append into a turn that is already running? `steer_max_messages`
     # of 0 is the agent saying no, so it answers false rather than steering once and

data/lib/insika/refinement/proposer.rb

@@ -214,7 +214,7 @@ module Insika
       end
 
       # `proposers` accepts either syntax — a bare ref ("deepseek/deepseek-v4-flash") or
-      # the RFC's `{ "model" =>, "provider"? => }` — because the two already coexist in
+      # the hash form `{ "model" =>, "provider"? => }` — because the two already coexist in
       # this config (`proposer` is a bare ref, `judges` are hashes) and refusing one of
       # them would only teach operators which page they were reading.
       def refs_for(config, utility_model)

data/lib/insika/reliability.rb

@@ -42,8 +42,12 @@ module Insika
     #
     # -> the successful response. Raises CircuitOpenError (primary open),
     # or the last retryable error when every node exhausted its retries.
+    # NOTHING about a run is stored on `self`: one Reliability instance serves
+    # every concurrent turn, and `ask` is a suspension point — an ivar written
+    # here would be read back after another fiber's turn overwrote it, and the
+    # WS6 alert would name the wrong agent (and, through it, the wrong tenant).
+    # The run's identity rides the stack.
     def call(policy:, tenant:, agent: nil, selection:, chain:, &attempt)
-      @agent = agent # event attribution (WF6 alerts) for THIS run
       nodes = ([selection] + Array(chain)).map { |node| { selection: node, tries: 0 } }
       retries = [policy["retries"].to_i, 0].max
       breaker = breaker_config(policy)
@@ -61,10 +65,21 @@ module Insika
       if breaker && breaker_open?(tenant, selection, breaker)
         raise circuit_open(tenant, selection, breaker)
       end
+      # the last node we actually ASKED: the `from` of a rotation. A node the
+      # breaker skipped was never asked, so it is never the `from`.
+      asked = nil
       nodes.each do |node|
         selection = node[:selection]
         next if breaker && breaker_open?(tenant, selection, breaker)
 
+        # ROTATION is an EVENT, not an inference from the usage attribution
+        # (WS3): the trace names the node we left, the node we moved to and why.
+        # Emitted for every node past the first one asked — with or WITHOUT a
+        # breaker (a fallback policy with no circuit_breaker used to rotate in
+        # complete silence).
+        emit_fallback(agent, asked, selection, last_error) if asked
+        asked = selection
+
         attempts = retries + 1
         attempts.times do |index|
           node[:tries] += 1
@@ -87,7 +102,7 @@ module Insika
             raise unless retryable
             raise if kind_of(e) == :fatal && !e.is_a?(Insika::TimeoutError)
 
-            record_failure(tenant, selection, breaker, e)
+            record_failure(tenant, selection, breaker, e, agent)
             # the last attempt of the last node re-raises; otherwise back off
             # and give the next attempt/node a turn.
             if index < attempts - 1 || node != nodes.last
@@ -127,17 +142,28 @@ module Insika
       )
     end
 
-    def record_failure(tenant, selection, breaker, error)
+    # The failure is ALWAYS an event; only the circuit bump needs a breaker (the
+    # old `return unless breaker` made a retry/fallback policy without a
+    # circuit_breaker run with no trace at all).
+    def record_failure(tenant, selection, breaker, error, agent)
+      emit(:provider_failure,
+           { agent: agent, ref: ref_of(selection), error: error.class.name, kind: kind_of(error) })
       return unless breaker
 
       tripped = @circuit_store.record_failure(
         tenant: tenant, ref: ref_of(selection),
         after: breaker[:after], within: breaker[:within]
       )
-      emit(:provider_failure,
-           { agent: @agent, ref: ref_of(selection), error: error.class.name, kind: kind_of(error) })
       # the failure that TRIPPED the circuit is itself an alert (WS6).
-      emit(:breaker_open, { agent: @agent, ref: ref_of(selection), tenant: tenant }) if tripped == :open
+      emit(:breaker_open, { agent: agent, ref: ref_of(selection), tenant: tenant }) if tripped == :open
+    end
+
+    # The mid-turn rotation across the fallback chain: the node we left, the one
+    # we moved to, and the error that spent the previous node's retries.
+    def emit_fallback(agent, from, to, error)
+      emit(:provider_fallback,
+           { agent: agent, from: ref_of(from), to: ref_of(to),
+             error: error&.class&.name, kind: error && kind_of(error) })
     end
 
     def kind_of(error) = ProviderErrorClassifier.classify(error).kind

data/lib/insika/retention.rb

@@ -0,0 +1,316 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  # WS8 (phase 2): retention — the engine forgets what is old enough to forget.
+  # Age-based purge of the CONVERSATION footprint: sessions (and their
+  # per-session tool/context traces), terminal tasks (and their checkpoints),
+  # customer/tenant memory cells and outcome records. The knob is data, not
+  # code: `settings.retention_days` (Integer; nil/0 = OFF — parity, nothing is
+  # ever swept by default).
+  #
+  # Cadence: the Tick calls `run` every pass; an internal DAILY claim (the
+  # tick's window idiom — one key, a timestamp, 24 h) makes the actual sweep
+  # once a day, so the O(n) scans never ride the 60 s loop. A sweep that
+  # crashes propagates to the tick, which logs and keeps ticking.
+  class Retention
+    SCOPE = "retention"
+    KEY = "claim"
+    BUDGET_KEY = "budget_claim"
+    # the MEMORY TTL's own daily claim. Deliberately NOT the age-based
+    # KEY — memory TTLs sweep on their own knob (`memory_ttl_days`), gated by
+    # neither retention_days nor the age-based claim (D5).
+    MEMORY_TTL_KEY = "memory_ttl_claim"
+    # the ARTIFACT TTL's own daily claim — same discipline as the memory TTL:
+    # reports expire on their own knob (`artifact_ttl_days`), never gated by
+    # retention_days (a deployment that keeps conversations forever must still
+    # expire the PII-carrying reports).
+    ARTIFACT_TTL_KEY = "artifact_ttl_claim"
+    WINDOW = 86_400 # one sweep per day, at most
+
+    TERMINAL = %w[completed failed cancelled].freeze
+
+    def initialize(session_store:, task_store:, checkpoint_store:,
+                   memory_store:, outcome_store:, tool_trace_store: nil,
+                   context_trace_store: nil, outbox_store: nil, shadow_pair_store: nil,
+                    settings_store: nil, budget_ledger: nil, funnel_store: nil,
+                    followup_store: nil, contact_store: nil, proposal_store: nil,
+                    model_visible_trace_store: nil,
+                     store:, window: WINDOW, now: nil, harvest_store: nil,
+                     artifact_store: nil)
+      @session_store = session_store
+      @task_store = task_store
+      @checkpoint_store = checkpoint_store
+      @memory_store = memory_store
+      @outcome_store = outcome_store
+      @tool_trace_store = tool_trace_store
+      @context_trace_store = context_trace_store
+      @model_visible_trace_store = model_visible_trace_store #  ; nil = parity
+      @outbox_store = outbox_store
+      @shadow_pair_store = shadow_pair_store
+      @settings_store = settings_store
+      @budget_ledger = budget_ledger # WS2 counter GC; nil = nothing to sweep
+      @funnel_store = funnel_store   #  ; nil = nothing to sweep
+      @followup_store = followup_store #  ; nil = nothing to sweep
+      @contact_store = contact_store   #  ; nil = nothing to sweep
+      @proposal_store = proposal_store #  ; nil = nothing to sweep
+      @store = store
+      @window = window
+      @now = now # injectable for specs (a deterministic "today")
+      @harvest_store = harvest_store #  ; nil = nothing to sweep
+      @artifact_store = artifact_store #  ; nil = nothing to sweep
+    end
+
+    # the sweep reads the memory store's cells/records (specs seed
+    # facts through it).
+    attr_reader :memory_store
+
+    # -> { claimed: false } |
+    #    { claimed: true, sessions:, tasks:, outcomes:, memory:, deliveries: }.
+    # Either shape may carry `budget_cells:` — the budget counter GC is NOT
+    # gated by retention_days (see #sweep_budget_cells). Either shape may carry
+    # `memory_ttl:` — the   memory TTL sweep, gated by ITS OWN daily
+    # claim and knob, never by retention_days (see #sweep_memory_ttl).
+    def run
+      budget_cells = sweep_budget_cells
+      memory_ttl = sweep_memory_ttl
+      artifacts = sweep_artifacts
+      days = retention_days
+      unless days.to_i.positive? && claim_window
+        summary = { claimed: false }
+        summary[:budget_cells] = budget_cells if budget_cells
+        summary[:memory_ttl] = memory_ttl if memory_ttl
+        summary[:artifacts] = artifacts if artifacts
+        return summary
+      end
+
+      cutoff = now - (days.to_i * 86_400)
+      summary = { claimed: true, sessions: sweep_sessions(cutoff),
+                  tasks: sweep_tasks(cutoff), outcomes: sweep_outcomes(cutoff),
+                  memory: @memory_store.prune_older_than(cutoff),
+                  deliveries: sweep_outbox(cutoff),
+                  pairs: sweep_shadow_pairs(cutoff) }
+      summary[:funnel] = sweep_funnel(cutoff) if @funnel_store
+      # the follow-up footprint ages out with the rest — records
+      # and contact cells under the SAME retention_days gate (nil collaborator
+      # = nothing to sweep, base graph parity).
+      summary[:followups] = @followup_store.delete_older_than(cutoff) if @followup_store
+      summary[:contacts] = @contact_store.delete_older_than(cutoff) if @contact_store
+      # proposals are evidence OF a transcript — when the
+      # transcript dies, the proposal's excerpt is gone and the pending fact is
+      # stale. Pending AND terminal rows age out together; a proposal is
+      # re-derivable (D2), so pruning is never data loss. The session MARKERS
+      # are never pruned (the store's rule — the marker is the claim).
+      summary[:proposals] = @proposal_store.delete_older_than(cutoff) if @proposal_store
+      # candidates (pending AND terminal), log rows and
+      # snapshots are DERIVED data of transcripts (D11) — when the transcripts
+      # die, the candidates' excerpts are gone; they are re-derivable (D2), so
+      # pruning is never data loss. The session markers are never pruned.
+      summary[:harvest] = @harvest_store.delete_older_than(cutoff) if @harvest_store
+      summary[:budget_cells] = budget_cells if budget_cells
+      summary[:memory_ttl] = memory_ttl if memory_ttl
+      summary[:artifacts] = artifacts if artifacts
+      summary
+    end
+
+    private
+
+    # The BudgetLedger's expired cells (WS2). Deliberately OUTSIDE the
+    # retention_days gate, on its OWN daily claim: those rows are engine
+    # bookkeeping whose window already rolled over, not customer content, so a
+    # deployment that keeps its conversations forever (retention OFF — the
+    # default) must still not grow budget rows forever. -> count | nil (no
+    # ledger, or another worker holds today's claim).
+    def sweep_budget_cells
+      return nil unless @budget_ledger && claim(BUDGET_KEY)
+
+      @budget_ledger.prune(now: now)
+    end
+
+    def retention_days
+      return nil unless @settings_store
+
+      value = @settings_store.get["retention_days"]
+      value.to_s.empty? ? nil : Integer(value)
+    rescue ArgumentError, TypeError
+      nil # a non-numeric value reads as OFF — never a crash at sweep time
+    end
+
+    # the memory TTL sweep — TWO independent expiry clocks under
+    # ONE daily claim:
+    #   1. per-fact expires_at (prune_expired — past dates physically removed);
+    #   2. per-cell TTL by `memory_ttl_days` (age by the cell's updated_at).
+    # A fact with an explicit expires_at is EXCLUDED from the age-based pass
+    # (the explicit override owns that fact's life). Runs on its OWN claim and
+    # knob — a deployment with retention_days off still honors memory TTLs.
+    # -> Integer (removed) | nil (no knob, or another worker holds the claim).
+    def sweep_memory_ttl
+      ttl = memory_ttl_setting
+      return nil if ttl.nil?
+      return nil unless claim(MEMORY_TTL_KEY)
+
+      removed = @memory_store.prune_expired(now)
+      ttl_cutoffs(ttl).each do |scope, cutoff|
+        removed += @memory_store.prune_older_than(cutoff, scope: scope)
+      end
+      removed
+    end
+
+    # settings["memory_ttl_days"]: Integer | Hash{ "<tenant>" => days, "*" => days }.
+    # nil/empty/blank -> nil (OFF — parity). A non-numeric value -> nil (never
+    # a crash at sweep time, the retention_days rescue pattern).
+    def memory_ttl_setting
+      return nil unless @settings_store
+
+      raw = @settings_store.get["memory_ttl_days"]
+      case raw
+      when Integer then raw
+      when Hash
+        map = raw.each_with_object({}) do |(k, v), acc|
+          acc[k.to_s] = Integer(v.to_s)
+        rescue ArgumentError, TypeError
+          next
+        end
+        map.empty? ? nil : map
+      end
+    end
+
+    # the artifact TTL sweep — the guarantee that PII inside a report expires
+    # even though no reader can see inside the opaque HTML. Its OWN daily
+    # claim + knob (`artifact_ttl_days` from settings; Integer; nil/absent =
+    # OFF), never gated by retention_days — a deployment that keeps its
+    # conversations forever must still expire the reports (the memory-TTL
+    # reasoning). -> Integer (removed) | nil (no knob, or the claim is held).
+    def sweep_artifacts
+      ttl = artifact_ttl_days
+      return nil if ttl.nil? || ttl <= 0
+      return nil unless claim(ARTIFACT_TTL_KEY)
+
+      @artifact_store.delete_older_than(now - ttl * 86_400)
+    end
+
+    # settings["artifact_ttl_days"]: Integer days. nil/blank/non-numeric -> nil
+    # (OFF — parity, never a crash at sweep time).
+    def artifact_ttl_days
+      return nil unless @settings_store
+
+      value = @settings_store.get["artifact_ttl_days"]
+      value.to_s.empty? ? nil : Integer(value)
+    rescue ArgumentError, TypeError
+      nil
+    end
+
+    # -> [[scope, Time]] — one per existing cell with a resolved TTL. The
+    # setting is passed in (one settings-store read per sweep — the caller
+    # already resolved it).
+    def ttl_cutoffs(setting = memory_ttl_setting)
+      return [] unless setting
+
+      @memory_store.cells.filter_map do |cell|
+        days = cell_ttl(cell, setting)
+        next if days.nil? || days <= 0
+
+        [cell[:scope], now - days * 86_400]
+      end
+    end
+
+    # Customer cell "memory:acme:c-1" -> map["acme"]; tenant/bare cell
+    # "memory:acme" or "memory:c-123" -> map["acme"] / map["c-123"]; fallback
+    # map["*"]; an Integer setting -> every cell gets it.
+    def cell_ttl(cell, setting)
+      return setting if setting.is_a?(Integer)
+
+      key = cell[:tenant] || cell[:customer]
+      v = key && setting[key]
+      v ||= setting["*"]
+      v
+    end
+
+    # Sessions untouched past the cutoff, and their per-session traces.
+    def sweep_sessions(cutoff)
+      removed = 0
+      @session_store.each_id.each do |id|
+        session = @session_store.find(id)
+        next unless session && session.updated_at && session.updated_at < cutoff.iso8601
+
+        @tool_trace_store&.clear(id)
+        @context_trace_store&.clear(id)
+        @session_store.delete(id)
+        removed += 1
+      end
+      removed
+    end
+
+    # TERMINAL tasks untouched past the cutoff, and their checkpoints. A
+    # non-terminal task (queued/running) is never touched here — the Recovery
+    # sweep owns those lives. the model-visible traces are
+    # transcripts — they die next to their checkpoints.
+    def sweep_tasks(cutoff)
+      removed = 0
+      @task_store.each_id.each do |id|
+        task = @task_store.find(id)
+        next unless task && TERMINAL.include?(task.status.to_s)
+        next unless task.updated_at && task.updated_at < cutoff.iso8601
+
+        @checkpoint_store.purge(id)
+        @model_visible_trace_store&.purge(id)
+        @task_store.delete(id)
+        removed += 1
+      end
+      removed
+    end
+
+    def sweep_outcomes(cutoff)
+      @outcome_store ? @outcome_store.delete_older_than(cutoff) : 0
+    end
+
+    # The delivered/failed outbox records past the cutoff. Their `payload` is
+    # the answer the customer received — conversation content, so it ages out
+    # with the rest of the footprint instead of living in the store forever.
+    def sweep_outbox(cutoff)
+      @outbox_store ? @outbox_store.delete_older_than(cutoff) : 0
+    end
+
+    # Shadow pairs  past the cutoff, TERMINAL statuses only
+    # (judged/incomplete) — an open/complete pair older than the window is
+    # still someone's unjudged evidence, exactly like the outbox's rule.
+    def sweep_shadow_pairs(cutoff)
+      @shadow_pair_store ? @shadow_pair_store.delete_older_than(cutoff) : 0
+    end
+
+    # the funnel DAY CELLS die with the outcomes they fold — same
+    # retention_days gate, same daily claim. Cursors/baselines live while their
+    # agent does. nil collaborator = nothing to sweep (base graph, parity).
+    def sweep_funnel(cutoff)
+      @funnel_store.delete_older_than(cutoff)
+    end
+
+    def claim_window = claim(KEY)
+
+    # The daily claim: one key, a timestamp, a 24 h window — the tick's
+    # claim_window idiom (a key per day would be a slow leak; the window is
+    # long enough that the store never grows). One key per SWEEP (the age-based
+    # one, the budget GC): they gate on different knobs, so a single shared key
+    # would let whichever ran first starve the other for a day.
+    def claim(key)
+      now_time = now
+      @store.transaction do
+        current = @store.get(SCOPE, key)
+        last = current && begin
+          Time.iso8601(current["claimed_at"].to_s)
+        rescue ArgumentError
+          nil
+        end
+        if last.nil? || (now_time - last) >= @window
+          @store.set(SCOPE, key, { "claimed_at" => now_time.iso8601 })
+          true
+        else
+          false
+        end
+      end
+    end
+
+    def now = @now || Time.now.utc
+  end
+end