truffler 0.1.4 → 0.1.5

data/lib/truffler/labeling/labeler.rb

@@ -23,7 +23,7 @@ module Truffler
         return Result.new(labeled: 0, requests: 0, cost: 0.0, demoted: false) if states.empty?
 
         tenant_key = tenant_key_of(states)
-        records = load_records(states)
+        records = load_records(states, tenant_key)
         vocabulary = definition.vocabulary
         @labels = vocabulary.labels_for(tenant_key: tenant_key, all_users: true)
         fingerprints = vocabulary.fingerprints(tenant_key: tenant_key, all_users: true)
@@ -87,17 +87,31 @@ module Truffler
         tenants.first
       end
 
-      def load_records(states)
-        records = model.where(model.primary_key => states.map(&:record_id)).to_a
+      # Records deleted or outside index_scope / index_if lose their state
+      # rows instead of being labeled. A disabled tenant keeps its state rows:
+      # they go back to pending at backfill priority, so re-enabling it
+      # relabels only what is stale instead of every record.
+      def load_records(states, tenant_key)
+        unless definition.tenant_enabled?(tenant_key)
+          Records::RecordState.where(id: states.map(&:id))
+            .update_all(status: "pending", priority: "backfill", claimed_at: nil, updated_at: Time.current)
+          return []
+        end
+
+        records = definition.index_relation(model.where(model.primary_key => states.map(&:record_id))).to_a
+          .select { |record| definition.index_if.nil? || definition.index_if.call(record) }
         found = records.map { |record| record.id.to_s }
         gone = states.reject { |state| found.include?(state.record_id.to_s) }
         Records::RecordState.where(id: gone.map(&:id)).delete_all if gone.any?
         records
       end
 
+      # A label is current when it has stored rows and all carry its current
+      # fingerprint; choice labels store only some options (see sparse_choice).
       def stale_keys(stored, fingerprints, tenant_key, askable)
         askable.reject do |label|
-          label.storage_keys(tenant_key).all? { |key| stored[key] == fingerprints[label.key] }
+          present = label.storage_keys(tenant_key).select { |key| stored.key?(key) }
+          present.any? && present.all? { |key| stored[key] == fingerprints[label.key] }
         end.map(&:key)
       end
 
@@ -154,7 +168,8 @@ module Truffler
         case label.type
         when :noul then [ [ label.key, answers.noul(id) ] ]
         when :score then [ [ label.key, answers.score(id) ] ]
-        when :choice then label.options(tenant_key).keys.map { |option| [ "#{label.key}:#{option}", answers.probability(id, option) ] }
+        when :choice
+          LabelDefinition.sparse_choice(label.options(tenant_key).keys.to_h { |option| [ "#{label.key}:#{option}", answers.probability(id, option) ] }).to_a
         end
       end
     end

data/lib/truffler/labeling/queue.rb

@@ -3,6 +3,8 @@ module Truffler
     # State transitions on truffler_record_states for one model, plus the
     # deduplicated scheduling of LabelFlushJob per tenant and of BackfillJob
     # for demoted rows. Jobs carry only the record type and tenant key.
+    # Records the definition does not index (a disabled tenant, `index_if`)
+    # are never enqueued.
     class Queue
       BACKFILL_WAIT = 1.minute
 
@@ -15,13 +17,15 @@ module Truffler
       end
 
       def enqueue(record, priority: :live)
+        return unless definition.indexable?(record)
+
         tenant_key = definition.tenant_key_for(record)
         now = Time.current
         Records::RecordState.upsert(
           { record_type: record_type, record_id: record.id, tenant_key: tenant_key, status: "pending",
             priority: priority.to_s, attempts: 0, created_at: now, updated_at: now },
           unique_by: %i[record_type record_id],
-          update_only: %i[tenant_key status priority attempts updated_at]
+          update_only: %i[tenant_key status priority attempts]
         )
         schedule(tenant_key)
       end
@@ -41,13 +45,14 @@ module Truffler
         job.perform_later(record_type, tenant_key)
       end
 
