insika 0.1.0 → 0.3.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/provider_error_classifier.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module Insika
+  # Classifies provider/transport failures by ACTION (B9). Four kinds —
+  # the hermes/openclaw structural rule: NON-retryable checked first, so an
+  # error we do not recognize defaults to :fatal (a retry would hammer a
+  # poisoned credential; a fatal is retried only after the operator fixes the
+  # cause):
+  #
+  #   :fatal              401/402/403/400 (auth, billing, permanent quota,
+  #                       bad request, context too long) — retrying does not help.
+  #   :retryable          5xx/529/socket/timeout — the same call may succeed
+  #                       moments later.
+  #   :rate_limited_short a 429 that says "back off briefly" (RPM-scale).
+  #   :rate_limited_long  a 429 with a long retry-after — quota-scale.
+  #
+  # The classification is STRING-based (class names, no constant references):
+  # the core loads without ruby_llm, and the smoke-shim's fake RubyLLM is a
+  # drop-in. `retry_after` is read from the provider's own Retry-After header
+  # when the error carries a response, else a per-kind default.
+  class ProviderErrorClassifier
+    Classification = Data.define(:kind, :retryable, :retry_after) do
+      # the additive envelope fields — compacted so a retry_after-less fatal
+      # never invents one.
+      def to_h
+        { kind: kind, retryable: retryable, retry_after: retry_after }.compact
+      end
+    end
+
+    KINDS = %i[fatal retryable rate_limited_short rate_limited_long].freeze
+
+    # Above this a 429 means quota, not RPM (this is what tells the two apart —
+    # a short 429 wants a quick retry; a long one is a billing event).
+    SHORT_RETRY_LIMIT = 60 # seconds
+
+    DEFAULTS = {
+      retryable: 5,
+      rate_limited_short: 10,
+      rate_limited_long: 300
+    }.freeze
+
+    # RubyLLM's taxonomy (error.rb), matched by class name so the core stays
+    # ruby_llm-free at load time.
+    FATAL_ERROR_NAMES = %w[
+      RubyLLM::ContextLengthExceededError RubyLLM::BadRequestError
+      RubyLLM::UnauthorizedError RubyLLM::PaymentRequiredError RubyLLM::ForbiddenError
+    ].freeze
+    RATE_LIMITED_ERROR_NAME = "RubyLLM::RateLimitError"
+    RETRYABLE_ERROR_NAMES = %w[
+      RubyLLM::ServerError RubyLLM::ServiceUnavailableError RubyLLM::OverloadedError
+    ].freeze
+    RUBY_LLM_ERROR_NAMES = (
+      FATAL_ERROR_NAMES + [RATE_LIMITED_ERROR_NAME] +
+      RETRYABLE_ERROR_NAMES + ["RubyLLM::Error"]
+    ).freeze
+
+    # Transport failures while talking to the provider: connection
+    # refused/reset, DNS, TLS, timeouts (Faraday wraps its own names; the
+    # stdlib ones surface from raw sockets).
+    TRANSPORT_NAME_PATTERNS = [
+      /\AFaraday::/,
+      /\ASocketError\z/,
+      /\AIOError\z/,
+      /\AErrno::/,
+      /\ANet::(Read|Open)Timeout\z/,
+      /\ATimeout::Error\z/,
+      /\AOpenSSL::SSL::SSLError\z/
+    ].freeze
+
+    class << self
+      # -> Classification
+      def classify(error)
+        names = class_names(error)
+
+        # Non-retryable first (the structural rule): a known fatal is NEVER
+        # retried, and an unknown error defaults to fatal — never to retry.
+        return fatal if (names & FATAL_ERROR_NAMES).any?
+
+        return rate_limited(error) if names.include?(RATE_LIMITED_ERROR_NAME)
+
+        return retryable if (names & RETRYABLE_ERROR_NAMES).any?
+        return retryable if transport?(names)
+
+        # A generic RubyLLM::Error (or a raw HTTP error) still carries the
+        # status: 429 and 5xx are retryable regardless of the wrapping class.
+        case http_status(error)
+        when 429      then rate_limited(error)
+        when 500..599 then retryable
+        else fatal
+        end
+      end
+
+      # True when the error came from the provider call itself (RubyLLM
+      # family or transport) — the executor routes these to the :ruby_llm
+      # stage with a wrapped classification instead of :unknown.
+      def provider_error?(error)
+        names = class_names(error)
+        (names & RUBY_LLM_ERROR_NAMES).any? || transport?(names)
+      end
+
+      # The typed ProviderError the executor stores and emits.
+      def wrap(error)
+        c = classify(error)
+        Insika::ProviderError.new(
+          error.message || error.class.name,
+          kind: c.kind, retryable: c.retryable, retry_after: c.retry_after
+        )
+      end
+
+      private
+
+      def fatal
+        Classification.new(kind: :fatal, retryable: false, retry_after: nil)
+      end
+
+      def retryable
+        Classification.new(kind: :retryable, retryable: true,
+                           retry_after: DEFAULTS[:retryable])
+      end
+
+      def rate_limited(error)
+        ra = retry_after_header(error)
+        if ra && ra > SHORT_RETRY_LIMIT
+          Classification.new(kind: :rate_limited_long, retryable: true, retry_after: ra)
+        else
+          Classification.new(kind: :rate_limited_short, retryable: true,
+                             retry_after: ra || DEFAULTS[:rate_limited_short])
+        end
+      end
+
+      def class_names(error)
+        ([error.class.name] + Array(error.class.ancestors).map(&:name)).compact
+      end
+
+      def transport?(names)
+        names.any? { |n| TRANSPORT_NAME_PATTERNS.any? { |p| p.match?(n) } }
+      end
+
+      # The provider's own Retry-After (seconds), when the error carries a
+      # response. All access guarded — a bare double must not raise.
+      def retry_after_header(error)
+        headers = response_headers(error)
+        value = headers && (headers["retry-after"] || headers["Retry-After"])
+        value = value.to_s.strip
+        value.match?(/\A\d+\z/) ? value.to_i : nil
+      end
+
+      def http_status(error)
+        response = error.respond_to?(:response) ? error.response : nil
+        status = response && response.respond_to?(:status) ? response.status : nil
+        status&.to_i
+      end
+
+      def response_headers(error)
+        response = error.respond_to?(:response) ? error.response : nil
+        response && response.respond_to?(:headers) ? response.headers : nil
+      end
+    end
+  end
+end

