truffler 0.1.3 → 0.1.5

data/lib/truffler/query_encoding/encoder.rb

@@ -16,7 +16,7 @@ module Truffler
     # label the query applies (its key, a word of its key, the chosen option,
     # or a word of that option's display name, ignoring case and plurals, or
     # sharing its first three letters) becomes a label term, and a common
-    # stopword becomes filler.
+    # stopword or `config.filler_words` noun becomes filler.
     #
     # Answers become a `Search::Encoding` with the KTD20 intent vector: boost
     # gives the declared boost, filter narrows and adds `filter_weight`
@@ -35,10 +35,7 @@ module Truffler
         "filler" => "A word that carries no meaning for the search"
       }.freeze
       NO_OPTION = Truffler::NO_OPTION
-      STOPWORDS = %w[
-        a about all an and any are at be by for from have i in is it me my now of on or our please so some that the their
-        them there they this to up us was we what when where which who why with you your
-      ].to_set.freeze
+      STOPWORDS = Search::Filler::STOPWORDS
 
       Request = Data.define(:state, :questions, :token_ids, :exact_tokens, :unasked_tokens)
 
@@ -120,8 +117,7 @@ module Truffler
         filters = {}
         boosts = {}
         intent = {}
-        stems = []
-        terms = []
+        names = {}
         labels(model, tenant_key, user_key).each_value do |label|
           key = storage_key(label, answers, tenant_key)
           next unless key
@@ -134,16 +130,18 @@ module Truffler
             boosts[key] = intent[key] = label.boost || DEFAULT_BOOST
           else next
           end
-          stems.concat(label_terms(key))
-          terms.concat(name_terms(option_name(label, key, tenant_key)))
+          names[key] = [ label_terms(key), name_terms(option_name(label, key, tenant_key)) ]
         end
 
         query = Search::Query.new(request.state["query"])
-        roles = reconcile(query, request.token_ids.transform_values { |id| answers.choice(id) }, stems.uniq, terms.uniq)
-        keyword_tokens = query.tokens.each_index.filter_map { |position| query.tokens[position] if roles[position] == "keyword" }
-        label_term_tokens = query.tokens.each_index.filter_map { |position| query.tokens[position] if roles[position] == "label_term" }
-        Search::Encoding.new(filters: filters, boosts: boosts, intent_vector: intent, keyword_tokens: keyword_tokens,
-          label_term_tokens: label_term_tokens)
+        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" }),
+          label_term_tokens: tokens.call(sources.keys), soft_keyword_tokens: tokens.call(soft).uniq,
+          filler_tokens: tokens.call(roles.keys.select { |position| roles[position] == "filler" }).uniq,
+          label_term_sources: sources.group_by { |position, _| query.tokens[position] }.transform_values { |pairs| pairs.flat_map(&:last).uniq })
       end
 
       private
@@ -194,35 +192,46 @@ module Truffler
         labels.transform_values do |label|
           entry = { "description" => label.description }
           if label.type == :choice
-            options = label.options(tenant_key)
-            entry["options"] = options.keys
-            names = options.compact
+            entry["options"] = label.options(tenant_key).keys
+            names = label.option_names(tenant_key)
             entry["option_names"] = names if names.any?
           end
           entry
         end
       end
 
-      # {position => role} for every token. Time phrase words are "time";
-      # exact tokens and unasked words are keywords; a keyword naming an
-      # applied label becomes a label term; stopwords become filler unless
-      # they are all that would be left of an encoding that applies nothing.
-      def reconcile(query, answered, stems, terms)
+      # Returns `[roles, sources, soft]`: {position => role} for every token,
+      # {label-term position => applied storage keys it names}, and the
+      # label-term positions that named a key only by prefix. Time phrase
+      # words are "time"; exact tokens and unasked words are keywords; a
+      # 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 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 names_label?(query.tokens[position], stems, terms) }
-        stopwords = words.select { |position| roles[position] == "keyword" && STOPWORDS.include?(query.tokens[position]) }
-        return roles if stems.empty? && roles.values.count("keyword") == stopwords.size
-
-        stopwords.each { |position| roles[position] = "filler" }
-        roles
+        words.each { |position| roles[position] = "label_term" if matches[position].any? }
+        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" }
+        label_terms = roles.keys.select { |position| roles[position] == "label_term" }
+        sources = label_terms.to_h { |position| [ position, matches[position].keys.presence || names.keys ] }
+        soft = (words & label_terms).select { |position| matches[position].values.all?(:prefix) }
+        [ roles, sources, soft ]
       end
 
       # "category:billing" names "category" and "billing"; "needs_action"
       # names "needs_action", "needs", and "action". These key terms also
-      # match by shared stem (see names_label?).
+      # match by shared stem (see label_matches).
       STEM = 3
 
       def label_terms(storage_key)
@@ -231,8 +240,9 @@ module Truffler
           .reject(&:empty?).map(&:singularize)
       end
 
