studio-engine 0.119.1 → 0.121.0

data/app/views/studio/voice/_styles.html.erb

@@ -0,0 +1,90 @@
+<%# The voice capture layer's scoped CSS (docs/VOICE_CAPTURE.md), rendered by
+    the chip and the recorder partials. Scoped classes rather than utilities, as
+    in studio/profiles/_voice_section: the chip, the dot, the ring and the help
+    drawing must render in an app whose Tailwind build never saw these files.
+    Every colour is a theme token (the primary through --color-primary-500-rgb
+    and the CTA fill under its label), so dark mode and each app's palette come
+    for free. Tap targets are 44px. A page rendering both partials carries this
+    block twice, which is harmless. %>
+<style>
+  .studio-mic { display: flex; width: 100%; flex-direction: column; align-items: center; gap: .5rem; }
+  .studio-mic-chip { display: inline-flex; min-height: 44px; max-width: 100%; align-items: center; gap: .5rem;
+    border-radius: 1.5rem; border: 1px solid var(--color-border, rgb(127 127 127 / .25));
+    background: var(--color-inset, rgb(127 127 127 / .12)); padding: .5rem 1rem; font-size: .875rem; font-weight: 600;
+    color: var(--color-text, inherit); cursor: pointer; text-align: left; }
+  .studio-mic-chip:focus-visible { outline: 3px solid rgb(var(--color-primary-500-rgb, 99 102 241) / .5); outline-offset: 2px; }
+  .studio-mic-icon { width: 1rem; height: 1rem; flex-shrink: 0; color: var(--color-text-secondary, currentColor); }
+  .studio-mic-name { min-width: 0; overflow-wrap: anywhere; }
+  .studio-mic-caret { width: .75rem; height: .75rem; flex-shrink: 0; color: var(--color-text-muted, currentColor); }
+  .studio-mic-chip[aria-expanded="true"] .studio-mic-caret { transform: rotate(180deg); }
+  [data-microphone-state="denied"] .studio-mic-chip { border-color: rgb(var(--color-primary-500-rgb, 99 102 241)); }
+  /* The live dot: hollow while nothing records; while a take records it fills
+     with the primary colour as loud as the voice (--studio-mic-level, 0..1). */
+  .studio-mic-dot { width: .625rem; height: .625rem; flex-shrink: 0; border-radius: 9999px; border: 2px solid currentColor; opacity: .35; }
+  [data-microphone-live="true"] .studio-mic-dot { opacity: 1; border-color: rgb(var(--color-primary-500-rgb, 99 102 241));
+    background-color: rgb(var(--color-primary-500-rgb, 99 102 241) / calc(.15 + var(--studio-mic-level, 0) * .85));
+    transform: scale(calc(1 + var(--studio-mic-level, 0) * .5)); transition: transform 80ms linear, background-color 80ms linear; }
+  .studio-mic-panel { width: 100%; max-width: 24rem; padding: .75rem; text-align: left; display: grid; gap: .5rem; }
+  .studio-mic-panel[hidden] { display: none; }
+  .studio-mic-note { font-size: .875rem; color: var(--color-text-muted, inherit); }
+  .studio-mic-list { list-style: none; margin: 0; padding: 0; display: grid; gap: .25rem; }
+  .studio-mic-option { display: flex; min-height: 44px; width: 100%; align-items: center; gap: .5rem; border-radius: .75rem;
+    border: 1px solid transparent; background: transparent; padding: .5rem .75rem; text-align: left; font-size: .875rem;
+    color: var(--color-text, inherit); cursor: pointer; }
+  .studio-mic-option:hover { background-color: rgb(var(--color-primary-500-rgb, 99 102 241) / .08); }
+  .studio-mic-option[aria-current="true"] { border-color: rgb(var(--color-primary-500-rgb, 99 102 241));
+    background-color: rgb(var(--color-primary-500-rgb, 99 102 241) / .12); font-weight: 600; }
+  .studio-mic-check { width: 1rem; flex-shrink: 0; font-weight: 700; color: rgb(var(--color-primary-500-rgb, 99 102 241)); }
+  .studio-mic-option-label { min-width: 0; flex: 1; overflow-wrap: anywhere; }
+  .studio-mic-in-use { flex-shrink: 0; border-radius: 9999px; padding: .125rem .5rem; font-size: .75rem; font-weight: 700;
+    background: var(--color-cta-fill, var(--color-cta, rgb(var(--color-primary-500-rgb, 99 102 241)))); color: var(--btn-primary-fg, #fff); }
+  .studio-mic-help-link { min-height: 44px; width: 100%; border-radius: .75rem; padding: 0 .75rem; text-align: left; font-size: .875rem;
+    font-weight: 600; color: var(--color-text-secondary, inherit); text-decoration: underline; background: transparent; border: 0; cursor: pointer; }
+  /* The help dialog: a native modal <dialog>, so the page behind it is inert. */
+  .studio-mic-help { border: 0; padding: 0; margin: auto; width: min(28rem, calc(100vw - 2rem)); max-height: calc(100dvh - 2rem);
+    overflow-y: auto; text-align: left; color: var(--color-text-body, inherit); background: var(--color-surface, Canvas); border-radius: 1rem; }
+  .studio-mic-help::backdrop { background-color: rgb(0 0 0 / .55); }
+  .studio-mic-help-body { display: grid; gap: 1rem; padding: 1.25rem; }
+  .studio-mic-help-lead { display: grid; gap: .25rem; border-radius: .75rem; background: var(--color-inset, rgb(127 127 127 / .12)); padding: .75rem; }
+  .studio-mic-help-lead[hidden], .studio-mic-help-chrome[hidden], .studio-mic-help-other[hidden] { display: none; }
+  .studio-mic-help-headline { font-weight: 600; color: var(--color-text, inherit); margin: 0; }
+  .studio-mic-help-tip { font-size: .875rem; color: var(--color-text-secondary, inherit); margin: 0; }
+  .studio-mic-help-title { font-size: 1.25rem; font-weight: 700; color: var(--color-text, inherit); margin: 0; }
+  .studio-mic-help-steps { list-style: none; margin: 0; padding: 0; display: grid; gap: .5rem; }
+  .studio-mic-help-steps li { display: flex; align-items: flex-start; gap: .75rem; }
+  .studio-mic-step { display: flex; width: 1.5rem; height: 1.5rem; flex-shrink: 0; align-items: center; justify-content: center;
+    border-radius: 9999px; font-size: .75rem; font-weight: 700;
+    background: var(--color-cta-fill, var(--color-cta, rgb(var(--color-primary-500-rgb, 99 102 241)))); color: var(--btn-primary-fg, #fff); }
+  .studio-mic-help-actions { display: flex; justify-content: flex-end; margin: 0; }
+  .studio-mic-help-close { min-height: 44px; padding: 0 1.5rem; }
+  /* The drawn address bar: never a screenshot, every stroke a token. */
+  .studio-mic-mock { width: 100%; height: auto; color: var(--color-text, currentColor); }
+  .studio-mic-mock .mock-bar, .studio-mic-mock .mock-panel { fill: var(--color-inset, rgb(127 127 127 / .12)); stroke: currentColor; stroke-opacity: .25; }
+  .studio-mic-mock .mock-ring { fill: none; stroke: rgb(var(--color-primary-500-rgb, 99 102 241)); stroke-width: 3; }
+  .studio-mic-mock .mock-ink { stroke: currentColor; }
+  .studio-mic-mock .mock-knob { fill: currentColor; stroke: none; }
+  .studio-mic-mock .mock-text { fill: currentColor; font-family: inherit; }
+  .studio-mic-mock .mock-on, .studio-mic-mock .mock-badge { fill: rgb(var(--color-primary-500-rgb, 99 102 241)); }
+  .studio-mic-mock .mock-knob-on, .studio-mic-mock .mock-badge-text { fill: var(--color-surface, Canvas); }
+
+  /* The record button: a ring as loud as the voice (--studio-recorder-level). */
+  .studio-recorder { display: flex; flex-direction: column; align-items: center; gap: .75rem; text-align: center; }
+  .studio-recorder-button { min-height: 44px; min-width: 12rem; max-width: 100%; border: 0; border-radius: 9999px; padding: .875rem 1.75rem;
+    font-weight: 700; cursor: pointer; touch-action: none; -webkit-user-select: none; user-select: none;
+    color: var(--btn-primary-fg, #fff); background: var(--color-cta-fill, var(--color-cta, rgb(var(--color-primary-500-rgb, 99 102 241))));
+    box-shadow: 0 0 0 calc(var(--studio-recorder-level, 0) * 14px) rgb(var(--color-primary-500-rgb, 99 102 241) / .3);
+    transition: box-shadow 80ms linear; }
+  .studio-recorder-button:focus-visible { outline: 3px solid rgb(var(--color-primary-500-rgb, 99 102 241) / .5); outline-offset: 3px; }
+  .studio-recorder-button:disabled { opacity: .5; cursor: not-allowed; }
+  [data-voice-recorder-state="recording"] .studio-recorder-button { background: var(--color-danger-fill, var(--color-danger, #dc2626)); }
+  .studio-recorder-timer { font-variant-numeric: tabular-nums; font-size: .875rem; color: var(--color-text-muted, inherit); }
+  .studio-recorder-status { min-height: 2.5rem; max-width: 24rem; margin: 0; color: var(--color-text-body, inherit); }
+  .studio-recorder-failed { display: none; font-size: .8125rem; color: var(--color-text-secondary, inherit); }
+  [data-studio-controller-failed~="voice-recorder"] .studio-recorder-failed { display: block; }
+  .studio-mic-failed { display: none; margin: 0; font-size: .8125rem; color: var(--color-text-secondary, inherit); }
+  [data-studio-controller-failed~="microphone-chip"] .studio-mic-failed { display: block; }
+  @media (prefers-reduced-motion: reduce) {
+    [data-microphone-live="true"] .studio-mic-dot { transform: none; transition: none; }
+    .studio-recorder-button { transition: none; }
+  }
+</style>

data/db/migrate/20261029120000_add_voice_profile_to_users.rb

@@ -0,0 +1,44 @@
+# The voice row on /profile (Studio.voice_profile): one speaker embedding on the
+# user's own record, the model it came from, and when it was saved.
+#
+# A HOST-TABLE MIGRATION, the engine's second after
+# add_standard_user_profile_columns, and built the same way for the same reason:
+# one definition the apps install (`bin/rails studio_engine:install:migrations`)
+# instead of a hand-written copy per app.
+#
+#   voice_embedding            jsonb  the averaged unit vector (256 floats for
+#                                     the wespeaker embedder). A pattern of the
+#                                     voice, never audio: the takes stay on the
+#                                     device.
+#   voice_embedding_model      string which embedder and revision made it
+#                                     (Studio::VoiceMatch::EMBEDDERS ids). Vectors
+#                                     from different models are not comparable,
+#                                     so the matcher filters on this.
+#   voice_embedding_updated_at datetime
+#
+# Every add is `if_not_exists`, and an app with no users table is skipped, as in
+# the standard-columns migration.
+#
+# THE DOWN DROPS THEM, unlike the standard-columns migration, which refuses. That
+# one could not tell its columns from columns the host already owned
+# (first_name, birth_year). These three names are the engine's own coinage, and
+# no consumer had any of them when this shipped (mcritchie-studio,
+# turf-monster, mcritchie-industries, cyvasse and moms-app checked 2026-10-29),
+# so a drop removes only what this migration added.
+class AddVoiceProfileToUsers < ActiveRecord::Migration[7.2]
+  def up
+    return unless table_exists?(:users)
+
+    add_column :users, :voice_embedding, :jsonb, if_not_exists: true
+    add_column :users, :voice_embedding_model, :string, if_not_exists: true
+    add_column :users, :voice_embedding_updated_at, :datetime, if_not_exists: true
+  end
+
+  def down
+    return unless table_exists?(:users)
+
+    remove_column :users, :voice_embedding_updated_at, if_exists: true
+    remove_column :users, :voice_embedding_model, if_exists: true
+    remove_column :users, :voice_embedding, if_exists: true
+  end
+end

data/lib/studio/engine.rb

@@ -299,6 +299,16 @@ module Studio
       app.config.middleware.use Studio::GoogleSignIn::Middleware
     end
 
+    # The voice row's vectors stay out of every consumer's request log and
+    # User#inspect: POST /profile/voice carries voice[embeddings], and the user
+    # holds voice_embedding (Voicebox logged vectors until it filtered them).
+    # `(\A|\.)` also masks the JSON param wrapper's copy (profile.voice.embeddings).
+    # POST /voice/takes carries voice[embedding] (one take's vector) and
+    # voice[audio] (the take itself); both are masked the same way.
+    initializer "studio.voice_profile.filter_parameters" do |app|
+      app.config.filter_parameters += [/(\A|\.)voice\.(embeddings|embedding|audio)\z/, /\Avoice_embedding\z/]
+    end
+
     initializer "studio.footer_only_eager_load" do
       next if Studio.active_record?
 

data/lib/studio/profile_sections.rb

@@ -6,6 +6,7 @@
 # and the engine fails to boot. Declaring the dependency where it is used makes
 # the pair immune to a future reorder of that require list.
 require_relative "newsletter"
+require_relative "voice_match"
 
 # Resolves Studio.profile_sections — the rows that make up the shared /profile
 # page — for a given view context. Pure Ruby (no Rails dependency) so the unit
@@ -100,6 +101,16 @@ module Studio
         requires: Studio::Newsletter::COLUMNS,
         modals: "studio/profiles/newsletter_modals" },
 
+      # The voice: three phrases read once, so an agent can tell who is
+      # talking. OPT-IN (Studio.voice_profile), because it fetches a speaker
+      # model from Hugging Face and stores a voice pattern, and a host's CSP and
+      # privacy page must say so first. Gated on the columns too: the engine
+      # migration add_voice_profile_to_users installs them.
+      { key: :voice, title: "Your voice", page: :show,
+        partial: "studio/profiles/voice_section",
+        requires: Studio::VoiceMatch::USER_COLUMNS,
+        if: -> { Studio.voice_profile } },
+
       # --- the edit page ------------------------------------------------------
       # These are FIELDS in one form with one Save, so they carry no buttons of
       # their own. Email included: it needed a separate action only while it was

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.119.1"
+  VERSION = "0.121.0"
 end

data/lib/studio/voice_capture.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+# The words on the engine's voice capture layer: the microphone chip and its
+# help dialog (studio/voice/_microphone_chip, _microphone_help), and the record
+# button (studio/voice/_recorder). Ported from Voicebox's MicrophoneHelper and
+# RecordingsHelper; the contract is docs/VOICE_CAPTURE.md.
+#
+# The chip names the microphone the page records from, so a switched-off
+# headset Chrome picked on its own is plain to see, and lets the person pick
+# another. A host passes `copy:` to either partial to change any line; its
+# keys merge over these, one level deep per section.
+module Studio
+  module VoiceCapture
+    # Where the chip remembers the pick (localStorage), unless a partial is given
+    # storage_key:. Mirrors STORAGE_KEY in app/javascript/studio/microphone.js.
+    STORAGE_KEY = "studio.microphone"
+
+    MICROPHONE_COPY = {
+      # Before the person allows the microphone the browser gives no names.
+      "prompt" => { "chip" => "Microphone: tap Record to allow",
+                    "note" => "Tap Record once and allow the microphone. Then you can pick one here." },
+      # The microphone icon says what the name is, so the name gets the whole
+      # width at 390px; a screen reader hears "aria" in full.
+      "ready" => { "chip" => "%{microphone}", "aria" => "Microphone: %{microphone}. Tap to pick another.",
+                   "note" => "Pick the microphone to record with. Your next take uses it." },
+      "denied" => { "chip" => "Microphone not allowed",
+                    "note" => "This site isn't allowed to use the microphone. Tap the icon beside the web address, " \
+                              "set Microphone to Allow, then reload this page." },
+      "unsupported" => { "chip" => "No microphone here",
+                         "note" => "This browser can't list microphones. Try Safari or Chrome." },
+      "fell_back" => "That microphone isn't connected, so I'm using %{microphone}.",
+      "empty" => "No microphones found. Plug one in and it shows up here.",
+      "in_use" => "In use",
+      # Shown only when the chip's controller failed to load.
+      "unavailable" => "Picking a microphone didn't load. Reload to try again.",
+      # The help dialog. Switching happens on the page, by device id, so the
+      # dialog never sends anyone to Chrome to switch: Chrome's settings are
+      # where the microphone is ALLOWED, and where a person checks it when a
+      # take stays silent.
+      "help" => {
+        "link" => "Help with microphones",
+        "title_chrome" => "How to change your microphone in Chrome",
+        "title_other" => "How to change your microphone",
+        "steps_chrome" => [
+          "Click the icon left of the address.",
+          "Turn Microphone on.",
+          "Make sure your microphone is allowed.",
+          "Reload the page."
+        ],
+        "other" => "Allow the microphone when your browser asks, or in its settings for this site, " \
+                   "then pick your microphone here and reload.",
+        "unnamed" => "the microphone",
+        "switched" => "Switched to %{microphone} ✓",
+        "switched_tip_chrome" => "If Chrome asks or it stays silent, here's how to check Chrome's microphone.",
+        "switched_tip_other" => "If your browser asks or it stays silent, here's how to check its microphone.",
+        "silent" => "I couldn't hear anything from %{microphone}.",
+        "silent_tip" => "Pick another microphone in the list, or check that the browser may use it:",
+        "denied" => "This site isn't allowed to use the microphone yet.",
+        "denied_tip" => "Allow it, then reload:",
+        "close" => "Close"
+      }
+    }.freeze
+
+    # The record button's words per state. Mirrors COPY in
+    # app/javascript/studio/voice_recorder.js, which fills any state a page
+    # leaves out; the partial renders the idle words so the button reads right
+    # before the controller connects.
+    RECORDER_COPY = {
+      "idle" => { "button" => "Record", "status" => "" },
+      "recording" => { "button" => "Stop", "status" => "Listening..." },
+      "unavailable" => "Recording didn't load on this page. Reload to try again."
+    }.freeze
+
+    module_function
+
+    # The copy with a host's overrides merged in: a Hash section merges key by
+    # key, anything else replaces.
+    def microphone_copy(overrides = nil)
+      merge(MICROPHONE_COPY, overrides)
+    end
+
+    def recorder_copy(overrides = nil)
+      merge(RECORDER_COPY, overrides)
+    end
+
+    def merge(base, overrides)
+      return base if overrides.nil? || overrides.empty?
+
+      overrides.to_h.each_with_object(base.dup) do |(key, value), merged|
+        key = key.to_s
+        merged[key] = merged[key].is_a?(Hash) && value.is_a?(Hash) ? merged[key].merge(value.transform_keys(&:to_s)) : value
+      end
+    end
+  end
+end

data/lib/studio/voice_match.rb

@@ -0,0 +1,238 @@
+# frozen_string_literal: true
+
+require "json"
+
+# Who is speaking: compares one take's speaker embedding with the voice
+# embeddings saved on users' own records (the voice row on /profile, opt-in with
+# Studio.voice_profile). Pure arithmetic on arrays of floats, with no Rails
+# dependency, so the threshold logic is unit-tested without a browser, a model or
+# a database.
+#
+# THE EMBEDDINGS COME FROM THE BROWSER. The profile page records three short
+# phrases, turns each take into a vector on the person's own device
+# (app/javascript/studio/voice_profile.js), drops the audio, and posts only the
+# vectors. The server averages them here and stores one vector on the user. No
+# audio is ever uploaded for this.
+#
+# Ported from Voicebox's SpeakerMatch (McRitchie-Studio/voicebox#10), where the
+# embedder, the threshold and the averaging were measured.
+module Studio
+  module VoiceMatch
+    # The speaker embedders the browser may run, by name. `id` is what is stored
+    # on the user beside the vector (users.voice_embedding_model): vectors from
+    # two models, or from two revisions of one model, are not comparable, so the
+    # matcher only ever compares a take with users whose id is the same.
+    #
+    # "wespeaker" is WeSpeaker's ResNet34 speaker model (trained on VoxCeleb),
+    # int8-quantized, run by transformers.js on onnxruntime-web. The model is
+    # about 6.7 MB and the runtime about 4.3 MB; the browser caches both after the
+    # first load. Its revision is pinned so THRESHOLD always describes the vectors
+    # it was tuned on. Changing the revision is changing the id, and every saved
+    # voice stops matching until its owner re-records.
+    #
+    # "fake" is for tests only: a deterministic vector seeded by a voice name the
+    # test sets on the page (window.studioFakeVoice), because Chrome's fake
+    # microphone cannot play chosen audio.
+    TRANSFORMERS_VERSION = "3.7.6"
+
+    # Where the browser imports transformers.js from, by full URL. NOT an
+    # importmap pin: every pin a host draws must be a fingerprinted local asset
+    # (the hub's AssetUrlsTest), and a ~1 MB runtime that fetches its own
+    # onnxruntime WebAssembly from the same jsDelivr path anyway gains nothing
+    # from being vendored. A host's CSP names this package path.
+    TRANSFORMERS_URL =
+      "https://cdn.jsdelivr.net/npm/@huggingface/transformers@#{TRANSFORMERS_VERSION}/dist/transformers.min.js"
+
+    EMBEDDERS = {
+      "wespeaker" => {
+        "id" => "wespeaker-voxceleb-resnet34-LM@6a61a18",
+        "size" => 256,
+        "model" => "onnx-community/wespeaker-voxceleb-resnet34-LM",
+        "revision" => "6a61a1833ff2583aabeba044f5c8221f00b67ceb",
+        "dtype" => "q8",
+        "runtime" => TRANSFORMERS_URL
+      }.freeze,
+      "fake" => {
+        "id" => "fake-256",
+        "size" => 256
+      }.freeze
+    }.freeze
+
+    # The columns the voice lives in on the host's users table, installed by the
+    # engine migration add_voice_profile_to_users.
+    USER_COLUMNS = %i[voice_embedding voice_embedding_model voice_embedding_updated_at].freeze
+
+    # What the setup asks the person to read: three short, phonetically varied
+    # sentences of about four seconds each. TAKES is their count, and the server
+    # refuses a save with any other number of vectors.
+    PHRASES = [
+      "The quick brown fox jumps over the lazy dog.",
+      "I'd like a cup of coffee and a slice of toast, please.",
+      "My voice is my own, and today is a good day to talk."
+    ].freeze
+
+    TAKES = PHRASES.size
+
+    # The cosine similarity a take must reach to be named. Measured in Voicebox
+    # (2026-10-29) on the wespeaker embedder, enrolling five synthetic voices from
+    # three phrases each and probing with a fourth: same voice 0.85 - 0.91,
+    # different voice 0.04 - 0.53 (the closest pair two adult women). 0.6 sits
+    # above every different-voice score and well under every same-voice one.
+    THRESHOLD = 0.6
+
+    # user: the closest user at or above the threshold, else nil. score: that
+    # closest similarity, or nil when there was nothing to compare.
+    Result = Struct.new(:user, :score, keyword_init: true) do
+      def unknown? = user.nil?
+    end
+
+    NONE = Result.new(user: nil, score: nil).freeze
+
+    module_function
+
+    # The settings the page hands the browser for one embedder.
+    def browser_config(name)
+      config = EMBEDDERS.fetch(name.to_s)
+      { "name" => name.to_s }.merge(config)
+    end
+
+    def embedder!(name)
+      EMBEDDERS.fetch(name.to_s) do
+        raise ArgumentError, "Studio.voice_embedder must be one of #{EMBEDDERS.keys.join(', ')} (got #{name.inspect})"
+      end
+    end
+
+    def model_id(name) = embedder!(name).fetch("id")
+
+    def size(name) = embedder!(name).fetch("size")
+
+    # The closest user to `embedding` among `among`, or nil when nobody reaches
+    # the threshold. Only users whose saved vector came from `model` are
+    # compared. `among` is anything enumerable of users; an ActiveRecord scope is
+    # narrowed to that model in SQL first.
+    def identify(embedding, among:, model:, threshold: THRESHOLD)
+      match(embedding, among: among, model: model, threshold: threshold).user
+    end
+
+    # identify, with the score: a caller that wants to say "someone new" needs to
+    # tell "nobody close" (a score below the threshold) from "nothing to compare".
+    def match(embedding, among:, model:, threshold: THRESHOLD)
+      probe = vector(embedding)
+      return NONE if probe.nil? || model.to_s.empty?
+
+      best = nil
+      best_score = nil
+      candidates(among, model).each do |user|
+        next unless user.respond_to?(:voice_embedding_model) && user.voice_embedding_model.to_s == model.to_s
+
+        saved = vector(user.voice_embedding)
+        next if saved.nil? || saved.size != probe.size
+
+        score = cosine(probe, saved)
+        next if score.nil?
+
+        if best_score.nil? || score > best_score
+          best = user
+          best_score = score
+        end
+      end
+      return NONE if best_score.nil?
+
+      Result.new(user: best_score >= threshold ? best : nil, score: best_score.round(4))
+    end
+
+    # Cosine similarity, -1..1; nil when the sizes differ or either vector has
+    # no length.
+    def cosine(a, b)
+      return nil unless a.size == b.size
+
+      dot = 0.0
+      norm_a = 0.0
+      norm_b = 0.0
+      a.each_with_index do |x, i|
+        y = b[i]
+        dot += x * y
+        norm_a += x * x
+        norm_b += y * y
+      end
+      return nil if norm_a.zero? || norm_b.zero?
+
+      dot / Math.sqrt(norm_a * norm_b)
+    end
+
+    # One profile vector from the setup takes: each take scaled to unit length,
+    # so a loud phrase does not outweigh a quiet one, then averaged and scaled to
+    # unit length again. nil when no take has any length (silence embeds to
+    # zeros), or the takes disagree on size.
+    def average(vectors)
+      units = Array(vectors).map { |v| normalize(v) }.compact
+      return nil if units.empty?
+      return nil unless units.all? { |u| u.size == units.first.size }
+
+      sum = Array.new(units.first.size, 0.0)
+      units.each { |u| u.each_with_index { |x, i| sum[i] += x } }
+      normalize(sum)
+    end
+
+    def normalize(vector)
+      return nil if vector.nil? || vector.empty?
+
+      norm = Math.sqrt(vector.sum { |x| x * x })
+      return nil if norm.zero? || !norm.finite?
+
+      vector.map { |x| x / norm }
+    end
+
+    # A vector the browser sent, as floats, or nil when it is not `size` finite
+    # numbers. Accepts a JSON string or an already-parsed array.
+    def parse(raw, size:)
+      values = raw.is_a?(String) ? JSON.parse(raw) : raw
+      return nil unless values.is_a?(Array) && values.size == size
+      return nil unless values.all? { |x| x.is_a?(Numeric) && x.to_f.finite? }
+
+      values.map(&:to_f)
+    rescue JSON::ParserError
+      nil
+    end
+
+    # The setup's takes, validated: exactly TAKES vectors of `size` finite
+    # numbers, each with some length. Returns the averaged unit vector, or nil.
+    def enrol(raw_takes, size:)
+      takes = raw_takes.is_a?(String) ? JSON.parse(raw_takes) : raw_takes
+      return nil unless takes.is_a?(Array) && takes.size == TAKES
+
+      vectors = takes.map { |take| parse(take, size: size) }
+      return nil if vectors.any?(&:nil?)
+      return nil if vectors.any? { |v| normalize(v).nil? }
+
+      average(vectors)
+    rescue JSON::ParserError
+      nil
+    end
+
+    # A stored embedding (jsonb array, or a JSON string on an adapter without
+    # json columns) as floats, or nil.
+    def vector(raw)
+      values = raw.is_a?(String) ? JSON.parse(raw) : raw
+      return nil unless values.is_a?(Array) && !values.empty?
+      return nil unless values.all? { |x| x.is_a?(Numeric) && x.to_f.finite? }
+
+      values.map(&:to_f)
+    rescue JSON::ParserError
+      nil
+    end
+
+    def candidates(among, model)
+      return Array(among) unless among.respond_to?(:where)
+
+      # A scope or the model class itself. Narrowed in SQL only when the table
+      # has the column; the per-user check in #match holds either way.
+      klass = among.respond_to?(:klass) ? among.klass : among
+      if klass.respond_to?(:column_names) && klass.column_names.include?("voice_embedding_model")
+        among.where(voice_embedding_model: model.to_s)
+      else
+        among
+      end
+    end
+  end
+end