truffler 0.1.0

data/lib/truffler/lenses/validation.rb

@@ -0,0 +1,69 @@
+module Truffler
+  module Lenses
+    # Checks lens questions against the KTD2 wire shape and Jev's limits
+    # before any Jev call: at most 10 score levels and 255 choice options.
+    module Validation
+      MAX_SCORE_LEVELS = 10
+      MAX_CHOICE_OPTIONS = 255
+      TYPES = %w[noul choice score].freeze
+
+      module_function
+
+      # questions: {label_key => wire-shape question}; reused: label keys the
+      # lens borrows; available: keys it may borrow; declared: keys a new
+      # question must not shadow.
+      def validate!(questions, reused: [], available: nil, declared: [], max_questions: Lenses.settings.max_questions)
+        questions = questions.to_h
+        raise InvalidLens, "a lens needs at least one new or reused label" if questions.empty? && reused.blank?
+        raise InvalidLens, "a lens may add at most #{max_questions} questions" if questions.size > max_questions
+
+        questions.each { |key, question| check_question(key.to_s, question, declared) }
+        unknown = Array(reused).map(&:to_s) - Array(available || reused).map(&:to_s)
+        raise InvalidLens, "reused labels #{unknown.join(', ')} do not exist" if unknown.any?
+
+        questions
+      end
+
+      def check_question(key, question, declared)
+        raise InvalidLens, "label #{key.inspect} must match #{LabelDefinition::KEY.source} without a double underscore" unless
+          LabelDefinition::KEY.match?(key) && !key.include?(Questions::SEPARATOR)
+        raise InvalidLens, "#{key} is already a declared label; reuse it instead" if declared.include?(key)
+        raise InvalidLens, "#{key}: question must be a hash" unless question.is_a?(Hash)
+
+        type = question["type"]
+        raise InvalidLens, "#{key}: type must be one of #{TYPES.join(', ')}" unless TYPES.include?(type)
+        raise InvalidLens, "#{key}: instructions are required" if question["instructions"].blank?
+
+        criteria = question["criteria"]
+        case type
+        when "noul" then check_noul(key, criteria)
+        when "choice" then check_choice(key, criteria)
+        when "score" then check_score(key, criteria)
+        end
+      end
+
+      def check_noul(key, criteria)
+        return if criteria.nil?
+        return if criteria.is_a?(Hash) && criteria.keys.map(&:to_s).sort == %w[false true]
+
+        raise InvalidLens, "#{key}: noul criteria keys must be true and false"
+      end
+
+      def check_choice(key, criteria)
+        raise InvalidLens, "#{key}: choice criteria must be a hash of options" unless criteria.is_a?(Hash) && criteria.any?
+        if criteria.size > MAX_CHOICE_OPTIONS
+          raise InvalidLens, "#{key}: #{criteria.size} choice options exceed Jev's limit of #{MAX_CHOICE_OPTIONS}"
+        end
+        raise InvalidLens, "#{key}: choice options must be named" if criteria.keys.any?(&:blank?)
+      end
+
+      def check_score(key, criteria)
+        raise InvalidLens, "#{key}: score criteria must list ordered levels" unless criteria.is_a?(Array)
+        raise InvalidLens, "#{key}: score labels need at least two levels" if criteria.size < 2
+        return if criteria.size <= MAX_SCORE_LEVELS
+
+        raise InvalidLens, "#{key}: #{criteria.size} score levels exceed Jev's limit of #{MAX_SCORE_LEVELS}"
+      end
+    end
+  end
+end

data/lib/truffler/lenses/version.rb