-      # Starts a backfill shortly after live rows are demoted over the tenant
-      # cap. One per model per marker lifetime; ResumeJob still catches rows a
-      # dropped job leaves behind.
-      def schedule_backfill
-        return unless config.cache_store.write(backfill_marker, true, unless_exist: true, expires_in: BACKFILL_WAIT + 300)
+      # Starts a backfill of the tenant shortly after its live rows are
+      # demoted over the tenant cap. One per tenant per marker lifetime;
+      # ResumeJob still catches rows a dropped job leaves behind.
+      def schedule_backfill(tenant_key = nil)
+        return unless definition.tenant_enabled?(tenant_key)
+        return unless config.cache_store.write(backfill_marker(tenant_key), true, unless_exist: true, expires_in: BACKFILL_WAIT + 300)
 
-        Jobs::BackfillJob.set(wait: BACKFILL_WAIT).perform_later(record_type)
+        Jobs::BackfillJob.set(wait: BACKFILL_WAIT).perform_later(record_type, **Jobs::BackfillJob.tenant_argument(model, tenant_key))
       end
 
       def clear_marker(tenant_key)
@@ -118,8 +123,8 @@ module Truffler
         "truffler/flush/#{record_type}/#{tenant_key}"
       end
 
-      def backfill_marker
-        "truffler/backfill/#{record_type}"
+      def backfill_marker(tenant_key)
+        "truffler/backfill/#{record_type}/#{tenant_key}"
       end
     end
   end

data/lib/truffler/labeling/supplied.rb

@@ -4,9 +4,13 @@ module Truffler
     # of one tenant into truffler_labels, under the same storage keys as asked
     # labels, and rewrites those records' label vectors. No Jev request, no
     # budget slot, no spend. A nil answer stores nothing, so the label reads
-    # as missing rather than 0. A `from` that raises or answers out of shape
-    # is instrumented as `supplied_label_failed`, skipped, and listed in
-    # `failed_ids` so the caller can retry it; its stored rows serve meanwhile.
+    # as missing rather than 0. Both failures are instrumented as
+    # `supplied_label_failed`. An answer out of shape (InvalidSuppliedAnswer)
+    # is permanent (`permanent: true`): it stores nothing for that label,
+    # like a nil answer, and the record settles, since retrying the same
+    # answer cannot succeed. A `from` that raises anything else is transient:
+    # the label is skipped and listed in `failed_ids` so the caller retries
+    # it (failed after max_attempts); its stored rows serve meanwhile.
     class Supplied
       attr_reader :model, :failed_ids
 
@@ -61,11 +65,18 @@ module Truffler
 
       def answer(label, record, tenant_key)
         label.supplied_values(record, tenant_key)
+      rescue InvalidSuppliedAnswer => error
+        instrument_failure(label, record, tenant_key, error, permanent: true)
+        nil
       rescue StandardError => error
-        Instrumentation.instrument(:supplied_label_failed, record_type: record_type, tenant_key: tenant_key, record_id: record.id,
-          label_key: label.key, error_class: error.class.name)
+        instrument_failure(label, record, tenant_key, error, permanent: false)
         :failed
       end
+
+      def instrument_failure(label, record, tenant_key, error, permanent:)
+        Instrumentation.instrument(:supplied_label_failed, record_type: record_type, tenant_key: tenant_key, record_id: record.id,
+          label_key: label.key, error_class: error.class.name, permanent: permanent)
+      end
     end
   end
 end

data/lib/truffler/lenses/backfill.rb

@@ -37,6 +37,8 @@ module Truffler
 
           attempted.concat(records.map(&:id))
           records.group_by { |record| definition.tenant_key_for(record) }.each do |tenant_key, slice|
+            next unless definition.tenant_enabled?(tenant_key)
+
             stop = label(slice, tenant_key)
             return result(stop) if stop
           end
@@ -70,22 +72,38 @@ module Truffler
       # lens row.
       def page(attempted)
         pk = model.primary_key
