truffler 0.1.0

data/lib/truffler/lenses/lens.rb

@@ -0,0 +1,161 @@
+module Truffler
+  module Lenses
+    # A named set of drafted label questions for one model and scope (R39).
+    # The row mirrors its active version's questions, so search-time
+    # visibility needs no join. Statuses: draft (never activated), proposed
+    # (system-drafted from misses, awaiting approval), active, expired.
+    class Lens < ActiveRecord::Base
+      include SealedDescription
+
+      self.table_name = "truffler_lenses"
+
+      STATUSES = %w[draft proposed active expired].freeze
+
+      HistoryEntry = Data.define(:number, :status, :label_keys, :reused, :restored_from, :created_by_digest, :created_at,
+        :activated_by_digest, :activated_at)
+
+      has_many :versions, -> { order(:number) }, class_name: "Truffler::Lenses::Version", foreign_key: :lens_id,
+        inverse_of: :lens, dependent: :delete_all
+      belongs_to :active_version, class_name: "Truffler::Lenses::Version", optional: true
+      serialize :questions, coder: JSON
+      serialize :reused_keys, coder: JSON
+
+      validates :status, inclusion: { in: STATUSES }
+      validates :scope_type, inclusion: { in: %w[app tenant user] }
+
+      scope :active, -> { where(status: "active") }
+      scope :proposed, -> { where(status: "proposed") }
+      scope :for_model, ->(model) { where(record_type: model.polymorphic_name) }
+
+      after_commit { Lenses.changed!(record_type) }
+
+      def self.build_from(draft, status:, origin: "user", creator_digest: nil, proposal_digest: nil)
+        new(record_type: draft.model.polymorphic_name, scope_type: draft.scope.type.to_s, scope_key: draft.scope.scope_key,
+          tenant_key: draft.scope.tenant_key, name: draft.name, description: draft.description, status: status,
+          origin: origin, creator_digest: creator_digest, proposal_digest: proposal_digest,
+          spend_cap_usd: Lenses.settings.spend_cap_usd)
+      end
+
+      # Active lenses nobody has searched with for `after` stop applying
+      # (R43). Their stored label rows stay until pruned.
+      def self.expire_unused!(now: Time.current, after: Lenses.settings.expire_after)
+        unused = active.where("COALESCE(last_used_at, updated_at) < ?", now - after)
+        record_types = unused.distinct.pluck(:record_type)
+        unused.update_all(status: "expired", updated_at: now).tap { record_types.each { |type| Lenses.changed!(type) } }
+      end
+
+      def model
+        record_type.safe_constantize
+      end
+
+      def scope
+        Scope.new(type: scope_type.to_sym, tenant_key: tenant_key, user_digest: (scope_key if scope_type == "user"))
+      end
+
+      def active? = status == "active"
+      def proposed? = status == "proposed"
+      def expired? = status == "expired"
+
+      # {"lens:<id>:<label>" => wire-shape question} for the active version.
+      def storage_questions
+        questions.to_h.transform_keys { |label| Lenses.label_key(id, label) }
+      end
+
+      # {"lens:<id>:<label>" => LensLabel} for the active version.
+      def labels
+        questions.to_h.to_h { |label, question| [ Lenses.label_key(id, label), LensLabel.new(id, label, question) ] }
+      end
+
+      # The truffler_labels keys this lens writes: one per noul or score, one
+      # per option for choices.
+      def storage_keys
+        questions.to_h.flat_map do |label, question|
+          key = Lenses.label_key(id, label)
+          question["type"] == "choice" ? question["criteria"].keys.map { |option| "#{key}:#{option}" } : [ key ]
+        end
+      end
+
+      def remaining_spend
+        spend_cap_usd && [ spend_cap_usd - spent_usd.to_f, 0.0 ].max
+      end
+
+      def spend_cap_reached?
+        spend_cap_usd.present? && spent_usd.to_f >= spend_cap_usd
+      end
+
+      def would_exceed_cap?(cost)
+        spend_cap_usd.present? && spent_usd.to_f + cost > spend_cap_usd
+      end
+
+      # Adds Jev spend atomically, so concurrent previews and backfill jobs
+      # never lose an increment.
+      def record_spend!(cost)
+        return if cost.to_f.zero?
+
+        self.class.where(id: id).update_all([ "spent_usd = spent_usd + ?, updated_at = ?", cost.to_f, Time.current ])
+        self.spent_usd = self.class.where(id: id).pick(:spent_usd)
+      end
+
+      def draft_version
+        versions.select(&:draft?).last
+      end
+
+      def add_version!(draft, by:, restored_from: nil)
+        versions.create!(number: versions.maximum(:number).to_i + 1, description: draft.description, questions: draft.questions,
+          reused_keys: draft.reused, fingerprint: draft.fingerprint, created_by_digest: Policy.digest_for(by),
+          status: "draft", restored_from: restored_from)
+      end
+
+      # Drafts a new version from the same or an edited description. Search
+      # keeps using the active version until the draft is activated.
+      def regenerate(by:, description: nil, drafter: Drafter.new)
+        Policy.authorize!(by, scope, model: model)
+        text = description.presence || self.description
+        raise InvalidLens, "lens #{id} has no readable description; pass description:" if text.blank?
+
+        add_version!(drafter.draft(text, model: model, scope: scope, lens: self), by: by)
+      end
+
+      # Makes an earlier version's questions active again as a new version
+      # that records where it came from, so history keeps every change.
+      def restore!(number, by:)
+        source = versions.find_by!(number: number)
+        Policy.authorize!(by, scope, model: model)
+        Activator.activate(add_version!(source.to_draft, by: by, restored_from: source.number), by: by)
+      end
+
+      def history
+        versions.reload.map do |version|
+          HistoryEntry.new(number: version.number, status: version.status, label_keys: version.questions.to_h.keys,
+            reused: Array(version.reused_keys), restored_from: version.restored_from,
+            created_by_digest: version.created_by_digest, created_at: version.created_at,
+            activated_by_digest: version.activated_by_digest, activated_at: version.activated_at)
+        end
+      end
+
+      # The declaration a developer pastes into the model to make this lens
+      # part of the declared vocabulary (R43).
+      def declaration_snippet
+        questions.to_h.map do |label, question|
+          line = "label :#{label}, :#{question['type']}, question: #{question['instructions'].to_s.inspect}"
+          case question["type"]
+          when "noul" then question["criteria"] ? "#{line}, criteria: #{question['criteria'].inspect}" : line
+          when "choice" then "#{line}, options: #{question['criteria'].inspect}"
+          when "score" then "#{line}, legend: #{question['criteria'].inspect}"
+          else raise InvalidLens, "#{label}: unknown question type #{question['type'].inspect}"
+          end
+        end.join("\n")
+      end
+
+      def promote!(io: $stdout)
+        declaration_snippet.tap { |snippet| io.puts(snippet) }
+      end
+
+      private
+
+      def described_model
+        model
+      end
+    end
+  end
+end

