@vellumai/assistant 0.11.3-staging.2 → 0.11.3-staging.4

package/src/providers/speech-to-text/provider-catalog.ts

@@ -16,6 +16,7 @@ import type {
   SttProviderId,
   TelephonySttMode,
 } from "../../stt/types.js";
+import { baseLanguageSubtag } from "../../util/language-subtag.js";
 
 // ---------------------------------------------------------------------------
 // Client display metadata
@@ -282,6 +283,43 @@ export function listProviderEntries(): readonly SttProviderEntry[] {
   return [...CATALOG.values()];
 }
 
+/**
+ * A base-subtag regex over the pinned listening language. The pin is
+ * free-form workspace config, and it flows into prompt interpolation and
+ * per-language table lookups, so only a plausible ISO 639 base subtag
+ * passes; anything else (junk strings, prototype keys like "constructor")
+ * resolves as no pin.
+ */
+const PINNED_LANGUAGE_SUBTAG_REGEX = /^[a-z]{2,3}$/;
+
+/**
+ * The configured `services.stt.language` pin as the caller's listening
+ * language, or undefined when the pin carries no signal.
+ *
+ * A persisted pin only counts when the provider honors manual language
+ * selection: auto-detecting providers (gemini, whisper) ignore the setting
+ * entirely, so treating it as the caller's language would force every
+ * turn into a stale pin. "multi" and blank mean auto-detect (no pin), and
+ * the value must normalize to a plausible base subtag. Shared by the
+ * telephony pre-speech prompt rule (voice-session-bridge.ts), live
+ * voice's turn language (live-voice-session.ts), and telephony synthesis
+ * (telephony-synthesis-language.ts) so the gate cannot drift.
+ */
+export function pinnedListeningLanguage(
+  provider: string,
+  configuredLanguage: string | undefined,
+): string | undefined {
+  const providerHonorsLanguagePin =
+    getProviderEntry(provider as SttProviderId)?.languageSelection === "manual";
+  if (!providerHonorsLanguagePin || configuredLanguage?.trim() === "multi") {
+    return undefined;
+  }
+  const base = baseLanguageSubtag(configuredLanguage);
+  return base !== undefined && PINNED_LANGUAGE_SUBTAG_REGEX.test(base)
+    ? base
+    : undefined;
+}
+
 /**
  * Look up the credential-provider name for a given STT provider.
  *

package/src/runtime/__tests__/local-actor-identity-force-refresh.test.ts

@@ -0,0 +1,104 @@
+/**
+ * Tests for the cache-bypass option on the local guardian principal lookup.
+ *
+ * The guardian-delivery reader caches a successful read that finds no binding,
+ * and gateway-side binding writes do not invalidate the daemon's cache. A
+ * caller polling for a binding it expects to appear (the SSE actor-principal
+ * heal) therefore has to force the read, or every attempt re-reads the same
+ * empty answer until the TTL lapses.
+ */
+import { afterAll, beforeEach, describe, expect, mock, test } from "bun:test";
+
+import type { GuardianDelivery } from "@vellumai/gateway-client";
+
+let cachedResult: GuardianDelivery[] | null = null;
+let freshResult: GuardianDelivery[] | null = null;
+let cachedCalls = 0;
+let freshCalls = 0;
+
+mock.module("../../config/env.js", () => ({
+  isHttpAuthDisabled: () => true,
+  hasUngatedHttpAuthDisabled: () => false,
+}));
+
+mock.module("../../contacts/guardian-delivery-reader.js", () => ({
+  getGuardianDelivery: () => {
+    cachedCalls++;
+    return Promise.resolve(cachedResult);
+  },
+  getGuardianDeliveryFresh: () => {
+    freshCalls++;
+    return Promise.resolve(freshResult);
+  },
+  peekCachedGuardianDelivery: () => undefined,
+  guardianForChannel: (list: GuardianDelivery[]) => list[0],
+}));
+
+import {
+  findLocalGuardianPrincipalId,
+  resolveActorPrincipalIdForLocalGuardian,
+} from "../local-actor-identity.js";
+
+afterAll(() => {
+  mock.restore();
+});
+
+/** Minimal guardian row: only `principalId` is read here. */
+function guardian(principalId: string): GuardianDelivery {
+  return { principalId } as unknown as GuardianDelivery;
+}
+
+describe("local guardian principal lookup — cache bypass", () => {
+  beforeEach(() => {
+    cachedCalls = 0;
+    freshCalls = 0;
+    cachedResult = [];
+    freshResult = [];
+  });
+
+  test("reads the cache by default", async () => {
+    cachedResult = [guardian("guardian-cached")];
+    freshResult = [guardian("guardian-fresh")];
+
+    expect(await findLocalGuardianPrincipalId()).toBe("guardian-cached");
+    expect(cachedCalls).toBe(1);
+    expect(freshCalls).toBe(0);
+  });
+
+  test("forceRefresh bypasses the cache and sees a binding the cache would miss", async () => {
+    // Cached read holds the empty result from before the binding existed.
+    cachedResult = [];
+    freshResult = [guardian("guardian-fresh")];
+
+    expect(await findLocalGuardianPrincipalId()).toBeUndefined();
+    expect(await findLocalGuardianPrincipalId({ forceRefresh: true })).toBe(
+      "guardian-fresh",
+    );
+    expect(freshCalls).toBe(1);
+  });
+
+  test("resolveActorPrincipalIdForLocalGuardian threads forceRefresh through", async () => {
+    cachedResult = [];
+    freshResult = [guardian("guardian-fresh")];
+
+    expect(
+      await resolveActorPrincipalIdForLocalGuardian("dev-bypass"),
+    ).toBeUndefined();
+    expect(
+      await resolveActorPrincipalIdForLocalGuardian("dev-bypass", {
+        forceRefresh: true,
+      }),
+    ).toBe("guardian-fresh");
+    expect(freshCalls).toBe(1);
+  });
+
+  test("a non-dev-bypass principal is passed through without any lookup", async () => {
+    expect(
+      await resolveActorPrincipalIdForLocalGuardian("actor-123", {
+        forceRefresh: true,
+      }),
+    ).toBe("actor-123");
+    expect(cachedCalls).toBe(0);
+    expect(freshCalls).toBe(0);
+  });
+});

