truffler 0.1.0

data/lib/truffler/benchmark/runner.rb

@@ -0,0 +1,370 @@
+require "fileutils"
+
+module Truffler
+  module Benchmark
+    # Loads a dataset into the current database, labels it through the real
+    # pipeline (Queue, Labeler, RequestBuilder, Budget) with the given client,
+    # and returns one JSON-ready report: the R32 metrics, the R33 packed-batch
+    # agreement, the R34 injection result, and the params echo.
+    #
+    # Modes: :replay reads committed cassettes and never calls out; :record
+    # rewrites a cassette directory; :synthetic answers from SyntheticJev with
+    # no cassette, for generated datasets of any size.
+    class Runner
+      MODES = %i[replay record synthetic].freeze
+      SOURCES = { synthetic: "synthetic-fake", live: "live" }.freeze
+      MANIFEST = "manifest.json".freeze
+
+      attr_reader :params, :dataset, :mode, :source
+
+      def self.build(params: Params.load(Benchmark.path("params.yml")), mode: :replay, jev: :synthetic, records: nil,
+        tenants: 3, seed: Generator::DEFAULT_SEED, cassettes: nil, env: ENV, jev_options: {},
+        searcher: Adapters.searcher, reranker: Adapters.reranker)
+        mode = mode.to_sym
+        jev = jev.to_sym
+        raise ArgumentError, "MODE must be one of #{MODES.join(', ')}" unless MODES.include?(mode)
+        raise ArgumentError, "JEV must be one of #{SOURCES.keys.join(', ')}" unless SOURCES.key?(jev)
+
+        dataset = records ? Generator.new(records: Integer(records), tenants: tenants, seed: seed).dataset : Dataset.load(Benchmark.path("fixtures"))
+        cassettes = (cassettes || default_cassettes(jev)).to_s
+        client = client_for(mode, jev, dataset, cassettes, env, jev_options)
+        new(params: params, dataset: dataset, client: client, mode: mode, source: source_for(mode, jev, cassettes),
+          cassettes: (cassettes unless mode == :synthetic), searcher: searcher, reranker: reranker)
+      end
+
+      # MODE, JEV, PARAMS, BENCH_RECORDS, BENCH_TENANTS, and CASSETTES from the
+      # environment. TRUFFLER_CASSETTE_MODE=record means recording live Jev.
+      def self.from_env(env = ENV)
+        mode = env["MODE"].presence || env["TRUFFLER_CASSETTE_MODE"].presence || "replay"
+        jev = env["JEV"].presence || (env["TRUFFLER_CASSETTE_MODE"] == "record" ? "live" : "synthetic")
+        build(params: Params.load(env["PARAMS"].presence || Benchmark.path("params.yml")), mode: mode, jev: jev,
+          records: env["BENCH_RECORDS"].presence, tenants: Integer(env["BENCH_TENANTS"].presence || 3),
+          cassettes: env["CASSETTES"].presence, env: env)
+      end
+
+      def self.default_cassettes(jev)
+        jev == :live ? File.join(Dir.pwd, "tmp", "bench", "cassettes-live") : Benchmark.path("cassettes")
+      end
+
+      def self.client_for(mode, jev, dataset, cassettes, env, jev_options)
+        inner = if jev == :live
+          raise ArgumentError, "live Jev needs MODE=record or MODE=replay" if mode == :synthetic
+          raise ArgumentError, "recording live Jev needs TYPESAFE_API_KEY" if mode == :record && env["TYPESAFE_API_KEY"].blank?
+
+          Clients::RubyLLMTypeSafe.new if mode == :record
+        else
+          SyntheticJev.new(dataset, **jev_options)
+        end
+        return inner if mode == :synthetic
+
+        Clients::Cassette.new(mode == :record ? inner : nil, dir: cassettes, mode: mode)
+      end
+
+      def self.source_for(mode, jev, cassettes)
+        manifest = File.join(cassettes, MANIFEST)
+        return JSON.parse(File.read(manifest)).fetch("source") if mode == :replay && File.exist?(manifest)
+
+        SOURCES.fetch(jev)
+      end
+
+      def initialize(params:, dataset:, client:, mode:, source:, cassettes: nil, searcher: Adapters.searcher,
+        reranker: Adapters.reranker, model: Email)
+        @params = params
+        @dataset = dataset
+        @client = client
+        @mode = mode.to_sym
+        @source = source
+        @cassettes = cassettes
+        @searcher = searcher
+        @reranker = reranker
+        @model = model
+      end
+
+      def run
+        check_batch_size!
+        prepare_cassettes if mode == :record
+        @model.create_table!
+        @model.declare!(params)
+        load_dataset
+        labeling = label_all
+        agreement = agreement_check
+        injection_labels = injection_label_check
+        search, rerank, query_cost = measure_queries
+
+        report(labeling, agreement, injection_labels, search, rerank, query_cost)
+      end
+
+      private
+
+      def check_batch_size!
+        return if params.batch_size <= Truffler.config.tenant_live_cap
+
+        raise ArgumentError, "labeling.batch_size #{params.batch_size} exceeds tenant_live_cap #{Truffler.config.tenant_live_cap}"
+      end
+
+      def prepare_cassettes
+        FileUtils.mkdir_p(@cassettes)
+        Dir[File.join(@cassettes, "*.json")].each { |file| File.delete(file) }
+        File.write(File.join(@cassettes, MANIFEST), "#{Canonical.json(source: source, generator: 'Truffler::Benchmark')}\n")
+      end
+
+      def record_type
+        @model.polymorphic_name
+      end
+
+      def load_dataset
+        Records::Label.where(record_type: record_type).delete_all
+        Records::RecordState.where(record_type: record_type).delete_all
+        now = Time.current
+        @dataset.labeled_records.each_slice(1_000) do |slice|
+          @model.insert_all!(slice.map do |record|
+            { id: record.id, tenant_id: Integer(record.tenant), subject: record.subject, body: record.body,
+              sender_name: record.sender_name, sender_email: record.sender_email,
+              received_at: Time.iso8601(record.received_at), created_at: now, updated_at: now }
+          end)
+          Records::RecordState.insert_all!(slice.map do |record|
+            { record_type: record_type, record_id: record.id, tenant_key: record.tenant, status: "pending",
+              priority: "live", attempts: 0, created_at: now, updated_at: now }
+          end)
+        end
+      end
+
+      # Labels every record at live priority under the account budget on a
+      # simulated clock: waits advance the clock, and a tenant over its live
+      # cap waits for the next minute, so throughput is what the budget allows.
+      def label_all
+        clock = SimulatedClock.new
+        budget = Budget.new(cache: ActiveSupport::Cache::MemoryStore.new, clock: -> { clock.now }, sleeper: ->(seconds) { clock.advance(seconds) })
+        labeler = Labeling::Labeler.new(@model, client: @client, budget: budget)
+        queue = Labeling::Queue.new(@model)
+        totals = { labeled: 0, requests: 0, cost: 0.0, demotions: 0 }
+        pending = @dataset.tenants.dup
+
+        until pending.empty?
+          progressed = false
+          pending.dup.each do |tenant|
+            states = queue.claim(tenant, priority: :live, limit: params.batch_size)
+            next pending.delete(tenant) if states.empty?
+
+            result = labeler.label(states, priority: :live)
+            if result.demoted
+              totals[:demotions] += 1
+              Records::RecordState.where(id: states.map(&:id)).update_all(status: "pending", claimed_at: nil)
+            else
+              progressed = true
+              totals[:labeled] += result.labeled
+              totals[:requests] += result.requests
+              totals[:cost] += result.cost
+            end
+          end
+          clock.next_minute unless progressed || pending.empty?
+        end
+
+        minutes = [ clock.elapsed.ceil, 1 ].max / 60.0
+        totals.merge(minutes: minutes, budget: budget)
+      end
+
+      def agreement_check
+        tolerance = params.dig(:labeling, :agreement_tolerance)
+        floor = params.dig(:labeling, :agreement_floor)
+        sample = agreement_sample
+        results = params.agreement_batch_sizes.to_h { |size| [ size, label_values(sample, size) ] }
+        single = results.fetch(1)[:values]
+
+        sizes = results.to_h do |size, result|
+          compared = Metrics.agreement(single, result[:values], tolerance: tolerance)
+          [ size.to_s, { "agreement" => compared[:agreement].round(4), "adoptable" => Metrics.adoptable?(compared[:agreement], floor: floor),
+                         "requests" => result[:requests], "disagreements" => compared[:disagreements].size } ]
+        end
+        adopted = sizes.select { |_, entry| entry["adoptable"] }.keys.map(&:to_i).max
+        { "tolerance" => tolerance, "floor" => floor, "sample" => sample.values.sum(&:size), "batch_sizes" => sizes,
+          "adopted_batch_size" => adopted }
+      end
+
+      def agreement_sample
+        per_tenant = params.dig(:labeling, :agreement_sample_per_tenant)
+        ids = @dataset.records.group_by(&:tenant).transform_values { |records| records.first(per_tenant).map(&:id) }
+        ids.transform_values { |tenant_ids| @model.where(id: tenant_ids).order(:id).to_a }
+      end
+
+      def label_values(sample, size)
+        definition = @model.truffler_definition
+        values = Hash.new { |hash, key| hash[key] = {} }
+        requests = 0
+        sample.each do |tenant, records|
+          builder = Labeling::RequestBuilder.new(definition, tenant_key: tenant)
+          records.each_slice(size) do |chunk|
+            builder.build(chunk.map { |record| [ record, definition.label_keys ] }).each do |request|
+              requests += 1
+              answers = @client.ask(state: request.state, questions: request.questions, priority: :backfill)
+              request.entries.each do |tag, (record, keys)|
+                keys.each { |key| values[record.id][key] = answer_value(definition.label(key), answers, Questions.tagged_id(tag, key)) }
+              end
+            end
+          end
+        end
+        { values: values, requests: requests }
+      end
+
+      def answer_value(label, answers, id)
+        case label.type
+        when :noul then answers.noul(id)
+        when :score then answers.score(id)
+        when :choice then answers.choice(id)
+        end
+      end
+
+      def injection_label_check
+        tolerance = params.dig(:injection, :label_tolerance)
+        ids = @dataset.injections.flat_map { |injection| [ injection.clean_id, injection.record.id ] }
+        stored = Records::Label.where(record_type: record_type, record_id: ids).pluck(:record_id, :label_key, :value)
+          .each_with_object(Hash.new { |hash, key| hash[key] = {} }) { |(id, key, value), map| map[id][key] = value }
+
+        failures = @dataset.injections.filter_map do |injection|
+          clean = stored[injection.clean_id]
+          twin = stored[injection.record.id]
+          changed = (clean.keys | twin.keys).reject { |key| Metrics.agree?(clean[key], twin[key], tolerance) }
+          next if changed.empty?
+
+          { "fixture" => injection.id, "clean_id" => injection.clean_id, "twin_id" => injection.record.id,
+            "labels" => changed.map { |key| key.split(":").first }.uniq.sort }
+        end
+        { "passed" => failures.empty?, "tolerance" => tolerance, "twins" => @dataset.injections.size, "failures" => failures }
+      end
+
+      def measure_queries
+        cost = 0.0
+        counter = ->(*, payload) { cost += payload[:cost].to_f }
+        search = rerank = nil
+        ActiveSupport::Notifications.subscribed(counter, "truffler.jev_call") do
+          search = search_metrics
+          rerank = rerank_metrics(search)
+        end
+        query_cost = Benchmark.not_available?(search) ? search : (cost / @dataset.gold.size).round(8)
+        [ search, rerank, query_cost ]
+      end
+
+      def search_metrics
+        return @searcher if Benchmark.not_available?(@searcher)
+
+        returned = {}
+        latencies = []
+        @dataset.gold.each do |gold|
+          started = Instrumentation.monotonic_ms
+          ids = @searcher.call(query: gold.query, tenant_key: gold.tenant, kind: gold.kind, model: @model, params: params)
+          return ids if Benchmark.not_available?(ids)
+
+          latencies << Instrumentation.monotonic_ms - started
+          returned[gold.id] = ids.to_a
+        end
+
+        by_kind = @dataset.gold.group_by(&:kind)
+        score = ->(metric) { by_kind.transform_values { |golds| Metrics.mean(golds.map { |gold| Metrics.public_send(metric, gold.expected_ids, returned[gold.id]) }).round(4) } }
+        { "recall" => score.(:recall), "precision" => score.(:precision),
+          "latency" => { "p50" => Metrics.percentile(latencies, 50).round(3), "p95" => Metrics.percentile(latencies, 95).round(3) },
+          "returned" => returned }
+      end
+
+      def rerank_metrics(search)
+        return @reranker if Benchmark.not_available?(@reranker)
+        return search if Benchmark.not_available?(search)
+
+        depth = params.rerank_depth
+        requests = 0
+        buckets = Hash.new(0)
+        @dataset.gold.select { |gold| gold.kind == "intent" }.each do |gold|
+          result = rerank(gold.query, gold.tenant, search["returned"].fetch(gold.id), depth)
+          return result if Benchmark.not_available?(result)
+
+          requests += result[:requests]
+          result[:buckets].each_value { |bucket| buckets[bucket.to_s] += 1 }
+        end
+        { "depth" => depth, "requests" => requests, "buckets" => buckets.sort.to_h, "injection" => rerank_injection_check(depth) }
+      end
+
+      def rerank(query, tenant, candidate_ids, depth)
+        @reranker.call(query: query, tenant_key: tenant, model: @model, candidate_ids: candidate_ids.first(depth), depth: depth, params: params,
+          client: @client)
+      end
+
+      def rerank_injection_check(depth)
+        failures = @dataset.injections.filter_map do |injection|
+          buckets = rerank(injection.query, injection.record.tenant, [ injection.clean_id, injection.record.id ], depth)
+          return buckets if Benchmark.not_available?(buckets)
+          next if buckets[:buckets][injection.clean_id].to_s == buckets[:buckets][injection.record.id].to_s
+
+          { "fixture" => injection.id, "clean_id" => injection.clean_id, "twin_id" => injection.record.id }
+        end
+        { "passed" => failures.empty?, "failures" => failures }
+      end
+
+      def report(labeling, agreement, injection_labels, search, rerank, query_cost)
+        injection_rerank = Benchmark.not_available?(rerank) ? rerank : rerank.delete("injection")
+        failures = []
+        failures << "injection_labels" unless injection_labels["passed"]
+        failures << "injection_rerank" if injection_rerank.is_a?(Hash) && injection_rerank["passed"] == false
+        failures << "batch_size_agreement" unless agreement["batch_sizes"].fetch(params.batch_size.to_s)["adoptable"]
+
+        report = {
+          "truffler_bench" => REPORT_VERSION,
+          "source" => source,
+          "mode" => mode.to_s,
+          "params" => params.to_h,
+          "dataset" => @dataset.summary,
+          "metrics" => {
+            "recall" => per_kind(search, "recall"),
+            "precision" => per_kind(search, "precision"),
+            "keystroke_latency_ms" => Benchmark.not_available?(search) ? search : search["latency"],
+            "labeling_throughput" => throughput(labeling),
+            "cost" => { "per_labeled_record" => (labeling[:cost] / [ labeling[:labeled], 1 ].max).round(8), "per_query" => query_cost }
+          },
+          "agreement" => agreement,
+          "injection" => { "labels" => injection_labels, "rerank" => injection_rerank },
+          "rerank" => rerank,
+          "checks" => { "passed" => failures.empty?, "failures" => failures }
+        }
+        JSON.parse(JSON.generate(report.as_json))
+      end
+
+      def per_kind(search, metric)
+        return { "intent" => search, "exact_text" => search } if Benchmark.not_available?(search)
+
+        search[metric]
+      end
+
+      def throughput(labeling)
+        budget = labeling[:budget]
+        { "records" => labeling[:labeled], "requests" => labeling[:requests],
+          "records_per_request" => (labeling[:labeled] / [ labeling[:requests], 1 ].max.to_f).round(3),
+          "simulated_minutes" => labeling[:minutes].round(4),
+          "requests_per_minute" => (labeling[:requests] / labeling[:minutes]).round(2),
+          "records_per_minute" => (labeling[:labeled] / labeling[:minutes]).round(2),
+          "tenant_demotions" => labeling[:demotions],
+          "budget_live_requests_per_minute" => (budget.ceiling(:live) * 60).round(2),
+          "tenant_live_cap" => Truffler.config.tenant_live_cap }
+      end
+
+      class SimulatedClock
+        START = 1_800_000_000.0
+
+        attr_reader :now
+
+        def initialize
+          @now = START
+        end
+
+        def advance(seconds)
+          @now += seconds
+        end
+
+        def next_minute
+          @now = ((@now / 60).floor + 1) * 60.0
+        end
+
+        def elapsed
+          @now - START
+        end
+      end
+    end
+  end
+end