data/lib/truffler/lenses/lens_label.rb

@@ -0,0 +1,51 @@
+module Truffler
+  module Lenses
+    # One lens question behind the LabelDefinition interface, so the labeler,
+    # request builder, label vectors, and query encoding treat it like a
+    # declared label. `key` is its storage key ("lens:<id>:<label>"); in Jev
+    # requests it is asked as "lens<id>__<label>", which cannot collide with a
+    # declared key because declared keys never hold a double underscore.
+    class LensLabel
+      attr_reader :lens_id, :label, :key, :type, :instructions
+
+      def initialize(lens_id, label, question)
+        @lens_id = lens_id
+        @label = label.to_s
+        @question = question.deep_dup.freeze
+        @key = Lenses.label_key(lens_id, @label)
+        @type = question.fetch("type").to_sym
+        @instructions = question["instructions"]
+      end
+
+      def question_key
+        "#{KEY_PREFIX}#{lens_id}#{Questions::SEPARATOR}#{label}"
+      end
+
+      def question(_tenant_key = nil)
+        @question.deep_dup
+      end
+
+      def options(_tenant_key = nil)
+        @question["criteria"].to_h.transform_keys(&:to_s)
+      end
+
+      def storage_keys(tenant_key = nil)
+        type == :choice ? options(tenant_key).keys.map { |option| "#{key}:#{option}" } : [ key ]
+      end
+
+      def per_tenant?
+        false
+      end
+
+      def supplied?
+        false
+      end
+
+      def description = instructions
+
+      def filter_at = nil
+      def boost = nil
+      def filter_weight = 0.0
+    end
+  end
+end