-      # An option's display name adds its words minus stopwords: "p_17" shown
-      # as "Spiral writing tool" names "spiral", "writing", and "tool". These
+      # An option's display name (its search text, else its description) adds
+      # its words minus stopwords: "p_17" shown as "Spiral writing tool" names
+      # "spiral", "writing", and "tool". These
       # match exactly only: descriptions are prose, and a stem match on them
       # would swallow ordinary search words ("chat" against "charge").
       def name_terms(option_name)
@@ -242,16 +252,23 @@ module Truffler
       def option_name(label, storage_key, tenant_key)
         return unless label.type == :choice
 
-        label.options(tenant_key)[Search::Encoding.split_key(storage_key).last]
+        label.option_names(tenant_key)[Search::Encoding.split_key(storage_key).last]
       end
 
-      # "angry" names "anger": the same word ignoring plurals, or, against a
-      # label or option key, two words of four letters or more that share
-      # their first three letters. Display-name words match exactly.
-      def names_label?(word, stems, terms)
+      # {storage key => :exact or :prefix} for the applied labels `word`
+      # names. "angry" names "anger": the same word ignoring plurals is
+      # :exact; against a label or option key, two words of four letters or
+      # more that share their first three letters are :prefix. Display-name
+      # words match exactly only.
+      def label_matches(word, names)
         word = word.singularize
-        terms.include?(word) ||
-          stems.any? { |term| term == word || (word.length > STEM && term.length > STEM && word[0, STEM] == term[0, STEM]) }
+        names.each_with_object({}) do |(key, (stems, terms)), matches|
+          if terms.include?(word) || stems.include?(word)
+            matches[key] = :exact
+          elsif word.length > STEM && stems.any? { |term| term.length > STEM && word[0, STEM] == term[0, STEM] }
+            matches[key] = :prefix
+          end
+        end
       end
 
       def intent_instructions(label)

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

@@ -10,11 +10,20 @@ module Truffler
     #   for the label term SUM(weight * value). Defaults to `boosts`; the
     #   encoder decides whether filtered labels also carry weight here.
     # - `keyword_tokens`: query tokens for the keyword source; nil means
-    #   every token that is not a label term.
+    #   every token that is not a label term or filler.
     # - `label_term_tokens`: tokens that named a label rather than a keyword.
+    # - `label_term_sources`: label-term token => the applied storage keys it
+    #   named. Once the searcher removes every one of them, the token is a
+    #   keyword again.
+    # - `soft_keyword_tokens`: label terms that named a label or option key
+    #   only by shared prefix ("urgently" for urgent). They add a small
+    #   keyword score and are never required.
+    # - `filler_tokens`: stopwords and filler words the encoder dropped.
+    #   Removing the chips that justified the drop brings filler nouns back.
     # - `time`: the query's `TimeRange`, resolved at search time and never
     #   cached, since "today" moves.
-    Encoding = Data.define(:filters, :boosts, :intent_vector, :keyword_tokens, :label_term_tokens, :time) do
+    Encoding = Data.define(:filters, :boosts, :intent_vector, :keyword_tokens, :label_term_tokens, :label_term_sources,
+      :soft_keyword_tokens, :filler_tokens, :time) do
       def self.load(value, query)
         return value if value.is_a?(self)
         return if value.nil?
@@ -22,15 +31,22 @@ module Truffler
         tokens = query.tokens
         new(filters: value["filters"], boosts: value["boosts"], intent_vector: value["intent_vector"],
           keyword_tokens: value["keyword_positions"]&.map { |position| tokens[position] }&.compact,
-          label_term_tokens: Array(value["label_term_positions"]).filter_map { |position| tokens[position] })
+          label_term_tokens: Array(value["label_term_positions"]).filter_map { |position| tokens[position] },
+          label_term_sources: Array(value["label_term_sources"]).filter_map { |position, keys| [ tokens[position], keys ] if tokens[position] },
+          soft_keyword_tokens: Array(value["soft_keyword_positions"]).filter_map { |position| tokens[position] },
+          filler_tokens: Array(value["filler_positions"]).filter_map { |position| tokens[position] })
       end
 
-      def initialize(filters: {}, boosts: {}, intent_vector: nil, keyword_tokens: nil, label_term_tokens: [], time: nil)
+      def initialize(filters: {}, boosts: {}, intent_vector: nil, keyword_tokens: nil, label_term_tokens: [], label_term_sources: {},
+        soft_keyword_tokens: [], filler_tokens: [], time: nil)
         filters = weights(filters)
         boosts = weights(boosts)
         intent_vector = weights(intent_vector || boosts).reject { |_, weight| weight.zero? }