-        scope = model.all
-        scope = scope.where(definition.tenant_column => lens.tenant_key) if definition.scoped? && lens.tenant_key
+        scope = definition.index_relation(model.all)
+        if definition.scoped? && lens.tenant_key
+          return [] unless definition.tenant_enabled?(lens.tenant_key)
+
+          scope = scope.where(definition.tenant_column => lens.tenant_key)
+        elsif definition.scoped? && Truffler.config.tenant_enabled
+          scope = scope.where(definition.tenant_column => enabled_tenants)
+        end
         scope = scope.where.not(pk => attempted) if attempted.any?
         scope.where(Arel.sql(stale_sql)).reorder(definition.arrival_order).limit(batch_size).to_a
       end
 
+      # Tenants in index_scope that config.tenant_enabled allows, looked up
+      # once per run, so disabled tenants are never paged (and never refetched
+      # by the next LensBackfillJob).
+      def enabled_tenants
+        @enabled_tenants ||= definition.index_relation(model.all).reorder(nil).distinct.pluck(definition.tenant_column)
+          .select { |tenant_key| definition.tenant_enabled?(tenant_key.to_s) }
+      end
+
+      # Stale unless every lens label has a row under its current fingerprint;
+      # a choice label stores only some of its options.
       def stale_sql
-        expected = lens.labels.values.flat_map do |label|
-          print = Lenses.fingerprint(label.question)
-          label.storage_keys.map { |key| ActiveRecord::Base.sanitize_sql_array([ "(label_key = ? AND fingerprint = ?)", key, print ]) }
-        end
         pk = "#{model.quoted_table_name}.#{model.connection.quote_column_name(model.primary_key)}"
-        ActiveRecord::Base.sanitize_sql_array([
-          "(SELECT COUNT(*) FROM #{LABELS} WHERE #{LABELS}.record_type = ? AND #{LABELS}.record_id = #{pk} " \
-          "AND (#{expected.join(' OR ')})) < ?", model.polymorphic_name, expected.size
-        ])
+        current = lens.labels.values.map do |label|
+          ActiveRecord::Base.sanitize_sql_array([
+            "EXISTS (SELECT 1 FROM #{LABELS} WHERE #{LABELS}.record_type = ? AND #{LABELS}.record_id = #{pk} " \
+            "AND #{LABELS}.label_key IN (?) AND #{LABELS}.fingerprint = ?)",
+            model.polymorphic_name, label.storage_keys, Lenses.fingerprint(label.question)
+          ])
+        end
+        "NOT (#{current.join(' AND ')})"
       end
 
       # Labels one tenant's records through the labeler, which asks only

data/lib/truffler/model.rb

@@ -62,6 +62,8 @@ module Truffler
     # outside the watched columns, e.g. from the job that classified it.
     def truffler_refresh_labels!
       definition = self.class.truffler_definition
+      return self unless definition.indexable?(self)
+
       tenant_key = definition.tenant_key_for(self)
       keys = definition.supplied_labels.select { |label| label.available?(tenant_key) }.map(&:key)
       Labeling::Supplied.new(self.class).write([ [ self, keys ] ], tenant_key: tenant_key) if keys.any?
@@ -72,6 +74,8 @@ module Truffler
 
     def truffler_enqueue_labeling
       definition = self.class.truffler_definition
+      return unless definition.indexable?(self)
+
       if previously_new_record?
         Labeling::Queue.new(self.class).enqueue(self)
         return
@@ -105,6 +109,7 @@ module Truffler
       definition = self.class.truffler_definition
       return unless Embeddings.managed?(definition)
       return unless previously_new_record? || saved_changes.keys.intersect?(definition.relabel_columns)
+      return unless definition.indexable?(self)
 
       Jobs::EmbedJob.perform_later(self.class.polymorphic_name, id)
     end

data/lib/truffler/providers/backup.rb

@@ -39,7 +39,7 @@ module Truffler
       end
 
       def weak_local?
-        return @local_result.invite_row.present? if @local_result
+        return @local_result.local_weak? 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"

data/lib/truffler/query_encoding/encoder.rb

@@ -134,7 +134,8 @@ module Truffler
         end
 
         query = Search::Query.new(request.state["query"])