data/lib/truffler/lenses/policy.rb

@@ -0,0 +1,46 @@
+module Truffler
+  module Lenses
+    # Who may create, regenerate, activate, and restore lenses (R42).
+    #
+    # `config.lenses.creators` bounds the scopes a lens may have:
+    #   :developers   - any scope, for users the host hook marks as developers or admins
+    #   :tenant_users - tenant or personal lenses, for users of that tenant
+    #   :each_user    - personal lenses only, for their own creator
+    # The host hook `config.lenses.authorize_lens.call(user, scope)` always has
+    # the final word; without one, every change is refused.
+    module Policy
+      SCOPES = { developers: %i[app tenant user], tenant_users: %i[tenant user], each_user: %i[user] }.freeze
+
+      module_function
+
+      def authorize!(user, scope, model: nil, settings: Lenses.settings)
+        allowed = SCOPES.fetch(settings.creators)
+        unless allowed.include?(scope.type)
+          raise NotAuthorized, "#{scope.type} lenses are not allowed when lens creators are #{settings.creators}"
+        end
+        if settings.creators == :each_user && scope.user_digest != digest_for(user, settings: settings)
+          raise NotAuthorized, "a personal lens can only be changed by its own user"
+        end
+
+        hook = settings.authorize_lens
+        raise NotAuthorized, "configure config.lenses.authorize_lens to allow lens changes" unless hook
+        raise NotAuthorized, "not allowed to change #{scope.type} lenses#{" on #{model.name}" if model}" unless hook.call(user, scope)
+
+        true
+      end
+
+      def allowed?(user, scope, **options)
+        authorize!(user, scope, **options)
+      rescue NotAuthorized
+        false
+      end
+
+      def digest_for(user, settings: Lenses.settings)
+        return if user.nil?
+
+        key = settings.key_for(user)
+        Lenses.digest(key) if key.present?
+      end
+    end
+  end
+end

data/lib/truffler/lenses/previewer.rb

