insika 0.1.0 → 0.3.0

data/lib/insika/outbox_store.rb

@@ -4,11 +4,11 @@ require "securerandom"
 require "time"
 
 module Insika
-  # Durable record of one pending OUTBOUND reply (RFC-0011 §6.5). A Shape B
+  # Durable record of one pending OUTBOUND reply. A Shape B
   # channel answers out of band — the turn ends and the reply is POSTed to the
   # platform (or, for a relay, to the consumer's own callback) afterwards — so
   # "the answer exists but the recipient is not on this connection" is exactly
-  # the problem RFC-0010 Phase 2 already solved for async delegation. This store
+  # the problem already solved for async delegation. This store
   # is DelegationStore's shape with a different recipient, deliberately: a second
   # invention here would be a second thing to get wrong.
   #
@@ -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
 

data/lib/insika/outcome_store.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "time"
+
+module Insika
+  # WS7: business outcomes over real traffic, recorded per conversation by the
+  # OPERATOR or the integration (`POST /v1/outcomes`) — `conversion`,
+  # `escalation`, `deflected`, … optionally with a monetary `value`. The engine
+  # TRANSPORTS the outcome and never interprets it (the same rule as alerts):
+  # what "conversion" means is the operator's. Durable in the KV backend,
+  # tenant-scoped (WS1) — a tenant can only ever read/write its own cells (the
+  # key carries the tenant, and the read methods narrow on it).
+  #
+  # The Studio's scorecard is the consumer: the LAST outcome per agent as a
+  # pill on the grid, and the per-day series on the agent detail — both fed
+  # from the same store, no scheduler.
+  class OutcomeStore
+    SCOPE = "outcomes"
+
+    Record = Data.define(:id, :tenant, :agent, :session_id, :outcome, :value, :at)
+
+    def initialize(store:)
+      @store = store
+    end
+
+    # -> Record. `at` defaults to now (UTC); `value` defaults to 0.0 (an
+    # outcome without a value is a unit outcome).
+    def create(tenant:, agent:, session_id: nil, outcome:, value: nil, id: SecureRandom.uuid, at: Time.now.utc)
+      time = at.utc
+      record = { "id" => id, "tenant" => tenant.to_s, "agent" => agent.to_s,
+                 "session_id" => session_id.to_s, "outcome" => outcome.to_s,
+                 "value" => value.to_f, "at" => time.iso8601 }
+      @store.set(SCOPE, key(tenant, agent, time, id), record)
+      to_record(record)
+    end
+
+    # All records, NEWEST first. `tenant:` narrows to one tenant's (WS1 — the
+    # read path a tenant query uses); `agent:` narrows further. An outcome is a
+    # fact, never a secret: the fields are ids, an outcome name and a number.
+    # NOTE: `tenant: nil` means NO filter — the record's tenant field is
+    # `tenant.to_s` ("" for a single-tenant write), so a caller that wants only
+    # the no-tenant records must pass `tenant: ""` explicitly (the FOLD uses
+    # `for_pair`, never this nil-means-everything trap).
+    def all(tenant: nil, agent: nil)
+      records = @store.list(SCOPE).filter_map { |k| to_record(@store.get(SCOPE, k)) }
+      records.select! { |r| r.tenant == tenant } if tenant
+      records.select! { |r| r.agent == agent } if agent
+      records.sort_by(&:at).reverse
+    end
+
+    # the fold's per-pair read — one KEY-prefix scan (the key IS
+    # tenant:agent:YYYY-MM-DD:id, WS1), optionally skipping the keys older than
+    # an ISO date WITHOUT reading them (the fold's cursor day — everything
+    # before it is already folded). `tenant:` takes either spelling (nil/""
+    # and "platform" all mean the no-tenant key segment). -> [Record].
+    def for_pair(tenant:, agent:, since_date: nil)
+      prefix = "#{key_tenant(tenant)}:#{agent}:"
+      keys = @store.list(SCOPE).select { |k| k.start_with?(prefix) }
+      keys.select! { |k| date_segment(k) >= since_date } if since_date
+      keys.filter_map { |k| to_record(@store.get(SCOPE, k)) }
+    end
+
+    # the distinct (tenant, agent) pairs present in the store —
+    # one key scan, no record reads. `tenant` is nil for the no-tenant segment
+    # (the FunnelStore#pairs spelling; every key-based API normalizes it back).
+    # -> [{ tenant: String | nil, agent: String }]
+    def pairs
+      @store.list(SCOPE).map { |k| pair_of(k) }.uniq
+    end
+
+    # -> { agent => { outcome:, value:, at:, session_id: } }: the LAST outcome
+    # per agent — the Studio's scorecard state card. A map so the agent grid
+    # looks up in O(1) per card.
+    def latest_per_agent(tenant: nil)
+      all(tenant: tenant).each_with_object({}) do |r, acc|
+        acc[r.agent] ||= { outcome: r.outcome, value: r.value, at: r.at,
+                           session_id: r.session_id }
+      end
+    end
+
+    # -> { "YYYY-MM-DD" => { outcome => { count:, value: } } } — per-period
+    # series for the Studio. `period: :month` buckets by "YYYY-MM".
+    def series(tenant: nil, agent: nil, period: :day)
+      all(tenant: tenant, agent: agent).each_with_object({}) do |r, acc|
+        bucket = period == :month ? r.at[0, 7] : r.at[0, 10]
+        cell = ((acc[bucket] ||= {})[r.outcome] ||= { count: 0, value: 0.0 })
+        cell[:count] += 1
+        cell[:value] += r.value
+      end
+    end
+
+    # Purges a tenant's records (WS8 phase 2 — delete_tenant_data). The tenant
+    # is the FIRST key segment, so the purge is a prefix scan — the key IS the
+    # isolation (WS1). -> count removed.
+    def purge(tenant:)
+      prefix = "#{tenant}:"
+      keys = @store.list(SCOPE).select { |k| k.start_with?(prefix) }
+      keys.each { |k| @store.delete(SCOPE, k) }
+      keys.size
+    end
+
+    # Purges records older than the cutoff (WS8 retention — the tick's sweep).
+    # `at` is ISO8601 UTC, so the comparison is lexicographic. -> count removed.
+    def delete_older_than(time)
+      cutoff = time.utc.iso8601
+      removed = 0
+      @store.list(SCOPE).each do |k|
+        rec = @store.get(SCOPE, k)
+        next unless rec && rec["at"].to_s < cutoff
+
+        @store.delete(SCOPE, k)
+        removed += 1
+      end
+      removed
+    end
+
+    private
+
+    def key_tenant(tenant) = tenant.to_s.empty? ? "platform" : tenant.to_s
+
+    # The date segment of the key (the 3rd segment, 0-indexed: 2).
+    def date_segment(k) = k.split(":").fetch(2, "")
+
+    # Parses the key's tenant segment back: "platform" -> nil (the
+    # FunnelStore#pairs spelling); anything else stays.
+    def pair_of(k)
+      tenant, agent, = k.split(":")
+      { tenant: tenant == "platform" ? nil : tenant, agent: agent }
+    end
+
+    def key(tenant, agent, time, id)
+      # tenant + agent + UTC date prefix: per-period / per-agent listing is a
+      # prefix scan, and the tenant IS the first segment — WS1 isolation is the
+      # key itself, like the session namespace.
+      "#{(tenant || 'platform')}:#{agent}:#{time.strftime('%Y-%m-%d')}:#{id}"
+    end
+
+    def to_record(rec)
+      return nil if rec.nil?
+
+      Record.new(id: rec["id"], tenant: rec["tenant"], agent: rec["agent"],
+                 session_id: rec["session_id"], outcome: rec["outcome"],
+                 value: rec["value"].to_f, at: rec["at"])
+    end
+  end
+end