-        roles, sources, soft = reconcile(query, request.token_ids.transform_values { |id| answers.choice(id) }, names)
+        roles, sources, soft = reconcile(query, request.token_ids.transform_values { |id| answers.choice(id) }, names,
+          Search::Filler.label_words(model.truffler_definition, tenant_key))
         tokens = ->(positions) { positions.map { |position| query.tokens[position] } }
         Search::Encoding.new(filters: filters, boosts: boosts, intent_vector: intent,
           keyword_tokens: tokens.call(roles.keys.select { |position| roles[position] == "keyword" }),
@@ -206,16 +207,19 @@ module Truffler
       # keyword naming an applied label becomes a label term; stopwords and
       # filler words become filler unless they are all that would be left of
       # an encoding that applies no label and no time range (Search::Filler).
-      # A word Jev called a label term that names no applied label locally
-      # is sourced to every applied label.
-      def reconcile(query, answered, names)
+      # A word naming any declared label (`keep`, see Filler.label_words) is
+      # never filler, even when Jev calls it that. A word Jev called a label
+      # term that names no applied label locally is sourced to every applied
+      # label.
+      def reconcile(query, answered, names, keep)
         roles = query.tokens.each_index.to_h do |position|
-          [ position, query.time_position?(position) ? "time" : answered.fetch(position, "keyword") ]
+          role = query.time_position?(position) ? "time" : answered.fetch(position, "keyword")
+          [ position, role == "filler" && keep.include?(query.tokens[position].singularize) ? "keyword" : role ]
         end
         matches = roles.keys.to_h { |position| [ position, roles[position] == "time" ? {} : label_matches(query.tokens[position], names) ] }
         words = roles.keys.select { |position| roles[position] == "keyword" && !query.exact_tokens.include?(query.tokens[position]) }
         words.each { |position| roles[position] = "label_term" if matches[position].any? }
-        filler = words.select { |position| roles[position] == "keyword" && Search::Filler.word?(query.tokens[position]) }
+        filler = words.select { |position| roles[position] == "keyword" && Search::Filler.word?(query.tokens[position], keep: keep) }
         Search::Filler.drop(filler, keyword_count: roles.values.count("keyword"), anchored: names.any? || !query.time_phrase.nil?,
           stopword: ->(position) { Search::Filler.stopword?(query.tokens[position]) })
           .each { |position| roles[position] = "filler" }

data/lib/truffler/records/backfill_spend.rb

@@ -1,9 +1,9 @@
 module Truffler
   module Records
-    # The backfill spend ledger: one row per model and app-wide vocabulary
-    # version, so a spend cap holds across runs, reruns, and overlapping
-    # BackfillJob chains. Spend is reserved and settled in SQL, never read,
-    # added to, and written back.
+    # The backfill spend ledger: one row per model, tenant (nil for the
+    # app-wide ledger), and vocabulary version, so a spend cap holds across
+    # runs, reruns, and overlapping BackfillJob chains. Spend is reserved and
+    # settled in SQL, never read, added to, and written back.
     class BackfillSpend < ActiveRecord::Base
       self.table_name = "truffler_backfill_spends"
 
@@ -18,10 +18,34 @@ module Truffler
         false
       end
 
-      def self.ledger(model, version)
-        create_or_find_by!(record_type: model.polymorphic_name, vocabulary_version: version)
+      def self.for_ledger(model, tenant_key)
+        tenant_ledgers? ? for_model(model).where(tenant_key: tenant_key) : for_model(model)
       end
 
+      # Before `rails g truffler:upgrade` adds tenant_key, every tenant
+      # shares the app-wide row.
+      def self.ledger(model, version, tenant_key: nil)
+        attributes = { record_type: model.polymorphic_name, vocabulary_version: version }
+        attributes[:tenant_key] = tenant_key if tenant_ledgers?
+        create_or_find_by!(attributes)
+      end
+
+      def self.tenant_ledgers?
+        return true if column_names.include?("tenant_key")
+
+        warn_missing_tenant_key
+        false
+      end
+
+      def self.warn_missing_tenant_key
+        return if @missing_tenant_warned
+
+        @missing_tenant_warned = true
+        Truffler.config.logger.warn("[truffler] #{table_name}.tenant_key is missing, so backfill spend caps are app-wide. " \
+          "Run `bin/rails g truffler:upgrade && bin/rails db:migrate`.")
+      end
+      private_class_method :warn_missing_tenant_key
+
       def self.warn_missing
         return if @missing_warned
 

data/lib/truffler/redaction.rb

@@ -6,7 +6,7 @@ module Truffler
   module Redaction
     KEYS = %i[
       priority model cost input_tokens tokens_estimated latency_ms error_class status outcome reason
-      record_type tenant_key user_key surface section sources vocabulary_version label_key
+      record_type tenant_key user_key surface section sources vocabulary_version label_key permanent
     ].to_set.freeze
     SUFFIXES = %w[_id _ids _count _digest _ms].freeze
 

data/lib/truffler/search/encoding.rb

@@ -55,8 +55,10 @@ module Truffler
 
       # The encoding minus the chips the searcher removed (R20), matched by
       # storage key or by label key; "time" removes the time range. A label
-      # term whose every source label is gone becomes a keyword again.
-      def without(suppressed)
+      # term whose every source label is gone becomes a keyword again. `keep_words`
+      # (a set, or a callable returning one) holds the words that are never
+      # filler, as in `keywords`.
+      def without(suppressed, keep_words: nil)
         suppressed = Array(suppressed).map(&:to_s).to_set
         return self if suppressed.empty?
 
@@ -66,7 +68,9 @@ module Truffler
         freed = label_term_sources.select { |_, keys| keys.any? && keys.none? { |key| applied.include?(key) } }.keys
         kept_time = (time unless suppressed.include?(TimeRange.key))
         keywords = keyword_tokens && (keyword_tokens + freed).uniq
-        keywords = Filler.keywords(keywords + filler_tokens, anchored: false) if keywords && applied.empty? && kept_time.nil?
+        if keywords && applied.empty? && kept_time.nil?
+          keywords = Filler.keywords(keywords + filler_tokens, anchored: false, keep: keep_words.respond_to?(:call) ? keep_words.call : keep_words)
+        end
         with(**kept, time: kept_time, label_term_tokens: label_term_tokens - freed,
           label_term_sources: label_term_sources.except(*freed), soft_keyword_tokens: soft_keyword_tokens - freed,
           keyword_tokens: keywords)
@@ -85,10 +89,12 @@ module Truffler
       end
 
       # Without encoder decisions (a cold cache), every search token that is
-      # not a label term, minus filler words (see Filler).
-      def keywords(query)
+      # not a label term, minus filler words (see Filler). `keep` is called
+      # only then, for the words that are never filler.
+      def keywords(query, keep: nil)
         keyword_tokens ||
-          Filler.keywords(query.search_tokens - label_term_tokens, anchored: !empty? || !time.nil?, exact: query.exact_tokens)
+          Filler.keywords(query.search_tokens - label_term_tokens, anchored: !empty? || !time.nil?, exact: query.exact_tokens,
+            keep: keep&.call)
       end
 
       # The cache form: decisions plus token positions in the normalized

data/lib/truffler/search/filler.rb

@@ -1,7 +1,7 @@
 module Truffler
   module Search
     # Words that carry no search meaning on their own: common stopwords and
-    # `config.filler_words` (generic nouns such as "customers" or "emails",
+    # `config.filler_words` (generic nouns such as "customers" or "items",
     # matched ignoring plurals). One rule serves the encoder's reconcile and
     # the cold-cache keywords: filler is dropped as a keyword unless dropping
     # it would leave the search with no keyword, no applied label, and no
@@ -12,7 +12,7 @@ module Truffler
         them there they this to up us was we what when where which who why with you your
       ].to_set.freeze
 