@@ -0,0 +1,217 @@
+module Truffler
+  module Lenses
+    # Answers a draft's questions on a sample of recent in-scope records in
+    # one packed single-tenant Jev request, at encode priority and inside the
+    # lens's spend cap (R40). `compare` runs an old and a new version on the
+    # same sample and reports how the answers moved (R45).
+    #
+    # A preview holds record ids and numbers only; record text exists only in
+    # the request state while the call runs.
+    class Previewer
+      MAX_EXAMPLES = 5
+
+      Preview = Data.define(:tenant_key, :sample_ids, :types, :values, :buckets, :distribution, :means, :examples,
+        :estimate, :cost)
+      Estimate = Data.define(:records, :requests, :input_tokens, :cost_usd, :duration_seconds, :within_cap)
+      Comparison = Data.define(:before, :after, :shift, :changed_count, :changed_ids, :added, :removed)
+
+      def self.preview(target, **options)
+        new.preview(target, **options)
+      end
+
+      def self.compare(draft, active, **options)
+        new.compare(draft, active, **options)
+      end
+
+      attr_reader :client, :budget, :config
+
+      def initialize(client: Truffler.config.client, budget: Budget.new, config: Truffler.config)
+        @client = client
+        @budget = budget
+        @config = config
+      end
+
+      # target: a Draft, a Version, or a Lens (its active version). relation
+      # narrows the sample to what the host's permission scope allows.
+      def preview(target, sample: config.lenses.sample_size, ids: nil, tenant_key: nil, relation: nil, by: nil)
+        draft = coerce(target)
+        Validation.validate!(draft.questions, reused: draft.reused)
+        scope = relation || draft.model.all
+        tenant_key = resolve_tenant(draft, scope, tenant_key)
+        records = sample_records(draft, scope, tenant_key, sample, ids)
+        return empty_preview(draft, scope, tenant_key, records) if records.empty? || draft.questions.empty?
+
+        state, questions, tags = build(draft, records)
+        request_tokens = Tokens.estimate({ state: state, questions: questions })
+        check_cap!(draft, config.cost_for(request_tokens))
+        decision = budget.acquire(priority: :encode, user_key: (config.lenses.key_for(by) if by))
+        raise BudgetExhausted, "no Jev budget for a lens preview" unless decision.granted?
+
+        answers = client.ask(state: state, questions: questions, priority: :encode)
+        cost = answers.usage&.cost.to_f
+        draft.lens&.record_spend!(cost)
+        summarize(draft, scope, tenant_key, tags, answers, request_tokens, cost)
+      end
+
+      def compare(draft, active, sample: config.lenses.sample_size, tenant_key: nil, relation: nil, by: nil)
+        before = preview(active, sample: sample, tenant_key: tenant_key, relation: relation, by: by)
+        after = preview(draft, ids: before.sample_ids, tenant_key: before.tenant_key, relation: relation, by: by)
+        shared = before.types.keys.select { |label| after.types[label] == before.types[label] }
+        common = before.sample_ids & after.sample_ids
+        changed = common.select { |id| shared.any? { |label| before.buckets.dig(id, label) != after.buckets.dig(id, label) } }
+
+        Comparison.new(before: before, after: after, shift: shared.index_with { |label| shift(before, after, label, common) },
+          changed_count: changed.size, changed_ids: changed, added: after.types.keys - shared, removed: before.types.keys - shared)
+      end
+
+      private
+
+      def coerce(target)
+        case target
+        when Draft then target
+        when Version then target.to_draft
+        when Lens then target.active_version&.to_draft || raise(InvalidLens, "lens #{target.id} has no active version")
+        else raise ArgumentError, "cannot preview #{target.class.name}"
+        end
+      end
+
+      def definition(draft)
+        draft.model.truffler_definition
+      end
+
+      def resolve_tenant(draft, scope, tenant_key)
+        tenant_key ||= draft.scope.tenant_key
+        return tenant_key&.to_s if tenant_key || !definition(draft).scoped?
+
+        scope.reorder(definition(draft).arrival_order).pick(definition(draft).tenant_column)&.to_s
+      end
+
+      def in_tenant(draft, scope, tenant_key)
+        definition(draft).scoped? ? scope.where(definition(draft).tenant_column => tenant_key) : scope
+      end
+
+      def sample_records(draft, scope, tenant_key, sample, ids)
+        model = draft.model
+        records = in_tenant(draft, scope, tenant_key)
+        records = records.where(model.primary_key => ids) if ids
+        per_request = [ config.max_questions_per_request / [ draft.questions.size, 1 ].max, 1 ].max
+        records.reorder(definition(draft).arrival_order).limit([ ids&.size || sample, per_request ].min).to_a
+      end
+
+      def build(draft, records)
+        state_records = {}
+        questions = {}
+        tags = {}
+        used = Tokens.estimate(Labeling::RequestBuilder::TASK)
+        records.each.with_index(1) do |record, index|
+          tag = Questions.tag("r", index)
+          fields = definition(draft).request_fields(record, max_chars: config.max_field_chars)
+          asked = draft.questions.to_h do |label, question|
+            [ Questions.tagged_id(tag, label), question.merge("instructions" => { "record" => tag, "question" => question["instructions"] }) ]
+          end
+          used += Tokens.estimate(fields) + Tokens.estimate(asked)
+          break if tags.any? && used > config.request_token_budget
+
+          state_records[tag] = fields
+          questions.merge!(asked)
+          tags[tag] = record.id
+        end
+        [ { "task" => Labeling::RequestBuilder::TASK, "records" => state_records }, questions, tags ]
+      end
+
+      def check_cap!(draft, estimate)
+        remaining = remaining_cap(draft)
+        return if remaining.nil? || estimate <= remaining
+
+        raise LensSpendCapExceeded, format("a lens preview needs about $%.6f but the lens has $%.6f left", estimate, remaining)
+      end
+
+      def remaining_cap(draft)
+        draft.lens ? draft.lens.remaining_spend : config.lenses.spend_cap_usd
+      end
+
+      def summarize(draft, scope, tenant_key, tags, answers, request_tokens, cost)
+        types = draft.question_types
+        values = {}
+        buckets = {}
+        tags.each do |tag, record_id|
+          values[record_id] = {}
+          buckets[record_id] = {}
+          draft.questions.each do |label, question|
+            record_values, bucket = answer(label, question, answers, Questions.tagged_id(tag, label))
+            values[record_id].merge!(record_values)
+            buckets[record_id][label] = bucket
+          end
+        end
+
+        distribution = draft.questions.to_h do |label, question|
+          counts = bucket_names(question).index_with(0)
+          buckets.each_value { |record| counts[record[label]] = counts[record[label]].to_i + 1 }
+          [ label, counts ]
+        end
+        means = types.reject { |_, type| type == "choice" }.to_h do |label, _|
+          [ label, values.values.sum { |record| record[label] } / values.size ]
+        end
+        examples = draft.questions.keys.index_with do |label|
+          buckets.group_by { |_, record| record[label] }.transform_values { |rows| rows.first(MAX_EXAMPLES).map(&:first) }
+        end
+
+        Preview.new(tenant_key: tenant_key, sample_ids: tags.values, types: types, values: values, buckets: buckets,
+          distribution: distribution, means: means, examples: examples, cost: cost,
+          estimate: estimate(draft, scope, tenant_key, request_tokens / tags.size.to_f, cost))
+      end
+
+      # Returns [{storage suffix => value}, bucket]. Storage suffixes match
+      # the label rows a lens writes: "label" or "label:option".
+      def answer(label, question, answers, id)
+        case question["type"]
+        when "noul"
+          value = answers.noul(id)
+          [ { label => value }, value >= 0.5 ? "yes" : "no" ]
+        when "score"
+          value = answers.score(id)
+          [ { label => value }, (value * (question["criteria"].size - 1)).round.to_s ]
+        when "choice"
+          options = question["criteria"].keys
+          [ options.to_h { |option| [ "#{label}:#{option}", answers.probability(id, option) ] }, answers.choice(id) ]
+        else raise InvalidLens, "#{label}: unknown question type #{question['type'].inspect}"
+        end
+      end
+
+      def bucket_names(question)
+        case question["type"]
+        when "noul" then %w[yes no]
+        when "score" then question["criteria"].each_index.map(&:to_s)
+        when "choice" then question["criteria"].keys
+        else raise InvalidLens, "unknown question type #{question['type'].inspect}"
+        end
+      end
+
+      # Backfill estimate for every record the lens applies to: records ×
+      # tokens per record × price, and requests at the backfill ceiling.
+      def estimate(draft, scope, tenant_key, tokens_per_record, preview_cost)
+        records = (draft.scope.app? ? scope : in_tenant(draft, scope, tenant_key)).count
+        tokens = (records * tokens_per_record).ceil
+        cost = config.cost_for(tokens)
+        requests = (records / config.batch_size.to_f).ceil
+        remaining = remaining_cap(draft)
+        remaining -= preview_cost if remaining && !draft.lens
+        Estimate.new(records: records, requests: requests, input_tokens: tokens, cost_usd: cost,
+          duration_seconds: (requests / budget.ceiling(:backfill)).ceil, within_cap: remaining.nil? || cost <= remaining)
+      end
+
+      def empty_preview(draft, scope, tenant_key, records)
+        Preview.new(tenant_key: tenant_key, sample_ids: records.map(&:id), types: draft.question_types, values: {}, buckets: {},
+          distribution: draft.questions.transform_values { |question| bucket_names(question).index_with(0) }, means: {},
+          examples: {}, cost: 0.0, estimate: estimate(draft, scope, tenant_key, 0, 0.0))
+      end
+
+      def shift(before, after, label, ids)
+        names = before.distribution[label].keys | after.distribution[label].keys
+        buckets = names.index_with { |name| after.distribution[label][name].to_i - before.distribution[label][name].to_i }
+        mean = after.means[label] - before.means[label] if before.means.key?(label) && after.means.key?(label)
+        { buckets: buckets, mean: mean, changed: ids.count { |id| before.buckets.dig(id, label) != after.buckets.dig(id, label) } }
+      end
+    end
+  end
+end