data/lib/insika/overlay_tool_registry.rb

@@ -3,17 +3,16 @@
 module Insika
   # DYNAMIC tool registry: composes the CODE registry (base, built at boot,
   # immutable) with the DATA-DEFINED tools from the ToolStore. Drop-in for ToolRegistry —
-  # the Executor/ToolCatalog/ToolEnvelope only use entries/resolve/side_effect?. Phase 5,
-  # Step B / D2.
+  # the Executor/ToolCatalog/ToolEnvelope only use entries/resolve/side_effect?.,
   #
   # Rules:
   #   - COLLISION: the base (code) ALWAYS wins — a data-tool cannot hijack
   #     the name of a code tool (security, R3). The authoring Command also
   #     refuses to create with a colliding name (code_tool?), but the defense stays here.
   #   - HOT: `reload` re-reads the store and swaps the dynamic index atomically — a
-  #     new/edited data-tool takes effect on the next turn without a restart (F5), mirroring
+  #     new/edited data-tool takes effect on the next turn without a restart, mirroring
   #     SkillCatalog.reload. An in-flight turn has already captured the index.
-  #   - PARITY (NF1): empty ToolStore ⇒ entries/resolve/side_effect? identical to the
+  # PARITY: empty ToolStore ⇒ entries/resolve/side_effect? identical to the
   #     pure base. The base (config/wiring.rb) does not even use the overlay — zero regression.
   #
   # The data-tools enter as NORMAL Registry::Entry (optional: false) — they obey