data/lib/insika/queue_policy.rb

@@ -3,7 +3,7 @@
 require_relative "coercion"
 
 module Insika
-  # RFC-0015 §4 — what happens to an inbound message for a session that is ALREADY
+  # what happens to an inbound message for a session that is ALREADY
   # busy. Today the engine has exactly one answer, "it waits in line"; this names
   # that answer `followup` and adds three others:
   #
@@ -32,7 +32,7 @@ module Insika
   # `turn_timeout` because they are bounds on the same thing — how much work one
   # turn is allowed to absorb.
   class QueuePolicy
-    # All four of RFC-0015 are delivered, so there is no "specified but unshipped"
+    # All four of are delivered, so there is no "specified but unshipped"
     # tier any more — a mode outside this set is a typo, and it is refused rather than
     # approximated. Treating an unknown mode as `followup` would look exactly like a
     # mode that never fires.
@@ -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/recovery.rb

@@ -17,7 +17,7 @@ module Insika
   class Recovery
     SWEEP_SCOPE = "recovery"
 
-    # The per-boot-generation sweep claim (RFC-0016 E2). N workers share one
+    # The per-boot-generation sweep claim. N workers share one
     # store, and the sweep's "orphaned :running" test is per-process: a worker
     # booting while a sibling holds a live turn would see it as an orphan and
     # re-run it. So the TASK sweep runs once per boot generation — the first
@@ -52,27 +52,59 @@ module Insika
     # -> { resumed: [ids], failed: [ids] }
     # The initial sweep runs OUTSIDE the per-task rescue: a StoreError here
     # aborts the boot.
-    def run
+    #
+    # stale_after (seconds): the periodic tick's semantics instead of
+    # boot's. Only :queued/:running tasks untouched for longer than that are
+    # candidates — :waiting/:paused are idle by nature (a human wait), so
+    # staleness cannot tell a live one from a dead one, and they stay boot
+    # recovery's. The threshold exists because a live :running turn is bounded
+    # by turn_timeout: anything older cannot be alive.
+    def run(stale_after: nil)
       resumed = []
       failed = []
       # Ordered by created_at: tasks from the SAME session are reprocessed
       # in their original order. Global time ordering is harmless for standalone tasks.