data/lib/truffler/lenses/proposer.rb

@@ -0,0 +1,53 @@
+module Truffler
+  module Lenses
+    # Drafts lenses from query-miss clusters that passed the distinct-user
+    # gate (R28, R29, R42). Proposals are stored as `proposed` and change
+    # nothing until someone the policy allows activates them. The drafting
+    # model sees only aggregated cluster terms and counts.
+    class Proposer
+      def self.propose(model, **options)
+        new.propose(model, **options)
+      end
+
+      def initialize(drafter: Drafter.new, settings: Lenses.settings)
+        @drafter = drafter
+        @settings = settings
+      end
+
+      # tenant_key: one tenant's misses become tenant proposals;
+      # Misses::ALL_TENANTS pools every tenant into app proposals.
+      def propose(model, tenant_key:)
+        return [] unless @settings.proposals
+
+        model = Misses.resolve(model)
+        scope = tenant_key == Misses::ALL_TENANTS ? Scope.app : Scope.tenant(tenant_key)
+        Misses.clusters(model, tenant_key: tenant_key).filter_map do |cluster|
+          proposal_digest = Canonical.digest(terms: cluster.terms.sort)
+          next if existing?(model, scope, proposal_digest)
+
+          draft = @drafter.draft(description_for(model, cluster), model: model, scope: scope, clusters: [ cluster ])
+          create(draft, proposal_digest)
+        end
+      end
+
+      private
+
+      def existing?(model, scope, proposal_digest)
+        Lens.for_model(model).where(scope_type: scope.type.to_s, tenant_key: scope.tenant_key, proposal_digest: proposal_digest).exists?
+      end
+
+      def description_for(model, cluster)
+        "#{model.model_name.human.downcase.pluralize} about #{cluster.terms.to_sentence}"
+      end
+
+      def create(draft, proposal_digest)
+        Lens.transaction do
+          lens = Lens.build_from(draft, status: "proposed", origin: "proposal", proposal_digest: proposal_digest).tap(&:save!)
+          lens.add_version!(draft, by: nil)
+          Instrumentation.instrument(:lens_proposed, record_type: lens.record_type, tenant_key: lens.tenant_key, lens_id: lens.id)
+          lens
+        end
+      end
+    end
+  end
+end