-      DEFAULT_WORDS = %w[customer customers people person user users message messages email emails item items stuff thing things].freeze
+      DEFAULT_WORDS = %w[customer customers people person user users message messages item items stuff thing things].freeze
 
       module_function
 
@@ -20,11 +20,34 @@ module Truffler
         STOPWORDS.include?(word.to_s.downcase)
       end
 
-      def word?(word, filler_words: Truffler.config.filler_words)
+      # `keep` holds singular words that are never filler (see label_words).
+      def word?(word, filler_words: Truffler.config.filler_words, keep: nil)
         word = word.to_s.downcase
+        return false if keep&.include?(word.singularize)
+
         stopword?(word) || Array(filler_words).any? { |filler| filler.to_s.downcase.singularize == word.singularize }
       end
 
+      # Singular words that name one of the model's declared labels for this
+      # tenant, applied or not: words of a label key, of a choice option key,
+      # and of an option's search text (not its description, which is prose).
+      # Such a word is never filler, so "text messages" still searches
+      # "messages" when an option's search text is "text message".
+      def label_words(definition, tenant_key = nil)
+        definition.labels.each_value.with_object(Set.new) do |label, words|
+          next unless label.available?(tenant_key)
+
+          names = [ label.key ]
+          if label.type == :choice
+            options = label.encoding_wording(tenant_key)[:options]
+            names.concat(options.keys, options.values.filter_map { |entry| entry[:search] })
+          end
+          names.each do |name|
+            name.to_s.downcase.split(/[^\p{Alnum}]+/).each { |word| words << word.singularize unless word.empty? || stopword?(word) }
+          end
+        end
+      end
+
       # The subset of `candidates` (droppable keywords) to drop, given how many
       # keywords there are and whether a label or time range is applied. When
       # nothing anchors the search and only droppable words are left, the