package/src/runtime/assistant-event-hub.ts

@@ -465,6 +465,29 @@ export class AssistantEventHub {
     return this.getClientById(clientId)?.actorPrincipalId;
   }
 
+  /**
+   * Whether the connection identified by `connectionId` is still an active
+   * client subscription that carries no `actorPrincipalId`.
+   *
+   * Drives the retrying SSE self-heal (`sse-actor-principal-heal.ts`): the loop
+   * re-checks before each attempt so it stops as soon as the connection closes,
+   * is replaced by a reconnect, or gets a principal from any path. Returns
+   * `false` for an unknown, inactive, or process-type connection.
+   */
+  needsActorPrincipalHeal(connectionId: string): boolean {
+    for (const entry of this.subscribers) {
+      if (entry.connectionId !== connectionId) {
+        continue;
+      }
+      return (
+        entry.active &&
+        entry.type === "client" &&
+        entry.actorPrincipalId == null
+      );
+    }
+    return false;
+  }
+
   /**
    * Fill a missing `actorPrincipalId` on a live client subscription.
    *

package/src/runtime/local-actor-identity.ts

@@ -11,6 +11,7 @@
 import { isHttpAuthDisabled } from "../config/env.js";
 import {
   getGuardianDelivery,
+  getGuardianDeliveryFresh,
   guardianForChannel,
   peekCachedGuardianDelivery,
 } from "../contacts/guardian-delivery-reader.js";
@@ -52,11 +53,19 @@ export function buildLocalAuthContext(conversationId: string): AuthContext {
  * Returns `undefined` when no vellum guardian binding exists (e.g. fresh
  * install before bootstrap, or the gateway is unreachable). Callers should
  * treat that case as "not yet available" and proceed without a principalId.
+ *
+ * `forceRefresh` bypasses the reader's TTL cache. A successful read that finds
+ * no binding is itself cached, and gateway-side binding writes do not
+ * invalidate the daemon's cache, so a caller that polls for a binding it
+ * expects to appear (the SSE actor-principal heal) must force the read or it
+ * re-reads the same empty answer until the TTL lapses.
  */
