truffler 0.1.5 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 41cc5bfdb1f4f8a5b18ab9388518140bb5b2c927c87f115094c43ffa1c37659a
-  data.tar.gz: 11ee26029552cfaaa18d68fed182a2ede4641f9491c942eecbf6aa86326baef8
+  metadata.gz: 1e678dd275fc608a97a93cc9eb7a881ae686c4cc428bfe2a823310f2d5a4b559
+  data.tar.gz: 3145a1087183f63dae1baf3bd38237761760f368b79828860af802c81caea690
 SHA512:
-  metadata.gz: b1bc305d0c1745424ce0c55e905a6f592a423f37274edb420def42073119de9f089ac52fded8f0af0319327e9e7e3738b41e6d62fe77ec1d398d1f7c7bddd170
-  data.tar.gz: 8dd567f12f014c36ac80e900a87965390cbaae8f3c3e63e588cd6668510e68afc020f8d0039198fea2c13a98aabff2425b6a5eef839c5b3be64864ca8be1e868
+  metadata.gz: ebe167d14a66fc74e219e1a5f9206ba158018418b87437b212e51eb6e356c27dd35a5312e443f6cd108a21f57c223e7219c39f5ed45d44ac643aae1feb08a103
+  data.tar.gz: 2352317c03e9c9e8b91597efdf3aab02ea09ca54bb9ff3bb9bcf1fc0a214d1b23d62f1542ef3c7f6866e720f7e7624aa9eab23bea04fe6fe86c649a20e5faaaf

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [0.1.6]
+
+A fix from happyhappy production and follow-ups from 0.1.5.
+
+- Zero-result relaxation. With a Cora product filter applied, the word "email" became a `Source: email` filter chip and results dropped from 50 to 0 because the tenant has no email sources. When a keystroke search under the encoding's filters returns nothing but would match without them, those filters now become soft boosts: they stay in the intent vector so matching records rank first, but nothing requires them. The words they consumed become keywords again. Truffler first relaxes only the filters no record in the tenant carries at their threshold and keeps the rest, then every filter if that still finds nothing. It never relaxes into "every record in the tenant" when no word, exact match, or vector match remains. The fallback costs one extra query, only on an empty result; non-empty keystrokes stay one SELECT. `Result#relaxed_labels` lists the relaxed storage keys, and their chips carry `relaxed: true`. Chips the searcher removed stay removed. Smart search candidate filtering falls back the same way instead of reranking an empty set, and records `relaxed_labels` on the run (`run.to_h`).
+- New `config.skip_empty_options` (default false). When true, query encoding offers Jev only the choice options the tenant has label rows for (at or above `choice_min_probability`) and leaves out choice labels with none. The present-option set is digested into the encoding cache key and cached for 5 minutes, so a new option reaches encoding within that TTL and keystrokes stay one SELECT.
+- `truffler:install` and `truffler:upgrade` migration templates pass rubocop-rails-omakase (`[ :a, :b ]` array brackets). A test renders every template and runs RuboCop with the omakase config on the output.
+- `Records::BackfillSpend` no longer caches a missing `truffler_backfill_spends.tenant_key` for the life of the process. On a miss it reloads the column information at most once a minute, so workers started before `db:migrate` move to tenant ledgers without a restart.
+- `Backfill.status` works with an `index_scope` that orders. It plucked distinct tenants over `index_relation` without `reorder(nil)`, which raised on Postgres (`for SELECT DISTINCT, ORDER BY expressions must appear in select list`).
+- A per-tenant choice `options:` callable runs once per label and tenant for each keystroke search, query encoding, labeler batch, and Smart run step, instead of at every vocabulary, fingerprint, and wording read. In happyhappy that was about 8 times per keystroke, and 14 per encoding and 21 per labeler batch in the test model. The new `Truffler::Current.scope` memoizes for one unit of work and clears when it ends, so nothing is shared between searches, jobs, or tenants.
+- Backfill spend ledgers key on the Jev-asked labels only (`Vocabulary#ledger_version`). Changing a supplied (`from:`) label, such as adding an option to a supplied product choice, no longer starts a fresh ledger; the backfill rewrites only that label with no Jev call and no charge. Changing an asked label still starts a new ledger. Existing ledgers keep counting: a model without supplied labels keeps the same key, and one with supplied labels has its pre-0.1.6 row taken over by the first backfill.
+
 ## [0.1.5]
 
 Fixes from the Cora integration at Postgres scale, and two from happyhappy's 0.1.4 upgrade.

data/README.md

@@ -51,7 +51,7 @@ bin/rails db:migrate
 
 The migration creates only that table and skips it if it already exists. Until you run it, backfills log one warning and cap spend per run, as 0.1.1 did.
 
-0.1.5 adds `truffler_backfill_spends.tenant_key` for per-tenant spend ledgers. The same `truffler:upgrade` command writes that migration. Until you run it, every tenant shares the model's app-wide ledger and a warning is logged once.
+0.1.5 adds `truffler_backfill_spends.tenant_key` for per-tenant spend ledgers. The same `truffler:upgrade` command writes that migration. Until you run it, every tenant shares the model's app-wide ledger and a warning is logged once. Workers already running when you migrate pick up the column within a minute, without a restart.
 
 `truffler:upgrade` is safe to rerun. It skips any migration already in `db/migrate` or already applied to the database, and writes only the missing ones.
 