@@ -38,9 +61,11 @@ module Truffler
       end
 
       # `tokens` minus filler words, or only minus stopwords when nothing else
-      # would anchor the search. Exact tokens (a quoted "the") are never filler.
-      def keywords(tokens, anchored:, exact: [])
-        dropped = drop(tokens.select { |token| !exact.include?(token) && word?(token) }, keyword_count: tokens.size, anchored: anchored)
+      # would anchor the search. Exact tokens (a quoted "the") and `keep`
+      # words are never filler.
+      def keywords(tokens, anchored:, exact: [], keep: nil)
+        dropped = drop(tokens.select { |token| !exact.include?(token) && word?(token, keep: keep) }, keyword_count: tokens.size,
+          anchored: anchored)
         tokens - dropped
       end
     end

data/lib/truffler/search/keystroke.rb

@@ -41,12 +41,12 @@ module Truffler
         explicit_action = surface_action
         cached = read_encoding
         status = encoding_status(cached)
-        encoding = with_time(visible_lenses_only(cached&.without(suppressed), record_usage: true))
+        encoding = visible_lenses_only(with_time(cached)&.without(suppressed, keep_words: label_words), record_usage: true)
         sql = sql(encoding)
         records = sql.relation(scope, limit: limit).to_a
         result = Result.new(records: records, query: query, encoding: encoding, encoding_status: status, watermark: watermark,
-          explicit_action: explicit_action, sources: sql.sources, invite_row: invite_row(records, cached),
-          weights: @weights, recount: ->(since) { count(since: since) })
+          explicit_action: explicit_action, sources: sql.sources, invite_row: invite_row(records, cached, status),
+          local_weak: local_weak?(records, cached), weights: @weights, recount: ->(since) { count(since: since) })
         instrument(result, started)
         result
       end
@@ -54,7 +54,7 @@ module Truffler
       # How many records the same search would return that arrived after
       # `since` (R25). Reads the cache only and never prefetches.
       def count(since:)
-        sql(with_time(visible_lenses_only(read_encoding&.without(suppressed)))).candidates(scope)
+        sql(visible_lenses_only(with_time(read_encoding)&.without(suppressed, keep_words: label_words))).candidates(scope)
           .where(model.arel_table[@definition.arrived_at_column].gt(since)).count
       end
 
@@ -83,6 +83,10 @@ module Truffler
 
       # Drops lens keys this searcher cannot see (another user's personal
       # lens, an expired lens) and counts a use of the rest (R42, R43).
