insika 0.2.0 → 0.3.0

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/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