@@ -96,7 +96,7 @@ end
 Here is what each option does:
 
 - `filter_at` makes a label a hard filter at that probability when the query asks for it. `boost` is the label's weight when the query prefers it. `filter_weight:` (default 0) is how much intent weight a filter adds on top.
-- Choice `options:` may be a callable of the tenant key, which gives each tenant its own vocabulary. A tenant it gives no options (`{}` or nil) simply lacks the label: it is neither asked nor encoded there. The option name `truffler:none` is reserved (see `Truffler::NO_OPTION` below).
+- Choice `options:` may be a callable of the tenant key, which gives each tenant its own vocabulary. A tenant it gives no options (`{}` or nil) simply lacks the label: it is neither asked nor encoded there. The callable runs once per label and tenant for each keystroke search, query encoding, labeler batch, and Smart run step (`Truffler::Current.scope`), never shared between them. The option name `truffler:none` is reserved (see `Truffler::NO_OPTION` below).
 - An option's value may be `{ description: "...", search: "..." }` instead of a plain description, e.g. `options: { "prod-a1" => { description: "Cora, the AI email assistant that drafts replies...", search: "Cora email assistant" } }`. Jev labels records with the description; query words are matched against the short search text (else the description), and the request state's `option_names` carries it. A per-tenant callable may return the same shape. Editing a search text never stales labels or triggers a backfill; it only changes the query-encoding cache key, so queries are re-encoded.
 - `watch :column, ...` relabels every label when one of those columns changes. Saving a record only relabels on columns that changed, so a `reads` field backed by a method (a conversation built from messages, say) needs the columns it is built from in `watch`.
 - `keyword` also accepts a single callable, `->(scope, tokens) { relation }`. It, and each `exact` callable, may return an Array of ids instead of a relation, which is far faster on a large tenant (see [Keystroke search at scale](#keystroke-search-at-scale)).
@@ -203,12 +203,15 @@ Query encoding sends Jev the label vocabulary (each label's description and a ch
 
 When the searcher removes a chip, the words that named only that label (or only labels that are now all removed) become keywords again, so removing the `urgent` chip from "urgent refunds" searches for both words. A word that named a label or option key only by shared prefix ("urgently" for `urgent`) also adds a small keyword score (a quarter of the keyword weight) while its label applies, ranking records whose text contains it higher without requiring it.
 
+When a search under the encoding's filters returns nothing but would match without them, the filters relax instead of leaving an empty list. With a product filter applied, "email" can become a `Source: email` filter in a tenant with no email sources. Truffler first relaxes only the filters no record in the tenant carries at their threshold, keeping the rest (the product filter stays). If that still finds nothing, it relaxes every filter. A relaxed filter becomes a soft boost, so records that do match it still rank first, and the words it consumed become keywords again. A filter is never relaxed into "every record in the tenant": if no word comes back and there is no exact or vector match, the list stays empty. Relaxation runs one extra query, only when the result is empty. `result.relaxed_labels` lists the relaxed storage keys, and their chips keep `kind: :filter` with `relaxed: true`, so the UI can say "No email sources; showing keyword matches". Chips the searcher removed stay removed.
+
 Time phrases are handled in Ruby and never asked of Jev: `today`, `yesterday`, `this week`, `last week`, `this month`, `last month`, `past|last N hours|days|weeks|months`, `last hour`, `past hour`, `past week`, `past month`, and `since monday` through `since sunday`. "Past/last N units" is a rolling window ending now; "this/last week" and "this/last month" are calendar windows. The first one in a query limits results to records whose `arrived_at` column falls in that window, its words are not keywords, and it shows as a chip `{key: "time", label: "time", kind: :time, name: "This week"}`. Pass `"time"` in `suppressed:` to drop it. Weeks start on `Date.beginning_of_week`, and the window is computed from `Time.current` (or a `clock:` callable passed to the search, for tests).
 
 The returned `Truffler::Search::Result` exposes:
 
 - `records` and `ids`.
-- `chips`: `[{key:, label:, kind: :filter | :boost | :time, name:}]`.
+- `chips`: `[{key:, label:, kind: :filter | :boost | :time, name:}]`, plus `relaxed: true` on a filter chip that was relaxed.
+- `relaxed_labels`: storage keys of filters relaxed because they left nothing to show (empty otherwise).
 - `invite_row`: `{query:, reason: :weak | :empty | :encoding_pending}` or nil.
 - `local_weak?`: whether the list is too weak to stand alone (starts the backup provider). A pending encoding on a model with a `keyword` source invites Smart search without making the list weak.
 - `encoding_status`: `:cached`, `:pending`, or `:none`.
@@ -260,7 +263,7 @@ The keystroke list is left untouched. The job then does the following:
 
 1. Starts the provider backup, if one is declared.
 2. Takes a rerank slot under the per-user cap. If no slot is available, the run pauses.
-3. Waits up to `encoding_deadline` for an in-flight query encoding and applies its filters.
+3. Waits up to `encoding_deadline` for an in-flight query encoding and applies its filters. If they leave no candidate, they relax as on the keystroke instead of reranking an empty set. `run.relaxed_labels` and `run.to_h[:relaxed_labels]` list them.
 4. Fans out one `RerankChunkJob` per `rerank_chunk_size` candidates.
 
 Each chunk appends to the buckets and pings. When the searcher edits the query or accepts or removes a chip, call `Email.jev_cancel_smart_search(tenant:, user:, surface:)`.
@@ -395,6 +398,7 @@ Set these in `Truffler.configure do |config| ... end`.
 | `tenant_enabled` | nil (every tenant) | `->(model, tenant_key) { ... }`, asked for tenant-scoped models only. A disabled tenant is never labeled, embedded, or backfilled (see Indexing only some tenants). |
 | `backfill_spend_cap_scope` | `:tenant` | `:tenant` keeps a spend ledger per tenant for tenant-scoped models, so `backfill_spend_cap` applies to each tenant. `:app` keeps one ledger per model. Unscoped models always use one. |
 | `choice_min_probability` | 0.05 | Choice labels store a row only for options at or above this probability, plus the most likely option. A missing option reads as 0.0 in filters, boosts, label vectors, and contributions. `nil` stores every option. No migration is needed: rows written earlier stay until their record is relabeled. |
+| `skip_empty_options` | false | When true, query encoding offers Jev only the choice options the tenant has label rows for (at or above `choice_min_probability`, or above 0.0 when that is `nil`), and leaves out choice labels with none, so a query cannot filter on an option no record carries. The present-option set is part of the encoding cache key and is read through the cache store for 5 minutes (`Truffler::QueryEncoding::PresentOptions::TTL`), so keystrokes stay one query and a new option reaches encoding within 5 minutes. |
 
 ## Jobs to schedule
 
@@ -436,7 +440,7 @@ truffler_expire_lenses:
 | `RESET_SPEND=1` | Zeroes the spend recorded for the current vocabulary version before starting (every tenant's ledger when no `TENANT` is given). |
 | `TENANT=42` | Backfills only that tenant, against that tenant's ledger. `truffler:status` takes it too, to print that tenant's spend. |
 
-The spend cap holds across runs. Truffler records backfill spend per model and app-wide vocabulary version in `truffler_backfill_spends`, and reserves each request's estimate against the cap in SQL. A rerun, a `ResumeJob` backfill, and overlapping `BackfillJob` chains all draw on the same total, so together they stop at `backfill_spend_cap`. Changing the vocabulary (a reworded question, a new label, or an activated lens) starts a new total. Lens backfills are capped separately by each lens's `spend_cap_usd`. `BackfillJob` reschedules itself after a denial with the same backoff. In code, `Truffler::Labeling::Backfill.new(Email).run(wait: true, max_duration: 600)` does what the task does.
+The spend cap holds across runs. Truffler records backfill spend per model and ledger version in `truffler_backfill_spends`, and reserves each request's estimate against the cap in SQL. A rerun, a `ResumeJob` backfill, and overlapping `BackfillJob` chains all draw on the same total, so together they stop at `backfill_spend_cap`. Changing what Jev is asked (a reworded question, a new asked label, or an activated lens) starts a new total. Supplied (`from:`) labels cost nothing and never do: adding an option to a supplied choice keeps the ledger, and the next backfill rewrites only that label with no Jev call. Ledgers written before 0.1.6 keep counting. A model without supplied labels keeps the same key, and one with supplied labels has its old row taken over on the first backfill, so no spend is reset. Lens backfills are capped separately by each lens's `spend_cap_usd`. `BackfillJob` reschedules itself after a denial with the same backoff. In code, `Truffler::Labeling::Backfill.new(Email).run(wait: true, max_duration: 600)` does what the task does.
 
 For tenant-scoped models the ledger is per tenant (`backfill_spend_cap_scope :tenant`, the default), so the cap applies to each tenant. A whole-model run skips a tenant once its ledger reaches the cap, keeps labeling the others, and ends with `spend_cap_reached`. A tenant run (`TENANT=`, or `BackfillJob.perform_later("Email", tenant_key: "42")`) stops at that tenant's cap. `ResumeJob` and the flush job's over-cap demotion enqueue one `BackfillJob` per tenant.
 

data/lib/generators/truffler/install/templates/migration.rb.tt

@@ -9,9 +9,9 @@ class CreateTrufflerTables < ActiveRecord::Migration<%= migration_version %>
       t.string :fingerprint, null: false
       t.datetime :labeled_at, null: false
     end
-    add_index :truffler_labels, [:record_type, :record_id, :label_key], unique: true,
+    add_index :truffler_labels, [ :record_type, :record_id, :label_key ], unique: true,
       name: "index_truffler_labels_on_record_and_label"
-    add_index :truffler_labels, [:record_type, :tenant_key, :label_key, :value], include: [:record_id],
+    add_index :truffler_labels, [ :record_type, :tenant_key, :label_key, :value ], include: [ :record_id ],
       name: "index_truffler_labels_for_search"
 
     create_table :truffler_record_states do |t|
@@ -29,9 +29,9 @@ class CreateTrufflerTables < ActiveRecord::Migration<%= migration_version %>
       t.datetime :embedded_at
       t.timestamps
     end
-    add_index :truffler_record_states, [:record_type, :record_id], unique: true,
+    add_index :truffler_record_states, [ :record_type, :record_id ], unique: true,
       name: "index_truffler_record_states_on_record"
-    add_index :truffler_record_states, [:record_type, :tenant_key, :status, :priority],
+    add_index :truffler_record_states, [ :record_type, :tenant_key, :status, :priority ],
       name: "index_truffler_record_states_for_claims"
 
     create_table :truffler_embeddings do |t|
@@ -49,9 +49,9 @@ class CreateTrufflerTables < ActiveRecord::Migration<%= migration_version %>
       t.string :label_vocabulary_version
       t.timestamps
     end
-    add_index :truffler_embeddings, [:record_type, :record_id], unique: true,
+    add_index :truffler_embeddings, [ :record_type, :record_id ], unique: true,
       name: "index_truffler_embeddings_on_record"
-    add_index :truffler_embeddings, [:record_type, :tenant_key], name: "index_truffler_embeddings_on_tenant"
+    add_index :truffler_embeddings, [ :record_type, :tenant_key ], name: "index_truffler_embeddings_on_tenant"
 
     create_table :truffler_query_misses do |t|
       t.string :record_type, null: false
@@ -61,7 +61,7 @@ class CreateTrufflerTables < ActiveRecord::Migration<%= migration_version %>
       t.text :query_text
       t.datetime :created_at, null: false
     end
-    add_index :truffler_query_misses, [:record_type, :tenant_key, :created_at],
+    add_index :truffler_query_misses, [ :record_type, :tenant_key, :created_at ],
       name: "index_truffler_query_misses_on_tenant"
     add_index :truffler_query_misses, :created_at
 
@@ -86,7 +86,7 @@ class CreateTrufflerTables < ActiveRecord::Migration<%= migration_version %>
       t.datetime :last_used_at
       t.timestamps
     end
-    add_index :truffler_lenses, [:record_type, :status, :scope_type, :tenant_key],
+    add_index :truffler_lenses, [ :record_type, :status, :scope_type, :tenant_key ],
       name: "index_truffler_lenses_for_visibility"
 
     create_table :truffler_lens_versions do |t|
@@ -103,7 +103,7 @@ class CreateTrufflerTables < ActiveRecord::Migration<%= migration_version %>
       t.datetime :activated_at
       t.datetime :created_at, null: false
     end
-    add_index :truffler_lens_versions, [:lens_id, :number], unique: true,
+    add_index :truffler_lens_versions, [ :lens_id, :number ], unique: true,
       name: "index_truffler_lens_versions_on_lens_and_number"
 
     create_table :truffler_backfill_spends do |t|
@@ -114,9 +114,9 @@ class CreateTrufflerTables < ActiveRecord::Migration<%= migration_version %>
       t.integer :requests, null: false, default: 0
       t.timestamps
     end
-    add_index :truffler_backfill_spends, [:record_type, :tenant_key, :vocabulary_version], unique: true,
+    add_index :truffler_backfill_spends, [ :record_type, :tenant_key, :vocabulary_version ], unique: true,
       name: "index_truffler_backfill_spends_on_tenant_ledger"
-    add_index :truffler_backfill_spends, [:record_type, :vocabulary_version], unique: true, where: "tenant_key IS NULL",
+    add_index :truffler_backfill_spends, [ :record_type, :vocabulary_version ], unique: true, where: "tenant_key IS NULL",
       name: "index_truffler_backfill_spends_on_app_ledger"
   end
 end

data/lib/generators/truffler/upgrade/templates/backfill_spends_migration.rb.tt

@@ -9,7 +9,7 @@ class CreateTrufflerBackfillSpends < ActiveRecord::Migration<%= migration_versio
       t.integer :requests, null: false, default: 0
       t.timestamps
     end
-    add_index :truffler_backfill_spends, [:record_type, :vocabulary_version], unique: true,
+    add_index :truffler_backfill_spends, [ :record_type, :vocabulary_version ], unique: true,
       name: "index_truffler_backfill_spends_on_ledger"
   end
 

data/lib/generators/truffler/upgrade/templates/backfill_spends_tenant_key_migration.rb.tt

@@ -5,11 +5,11 @@ class AddTenantKeyToTrufflerBackfillSpends < ActiveRecord::Migration<%= migratio
       remove_index :truffler_backfill_spends, name: "index_truffler_backfill_spends_on_ledger"
     end
     unless index_name_exists?(:truffler_backfill_spends, "index_truffler_backfill_spends_on_tenant_ledger")
-      add_index :truffler_backfill_spends, [:record_type, :tenant_key, :vocabulary_version], unique: true,
+      add_index :truffler_backfill_spends, [ :record_type, :tenant_key, :vocabulary_version ], unique: true,
         name: "index_truffler_backfill_spends_on_tenant_ledger"
     end
     unless index_name_exists?(:truffler_backfill_spends, "index_truffler_backfill_spends_on_app_ledger")
-      add_index :truffler_backfill_spends, [:record_type, :vocabulary_version], unique: true, where: "tenant_key IS NULL",
+      add_index :truffler_backfill_spends, [ :record_type, :vocabulary_version ], unique: true, where: "tenant_key IS NULL",
         name: "index_truffler_backfill_spends_on_app_ledger"
     end
   end
@@ -19,7 +19,7 @@ class AddTenantKeyToTrufflerBackfillSpends < ActiveRecord::Migration<%= migratio
     remove_index :truffler_backfill_spends, name: "index_truffler_backfill_spends_on_tenant_ledger", if_exists: true
     remove_index :truffler_backfill_spends, name: "index_truffler_backfill_spends_on_app_ledger", if_exists: true
     remove_column :truffler_backfill_spends, :tenant_key, if_exists: true
-    add_index :truffler_backfill_spends, [:record_type, :vocabulary_version], unique: true,
+    add_index :truffler_backfill_spends, [ :record_type, :vocabulary_version ], unique: true,
       name: "index_truffler_backfill_spends_on_ledger", if_not_exists: true
   end
 end

data/lib/truffler/configuration.rb

@@ -25,6 +25,8 @@ module Truffler
     attr_accessor :backfill_spend_cap_scope
     # Choice options below this probability store no row and read as 0.0 (nil stores every option).
     attr_accessor :choice_min_probability
+    # Query encoding omits choice options the tenant has no label row for (QueryEncoding::PresentOptions).
+    attr_accessor :skip_empty_options
 
     def initialize(env: ENV)
       @model = "jev-latest"
@@ -62,6 +64,7 @@ module Truffler
       @tenant_enabled = nil
       @backfill_spend_cap_scope = :tenant
       @choice_min_probability = 0.05
+      @skip_empty_options = false
     end
 
     def client

data/lib/truffler/current.rb

@@ -0,0 +1,30 @@
+module Truffler
+  # State scoped to one unit of work: a keystroke search, a query encoding,
+  # a labeler batch, a Smart run step. Inside `scope`, a per-tenant choice
+  # `options:` callable is resolved once per (label, tenant) instead of at
+  # every vocabulary, fingerprint, and wording read. Nested scopes share the
+  # outermost one, which clears everything when it ends, so nothing carries
+  # over to the next search or job. Outside a scope nothing is memoized.
+  module Current
+    KEY = :truffler_current_options
+
+    def self.scope
+      return yield if ActiveSupport::IsolatedExecutionState.key?(KEY)
+
+      ActiveSupport::IsolatedExecutionState[KEY] = {}
+      begin
+        yield
+      ensure
+        ActiveSupport::IsolatedExecutionState.delete(KEY)
+      end
+    end
+
+    def self.options(label, tenant_key)
+      memo = ActiveSupport::IsolatedExecutionState[KEY]
+      return yield unless memo
+
+      key = [ label, tenant_key&.to_s ]
+      memo.fetch(key) { memo[key] = yield }
+    end
+  end
+end

data/lib/truffler/label_definition.rb

@@ -131,7 +131,10 @@ module Truffler
     private
 
     def option_entries(tenant_key)
-      options = per_tenant? ? @options.call(tenant_key) : @options
+      per_tenant? ? Current.options(self, tenant_key) { build_option_entries(@options.call(tenant_key)).freeze } : build_option_entries(@options)
+    end
+
+    def build_option_entries(options)
       options = Array(options).to_h { |option| [ option, nil ] } unless options.is_a?(Hash)
       options = options.to_h { |option, value| [ option.to_s, option_entry(option, value) ] }
       raise DefinitionError, "#{key}: the option name #{NO_OPTION} is reserved" if options.key?(NO_OPTION)

data/lib/truffler/labeling/backfill.rb

@@ -14,7 +14,8 @@ module Truffler
     # Jev about them again. A spend cap stops the run before a request would
     # exceed it; host-supplied labels cost nothing, so they are still written
     # once the cap is reached. The cap counts everything spent under the
-    # current vocabulary version in the truffler_backfill_spends ledger, so
+    # current ledger version (the asked labels' fingerprints, so supplied
+    # labels never reset it) in the truffler_backfill_spends ledger, so
     # reruns and overlapping jobs share it. Tenant-scoped models keep one
     # ledger per tenant (backfill_spend_cap_scope :tenant, the default), so
     # the cap applies to each tenant: a whole-model run skips a tenant at its
@@ -105,13 +106,16 @@ module Truffler
         new(model, tenant_key: tenant_key).status
       end
 
-      # The ledger row for the current vocabulary version (the tenant's, for
-      # a tenant ledger), or nil when nothing was spent yet or the ledger
-      # table is missing.
+      # The ledger row for the current ledger version (the tenant's, for a
+      # tenant ledger), or nil when nothing was spent yet or the ledger table
+      # is missing. A row still keyed by the pre-0.1.6 vocabulary version
+      # counts until a backfill takes it over.
       def self.spend(model, tenant_key: nil)
         return unless Records::BackfillSpend.available?
 
-        Records::BackfillSpend.for_ledger(model, tenant_key).find_by(vocabulary_version: ledger_version(model, tenant_key))
+        ledgers = Records::BackfillSpend.for_ledger(model, tenant_key)
+        ledgers.find_by(vocabulary_version: ledger_version(model, tenant_key)) ||
+          ledgers.find_by(vocabulary_version: legacy_ledger_version(model, tenant_key))
       end
 
       # Zeroes the current vocabulary version's ledger in place, so a chain
@@ -123,12 +127,20 @@ module Truffler
         ledgers = if all_tenants && Records::BackfillSpend.tenant_ledgers?
           Records::BackfillSpend.for_model(model).where.not(tenant_key: nil)
         else
-          Records::BackfillSpend.for_ledger(model, tenant_key).where(vocabulary_version: ledger_version(model, tenant_key))
+          Records::BackfillSpend.for_ledger(model, tenant_key)
+            .where(vocabulary_version: [ ledger_version(model, tenant_key), legacy_ledger_version(model, tenant_key) ])
         end
         ledgers.update_all(spent_usd: 0.0, requests: 0, updated_at: Time.current)
       end
 
+      # Spend ledgers key on the asked labels only (Vocabulary#ledger_version),
+      # so a supplied-label change never resets the cap.
       def self.ledger_version(model, tenant_key = nil)
+        model.truffler_definition.vocabulary.ledger_version(tenant_key: tenant_key, all_users: true)
+      end
+
+      # What ledgers were keyed by before 0.1.6: the whole vocabulary version.
+      def self.legacy_ledger_version(model, tenant_key = nil)
         model.truffler_definition.vocabulary.version(tenant_key: tenant_key, all_users: true)
       end
 
@@ -220,7 +232,7 @@ module Truffler
         return [ scope.where(definition.tenant_column => @tenant_key), [ @tenant_key ] ] if @tenant_key
         return [ scope, nil ] unless Truffler.config.tenant_enabled
 
-        tenants = scope.distinct.pluck(definition.tenant_column).map(&:to_s).select { |tenant_key| enabled?(tenant_key) }
+        tenants = scope.reorder(nil).distinct.pluck(definition.tenant_column).map(&:to_s).select { |tenant_key| enabled?(tenant_key) }
         [ scope.where(definition.tenant_column => tenants), tenants ]
       end
 
@@ -233,7 +245,10 @@ module Truffler
       def meter(tenant_key)
         ledger_tenant = ledger_available? ? definition.ledger_tenant(tenant_key) : nil
         @meters[ledger_tenant] ||= begin
-          ledger = Records::BackfillSpend.ledger(model, version_for(ledger_tenant), tenant_key: ledger_tenant) if ledger_available?
+          if ledger_available?
+            ledger = Records::BackfillSpend.ledger(model, self.class.ledger_version(model, ledger_tenant), tenant_key: ledger_tenant,
+              legacy_version: version_for(ledger_tenant))
+          end
           SpendMeter.new(@client, cap: @spend_cap, spent: ledger ? 0.0 : @spent, ledger: ledger)
         end
       end

data/lib/truffler/labeling/labeler.rb

@@ -20,46 +20,48 @@ module Truffler
       end
 
       def label(states, priority:)
-        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, 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)
-        version = vocabulary.version(tenant_key: tenant_key, all_users: true)
-        states_by_id = states.index_by { |state| state.record_id.to_s }
-
-        stored = stored_fingerprints(records)
-        askable = askable_labels
-        stale = records.map { |record| [ record, stale_keys(stored[record.id.to_s].to_h, fingerprints, tenant_key, askable) ] }
-        supplied = askable.select(&:supplied?).map(&:key)
-        supplier = Supplied.new(model)
-        written = supplier.write(stale.map { |record, keys| [ record, keys & supplied ] }, tenant_key: tenant_key)
-        current, pending = stale.map { |record, keys| [ record, keys - supplied ] }.partition { |_, keys| keys.empty? }
-        settled = current.reject { |record, _| supplier.failed_ids.include?(record.id) }
-        Records::RecordState.mark_labeled(settled.map { |record, _| states_by_id[record.id.to_s].id }, version: version)
-        Embeddings::LabelVector.new(model).write(current.map { |record, _| record.id } - written, tenant_key: tenant_key)
-
-        requests = RequestBuilder.new(definition, tenant_key: tenant_key, labels: @labels).build(pending)
-        cost = 0.0
-        requests.each_with_index do |request, index|
-          decision = budget.acquire(priority: priority, tenant_key: (tenant_key if index.zero?),
-            records: index.zero? ? pending.size : 1)
-          if decision.demoted?
-            retry_failed_supplied(supplier.failed_ids, states_by_id)
-            return Result.new(labeled: current.size, requests: index, cost: cost, demoted: true)
+        Current.scope do
+          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, 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)
+          version = vocabulary.version(tenant_key: tenant_key, all_users: true)
+          states_by_id = states.index_by { |state| state.record_id.to_s }
+
+          stored = stored_fingerprints(records)
+          askable = askable_labels
+          stale = records.map { |record| [ record, stale_keys(stored[record.id.to_s].to_h, fingerprints, tenant_key, askable) ] }
+          supplied = askable.select(&:supplied?).map(&:key)
+          supplier = Supplied.new(model)
+          written = supplier.write(stale.map { |record, keys| [ record, keys & supplied ] }, tenant_key: tenant_key)
+          current, pending = stale.map { |record, keys| [ record, keys - supplied ] }.partition { |_, keys| keys.empty? }
+          settled = current.reject { |record, _| supplier.failed_ids.include?(record.id) }
+          Records::RecordState.mark_labeled(settled.map { |record, _| states_by_id[record.id.to_s].id }, version: version)
+          Embeddings::LabelVector.new(model).write(current.map { |record, _| record.id } - written, tenant_key: tenant_key)
+
+          requests = RequestBuilder.new(definition, tenant_key: tenant_key, labels: @labels).build(pending)
+          cost = 0.0
+          requests.each_with_index do |request, index|
+            decision = budget.acquire(priority: priority, tenant_key: (tenant_key if index.zero?),
+              records: index.zero? ? pending.size : 1)
+            if decision.demoted?
+              retry_failed_supplied(supplier.failed_ids, states_by_id)
+              return Result.new(labeled: current.size, requests: index, cost: cost, demoted: true)
+            end
+            raise BudgetExhausted.new("no Jev budget for #{priority} labeling", retry_after: decision.retry_after) if decision.denied?
+
+            answers = client.ask(state: request.state, questions: request.questions, priority: decision.priority)
+            cost += answers.usage&.cost.to_f
+            charge_lenses(request, answers.usage&.cost.to_f)
+            store(request, answers, fingerprints, tenant_key, version, states_by_id)
           end
-          raise BudgetExhausted.new("no Jev budget for #{priority} labeling", retry_after: decision.retry_after) if decision.denied?
 
-          answers = client.ask(state: request.state, questions: request.questions, priority: decision.priority)
-          cost += answers.usage&.cost.to_f
-          charge_lenses(request, answers.usage&.cost.to_f)
-          store(request, answers, fingerprints, tenant_key, version, states_by_id)
+          retry_failed_supplied(supplier.failed_ids, states_by_id)
+          Result.new(labeled: records.size, requests: requests.size, cost: cost, demoted: false)
         end
-
-        retry_failed_supplied(supplier.failed_ids, states_by_id)
-        Result.new(labeled: records.size, requests: requests.size, cost: cost, demoted: false)
       end
 
       private

data/lib/truffler/query_encoding/encoder.rb

@@ -51,50 +51,55 @@ module Truffler
       end
 
       def request(model, query, tenant_key:, user_key: nil)
-        labels = labels(model, tenant_key, user_key)
-        questions = Questions.new
-        labels.each_value do |label|
-          questions.choice(:"intent__#{label.question_key}", instructions: intent_instructions(label), criteria: INTENTS)
-        end
-        labels.each_value do |label|
-          next unless label.type == :choice
+        Current.scope do
+          present = present_options(model, tenant_key, user_key)
+          labels = labels(model, tenant_key, user_key, present)
+          questions = Questions.new
+          labels.each_value do |label|
+            questions.choice(:"intent__#{label.question_key}", instructions: intent_instructions(label), criteria: INTENTS)
+          end
+          labels.each_value do |label|
+            next unless label.type == :choice
 
-          options = label.options(tenant_key).merge(NO_OPTION => "The query names none of these")
-          questions.choice(:"option__#{label.question_key}", instructions: %(Which "#{label.key}" option does the search query ask about?),
-            criteria: options)
-        end
+            options = PresentOptions.options(label, tenant_key, present).merge(NO_OPTION => "The query names none of these")
+            questions.choice(:"option__#{label.question_key}", instructions: %(Which "#{label.key}" option does the search query ask about?),
+              criteria: options)
+          end
 
-        words = query.tokens.each_with_index.reject do |token, position|
-          query.exact_tokens.include?(token) || query.time_position?(position)
-        end
-        asked = words.first(MAX_TOKEN_QUESTIONS)
-        token_ids = asked.to_h do |_token, position|
-          id = :"token__#{position}"
-          questions.choice(id, instructions: %(In the search query, what is the word tokens[#{position}]? The labels it may name, ) +
-            %(with their options, are in `labels`.), criteria: TOKEN_ROLES)
-          [ position, id.to_s ]
-        end
+          words = query.tokens.each_with_index.reject do |token, position|
+            query.exact_tokens.include?(token) || query.time_position?(position)
+          end
+          asked = words.first(MAX_TOKEN_QUESTIONS)
+          token_ids = asked.to_h do |_token, position|
+            id = :"token__#{position}"
+            questions.choice(id, instructions: %(In the search query, what is the word tokens[#{position}]? The labels it may name, ) +
+              %(with their options, are in `labels`.), criteria: TOKEN_ROLES)
+            [ position, id.to_s ]
+          end
 
-        state = { "query" => query.normalized, "tokens" => query.tokens, "labels" => vocabulary_state(labels, tenant_key) }
-        Request.new(state: state, questions: questions.to_h, token_ids: token_ids, exact_tokens: query.exact_tokens,
-          unasked_tokens: words.drop(MAX_TOKEN_QUESTIONS).map(&:first))
+          state = { "query" => query.normalized, "tokens" => query.tokens, "labels" => vocabulary_state(labels, tenant_key, present) }
+          Request.new(state: state, questions: questions.to_h, token_ids: token_ids, exact_tokens: query.exact_tokens,
+            unasked_tokens: words.drop(MAX_TOKEN_QUESTIONS).map(&:first))
+        end
       end
 
       # Encodes the query pending under `cache_key`. Returns the encoding, or
       # nil when the payload expired, the vocabulary moved on, or the encode
       # budget was denied (a silent skip). Always releases the in-flight marker.
       def encode(cache_key)
-        pending = cache.read_payload(cache_key)
-        return unless pending
-
-        model, query, tenant_key, user_key = pending.values_at(:model, :query, :tenant_key, :user_key)
-        return unless cache.key(model, query, tenant_key: tenant_key, user_key: user_key) == cache_key
-
-        encoding = cache.encoded?(cache_key) ? cache.read_encoding(cache_key, query) : encode_labels(model, query, tenant_key, user_key)
-        embed_query(model, query, tenant_key)
-        encoding
-      ensure
-        cache.release(cache_key)
+        Current.scope do
+          pending = cache.read_payload(cache_key)
+          return unless pending
+
+          model, query, tenant_key, user_key = pending.values_at(:model, :query, :tenant_key, :user_key)
+          return unless cache.key(model, query, tenant_key: tenant_key, user_key: user_key) == cache_key
+
+          encoding = cache.encoded?(cache_key) ? cache.read_encoding(cache_key, query) : encode_labels(model, query, tenant_key, user_key)
+          embed_query(model, query, tenant_key)
+          encoding
+        ensure
+          cache.release(cache_key)
+        end
       end
 
       # Polls the cache until the encoding lands or the deadline (seconds
@@ -118,8 +123,9 @@ module Truffler
         boosts = {}
         intent = {}
         names = {}
-        labels(model, tenant_key, user_key).each_value do |label|
-          key = storage_key(label, answers, tenant_key)
+        present = present_options(model, tenant_key, user_key)
+        labels(model, tenant_key, user_key, present).each_value do |label|
+          key = storage_key(label, answers, tenant_key, present)
           next unless key
 
           case answers.choice("intent__#{label.question_key}")
@@ -175,25 +181,41 @@ module Truffler
         cache.write_vector(model, query, vector, tenant_key: tenant_key)
       end
 
-      def labels(model, tenant_key, user_key)
+      # The searcher's vocabulary; with skip_empty_options, minus choice
+      # labels the tenant has no option rows for (see PresentOptions).
+      def labels(model, tenant_key, user_key, present = present_options(model, tenant_key, user_key))
+        labels = vocabulary_labels(model, tenant_key, user_key)
+        return labels unless present
+
+        labels.select { |_, label| label.type != :choice || PresentOptions.options(label, tenant_key, present).any? }
+      end
+
+      def vocabulary_labels(model, tenant_key, user_key)
         model.truffler_definition.vocabulary.labels_for(tenant_key: tenant_key, user_key: user_key)
       end
 
+      def present_options(model, tenant_key, user_key)
+        return unless PresentOptions.enabled?
+
+        PresentOptions.new.keys(model, vocabulary_labels(model, tenant_key, user_key), tenant_key: tenant_key)
+      end
+
       # The label's storage key the query names, or nil for a choice label
       # whose option answer is NO_OPTION.
-      def storage_key(label, answers, tenant_key)
+      def storage_key(label, answers, tenant_key, present)
         return label.key unless label.type == :choice
 
         option = answers.choice("option__#{label.question_key}")
-        "#{label.key}:#{option}" if option != NO_OPTION && label.options(tenant_key).key?(option)
+        "#{label.key}:#{option}" if option != NO_OPTION && PresentOptions.options(label, tenant_key, present).key?(option)
       end
 
-      def vocabulary_state(labels, tenant_key)
+      def vocabulary_state(labels, tenant_key, present)
         labels.transform_values do |label|
           entry = { "description" => label.description }
           if label.type == :choice
-            entry["options"] = label.options(tenant_key).keys
-            names = label.option_names(tenant_key)
+            options = PresentOptions.options(label, tenant_key, present).keys
+            entry["options"] = options
+            names = label.option_names(tenant_key).slice(*options)
             entry["option_names"] = names if names.any?
           end
           entry