insika 0.2.0 → 0.7.0

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
 

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, read on demand.
+  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

@@ -2,47 +2,57 @@
 
 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?.,
+  # immutable), the DATA-DEFINED tools from the ToolStore, and — optionally —
+  # the LIVE MCP tools from Insika::McpToolRegistry. Drop-in
+  # for ToolRegistry — 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
+  #   - COLLISION: the base (code) ALWAYS wins — a data-tool or an MCP tool
+  #     cannot hijack the name of a code tool (security, R3); a data-tool
+  #     also wins over an MCP tool of the same name (an operator-authored
+  #     definition over a server's own naming). 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, mirroring
-  #     SkillCatalog.reload. An in-flight turn has already captured the index.
-  # 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.
+  #     SkillCatalog.reload. An in-flight turn has already captured the index. MCP
+  #     entries need no such reload — they read McpStore#tools_cache fresh every call
+  #     (no I/O, so there is nothing to memoize-then-invalidate).
+  # PARITY: empty ToolStore + no mcp_registry ⇒ 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
-  # the same per-agent allow/deny as code tools; exposure is the operator's
-  # (the /tools matrix), not automatic just because they are "data-defined".
+  # The data-tools and MCP tools enter as NORMAL Registry::Entry (optional:
+  # false) — they obey the same per-agent allow/deny as code tools; exposure
+  # is the operator's (the /tools matrix), not automatic just because they
+  # are "data-defined" or MCP-discovered.
   class OverlayToolRegistry
-    def initialize(base:, tool_store:, http:, egress: Insika::EgressGuard, egress_options: {}, event_stream: nil)
+    def initialize(base:, tool_store:, http:, egress: Insika::EgressGuard, egress_options: {}, event_stream: nil,
+                   mcp_registry: nil)
       @base = base
       @tool_store = tool_store
       @http = http
       @egress = egress
       @egress_options = egress_options
       @event_stream = event_stream
+      @mcp_registry = mcp_registry
     end
 
-    # Base + dynamic, except dynamic ones that collide with the base (base wins).
+    # Base + dynamic + mcp, except any that collide with something higher in
+    # the precedence (base > data-tools > mcp).
     def entries
-      @base.entries + dynamic.reject { |e| code_tool?(e.name) }
+      @base.entries + dynamic.reject { |e| code_tool?(e.name) } + mcp_entries
     end
 
     def names
-      (@base.names + dynamic.map(&:name)).uniq
+      (@base.names + dynamic.map(&:name) + mcp_entries.map(&:name)).uniq
     end
 
-    # -> instance (base wins) | raise NotFoundError.
+    # -> instance (base wins, then data-tools) | raise NotFoundError.
     def resolve(name)
       key = name.to_s
       return @base.resolve(key) if code_tool?(key)
 
-      entry = dynamic.find { |e| e.name == key }
+      entry = dynamic.find { |e| e.name == key } || mcp_entries.find { |e| e.name == key }
       raise Insika::NotFoundError, "'#{name}' not registered in #{self.class}" unless entry
 
       entry.factory.call
@@ -53,7 +63,7 @@ module Insika
       key = name.to_s
       return @base.side_effect?(key) if code_tool?(key)
 
-      entry = dynamic.find { |e| e.name == key }
+      entry = dynamic.find { |e| e.name == key } || mcp_entries.find { |e| e.name == key }
       entry ? !!entry.metadata[:side_effect] : false
     end
 
@@ -72,6 +82,16 @@ module Insika
       @dynamic ||= build_dynamic
     end
 
+    # No I/O (McpToolRegistry#entries only reads McpStore#tools_cache) ->
+    # recomputed fresh every call, unlike `dynamic` (nothing to reload).
+    # Drops anything already claimed by the base or a data-tool.
+    def mcp_entries
+      return [] unless @mcp_registry
+
+      claimed = @base.names + dynamic.map(&:name)
+      @mcp_registry.entries.reject { |e| claimed.include?(e.name) }
+    end
+
     def build_dynamic
       @tool_store.all_raw.filter_map { |raw| entry_for(raw) }
     end

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 bin/insika-router]
+        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 bin/insika-router].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