-export async function findLocalGuardianPrincipalId(): Promise<
-  string | undefined
-> {
-  const list = await getGuardianDelivery({ channelTypes: ["vellum"] });
+export async function findLocalGuardianPrincipalId(options?: {
+  forceRefresh?: boolean;
+}): Promise<string | undefined> {
+  const list = options?.forceRefresh
+    ? await getGuardianDeliveryFresh({ channelTypes: ["vellum"] })
+    : await getGuardianDelivery({ channelTypes: ["vellum"] });
   if (!list) {
     return undefined;
   }
@@ -136,15 +145,19 @@ export function findLocalGuardianPrincipalIdFromStore(): string | undefined {
  * `undefined` when dev-bypass is set but no guardian binding has been created
  * yet (e.g. fresh install before bootstrap); callers must treat this the
  * same as a missing principal.
+ *
+ * `forceRefresh` bypasses the guardian-delivery cache, for callers that poll
+ * for a binding they expect to appear. See {@link findLocalGuardianPrincipalId}.
  */
 export async function resolveActorPrincipalIdForLocalGuardian(
   rawHeader: string | undefined,
+  options?: { forceRefresh?: boolean },
 ): Promise<string | undefined> {
   if (rawHeader !== "dev-bypass" || !isHttpAuthDisabled()) {
     return rawHeader;
   }
 
-  const guardianPrincipalId = await findLocalGuardianPrincipalId();
+  const guardianPrincipalId = await findLocalGuardianPrincipalId(options);
   if (guardianPrincipalId) {
     return guardianPrincipalId;
   }

package/src/runtime/routes/__tests__/sse-actor-principal-heal.test.ts

@@ -0,0 +1,165 @@
+/**
+ * Tests for the retrying SSE actor-principal self-heal.
+ *
+ * The invariant they pin: a single empty or failed guardian lookup must not
+ * strand the subscription without a principal. The read goes over the gateway
+ * IPC and comes back empty both when the transport fails and when no binding
+ * exists yet, and a subscription that stays principal-less rejects every
+ * host-proxy result its client submits with "Submitting actor does not match
+ * the target client's actor for this request" until it reconnects.
+ */
+import { describe, expect, mock, test } from "bun:test";
+
+import { startActorPrincipalHeal } from "../sse-actor-principal-heal.js";
+
+/** All-zero schedule so the retries run without real wall-clock delay. */
+const NO_DELAYS = [0, 0, 0];
+
+/** Minimal hub double: `needs` flips to false once a principal is filled. */
+function fakeHub(options?: { needs?: boolean }) {
+  let needs = options?.needs ?? true;
+  const filled: string[] = [];
+  return {
+    filled,
+    setNeeds(value: boolean) {
+      needs = value;
+    },
+    needsActorPrincipalHeal: mock(() => needs),
+    fillClientActorPrincipalId: mock((_connectionId: string, id: string) => {
+      filled.push(id);
+      needs = false;
+    }),
+  };
+}
+
+/** Let the heal's async loop run to completion. */
+async function settle(): Promise<void> {
+  for (let i = 0; i < 10; i++) {
+    await new Promise((resolve) => setTimeout(resolve, 0));
+  }
+}
+
+describe("startActorPrincipalHeal", () => {
+  test("fills the principal on the first successful attempt", async () => {
+    const hub = fakeHub();
+    startActorPrincipalHeal({
+      hub,
+      connectionId: "conn-1",
+      resolve: () => Promise.resolve("guardian-real-id"),
+      delaysMs: NO_DELAYS,
+    });
+    await settle();
+
+    expect(hub.filled).toEqual(["guardian-real-id"]);
+    expect(hub.needsActorPrincipalHeal).toHaveBeenCalledTimes(1);
+  });
+
+  test("retries after a lookup that resolves undefined (gateway unreachable)", async () => {
+    const hub = fakeHub();
+    let calls = 0;
+    startActorPrincipalHeal({
+      hub,
+      connectionId: "conn-1",
+      resolve: () => {
+        calls++;
+        // Two failed reads, then the gateway comes up.
+        return Promise.resolve(calls < 3 ? undefined : "guardian-real-id");
+      },
+      delaysMs: NO_DELAYS,
+    });
+    await settle();
+
+    expect(calls).toBe(3);
+    expect(hub.filled).toEqual(["guardian-real-id"]);
+  });
+
+  test("retries after a lookup that rejects", async () => {
+    const hub = fakeHub();
+    let calls = 0;
+    startActorPrincipalHeal({
+      hub,
+      connectionId: "conn-1",
+      resolve: () => {
+        calls++;
+        return calls === 1
+          ? Promise.reject(new Error("ipc timeout"))
+          : Promise.resolve("guardian-real-id");
+      },
+      delaysMs: NO_DELAYS,
+    });
+    await settle();
+
+    expect(calls).toBe(2);
+    expect(hub.filled).toEqual(["guardian-real-id"]);
+  });
+
+  test("stops retrying once the connection no longer needs healing", async () => {
+    // Models a disconnect (or a reconnect that replaced this subscription)
+    // between attempts: the loop must not keep polling the gateway for a
+    // connection that is gone.
+    const hub = fakeHub();
+    let calls = 0;
+    startActorPrincipalHeal({
+      hub,
+      connectionId: "conn-1",
+      resolve: () => {
+        calls++;
+        hub.setNeeds(false);
+        return Promise.resolve(undefined);
+      },
+      delaysMs: NO_DELAYS,
+    });
+    await settle();
+
+    expect(calls).toBe(1);
+    expect(hub.filled).toEqual([]);
+  });
+
+  test("never starts a lookup when the connection is already healed or gone", async () => {
+    const hub = fakeHub({ needs: false });
+    const resolve = mock(() => Promise.resolve("guardian-real-id"));
+    startActorPrincipalHeal({
+      hub,
+      connectionId: "conn-1",
+      resolve,
+      delaysMs: NO_DELAYS,
+    });
+    await settle();
+
+    expect(resolve).toHaveBeenCalledTimes(0);
+    expect(hub.filled).toEqual([]);
+  });
+
+  test("gives up after the schedule is exhausted without filling", async () => {
+    const hub = fakeHub();
+    let calls = 0;
+    startActorPrincipalHeal({
+      hub,
+      connectionId: "conn-1",
+      resolve: () => {
+        calls++;
+        return Promise.resolve(undefined);
+      },
+      delaysMs: NO_DELAYS,
+    });
+    await settle();
+
+    expect(calls).toBe(NO_DELAYS.length);
+    expect(hub.filled).toEqual([]);
+  });
+
+  test("dispatches the first attempt synchronously", () => {
+    const hub = fakeHub();
+    const resolve = mock(() => Promise.resolve("guardian-real-id"));
+    startActorPrincipalHeal({
+      hub,
+      connectionId: "conn-1",
+      resolve,
+      delaysMs: NO_DELAYS,
+    });
+
+    // No await: the leading zero delay must not cost a macrotask, so a
+    // warm-cache heal lands before the stream delivers its first event.
+    expect(resolve).toHaveBeenCalledTimes(1);
+  });
+});

package/src/runtime/routes/__tests__/surface-action-routes.test.ts

@@ -59,6 +59,8 @@ let mockReResolve: { trustClass: string; sourceChannel: string } | null = null;
 mock.module("../../../contacts/guardian-delivery-reader.js", () => ({
   getGuardianDelivery: (_input?: { channelTypes?: string[] }) =>
     Promise.resolve(mockGuardianList),
+  getGuardianDeliveryFresh: (_input?: { channelTypes?: string[] }) =>
+    Promise.resolve(mockGuardianList),
   peekCachedGuardianDelivery: () => mockGuardianList ?? undefined,
   guardianForChannel: (
     list: Array<Record<string, unknown>>,

package/src/runtime/routes/events-routes.ts

@@ -52,6 +52,7 @@ import {
   ServiceUnavailableError,
 } from "./errors.js";
 import { parseBody } from "./parse-body.js";
+import { startActorPrincipalHeal } from "./sse-actor-principal-heal.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
 const log = getLogger("events-routes");
@@ -455,28 +456,28 @@ export function handleSubscribeAssistantEvents(
     throw err;
   }
 
-  // Self-heal for dev-bypass connections: the sync resolution above reads
-  // only the guardian-delivery cache, which can be cold at connect time.
-  // Without this, the subscription would carry no principal for its whole
-  // lifetime and every host-proxy result would 403. Fire-and-forget so the
-  // stream is not delayed; keyed by connectionId so a reconnect race cannot
-  // patch the subscription that replaced this one.
+  // Self-heal for dev-bypass connections: the sync resolution above reads only
+  // the guardian-delivery cache, which can be cold at connect time, and a
+  // subscription that carries no principal for its lifetime 403s every
+  // host-proxy result it submits. The heal retries on a bounded backoff
+  // (`sse-actor-principal-heal.ts`), fire-and-forget so the stream is not
+  // delayed, keyed by connectionId so a reconnect race cannot patch the
+  // subscription that replaced this one. The lookup forces a fresh gateway read
+  // because a cached empty result outlives the retry schedule.
   if (
     clientId &&
     interfaceId &&
     actorPrincipalId == null &&
     rawActorPrincipalId?.trim() === "dev-bypass"
   ) {
-    void resolveActorPrincipalIdForLocalGuardian("dev-bypass")
-      .then((resolved) => {
-        if (resolved) {
-          hub.fillClientActorPrincipalId(sub.connectionId, resolved);
-        }
-      })
-      .catch(() => {
-        // Best-effort: an unreachable gateway leaves the record unhealed;
-        // the next reconnect retries.
-      });
+    startActorPrincipalHeal({
+      hub,
+      connectionId: sub.connectionId,
+      resolve: () =>
+        resolveActorPrincipalIdForLocalGuardian("dev-bypass", {
+          forceRefresh: true,
+        }),
+    });
   }
 
   const stream = new ReadableStream<Uint8Array>(

package/src/runtime/routes/sse-actor-principal-heal.ts

@@ -0,0 +1,113 @@
+/**
+ * Retrying self-heal for an SSE client subscription that registered without an
+ * actor principal.
+ *
+ * In `DISABLE_HTTP_AUTH` deployments the SSE subscribe path cannot await, so it
+ * resolves the dev-bypass actor principal from an IO-free peek at the
+ * guardian-delivery cache. A cold cache registers the subscription with
+ * `actorPrincipalId: undefined`, and every host-proxy result that client
+ * submits then fails the same-actor gate with `missing_target`: a 403 that only
+ * a fresh registration clears.
+ *
+ * The heal resolves the guardian asynchronously and patches the live hub
+ * record. Each attempt can come back empty, since the lookup goes over the
+ * gateway IPC and yields nothing both when the transport fails (unreachable
+ * gateway, its 2s timeout, a pod still starting) and when no guardian binding
+ * exists yet, so attempts repeat on a bounded backoff. The loop stops on the
+ * first success, when the connection is gone or already carries a principal, or
+ * when the schedule is exhausted.
+ *
+ * Callers must pass a cache-bypassing lookup: the guardian-delivery reader
+ * caches a successful empty result for minutes, which outlives the whole
+ * schedule, so a cached read would spend every attempt on the same stale
+ * answer.
+ */
+import { getLogger } from "../../util/logger.js";
+
+const log = getLogger("sse-actor-heal");
+
+/**
+ * The hub surface this module needs: a liveness check and the fill. Narrow by
+ * design so tests can drive the loop without a real hub.
+ */
+export interface ActorPrincipalHealHub {
+  needsActorPrincipalHeal(connectionId: string): boolean;
+  fillClientActorPrincipalId(
+    connectionId: string,
+    actorPrincipalId: string,
+  ): void;
+}
+
+/**
+ * Delay before each attempt, in milliseconds. The leading zero dispatches the
+ * first attempt inline with the subscribe; the rest back off to cover a gateway
+ * that is slow to come up, without holding a timer for the life of a long-lived
+ * stream. Total span is about 44s.
+ */
+export const ACTOR_PRINCIPAL_HEAL_DELAYS_MS: readonly number[] = [
+  0, 1_000, 3_000, 10_000, 30_000,
+];
+
+/**
+ * Start the retrying heal for `connectionId`. Fire-and-forget: never awaited by
+ * the route, never delays the stream.
+ *
+ * `resolve` performs the daemon's own server-side guardian lookup, bypassing
+ * the guardian-delivery cache. The value must never come from client input. It
+ * may resolve `undefined` (no binding yet, or the gateway is unreachable) or
+ * reject; both count as a failed attempt.
+ */
+export function startActorPrincipalHeal(args: {
+  hub: ActorPrincipalHealHub;
+  connectionId: string;
+  resolve: () => Promise<string | undefined>;
+  /** Override the backoff schedule. Tests pass all-zero delays. */
+  delaysMs?: readonly number[];
+}): void {
+  const { hub, connectionId, resolve } = args;
+  const delays = args.delaysMs ?? ACTOR_PRINCIPAL_HEAL_DELAYS_MS;
+
+  void (async () => {
+    for (let attempt = 0; attempt < delays.length; attempt++) {
+      const delayMs = delays[attempt] ?? 0;
+      if (delayMs > 0) {
+        await sleep(delayMs);
+      }
+
+      // Re-check every pass: the connection may have closed, been replaced by a
+      // reconnect, or been healed by another path since the last one.
+      if (!hub.needsActorPrincipalHeal(connectionId)) {
+        return;
+      }
+
+      let resolved: string | undefined;
+      try {
+        resolved = await resolve();
+      } catch {
+        resolved = undefined;
+      }
+      if (resolved) {
+        hub.fillClientActorPrincipalId(connectionId, resolved);
+        return;
+      }
+    }
+
+    // Log the give-up so a principal-less subscription is greppable next to the
+    // same-actor rejections it causes, rather than surfacing only as opaque
+    // 403s on the client.
+    if (hub.needsActorPrincipalHeal(connectionId)) {
+      log.warn(
+        { connectionId, attempts: delays.length },
+        "gave up healing missing actorPrincipalId for client subscription; host-proxy results from this connection are rejected until it reconnects",
+      );
+    }
+  })();
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    // Never hold the process (or a test runner) open on a pending backoff.
+    (timer as { unref?: () => void }).unref?.();
+  });
+}

package/src/stt/__tests__/language-metadata.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  dominantLanguageTag,
+  rankLanguages,
+  voteDominantLanguage,
+} from "../language-metadata.js";
+
+describe("voteDominantLanguage", () => {
+  test("only the dominance-ranked first entry votes", () => {
+    const tally = new Map<string, number>();
+    voteDominantLanguage(tally, ["en", "es"]);
+    expect(tally.get("en")).toBe(1);
+    expect(tally.has("es")).toBe(false);
+  });
+
+  test("regional variants count toward their base subtag", () => {
+    const tally = new Map<string, number>();
+    voteDominantLanguage(tally, ["pt-BR"]);
+    voteDominantLanguage(tally, ["pt"]);
+    expect(tally.get("pt")).toBe(2);
+  });
+
+  test("underscore-separated variants count toward their base subtag", () => {
+    const tally = new Map<string, number>();
+    voteDominantLanguage(tally, ["hi_IN"]);
+    expect(tally.get("hi")).toBe(1);
+  });
+
+  test("blank and absent tags cast no vote", () => {
+    const tally = new Map<string, number>();
+    voteDominantLanguage(tally, undefined);
+    voteDominantLanguage(tally, []);
+    voteDominantLanguage(tally, ["  "]);
+    expect(tally.size).toBe(0);
+  });
+});
+
+describe("dominantLanguageTag", () => {
+  test("most votes wins", () => {
+    const tally = new Map([
+      ["en", 1],
+      ["es", 3],
+    ]);
+    expect(dominantLanguageTag(tally)).toBe("es");
+  });
+
+  test("ties break by first insertion", () => {
+    const tally = new Map([
+      ["hi", 2],
+      ["en", 2],
+    ]);
+    expect(dominantLanguageTag(tally)).toBe("hi");
+  });
+
+  test("undefined for an empty tally", () => {
+    expect(dominantLanguageTag(new Map())).toBeUndefined();
+  });
+});
+
+describe("rankLanguages", () => {
+  test("returns empty array for empty input", () => {
+    expect(rankLanguages([])).toEqual([]);
+  });
+
+  test("ranks by frequency, most frequent first", () => {
+    expect(rankLanguages(["es", "en", "en", "en", "es"])).toEqual(["en", "es"]);
+  });
+
+  test("breaks ties by first appearance", () => {
+    expect(rankLanguages(["hi", "en", "en", "hi"])).toEqual(["hi", "en"]);
+  });
+
+  test("counts regional variants toward their base subtag", () => {
+    expect(rankLanguages(["en-US", "es", "en", "en-GB"])).toEqual(["en", "es"]);
+  });
+
+  test("skips blank tags", () => {
+    expect(rankLanguages(["", "  ", "ja"])).toEqual(["ja"]);
+  });
+
+  test("accepts any iterable", () => {
+    expect(rankLanguages(new Set(["fr", "de"]))).toEqual(["fr", "de"]);
+  });
+});