-      # 1) interrupted (crash mid-flight) -> resume from the checkpoint.
-      @task_store.running_or_interrupted.sort_by(&:created_at).each { |task| process(task, resumed, failed) }
+      # 1) interrupted (crash mid-flight) -> resume from the checkpoint. Tick mode
+      #    narrows this to :running — the only mid-flight state staleness can judge.
+      running = stale_after ? @task_store.with_status(:running) : @task_store.running_or_interrupted
+      sweep(running, stale_after).each { |task| process(task, resumed, failed, tick: !stale_after.nil?) }
       # 2) queued but never started (turn in the SessionActor queue at crash time)
       #    -> re-run from scratch (the same resume_task handles :queued). Without
       #    this, a :queued turn in the volatile queue would be lost on kill -9.
-      @task_store.queued.sort_by(&:created_at).each { |task| process(task, resumed, failed) }
+      sweep(@task_store.queued, stale_after).each { |task| process(task, resumed, failed, tick: !stale_after.nil?) }
       log(:info, "recovery finished: #{resumed.size} resumed, #{failed.size} failed")
       { resumed: resumed, failed: failed }
     end
 
     private
 
+    # Boot mode (stale_after nil) takes the candidate list as-is; tick mode keeps
+    # only tasks untouched past the threshold — the liveness gate of.
+    def sweep(tasks, stale_after)
+      tasks = tasks.sort_by(&:created_at)
+      return tasks unless stale_after
+
+      cutoff = Time.now.utc - stale_after
+      tasks.select { |task| stale?(task, cutoff) }
+    end
+
+    def stale?(task, cutoff)
+      Time.iso8601(task.updated_at.to_s) < cutoff
+    rescue ArgumentError
+      true # an unreadable timestamp is not proof of life — treat as stale
+    end
+
     # Failing to resume ONE task does not bring down the boot: a non-store
     # dispatch/latest error -> mark :failed and continue. StoreError -> propagate
     # (aborts the boot).
-    def process(task, resumed, failed)
+    #
+    # tick: true flips ONE rescue: a ValidationError from the dispatch
+    # is ResumeTask's local liveness check ("task is running") — someone alive
+    # owns it, the normal case on a timer, so the task is SKIPPED for the next
+    # tick. At boot a ValidationError means corruption (nothing may be alive),
+    # so it still fails the task there. This is the trap defused in-process:
+    # the tick must never murder a live turn with its own recovery.
+    def process(task, resumed, failed, tick: false)
       # :queued never started (no checkpoint) but IS recoverable — ResumeTask
       # re-runs from the Command. An interrupted task requires a checkpoint;
       # without one, it is unrecoverable.
@@ -88,6 +120,15 @@ module Insika
       end
     rescue Insika::StoreError
       raise
+    rescue Insika::ValidationError => e
+      # Boot keeps the old contract (corruption -> :failed); the tick skips.
+      if tick
+        log(:info, "skipped (alive elsewhere): #{task.id} — #{e.message}")
+      else
+        fail_task(task.id, class_name: e.class.name, message: e.message, stage: "recovery")
+        failed << task.id unless failed.include?(task.id)
+        log(:warn, "failed to resume #{task.id}: #{e.class}: #{e.message}")
+      end
     rescue StandardError => e
       fail_task(task.id, class_name: e.class.name, message: e.message, stage: "recovery")
       failed << task.id unless failed.include?(task.id)

data/lib/insika/refinement/candidate.rb

@@ -4,7 +4,7 @@ require "securerandom"
 
 module Insika
   module Refinement
-    # ONE proposed change to an agent's instruction files (RFC-0013 §3.4). Data, not
+    # ONE proposed change to an agent's instruction files. Data, not
     # a diff of free text, and that is the load-bearing decision of the whole phase:
     #
     #   · an ANCHORED edit is reviewable — the operator reads three lines, not a
@@ -40,7 +40,7 @@ module Insika
 
     # A dropped edit and why. Kept ON the candidate rather than logged: "the model
     # proposed four things and one was stale" is exactly what an operator reviewing