+        sources = label_term_sources.to_h { |token, keys| [ token.to_s, Array(keys).map(&:to_s).freeze ] }
         super(filters: filters.freeze, boosts: boosts.freeze, intent_vector: intent_vector.freeze,
-          keyword_tokens: keyword_tokens&.map(&:to_s)&.freeze, label_term_tokens: Array(label_term_tokens).map(&:to_s).freeze, time: time)
+          keyword_tokens: keyword_tokens&.map(&:to_s)&.freeze, label_term_tokens: Array(label_term_tokens).map(&:to_s).freeze,
+          label_term_sources: sources.freeze, soft_keyword_tokens: Array(soft_keyword_tokens).map(&:to_s).freeze,
+          filler_tokens: Array(filler_tokens).map(&:to_s).freeze, time: time)
       end
 
       def empty?
@@ -38,14 +54,26 @@ module Truffler
       end
 
       # The encoding minus the chips the searcher removed (R20), matched by
-      # storage key or by label key; "time" removes the time range.
-      def without(suppressed)
+      # storage key or by label key; "time" removes the time range. A label
+      # 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?
 
         keep = ->(key, _) { !suppressed.include?(key) && !suppressed.include?(self.class.split_key(key).first) }
-        with(filters: filters.select(&keep), boosts: boosts.select(&keep), intent_vector: intent_vector.select(&keep),
-          time: (time unless suppressed.include?(TimeRange.key)))
+        kept = { filters: filters.select(&keep), boosts: boosts.select(&keep), intent_vector: intent_vector.select(&keep) }
+        applied = kept.values.flat_map(&:keys).to_set
+        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
+        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)
       end
 
       # Splits a storage key into its label key and choice option. Lens keys
@@ -60,8 +88,13 @@ module Truffler
         end
       end
 
-      def keywords(query)
-        keyword_tokens || (query.search_tokens - label_term_tokens)
+      # Without encoder decisions (a cold cache), every search token that is
+      # 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,
+            keep: keep&.call)
       end
 
       # The cache form: decisions plus token positions in the normalized
@@ -70,7 +103,12 @@ module Truffler
       def dump(query)
         { "filters" => filters, "boosts" => boosts, "intent_vector" => intent_vector,
           "keyword_positions" => keyword_tokens && positions(query, keyword_tokens),
-          "label_term_positions" => positions(query, label_term_tokens) }
+          "label_term_positions" => positions(query, label_term_tokens),
+          "label_term_sources" => query.tokens.each_index.filter_map do |position|
+            [ position, label_term_sources[query.tokens[position]] ] if label_term_sources.key?(query.tokens[position])
+          end,
+          "soft_keyword_positions" => positions(query, soft_keyword_tokens),
+          "filler_positions" => positions(query, filler_tokens) }
       end
 
       private

data/lib/truffler/search/encoding_cache.rb

@@ -1,8 +1,9 @@
 module Truffler
   module Search
     # Where keystroke search finds query encodings and query vectors (R12,
-    # R15). Keys digest the model, the normalized query, and the vocabulary
-    # version, plus the tenant when the vocabulary has per-tenant choices.
+    # R15). Keys digest the model, the normalized query, and the vocabulary's
+    # encoding version (labeling fingerprints plus descriptions and option
+    # search texts), plus the tenant when the vocabulary has per-tenant choices.
     # Values hold decisions and floats, never query text. Encoding keys use
     # the searcher's vocabulary version, which holds the lenses that searcher
     # can see (KTD21), so a personal lens's encoding is never shared; query
@@ -60,7 +61,7 @@ module Truffler
       def digest(model, query, tenant_key, user_key)
         definition = model.truffler_definition
         tenant = tenant_key&.to_s if definition.per_tenant_vocabulary?
-        version = definition.vocabulary.version(tenant_key: tenant_key&.to_s, user_key: user_key)
+        version = definition.vocabulary.encoding_version(tenant_key: tenant_key&.to_s, user_key: user_key)
         Canonical.digest(record_type: model.polymorphic_name, query: query.normalized, vocabulary_version: version, tenant_key: tenant)
       end
     end

data/lib/truffler/search/filler.rb

@@ -0,0 +1,73 @@
+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 "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
+    # time range, so a lone "customers" still searches text.
+    module Filler
+      STOPWORDS = %w[
+        a about all an and any are at be by for from have i in is it me my now of on or our please so some that the their
+        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 item items stuff thing things].freeze
+
+      module_function
+
+      def stopword?(word)
+        STOPWORDS.include?(word.to_s.downcase)
+      end
+
+      # `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
+      # filler nouns stay as keywords and only pure stopwords go ("customers
+      # in the" searches "customers"); if every word is a stopword, all stay.
+      def drop(candidates, keyword_count:, anchored:, stopword: ->(candidate) { stopword?(candidate) })
+        return candidates if anchored || candidates.size < keyword_count
+
+        stopwords = candidates.select(&stopword)
+        stopwords.size == candidates.size ? [] : stopwords
+      end
+
+      # `tokens` minus filler words, or only minus stopwords when nothing else
+      # 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
+  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