+      def label_words
+        -> { Filler.label_words(@definition, tenant_key) }
+      end
+
       def visible_lenses_only(encoding, record_usage: false)
         lens_keys = encoding ? (encoding.intent_vector.keys | encoding.filters.keys | encoding.boosts.keys).select { |key| lens_id(key) } : []
         return encoding if lens_keys.empty?
@@ -90,11 +94,12 @@ module Truffler
         visible = Lenses.labels(model, tenant_key: tenant_key, user_key: user_key).values.map(&:lens_id).uniq
         hidden, shown = lens_keys.partition { |key| !visible.include?(lens_id(key)) }
         Lenses.record_usage(shown.map { |key| lens_id(key) }.uniq) if record_usage
-        encoding.without(hidden)
+        encoding.without(hidden, keep_words: label_words)
       end
 
       # The query's time phrase, resolved on this search's clock, unless the
-      # searcher removed its chip.
+      # searcher removed its chip. Attached before `without`, which keeps
+      # filler dropped while a time range still anchors the search.
       def with_time(encoding)
         phrase = query.time_phrase
         return encoding if phrase.nil? || suppressed.include?(TimeRange.key)
@@ -133,20 +138,29 @@ module Truffler
         Sql.new(model, tenant_key: tenant_key, query: query, encoding: encoding, vector: read_vector, weights: @weights)
       end
 
-      # R21: the Smart search row. A model with no local text search whose
-      # encoding is not cached yet invites the action even when a blind index
-      # matched, because intent queries resolve on the action there (AE10).
-      def invite_row(records, cached)
+      # R21: the Smart search row. A query whose encoding is not cached yet
+      # invites the action even when a blind index or keyword matched,
+      # because a first-time intent query resolves on the action (AE10): on a
+      # model with no local text search always, and with a `keyword` source
+      # while the encoding is in flight unless `invite_on_pending_encoding false`.
+      def invite_row(records, cached, status)
         return if query.blank?
 
-        reason =
-          if @definition.keyword.blank? && cached.nil? then :encoding_pending
-          elsif records.empty? then :empty
-          elsif records.size < @definition.weak_below then :weak
-          end
+        pending = cached.nil? && (@definition.keyword.blank? || (@definition.invite_on_pending_encoding && status == :pending))
+        reason = pending ? :encoding_pending : weak_reason(records)
         { query: query.raw.strip, reason: reason } if reason
       end
 
+      def weak_reason(records)
+        if records.empty? then :empty
+        elsif records.size < @definition.weak_below then :weak
+        end
+      end
+
+      def local_weak?(records, cached)
+        !query.blank? && (weak_reason(records).present? || (@definition.keyword.blank? && cached.nil?))
+      end
+
       def instrument(result, started)
         payload = { record_type: model.polymorphic_name, tenant_key: tenant_key, surface: surface, outcome: result.encoding_status,
           result_count: result.records.size, filter_count: result.encoding&.filters&.size.to_i,

data/lib/truffler/search/result.rb

@@ -12,7 +12,9 @@ module Truffler
 
       attr_reader :records, :query, :encoding, :encoding_status, :watermark, :explicit_action, :sources, :invite_row
 
-      def initialize(records:, query:, encoding:, encoding_status:, watermark:, explicit_action:, sources:, invite_row:, weights:, recount:)
+      def initialize(records:, query:, encoding:, encoding_status:, watermark:, explicit_action:, sources:, invite_row:, weights:, recount:,
+        local_weak: nil)
+        @local_weak = local_weak
         @records = records
         @query = query
         @encoding = encoding
@@ -29,6 +31,14 @@ module Truffler
         records.map(&:id)
       end
 
+      # Whether the local list is too weak to stand alone, which starts the
+      # backup provider on the explicit action. An `:encoding_pending` row on
+      # a model with a `keyword` source invites Smart search without making
+      # the list weak.
+      def local_weak?
+        @local_weak.nil? ? invite_row.present? : @local_weak
+      end
+
       # Applied filters, then boosts, then the time range, as `{key:, label:, kind:, name:}`.
       def chips
         return [] unless encoding