-    # the loop's usefulness needs, and §10 asks them to judge precisely that.
+    # the loop's usefulness needs, and asks them to judge precisely that.
     Dropped = Data.define(:file, :op, :reason) do
       def to_h = { "file" => file, "op" => op, "reason" => reason }
     end
@@ -63,7 +63,7 @@ module Insika
                    "edits" => edits.map(&:to_h), "dropped" => dropped.map(&:to_h) }
     end
 
-    # The bounds, all config (§3.4). Defaults are deliberately small: what makes a
+    # The bounds, all config. Defaults are deliberately small: what makes a
     # diff reviewable is that it is short, and what keeps the gate's signal readable
     # is that a run changed few things.
     DEFAULT_LIMITS = { "max_edits" => 3, "max_bytes" => 1200, "max_total_growth" => 0.15 }.freeze
@@ -75,7 +75,7 @@ module Insika
 
       # raw:       { "proposer" =>, "rationale" =>, "edits" => [ … ] } (string keys)
       # allowlist: the agent's `refinement.files`. EMPTY MEANS NOTHING IS WRITABLE —
-      #            report-only (§3.1/§3.8), so every edit drops. Not "no restriction":
+      #            report-only, so every edit drops. Not "no restriction":
       #            an unset allowlist that meant "anything" would turn a missing
       #            config into the most permissive setting there is.
       # contents:  name => current content, for staleness and growth.

data/lib/insika/refinement/evidence_collector.rb

@@ -5,7 +5,7 @@ require "time"
 
 module Insika
   module Refinement
-    # RFC-0013 phase A. Reads a window of an agent's real traffic and emits RANKED
+    # Reads a window of an agent's real traffic and emits RANKED
     # FINDINGS — "here is what broke, how often, and in which conversations". No
     # model runs here and nothing is written to the agent: this is the evidence half
     # of the loop, and it is deliberately useful on its own.
@@ -17,7 +17,7 @@ module Insika
     #   ToolTraceStore  — per-session tool calls with ok/args/result (already masked
     #                     and clipped by the store itself)
     #
-    # Two signals of RFC-0013 §3.3 are NOT computed here, and that is a finding about
+    # Two signals of are NOT computed here, and that is a finding about
     # the engine rather than about an agent: guardrail decisions and edge-limit hits
     # are emitted as EVENTS and never persisted, so the only durable footprint they
     # leave is the canned safe reply in the transcript — which is exactly what the
@@ -42,7 +42,7 @@ module Insika
       # result delivered as a new turn — is persisted with `role: user` like any
       # other, because it is what the model saw. Counting those as the customer
       # repeating themselves turned the first production run into 219 false positives,
-      # every one of them the engine reading its own `<cacau_cep_obrigatorio>` back.
+      # every one of them the engine reading its own `<store_cep_required>` back.
       #
       # `MessageOrigin` is the structural answer and is preferred whenever a message
       # carries it. This regex stays for everything written before that field existed
@@ -188,12 +188,12 @@ module Insika
       # of an instruction the agent is not following. Heuristic on purpose (token overlap,
       # no model call); the snippet is PII-redacted.
       #
-      # "After the agent answered" is the load-bearing half, and RFC-0015 is what forced
+      # "After the agent answered" is the load-bearing half, and is what forced
       # it to be said out loud. Two customer messages in a row is now ORDINARY: `collect`
       # merges the fragments a person types into one turn and `steer` appends one into a
       # run in flight, so a turn legitimately holds two of them. Someone still typing is
       # not someone repeating themselves — and a steered message cannot be told apart in
-      # the transcript, because it correctly declares no origin (§7). The structure is the
+      # the transcript, because it correctly declares no origin. The structure is the
       # only honest signal: a reply has to sit between the two.
       def repetition_findings(session_ids)
         hits = session_ids.flat_map do |sid|
@@ -320,7 +320,7 @@ module Insika
 
       def words(text) = text.to_s.downcase.scan(/[[:alnum:]]+/).uniq
 
-      # Every reply the deployment may emit INSTEAD of a real answer: the RFC-0009
+      # Every reply the deployment may emit INSTEAD of a real answer: the
       # defaults, the agent's own overrides, and the edge limiter's reply (per-agent
       # first, then the platform setting).
       def canned_replies(profile)