data/lib/insika/pack.rb

@@ -3,11 +3,11 @@
 require "json"
 
 module Insika
-  # Provisioning pack (Phase 6/D4/F6): the PORTABLE form of an agent — a
+  # Provisioning pack: the PORTABLE form of an agent — a
   # manifest + the prompt files + the skills + the data-tool defs. It's what
   # `docs/prompt-base/06` describes as a workspace, here in a value object
   # consumable by the PackImporter (which emits the authoring Commands). GENERIC
-  # per project (NF1): the engine doesn't know achei-b2b — the pack is the contract.
+  # per project: the engine doesn't know any consumer — the pack is the contract.
   #
   #   config: Hash — manifest (AgentProfile.build attrs: id/model/provider/
   #           limits/metadata/tools_deferred/…). `id`/`model` required there.
@@ -16,7 +16,7 @@ module Insika
   #   skills: { "escalation-to-human" => "<SKILL.md>", ... } — 1 per skill.
   #   tools:  [ { ToolDefinition hash }, ... ] — the pack's data-tool defs.
   #
-  # Two sources: `from_h` (GatewayClient JSON — provisioning API, task 8) and
+  # Two sources: `from_h` (GatewayClient JSON — provisioning API) and
   # `from_dir` (a folder on disk per docs/prompt-base/06 — authoring/CLI).
   Pack = Data.define(:config, :files, :skills, :tools) do
     # Raw Hash (string|symbol keys) -> Pack. Tolerates both key conventions

data/lib/insika/pack_importer.rb

@@ -1,15 +1,15 @@
 # frozen_string_literal: true
 
 module Insika
-  # Pack importer (Phase 6/D4/F6, task 7): reads a Pack and emits the ALREADY
+  # Pack importer: reads a Pack and emits the ALREADY
   # existing authoring Commands — create_agent/update_agent + write_agent_file +
   # write_skill + write_data_tool — making an agent provisionable at runtime from
-  # a standardized pack. It's the piece that achei-b2b's `GatewayClient`/
-  # `ProvisionStore` triggers (via the provisioning API, task 8).
+  # a standardized pack. It's the piece a consumer's provisioning client
+  # triggers (via the provisioning API).
   #
-  # GENERIC (NF1): nothing here mentions achei-b2b — the pack is the contract. Tool
+  # GENERIC: nothing here mentions a consumer — the pack is the contract. Tool
   # names come from the PACK, so prompts<->tools stay consistent by construction
-  # (NF2). It doesn't write to the store directly: it only dispatches Commands on
+  # It doesn't write to the store directly: it only dispatches Commands on
   # the bus (the same transport discipline) + READS the ProfileSource to decide
   # create vs update.
   #
@@ -58,13 +58,15 @@ module Insika
     # its OWN pack (per-store isolation) and re-provisioning removes what left.
     #   - prompt_files = the pack's .md files (write_agent_file also registers;
     #     union is a no-op). Setting here makes the list authoritative (removes the ones that left).
-    #   - skills = the pack's skills/ dirs (explicit allowlist; [] if none in the
-    #     pack and config didn't declare any — never nil=all, which would leak
-    #     skills from other stores).
+    #   - skills = the pack's skills/ dirs (explicit allowlist; [] when the pack
+    #     has none — never nil=all, which would leak skills from other stores).
     #   - tools_allow = (config.tools_allow) ∪ (the pack's tool names) — guarantees
-    #     the agent can call its own data-tools (NF2).
+    #     the agent can call its own data-tools. [] when neither exists —
+    #     never nil=all: the ToolStore is GLOBAL, so a tool-less pack would
+    #     otherwise see every other store's tools (store A's pack calling
+    #     store B's set_location is exactly that leak).
     #   - tools_allow_groups = groups enabled by FLAG in the pack (see
-    #     #enabled_groups) — the per-flag schema CUT (Phase 7, Stage E / D5): only
+    #     #enabled_groups) — the per-flag schema CUT: only
     #     the tools of the enabled groups (union with tools_allow) go to the model;
     #     those of disabled groups are cut BEFORE the turn (resolves the OpenClaw
     #     tool-call waste, where the flag only exists in Rails).