data/lib/truffler/lenses/ruby_llm_generator.rb

@@ -0,0 +1,42 @@
+require "ruby_llm"
+
+module Truffler
+  module Lenses
+    # The default drafting model: `RubyLLM.chat(...).with_schema(...)`, which
+    # ruby_llm 1.x and 2 share. 1.x parses structured output into `content`;
+    # 2 keeps `content` as text and parses it in `parsed`. ruby_llm is not a
+    # truffler dependency; this file loads only when the default is used.
+    class RubyLLMGenerator
+      def generate(prompt:, schema:, model: nil)
+        message = chat(**{ model: model }.compact).with_schema(schema).ask(prompt)
+        { draft: parsed(message), model: model_of(message), input_tokens: input_tokens(message) }
+      end
+
+      private
+
+      def chat(**options)
+        RubyLLM.chat(**options)
+      end
+
+      def parsed(message)
+        body = message.respond_to?(:parsed) ? message.parsed : message.content
+        body = JSON.parse(body) if body.is_a?(String)
+        raise InvalidLens, "the drafting model returned no structured draft" unless body.is_a?(Hash)
+
+        body
+      rescue JSON::ParserError
+        raise InvalidLens, "the drafting model returned malformed JSON"
+      end
+
+      def model_of(message)
+        (message.respond_to?(:model_id) && message.model_id) || (message.respond_to?(:model) && message.model) || nil
+      end
+
+      def input_tokens(message)
+        return message.input_tokens if message.respond_to?(:input_tokens) && message.input_tokens
+
+        message.tokens&.input if message.respond_to?(:tokens)
+      end
+    end
+  end
+end