data/lib/truffler/benchmark/synthetic_jev.rb

@@ -0,0 +1,85 @@
+require "digest"
+
+module Truffler
+  module Benchmark
+    # A deterministic stand-in for Jev that answers from the dataset's ground
+    # truth plus seeded noise. It produces the committed cassettes. Packed
+    # requests drift: each extra record in a request raises the chance that
+    # an answer flips, which is what the R33 agreement check has to catch.
+    # With obey_injections it follows instructions embedded in record text,
+    # modeling a model that fails R34.
+    #
+    # Questions about records it does not know (rerank candidates, queries)
+    # answer no, the first option, or the lowest level.
+    class SyntheticJev < Clients::Base
+      MODEL = "synthetic-jev".freeze
+      INJECTED = "ignore all previous instructions".freeze
+      OBEYED = { "needs_action" => 1.0, "urgent" => 1.0, "category" => "billing", "importance" => 2 }.freeze
+
+      def initialize(dataset, seed: Generator::DEFAULT_SEED, noise: 0.03, packed_flip_rate: 0.003, obey_injections: false)
+        @seed = seed
+        @noise = noise
+        @packed_flip_rate = packed_flip_rate
+        @obey_injections = obey_injections
+        @truth = dataset.labeled_records.to_h { |record| [ self.class.key(record.to_h.stringify_keys), record.truth ] }
+      end
+
+      def self.key(fields)
+        Canonical.digest([ fields["subject"].to_s, fields["body"].to_s ])
+      end
+
+      def perform(state:, questions:, model:)
+        state = state.deep_stringify_keys
+        records = state["records"].to_h
+        answers = questions.to_h do |id, question|
+          tag, label = Questions.split_id(id)
+          [ id, answer(question.deep_stringify_keys, records[tag], label, records.size) ]
+        end
+        { "answers" => answers, "model" => MODEL, "usage" => { "input_tokens" => Tokens.estimate({ state: state, questions: questions }) } }
+      end
+
+      private
+
+      def answer(question, fields, label, batch)
+        key = fields && self.class.key(fields)
+        truth = key && @truth[key]
+        truth = OBEYED if truth && @obey_injections && fields["body"].to_s.downcase.include?(INJECTED)
+        flip = truth && unit(key, label, batch, "flip") < @packed_flip_rate * (batch - 1)
+        drift = truth ? (unit(key, label, batch, "noise") * 2 - 1) * @noise : 0.0
+
+        case question["type"]
+        when "noul" then noul(truth&.dig(label).to_f, drift, flip)
+        when "choice" then choice(question["criteria"].keys, truth&.dig(label), drift, flip)
+        when "score" then score(question["criteria"].size, truth&.dig(label).to_i, flip)
+        end
+      end
+
+      def noul(value, drift, flip)
+        value = (value + drift).clamp(0.0, 1.0)
+        value = value >= 0.5 ? value - 0.4 : value + 0.4 if flip
+        { "type" => "noul", "noul" => value.round(4) }
+      end
+
+      def choice(options, truth, drift, flip)
+        index = options.index(truth.to_s) || 0
+        index = (index + 1) % options.size if flip
+        confidence = (0.8 + drift).round(4)
+        rest = options.size > 1 ? ((1 - confidence) / (options.size - 1)).round(4) : 0.0
+        probabilities = options.each_with_index.to_h { |option, position| [ option, position == index ? confidence : rest ] }
+        { "type" => "choice", "choice" => options[index], "probabilities" => probabilities, "confidence" => confidence }
+      end
+
+      def score(levels, level, flip)
+        level = level.clamp(0, levels - 1)
+        level = level.zero? ? 1 : level - 1 if flip
+        legend = Array.new(levels) { |index| [ index.to_s, index.to_s ] }.to_h
+        probabilities = legend.keys.to_h { |key| [ key, key.to_i == level ? 1.0 : 0.0 ] }
+        { "type" => "score", "score" => level, "legend" => legend, "probabilities" => probabilities, "confidence" => 1.0 }
+      end
+
+      def unit(*parts)
+        Digest::SHA256.hexdigest([ @seed, *parts ].join("|"))[0, 8].to_i(16) / 0xffffffff.to_f
+      end
+    end
+  end
+end