@@ -72,24 +74,24 @@ module Insika
       attrs = pack.config.dup
       attrs[:id] = id
       attrs[:prompt_files] = pack.files.keys unless pack.files.empty?
-      attrs[:skills] = pack.skills.keys if pack.skills.any? || pack.config.key?(:skills)
+      attrs[:skills] = pack.skills.keys
 
       pack_tools = pack.tools.map { |t| tool_name(t) }
       allow = Array(pack.config[:tools_allow]).map(&:to_s) | pack_tools
-      attrs[:tools_allow] = allow unless allow.empty? && !pack.config.key?(:tools_allow)
+      attrs[:tools_allow] = allow
 
       groups = enabled_groups(pack.config)
       attrs[:tools_allow_groups] = groups unless groups.nil?
       attrs
     end
 
-    # PER-FLAG CUT (Phase 7, Stage E / D5, STATIC pilot): derives the agent's
+    # PER-FLAG CUT (/, STATIC pilot): derives the agent's
     # per-group allowlist from FLAGS declared in the pack config — DATA, never a
-    # core convention (NF1). The engine doesn't know "groceries_v2"/"b2b": the pack
+    # core convention. The engine doesn't know "groceries_v2"/"b2b": the pack
     # declares which GROUPS are enabled; the flag->group mapping is the
     # responsibility of provisioning/the pack, not the insika. Two forms (union):
     #   - `enabled_groups: ["default", "b2b"]`  — explicit list of ON groups.
-    #   - `flags: { "b2b" => true, "natura" => false }` — the flag key IS the group
+    #   - `flags: { "wholesale" => true, "outlet" => false }` — the flag key IS the group
     #     name; only the truthy ones enter (the false ones CUT the group).
     # Neither declared -> nil (no per-group cut; old behavior).
     # Explicit `[]` (empty enabled_groups, or all flags false) -> no group.