@@ -0,0 +1,34 @@
+module Truffler
+  module Lenses
+    # One drafted question set of a lens (R45). Versions are append-only:
+    # regenerating adds a draft, activating retires the previous active one,
+    # and restoring copies an earlier version forward as a new number.
+    class Version < ActiveRecord::Base
+      include SealedDescription
+
+      self.table_name = "truffler_lens_versions"
+
+      STATUSES = %w[draft active retired].freeze
+
+      belongs_to :lens, class_name: "Truffler::Lenses::Lens", inverse_of: :versions
+      serialize :questions, coder: JSON
+      serialize :reused_keys, coder: JSON
+
+      validates :status, inclusion: { in: STATUSES }
+
+      def draft? = status == "draft"
+      def active? = status == "active"
+
+      def to_draft
+        Draft.new(model: lens.model, scope: lens.scope, description: description, name: lens.name,
+          questions: questions.to_h, reused: Array(reused_keys), lens: lens)
+      end
+
+      private
+
+      def described_model
+        lens.model
+      end
+    end
+  end
+end

data/lib/truffler/lenses.rb

@@ -0,0 +1,138 @@
+module Truffler
+  # Lenses (KTD21): LLM-drafted label questions stored as vocabulary
+  # extensions. Their answers live in `truffler_labels` under
+  # "lens:<lens_id>:<label>", so filters, label vectors, staleness, and
+  # backfill treat them like declared labels.
+  #
+  # `visible_questions` and `lens_fingerprints` are the seam the vocabulary
+  # and query encoding plug into: the active lens questions one searcher can
+  # see, and a digest that changes whenever that set changes.
+  module Lenses
+    KEY_PREFIX = "lens".freeze
+
+    Visibility = Data.define(:questions, :fingerprints, :lens_fingerprints, :lens_ids)
+
+    module_function
+
+    def settings
+      Truffler.config.lenses
+    end
+
+    def storage_prefix(lens_id)
+      "#{KEY_PREFIX}:#{lens_id}:"
+    end
+
+    def label_key(lens_id, label)
+      "#{storage_prefix(lens_id)}#{label}"
+    end
+
+    # Active lenses of this model visible to one searcher: app lenses, the
+    # tenant's lenses, and the user's own lenses in that tenant.
+    def visible_lenses(model, tenant_key:, user_key: nil, user_digest: nil)
+      user_digest ||= digest(user_key) if user_key.present?
+      tenant_key = tenant_key&.to_s
+      lenses = Lens.active.where(record_type: model.polymorphic_name)
+      visible = lenses.where(scope_type: "app").or(lenses.where(scope_type: "tenant", tenant_key: tenant_key))
+      visible = visible.or(lenses.where(scope_type: "user", tenant_key: tenant_key, scope_key: user_digest)) if user_digest
+      visible.order(:id).to_a
+    end
+
+    # Active lenses whose questions records of one tenant are labeled with:
+    # app lenses, the tenant's lenses, and every user's personal lenses in
+    # that tenant. Personal answers are stored per record like any other,
+    # and only their owner's searches can see them.
+    def labeling_lenses(model, tenant_key:)
+      lenses = Lens.active.where(record_type: model.polymorphic_name)
+      lenses.where(scope_type: "app").or(lenses.where(scope_type: %w[tenant user], tenant_key: tenant_key&.to_s)).order(:id).to_a
+    end
+
+    # {"lens:<id>:<label>" => LensLabel} visible to one searcher, or with
+    # all_users: true, every label records of the tenant are labeled with.
+    def labels(model, tenant_key:, user_key: nil, all_users: false)
+      rows = active_rows(model, tenant_key)
+      unless all_users
+        personal = rows.select { |row| row["scope_type"] == "user" }
+        owner = digest(user_key) if personal.any? && user_key.present?
+        rows -= personal.reject { |row| owner && row["scope_key"] == owner }
+      end
+      rows.each_with_object({}) do |row, all|
+        row["questions"].each do |label, question|
+          lens_label = LensLabel.new(row["id"], label, question)
+          all[lens_label.key] = lens_label
+        end
+      end
+    end
+
+    ACTIVE_TTL = 1.minute
+
+    # The labeling lenses of one tenant from the cache store, so keystroke
+    # search computes its vocabulary version without a query (R12). Any lens
+    # change bumps a per-model generation; the TTL bounds staleness for
+    # per-process cache stores.
+    def active_rows(model, tenant_key)
+      cache = Truffler.config.cache_store
+      generation = cache.read(generation_key(model.polymorphic_name)) || "0"
+      key = "truffler/lenses/#{model.polymorphic_name}/#{generation}/#{Canonical.digest(tenant_key.to_s)}"
+      cache.fetch(key, expires_in: ACTIVE_TTL) do
+        labeling_lenses(model, tenant_key: tenant_key).map do |lens|
+          { "id" => lens.id, "scope_type" => lens.scope_type, "scope_key" => lens.scope_key, "questions" => lens.questions.to_h }
+        end
+      end
+    end
+
+    def changed!(record_type)
+      Truffler.config.cache_store.write(generation_key(record_type), SecureRandom.hex(8))
+    end
+
+    def generation_key(record_type)
+      "truffler/lenses/#{record_type}/generation"
+    end
+
+    def visible(model, tenant_key:, user_key: nil)
+      lenses = visible_lenses(model, tenant_key: tenant_key, user_key: user_key)
+      questions = lenses.each_with_object({}) { |lens, all| all.merge!(lens.storage_questions) }
+      fingerprints = questions.transform_values { |question| fingerprint(question) }
+      Visibility.new(questions: questions, fingerprints: fingerprints,
+        lens_fingerprints: (Canonical.digest(fingerprints) if fingerprints.any?), lens_ids: lenses.map(&:id))
+    end
+
+    # {"lens:<id>:<label>" => wire-shape question} for active visible lenses.
+    def visible_questions(model, tenant_key:, user_key: nil)
+      visible(model, tenant_key: tenant_key, user_key: user_key).questions
+    end
+
+    # A digest of every visible lens label's fingerprint, or nil when no lens
+    # is visible, so a vocabulary without lenses keeps its version.
+    def lens_fingerprints(model, tenant_key:, user_key: nil)
+      visible(model, tenant_key: tenant_key, user_key: user_key).lens_fingerprints
+    end
+
+    # The same formula as Vocabulary#fingerprint: canonical question plus the
+    # pinned Jev model.
+    def fingerprint(question, model: Truffler.config.model)
+      Canonical.digest(question: question, model: model)
+    end
+
+    # Counts a search that used these lenses, which keeps them from expiring
+    # and tells developers which lenses to promote (R43).
+    def record_usage(lens_ids, now: Time.current)
+      return 0 if lens_ids.blank?
+
+      Lens.where(id: lens_ids).update_all([ "usage_count = usage_count + 1, last_used_at = ?, updated_at = ?", now, now ])
+    end
+
+    def digest(user_key)
+      OpenSSL::HMAC.hexdigest("SHA256", Truffler.config.secret_key_base, "truffler/lens/user/#{user_key}")
+    end
+
+    # Descriptions on encrypted models follow the miss-log rules (R29, R44):
+    # AR-encryption ciphertext when it is configured, nothing otherwise.
+    def seal(model, text)
+      Misses.seal(model, text)
+    end
+
+    def unseal(model, stored)
+      Misses.unseal(model, stored)
+    end
+  end
+end