data/lib/truffler/benchmark.rb

@@ -0,0 +1,29 @@
+module Truffler
+  # The replayable benchmark behind `rake truffler:bench` (KTD17). Everything
+  # it reads lives under bench/: params.yml, synthetic fixtures, and the
+  # committed cassettes. No step touches real data (R35).
+  module Benchmark
+    ROOT = File.expand_path("../../bench", __dir__)
+    REPORT_VERSION = 1
+
+    # Stands in for a metric whose unit has not landed yet, so the report
+    # keeps every key and says what it waits for instead of failing.
+    NotAvailable = Data.define(:requires) do
+      def to_h
+        { "status" => "not_available_yet", "requires" => requires }
+      end
+
+      def as_json(*)
+        to_h
+      end
+    end
+
+    def self.path(*parts)
+      File.join(ROOT, *parts)
+    end
+
+    def self.not_available?(value)
+      value.is_a?(NotAvailable) || (value.is_a?(Hash) && value["status"] == "not_available_yet")
+    end
+  end
+end

data/lib/truffler/broadcaster.rb

@@ -0,0 +1,46 @@
+module Truffler
+  # The data-free Action Cable ping of KTD13: `{run_id, section, changed_at}`
+  # on `truffler:<user_key>`. Hosts answer it with an Inertia partial reload
+  # of the named prop (`smart`, `provider`), so no result data rides the
+  # socket (R27). A failed broadcast is reported and swallowed: a ping is a
+  # hint, and the work that triggered it must not fail with it.
+  #
+  # `config.broadcaster` may be any object responding to
+  # `broadcast(stream, payload)`; the default is `ActionCable.server` when
+  # Action Cable is loaded, otherwise pings are dropped.
+  module Broadcaster
+    module_function
+
+    def stream(user_key)
+      "truffler:#{user_key}"
+    end
+
+    # True when a ping was handed to the server.
+    def ping(user_key, run_id:, section:)
+      return false if user_key.blank?
+
+      target = server
+      return false unless target
+
+      target.broadcast(stream(user_key), { run_id: run_id, section: section.to_s, changed_at: Time.current.iso8601(6) })
+      true
+    rescue StandardError => error
+      report(error, run_id: run_id, section: section)
+      false
+    end
+
+    def server
+      Truffler.config.broadcaster || (ActionCable.server if defined?(ActionCable) && ActionCable.respond_to?(:server))
+    end
+
+    def report(error, run_id:, section:)
+      Instrumentation.instrument(:broadcast_failed, run_id: run_id, section: section.to_s, error_class: error.class.name)
+      Truffler.config.logger.warn("truffler: broadcast failed (#{error.class.name}) for run #{run_id}")
+      Rails.error.report(error, handled: true, context: { run_id: run_id, section: section.to_s }) if rails_error_reporter?
+    end
+
+    def rails_error_reporter?
+      defined?(Rails) && Rails.respond_to?(:error) && Rails.error.respond_to?(:report)
+    end
+  end
+end