data/lib/truffler/lenses/scope.rb

@@ -0,0 +1,35 @@
+module Truffler
+  module Lenses
+    # What a lens applies to: the whole app, one tenant, or one user inside a
+    # tenant. User keys are held only as keyed digests.
+    Scope = Data.define(:type, :tenant_key, :user_digest) do
+      def self.app
+        new(type: :app, tenant_key: nil, user_digest: nil)
+      end
+
+      def self.tenant(tenant_key)
+        raise ArgumentError, "a tenant lens needs a tenant key" if tenant_key.blank?
+
+        new(type: :tenant, tenant_key: tenant_key.to_s, user_digest: nil)
+      end
+
+      def self.user(tenant_key, user_key)
+        raise ArgumentError, "a user lens needs a user key" if user_key.blank?
+
+        new(type: :user, tenant_key: tenant_key&.to_s, user_digest: Lenses.digest(user_key))
+      end
+
+      def app? = type == :app
+      def tenant? = type == :tenant
+      def user? = type == :user
+
+      def scope_key
+        case type
+        when :app then nil
+        when :tenant then tenant_key
+        when :user then user_digest
+        end
+      end
+    end
+  end
+end

data/lib/truffler/lenses/sealed_description.rb

@@ -0,0 +1,29 @@
+module Truffler
+  module Lenses
+    # Stores `description` through Lenses.seal, so encrypted models keep only
+    # ciphertext (or nothing) in the lens tables (R44).
+    module SealedDescription
+      extend ActiveSupport::Concern
+
+      included do
+        before_save :seal_description
+      end
+
+      def description
+        return @description_text if defined?(@description_text)
+
+        Lenses.unseal(described_model, read_attribute(:description))
+      end
+
+      def description=(text)
+        @description_text = text
+      end
+
+      private
+
+      def seal_description
+        write_attribute(:description, Lenses.seal(described_model, @description_text)) if defined?(@description_text)
+      end
+    end
+  end
+end

data/lib/truffler/lenses/settings.rb

@@ -0,0 +1,45 @@
+module Truffler
+  module Lenses
+    # `config.lenses`: who may create lenses, whether the system proposes them
+    # from query misses, and the limits every lens runs under (R42, R43).
+    #
+    #   config.lenses.creators = :tenant_users
+    #   config.lenses.authorize_lens = ->(user, scope) { user.admin? || scope.tenant_key == user.account_id.to_s }
+    class Settings
+      CREATORS = %i[developers tenant_users each_user].freeze
+
+      attr_reader :creators
+      attr_accessor :proposals, :expire_after, :spend_cap_usd, :sample_size, :max_questions, :generator,
+        :drafter_model, :authorize_lens, :user_key
+
+      def initialize
+        @creators = :developers
+        @proposals = false
+        @expire_after = 30.days
+        @spend_cap_usd = 1.0
+        @sample_size = 20
+        @max_questions = 8
+        @generator = nil
+        @drafter_model = nil
+        @authorize_lens = nil
+        @user_key = ->(user) { user.is_a?(ActiveRecord::Base) ? Search::Keystroke.user_key(user) : (user.respond_to?(:id) ? user.id : user) }
+      end
+
+      def creators=(value)
+        value = value.to_sym
+        raise ArgumentError, "config.lenses.creators must be one of #{CREATORS.join(', ')}" unless CREATORS.include?(value)
+
+        @creators = value
+      end
+
+      def generator_or_default
+        generator || RubyLLMGenerator.new
+      end
+
+      def key_for(user)
+        key = user_key.call(user)
+        key.nil? ? nil : key.to_s
+      end
+    end
+  end
+end