data/lib/insika/packaging.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module Insika
+  # The single source of the gem payload selection. The
+  # gemspec and the domain-boundary audit spec call THE SAME function, so
+  # "what ships in the gem" is a fact the suite asserts on, never a prose
+  # promise: `git ls-files` (fallback: a glob where there is no .git) filtered
+  # to lib/ + docs/ + the four root files, minus the never-ship set.
+  #
+  # Pure and dependency-free (no git gem, no FileUtils beyond reads) so both
+  # the gemspec (built outside the app) and the spec can load it. It does NOT
+  # ship anything itself — it answers a list.
+  #
+  # `domain_content?` is the audit's yardstick: best-effort detection of pt-BR
+  # domain content in a payload file. Ruby files are scanned for their string
+  # literals, regex literals and heredoc bodies (comments stripped);
+  # everything else is scanned as raw text. The token set is the pt-BR
+  # vocabulary + the demo persona name (PT_BR_TOKENS). The corpus data files
+  # and the audit's own token table live in the spec's named allowlist.
+  module Packaging
+    # The pt-BR domain vocabulary the audit scans for. `loja`/`shop`/`store`
+    # are generic-retail stopwords — the ONE justification the inventory
+    # allows (D3); `bia` is the demo persona name (D8).
+    #
+    # The scan is FOLD-aware: both the scanned text and these words go through
+    # `fold` (accents stripped, regex bracket classes like `voc[êe]` collapsed
+    # to their canonical chars) before matching. That is what makes the
+    # shipped corpus data — whose patterns encode pt-BR as `voc[êe]`,
+    # `instru[çc][õo]es` — detectable by the same token table (D1: the
+    # boundary holds for the content the inventory names).
+    ACCENT_MAP = {
+      "á" => "a", "à" => "a", "â" => "a", "ã" => "a", "ä" => "a",
+      "é" => "e", "è" => "e", "ê" => "e", "ë" => "e",
+      "í" => "i", "ì" => "i", "î" => "i", "ï" => "i",
+      "ó" => "o", "ò" => "o", "ô" => "o", "õ" => "o", "ö" => "o",
+      "ú" => "u", "ù" => "u", "û" => "u", "ü" => "u",
+      "ç" => "c"
+    }.freeze
+    BRACKET_CLASS = /\[([^\]]*)\]/
+
+    # -> String: the canonical form the token match runs on. A bracket class
+    # folds to the deduped canonical chars of its members — `voc[êe]` folds
+    # to "voce", matching the folded token "voce" (você).
+    def self.fold(text)
+      text.to_s.gsub(BRACKET_CLASS) do
+        Regexp.last_match(1).chars.map { |c| ACCENT_MAP.fetch(c, c) }.uniq.join
+      end.gsub(/[#{ACCENT_MAP.keys.join}]/, ACCENT_MAP)
+    end
+
+    TOKEN_WORDS = ["você", "não", "loja", "pedido", "atendente", "obrigad",
+                   "conversa", "cliente"].freeze
+    PT_BR_VOCABULARY = /\b(?:#{TOKEN_WORDS.map { |w| fold(w) }.join("|")})\b/i
+    PERSONA_NAME = /\bbia\b/i
+    PT_BR_TOKENS = /(?:#{PT_BR_VOCABULARY.source}|#{PERSONA_NAME.source})/i
+
+    # The never-ship set: the studio JS toolchain (only assets/dist ships) and
+    # the docs' own Jekyll Gemfile/config.
+    NEVER_SHIP_PREFIXES = ["node_modules", "lib/insika/studio/test/", "lib/insika/studio/assets/src/"].freeze
+    NEVER_SHIP_PATHS = %w[
+      docs/Gemfile docs/Gemfile.lock docs/_config.yml
+      lib/insika/studio/README.md lib/insika/studio/package.json
+      lib/insika/studio/package-lock.json lib/insika/studio/tailwind.config.js
+    ].freeze
+
+    module_function
+
+    # -> [String] repo-relative file paths the gem ships, in the gemspec's
+    # order: `git ls-files` (fallback: glob where there is no .git), filtered
+    # to lib/ + docs/ + the four root files, minus the never-ship set.
+    def payload_files(root = Dir.pwd)
+      Dir.chdir(root) do
+        tracked = `git ls-files -z 2>/dev/null`.split("\x0")
+        if tracked.empty?
+          tracked = Dir.glob("{lib,docs}/**/*", File::FNM_DOTMATCH).reject { |f| File.directory?(f) } +
+                    %w[README.md LICENSE CHANGELOG.md bin/insika]
+        end
+        tracked.select { |file| payload_path?(file) }.reject { |file| excluded?(file) }
+      end
+    end
+
+    # -> bool: is this repo-relative path part of the payload selection?
+    def payload_path?(file)
+      file.start_with?("lib/", "docs/") || %w[README.md LICENSE CHANGELOG.md bin/insika].include?(file)
+    end
+
+    # -> bool: is this file in the never-ship set?
+    def excluded?(file)
+      NEVER_SHIP_PREFIXES.any? { |p| file.include?(p) } || NEVER_SHIP_PATHS.include?(file)
+    end
+
+    # -> bool: does a payload file hold pt-BR domain content? Best-effort:
+    #   - Ruby files: comments stripped, string literals / regex literals /
+    #     heredoc bodies scanned;
+    #   - everything else: scanned as-is.
+    # The token set is the pt-BR vocabulary + the demo persona name; both the
+    # text and the vocabulary are FOLDED before matching (accents stripped,
+    # bracket classes collapsed), so the corpus data's `voc[êe]`-style
+    # patterns are caught by the same table.
+    def domain_content?(path)
+      text = path.to_s.end_with?(".rb") ? ruby_text(path) : File.read(path)
+      fold(text).match?(PT_BR_TOKENS)
+    end
+
+    # -> bool: does a payload file mention the demo persona name (`bia`)?
+    def persona_content?(path)
+      text = path.to_s.end_with?(".rb") ? ruby_text(path) : File.read(path)
+      text.match?(PERSONA_NAME)
+    end
+
+    # The Ruby source as the audit reads it: heredoc bodies verbatim, string +
+    # regex literals, comments stripped. Best-effort by design (D1).
+    def ruby_text(path)
+      lines = File.readlines(path)
+      out = +""
+      heredoc = nil
+      lines.each do |line|
+        if heredoc
+          out << line
+          heredoc = nil if line.strip == heredoc
+          next
+        end
+        if (m = line.match(HEREDOC_OPEN))
+          heredoc = m[1] || m[2] || m[3]
+          next
+        end
+        code = strip_comments(line)
+        out << code.scan(STRING_LITERAL).join("\n")
+        out << code.scan(REGEX_LITERAL).join("\n")
+      end
+      out
+    end
+
+    # Cuts a line at its first `#` that starts a COMMENT — i.e. a `#` NOT
+    # inside a string/regex literal (an interpolation `#{…}` or a literal `#`
+    # must survive; a naive strip would corrupt the literal and hide content).
+    def strip_comments(line)
+      spans = literal_spans(line)
+      cut = nil
+      line.chars.each_index do |i|
+        next unless line[i] == "#"
+        next if spans.any? { |b, e| i >= b && i < e }
+
+        cut = i
+        break
+      end
+      cut ? line[0...cut] : line
+    end
+
+    # -> [[begin, end), …] spans of the complete string/regex literals in a line.
+    def literal_spans(line)
+      spans = []
+      line.scan(STRING_LITERAL) { spans << [Regexp.last_match.begin(0), Regexp.last_match.end(0)] }
+      line.scan(REGEX_LITERAL) { spans << [Regexp.last_match.begin(0), Regexp.last_match.end(0)] }
+      spans
+    end
+
+    HEREDOC_OPEN = /<<[~-]\s*(?:"([^"]+)"|'([^']+)'|([A-Za-z_]\w*))(?:\s*\.\w+)*\s*\z/
+    STRING_LITERAL = /"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'/
+    REGEX_LITERAL = %r{\/(?:[^\/\\\n]|\\.)+\/[a-z]*}
+
+    private_class_method :payload_path?, :excluded?, :ruby_text, :strip_comments, :literal_spans
+  end
+end

data/lib/insika/parity/criterion.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "digest"
+require "yaml"
+
+module Insika
+  module Parity
+    # C5 — the frozen criterion, parsed from the deployment's criterion file.
+    # The prose a human reads and the yaml block the machine applies are the SAME
+    # file, so there is exactly one place to edit — and the file's WHOLE bytes are
+    # hashed, so an edit to the rationale invalidates the frozen rule too, which is
+    # correct: the rationale is what makes the numbers reviewable.
+    #
+    # Strict by construction: a missing key or an unknown key is refused at load
+    # (`ValidationError`), and no key has a default — a number the machine filled in
+    # is a number nobody pre-registered.
+    class Criterion
+      Rule = Data.define(
+        :version, :unit, :window_days, :pairs_per_day, :min_decided,
+        :min_judge_models, :both_orders,
+        :win_or_tie_floor, :estimator,
+        :worse_rate_ceiling, :undecided_rate_ceiling, :incomplete_rate_ceiling,
+        :per_agent_min_decided, :per_agent_win_or_tie_floor,
+        :human_assisted, :silent
+      )
+
+      attr_reader :rule, :path, :sha
+
+      def initialize(rule:, path:, sha:)
+        @rule = rule
+        @path = path
+        @sha = sha
+      end
+
+      # Reads the file, extracts the FIRST ```yaml fence, validates STRICTLY.
+      # Raises Insika::ConfigError when the file is absent or has no block;
+      # Insika::ValidationError on an unknown or missing key.
+      def self.load(path)
+        bytes = read_bytes(path)
+        block = extract_yaml_block(bytes)
+        parsed = YAML.safe_load(block, permitted_classes: [], aliases: false)
+        rule = build_rule(parsed)
+        new(rule: rule, path: path, sha: "sha256:#{Digest::SHA256.hexdigest(bytes)}")
+      end
+
+      def to_h = @rule.to_h
+
+      class << self
+        private
+
+        def read_bytes(path)
+          File.read(path, encoding: "UTF-8")
+        rescue Errno::ENOENT, Errno::EACCES, Errno::EISDIR => e
+          raise Insika::ConfigError, "parity criterion not readable at #{path}: #{e.class}"
+        end
+
+        def extract_yaml_block(bytes)
+          match = bytes.match(/```yaml\n(.*?)\n```/m)
+          raise Insika::ConfigError, "parity criterion has no ```yaml block (nothing to pre-register)" unless match
+
+          match[1]
+        end
+
+        def build_rule(parsed)
+          raise Insika::ValidationError, "criterion yaml block must be a mapping" unless parsed.is_a?(Hash)
+
+          raw = parsed.transform_keys(&:to_s)
+          keys = raw.keys.sort
+          missing = Rule.members.map(&:to_s) - keys
+          unknown = keys - Rule.members.map(&:to_s)
+          raise Insika::ValidationError, "criterion is missing key(s): #{missing.join(', ')}" if missing.any?
+          raise Insika::ValidationError, "criterion has unknown key(s): #{unknown.join(', ')}" if unknown.any?
+
+          Rule.new(**Rule.members.to_h { |m| [m, raw[m.to_s]] })
+        end
+      end
+    end
+  end
+end