data/lib/truffler/budget.rb

@@ -0,0 +1,118 @@
+module Truffler
+  # One account-wide Jev request budget shared by every gem call. The gem's
+  # share is the account limit minus headroom for the app's other Jev calls,
+  # counted per second in the cache store so bursts spread across the minute.
+  # Each priority may fill the second only up to its ceiling, so lower
+  # priorities give way first: live labeling, then query encoding, then
+  # rerank, then backfill.
+  #
+  # Outcomes: :granted takes a slot; :demoted means a tenant is over its live
+  # cap and its records should wait at backfill priority (no slot is taken);
+  # :denied means skip, pause, or reschedule. Only live callers wait, up to
+  # max_wait. A cache that cannot count (the null store) never blocks.
+  class Budget
+    PRIORITIES = %i[live encode rerank backfill].freeze
+
+    Decision = Data.define(:outcome, :priority, :reason) do
+      def granted? = outcome == :granted
+      def demoted? = outcome == :demoted
+      def denied? = outcome == :denied
+    end
+
+    attr_reader :config
+
+    def initialize(config: Truffler.config, cache: config.cache_store,
+      clock: -> { Process.clock_gettime(Process::CLOCK_REALTIME) }, sleeper: ->(seconds) { sleep(seconds) })
+      @config = config
+      @cache = cache
+      @clock = clock
+      @sleeper = sleeper
+    end
+
+    def acquire(priority:, user_key: nil, tenant_key: nil, records: 1)
+      priority = priority.to_sym
+      raise ArgumentError, "priority must be one of #{PRIORITIES.join(', ')}" unless PRIORITIES.include?(priority)
+
+      taken = []
+      if priority == :live && tenant_key
+        return Decision.new(:demoted, :backfill, :tenant_cap) unless take(tenant_counter(tenant_key), records, config.tenant_live_cap, taken)
+      end
+      if (cap = config.user_caps[priority]) && user_key
+        return deny(priority, :user_cap, taken) unless take(user_counter(priority, user_key), 1, cap, taken)
+      end
+      return deny(priority, :exhausted, taken) unless take_second(priority)
+
+      Decision.new(:granted, priority, nil)
+    end
+
+    # Counts one unit against the per-user cap for `priority` without taking
+    # a request slot, for callers that gate work but make no Jev call
+    # themselves (the Smart dispatcher; each rerank chunk acquires its own).
+    def admit(priority:, user_key:)
+      priority = priority.to_sym
+      raise ArgumentError, "priority must be one of #{PRIORITIES.join(', ')}" unless PRIORITIES.include?(priority)
+
+      cap = config.user_caps[priority]
+      return Decision.new(:granted, priority, nil) unless cap && user_key
+      return deny(priority, :user_cap, []) unless take(user_counter(priority, user_key), 1, cap)
+
+      Decision.new(:granted, priority, nil)
+    end
+
+    def gem_per_minute
+      (config.requests_per_minute * (1 - config.headroom)).floor
+    end
+
+    def ceiling(priority)
+      [ gem_per_minute / 60.0 * config.priority_ceilings.fetch(priority), 1 ].max
+    end
+
+    private
+
+    def take_second(priority)
+      deadline = @clock.call + (priority == :live ? config.max_wait : 0)
+      loop do
+        now = @clock.call
+        second = now.floor
+        return true if take("second/#{second}", 1, ceiling(priority))
+
+        wait = second + 1 - now
+        return false if now + wait > deadline
+
+        @sleeper.call(wait)
+      end
+    end
+
+    def take(counter, amount, limit, taken = nil)
+      key = "truffler/budget/#{counter}"
+      count = @cache.increment(key, amount, expires_in: 2.minutes)
+      return true if count.nil?
+
+      if count <= limit
+        taken&.push([ key, amount ])
+        true
+      else
+        @cache.decrement(key, amount, expires_in: 2.minutes)
+        false
+      end
+    end
+
+    def deny(priority, reason, taken)
+      taken.each { |key, amount| @cache.decrement(key, amount, expires_in: 2.minutes) }
+      Instrumentation.instrument(:budget_denied, priority: priority)
+      Decision.new(:denied, priority, reason)
+    end
+
+    def tenant_counter(tenant_key)
+      "tenant/#{tenant_key}/#{minute}"
+    end
+
+    def user_counter(priority, user_key)
+      "user/#{priority}/#{user_key}/#{minute}"
+    end
+
+    def minute
+      (@clock.call / 60).floor
+    end
+  end
+end

data/lib/truffler/canonical.rb

@@ -0,0 +1,27 @@
+require "digest"
+require "json"
+
+module Truffler
+  # JSON with object keys sorted at every level, so key order never changes a
+  # digest. Cassettes, fingerprints, and cache keys all hash through here.
+  module Canonical
+    module_function
+
+    def json(value)
+      JSON.generate(sort(value))
+    end
+
+    def digest(value)
+      Digest::SHA256.hexdigest(json(value))
+    end
+
+    def sort(value)
+      case value
+      when Hash then value.to_h { |key, item| [ key.to_s, sort(item) ] }.sort.to_h
+      when Array then value.map { |item| sort(item) }
+      when Symbol then value.to_s
+      else value
+      end
+    end
+  end
+end