data/lib/truffler/misses/clusterer.rb

@@ -0,0 +1,69 @@
+module Truffler
+  module Misses
+    # Groups normalized queries by shared non-filler terms. The anchor term with
+    # the most distinct users claims every unclaimed query containing it; a
+    # cluster qualifies only when its queries came from enough distinct users,
+    # and it names only terms that each cleared the same gate, so no single
+    # user's wording leaves the log. Tokens with digits or "@" are dropped:
+    # they are exact identifiers (R18), not intents.
+    class Clusterer
+      MAX_TERMS = 3
+      FILLER = %w[
+        a about after all an and any are as at be before by can do find for from get give has have how i in is it
+        list me mine my of on or please search see show that the their them there these this those to was were
+        what when where which who why will with without you your
+      ].to_set.freeze
+
+      def initialize(model, min_distinct_users:)
+        @min = min_distinct_users
+        noun = model.model_name.human.downcase
+        @filler = FILLER | [ noun, noun.pluralize, *noun.split ]
+      end
+
+      # entries: [[normalized query, user digest or nil], ...]
+      def clusters(entries)
+        rows = entries.filter_map do |text, user|
+          terms = terms_for(text)
+          [ terms, user ] if terms.any?
+        end
+        claimed = Array.new(rows.size, false)
+
+        gated_terms(rows).filter_map do |anchor|
+          members = rows.each_index.select { |i| !claimed[i] && rows[i].first.include?(anchor) }
+          users = members.filter_map { |i| rows[i].last }.to_set
+          next if users.size < @min
+
+          members.each { |i| claimed[i] = true }
+          Cluster.new(terms: top_terms(rows.values_at(*members)), query_count: members.size, distinct_users: users.size)
+        end
+      end
+
+      def terms_for(text)
+        text.to_s.scan(/[[:alnum:]@._'-]+/).filter_map do |token|
+          next if token.match?(/[\d@]/)
+
+          term = token.delete("'").gsub(/\A[._-]+|[._-]+\z/, "").singularize
+          term if term.length > 1 && !@filler.include?(term) && !@filler.include?(token)
+        end.uniq
+      end
+
+      private
+
+      def top_terms(rows)
+        gated_terms(rows).first(MAX_TERMS)
+      end
+
+      # Terms seen from enough users, most users first, ties in reading order.
+      def gated_terms(rows)
+        users_by_term(rows).select { |_, users| users.size >= @min }.each_with_index
+          .sort_by { |(_, users), position| [ -users.size, position ] }.map { |(term, _), _| term }
+      end
+
+      def users_by_term(rows)
+        rows.each_with_object(Hash.new { |hash, term| hash[term] = Set.new }) do |(terms, user), index|
+          terms.each { |term| index[term] << user if user }
+        end
+      end
+    end
+  end
+end

data/lib/truffler/misses/recorder.rb

@@ -0,0 +1,29 @@
+module Truffler
+  module Misses
+    # Stores one miss per call. Recording is best-effort: a failure is
+    # instrumented by error class and never raises into the encoding path.
+    class Recorder
+      def call(model, tenant_key:, user_key:, query:)
+        return unless model.try(:truffler_definition)
+
+        normalized = Misses.normalize(query)
+        return if normalized.empty?
+
+        miss = Records::QueryMiss.create!(
+          record_type: model.polymorphic_name,
+          tenant_key: tenant_key&.to_s,
+          query_digest: Misses.digest(:query, normalized),
+          user_digest: (Misses.digest(:user, user_key) if user_key.present?),
+          query_text: Misses.seal(model, normalized)
+        )
+        Instrumentation.instrument("miss", record_type: miss.record_type, tenant_key: miss.tenant_key, outcome: "recorded")
+        miss
+      rescue Truffler::Error, ActiveRecord::ActiveRecordError, ActiveRecord::Encryption::Errors::Base => error
+        Instrumentation.instrument("miss", record_type: model.try(:name), outcome: "error", error_class: error.class.name)
+        Truffler.config.logger.warn("[truffler] query miss not recorded: #{error.class.name}")
+        nil
+      end
+      alias_method :record, :call
+    end
+  end
+end

data/lib/truffler/misses/suggestions.rb

@@ -0,0 +1,49 @@
+module Truffler
+  module Misses
+    # Candidate label questions for developers (F4). Adding one stays a manual
+    # step followed by backfill. Encrypted models without AR encryption have no
+    # stored text, so their qualifying misses surface as digest-only counts.
+    module Suggestions
+      Suggestion = Data.define(:terms, :query_count, :distinct_users, :label_key, :question)
+
+      module_function
+
+      def for(record_type, tenant_key: ALL_TENANTS, min_distinct_users: nil)
+        model = Misses.resolve(record_type)
+        entries = Misses.entries(model, tenant_key: tenant_key)
+        gate = Misses.gate(min_distinct_users)
+        texts = entries.filter_map { |text, user, _| [ text, user ] if text }
+
+        suggestions = Clusterer.new(model, min_distinct_users: gate).clusters(texts).map { |cluster| draft(model, cluster) }
+        suggestions + digest_only(entries.reject(&:first), gate)
+      end
+
+      def report(record_type, io: $stdout, tenant_key: ALL_TENANTS)
+        model = Misses.resolve(record_type)
+        suggestions = self.for(model, tenant_key: tenant_key)
+        return io.puts("No query miss clusters for #{model.name} from at least #{Misses.gate(nil)} distinct users.") if suggestions.empty?
+
+        suggestions.each do |suggestion|
+          terms = suggestion.terms.any? ? suggestion.terms.join(", ") : "(encrypted, no stored text)"
+          io.puts "#{suggestion.query_count} queries from #{suggestion.distinct_users} users: #{terms}"
+          io.puts %(  label :#{suggestion.label_key}, :noul, question: "#{suggestion.question}") if suggestion.question
+        end
+      end
+
+      def draft(model, cluster)
+        Suggestion.new(
+          terms: cluster.terms, query_count: cluster.query_count, distinct_users: cluster.distinct_users,
+          label_key: cluster.terms.join("_").parameterize(separator: "_"),
+          question: "Is this #{model.model_name.human.downcase} about #{cluster.terms.to_sentence}?"
+        )
+      end
+
+      def digest_only(entries, gate)
+        entries.group_by(&:last).filter_map do |_, misses|
+          users = misses.filter_map { |_, user, _| user }.uniq.size
+          Suggestion.new(terms: [], query_count: misses.size, distinct_users: users, label_key: nil, question: nil) if users >= gate
+        end
+      end
+    end
+  end
+end

data/lib/truffler/misses.rb

@@ -0,0 +1,83 @@
+module Truffler
+  # The query miss log (R28, R29). The query encoder calls `hook` when an
+  # encoding matched no label; developers and the lens proposer read only
+  # aggregated clusters that passed the distinct-user gate.
+  module Misses
+    ALL_TENANTS = :all
+    MAX_ROWS = 10_000
+
+    Cluster = Data.define(:terms, :query_count, :distinct_users)
+
+    module_function
+
+    # The callable the encoder invokes: `call(model, tenant_key:, user_key:, query:)`.
+    def hook
+      @hook ||= Recorder.new
+    end
+
+    def record(model, tenant_key:, user_key:, query:)
+      hook.call(model, tenant_key: tenant_key, user_key: user_key, query: query)
+    end
+
+    # Clusters of normalized non-filler terms with their query and distinct-user
+    # counts, newest misses within the retention window only. Every exposed term
+    # was itself seen from at least the gate's number of users. The gate can be
+    # raised per call but never lowered below `miss_min_distinct_users`.
+    def clusters(record_type, tenant_key:, min_distinct_users: nil)
+      model = resolve(record_type)
+      texts = entries(model, tenant_key: tenant_key).filter_map { |text, user, _| [ text, user ] if text }
+      Clusterer.new(model, min_distinct_users: gate(min_distinct_users)).clusters(texts)
+    end
+
+    # [normalized query or nil, user digest, query digest] per retained miss.
+    def entries(model, tenant_key:)
+      scope = Records::QueryMiss.for_model(model).retained
+      scope = scope.where(tenant_key: tenant_key) unless tenant_key == ALL_TENANTS
+      scope.order(created_at: :desc).limit(MAX_ROWS).map { |miss| [ miss.query, miss.user_digest, miss.query_digest ] }
+    end
+
+    def gate(min_distinct_users)
+      [ min_distinct_users.to_i, Truffler.config.miss_min_distinct_users.to_i, 1 ].max
+    end
+
+    def normalize(query)
+      Search::Query.normalize(query)
+    end
+
+    def digest(purpose, value)
+      OpenSSL::HMAC.hexdigest("SHA256", Truffler.config.secret_key_base, "truffler/miss/#{purpose}/#{value}")
+    end
+
+    def encrypted_model?(model)
+      Array(model.try(:encrypted_attributes)).any?
+    end
+
+    def encryption_configured?
+      config = ActiveRecord::Encryption.config
+      config.has_primary_key? && config.has_key_derivation_salt?
+    end
+
+    # Text stored about an encrypted model is AR-encryption ciphertext when
+    # that is configured, and nothing otherwise (R29).
+    def seal(model, text)
+      return text if text.nil? || !encrypted_model?(model)
+
+      ActiveRecord::Encryption.encryptor.encrypt(text) if encryption_configured?
+    end
+
+    def unseal(model, stored)
+      return stored if stored.nil? || !encrypted_model?(model)
+
+      ActiveRecord::Encryption.encryptor.decrypt(stored)
+    rescue ActiveRecord::Encryption::Errors::Base
+      nil
+    end
+
+    def resolve(record_type)
+      model = record_type.is_a?(Class) ? record_type : record_type.to_s.safe_constantize
+      raise ArgumentError, "#{record_type} is not a truffler model" unless model.try(:truffler_definition)
+
+      model
+    end
+  end
+end

data/lib/truffler/model.rb

@@ -0,0 +1,111 @@
+module Truffler
+  module Model
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :truffler_definition, instance_accessor: false, instance_predicate: false
+    end
+
+    class_methods do
+      # With a block, declares what truffler labels and searches. With a
+      # query, runs a keystroke search:
+      #
+      #   Email.truffler("needs action", tenant: account.id, scope: Email.all, user: current_user)
+      def truffler(query = nil, **options, &block)
+        return truffler_search(query, **options) unless block || (query.nil? && options.empty?)
+        raise ArgumentError, "truffler needs a declaration block or a query" unless block
+        raise ArgumentError, "truffler takes a declaration block or a query, not both" if query || options.any?
+
+        definition = Definition.new(self)
+        Definition::DSL.new(definition).instance_exec(&block)
+        definition.validate!
+        install_truffler_callbacks unless truffler_definition
+        self.truffler_definition = definition
+        Truffler.registry.register(self)
+        definition
+      end
+
+      def truffler_search(query, tenant: nil, scope: nil, user: nil, suppressed: [], surface: nil, **options)
+        Search::Keystroke.new(self, query, tenant: tenant, scope: scope, user: user, suppressed: suppressed, surface: surface,
+          **options).call
+      end
+
+      # Records matching the same search that arrived after `since`, usually
+      # a result's watermark (R25).
+      def jev_new_matches_count(query, tenant: nil, scope: nil, user: nil, since:, suppressed: [])
+        Search::Keystroke.new(self, query, tenant: tenant, scope: scope, user: user, suppressed: suppressed).count(since: since)
+      end
+
+      # The explicit action (R22): starts a Smart run and returns it,
+      # already reserved. The keystroke list stays as it was.
+      def jev_smart_search(query, tenant: nil, scope: nil, user: nil, surface: nil, suppressed: [])
+        SmartSearch.start(self, query, tenant: tenant, scope: scope, user: user, surface: surface, suppressed: suppressed)
+      end
+
+      # Cancels the searcher's in-flight Smart run, as on a query edit or a
+      # chip change (R24).
+      def jev_cancel_smart_search(tenant: nil, user: nil, surface: nil)
+        SmartSearch.cancel(self, tenant: tenant, user: user, surface: surface)
+      end
+
+      private
+
+      def install_truffler_callbacks
+        after_commit :truffler_enqueue_labeling, on: %i[create update]
+        after_commit :truffler_forget, on: :destroy
+        after_commit :truffler_enqueue_embedding, on: %i[create update]
+      end
+    end
+
+    # Rewrites this record's host-supplied labels (`label ..., from:`) now,
+    # without Jev. Call it when the host's own classifier updates answers
+    # outside the watched columns, e.g. from the job that classified it.
+    def truffler_refresh_labels!
+      definition = self.class.truffler_definition
+      keys = definition.supplied_labels.map(&:key)
+      Labeling::Supplied.new(self.class).write([ [ self, keys ] ], tenant_key: definition.tenant_key_for(self)) if keys.any?
+      self
+    end
+
+    private
+
+    def truffler_enqueue_labeling
+      definition = self.class.truffler_definition
+      if previously_new_record?
+        Labeling::Queue.new(self.class).enqueue(self)
+        return
+      end
+
+      changed = saved_changes.keys
+      if changed.intersect?([ *definition.fields, definition.tenant_column ].compact)
+        truffler_expire_labels
+      else
+        watched = definition.supplied_labels.select { |label| changed.intersect?(label.watch) }
+        return if watched.empty?
+
+        truffler_expire_labels(watched.map(&:key))
+      end
+      Labeling::Queue.new(self.class).enqueue(self)
+    end
+
+    # Stored values keep serving search until the relabel lands; clearing the
+    # fingerprints is what makes the labeler write or ask them again.
+    def truffler_expire_labels(keys = nil)
+      rows = Records::Label.where(record_type: self.class.polymorphic_name, record_id: id)
+      rows = rows.merge(keys.map { |key| Records::Label.for_label(key) }.reduce(:or)) if keys
+      rows.update_all(fingerprint: "")
+    end
+
+    def truffler_forget
+      Labeling::Queue.new(self.class).forget(self)
+    end
+
+    def truffler_enqueue_embedding
+      definition = self.class.truffler_definition
+      return unless Embeddings.managed?(definition)
+      return unless previously_new_record? || saved_changes.keys.intersect?([ *definition.fields, definition.tenant_column ].compact)
+
+      Jobs::EmbedJob.perform_later(self.class.polymorphic_name, id)
+    end
+  end
+end

data/lib/truffler/providers/backup.rb

@@ -0,0 +1,58 @@
+module Truffler
+  module Providers
+    # Decides whether the provider backup runs for one explicit action and,
+    # when it does, marks the section pending and enqueues the search. Local
+    # sections are never touched.
+    class Backup
+      def initialize(run, query:, tenant_key:, user_key:, local_result: nil)
+        @run = run
+        @query = Search::Query.wrap(query)
+        @tenant_key = tenant_key&.to_s
+        @user_key = user_key&.to_s
+        @local_result = local_result
+      end
+
+      def start
+        provider = Providers.declared(definition)
+        return unless provider
+
+        reason = self.reason
+        instrument(reason)
+        return unless reason
+
+        @run.update_section(SECTION, Providers.state(provider, :pending))
+        Jobs::ProviderSearchJob.perform_later(@run.id.to_s, @tenant_key, @user_key)
+        reason
+      end
+
+      def reason
+        return if @query.blank?
+        return :exact_text if @query.exact_text?
+
+        :weak_local if weak_local?
+      end
+
+      private
+
+      def definition
+        @run.model.truffler_definition
+      end
+
+      def weak_local?
+        return @local_result.invite_row.present? if @local_result
+        return @run.local_weak? if @run.respond_to?(:local_weak?)
+        unless @run.respond_to?(:candidate_ids)
+          raise ArgumentError, "Providers.start needs local_result: or a run that responds to local_weak? or candidate_ids"
+        end
+
+        Array(@run.candidate_ids).size < definition.weak_below
+      end
+
+      def instrument(reason)
+        Instrumentation.instrument("provider_start", run_id: @run.id.to_s, record_type: @run.model.polymorphic_name,
+          tenant_key: @tenant_key, user_key: @user_key, section: SECTION.to_s, outcome: reason ? :enqueued : :skipped,
+          reason: reason)
+      end
+    end
+  end
+end