@chatpanel/gateway 0.6.59 → 0.6.61

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chatpanel/gateway",
-  "version": "0.6.59",
+  "version": "0.6.61",
   "description": "Local privacy gateway — redacts PII out of OpenAI/Anthropic API traffic before it reaches a model, then restores it in the reply. Point opencode, codex, aider, Claude Code, etc. at it.",
   "type": "module",
   "bin": {
@@ -27,7 +27,7 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@chatpanel/pii": "^0.4.0",
+    "@chatpanel/pii": "^0.7.0",
     "@huggingface/transformers": "^4.2.0",
     "onnxruntime-web": "1.26.0-dev.20260416-b7804b056c",
     "phonemizer": "^1.2.1"

package/src/config.js

@@ -8,6 +8,8 @@
 import { readFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import os from 'node:os';
+import { DEFAULT_MODEL as DEFAULT_NER_MODEL } from './models.js';
+import { DEFAULT_STT_MODEL } from './stt-models.js';
 
 // Exported so tests can assert that every section here survives persistConfig's
 // allowlist — a new section that is not persisted reverts on restart, and that
@@ -90,19 +92,22 @@ export const DEFAULTS = {
   // Fails open: if the model can't load, the gateway runs deterministic-only.
   ner: {
     autostart: true,
-    model: 'Xenova/bert-base-NER',
+    // One definition, in models.js. It lived here, in models.js and in ner-engine.js at
+    // once — three constants for one default, which is three chances to move two of them.
+    model: DEFAULT_NER_MODEL,
     allowDownload: true,
     // Auto-bump redaction.tier to 'full' once the detector is ready (names/orgs).
     enableFullTier: true,
   },
 
-  // Local speech-to-text (dictation) — whisper via the same in-process ONNX engine
-  // and model dir as NER (stt-engine.js). No autostart on purpose: the model
-  // downloads on FIRST dictation, never on gateway boot (first-run load time).
-  // Multilingual default so the spoken language is auto-detected per segment.
+  // Local speech-to-text (dictation) — the in-process ONNX engine and model dir shared
+  // with NER (stt-engine.js). No autostart on purpose: the model downloads on FIRST
+  // dictation, never on gateway boot (first-run load time). The default is Parakeet, which
+  // is multilingual and several times faster than Whisper — see stt-models.js for what
+  // that costs on a first run.
   stt: {
     enabled: true,
-    model: 'onnx-community/whisper-base',
+    model: DEFAULT_STT_MODEL,
     allowDownload: true,
     // Speaker diarization ("who said what") is an OPT-IN per-session stage (its
     // model loads only when a session asks). Set false to disable it gateway-wide.

package/src/history-store.js

@@ -216,8 +216,9 @@ export class HistoryStore {
   }
 
   // Metadata list for an external UI, newest first, paginated. No bodies.
-  list({ limit = 50, offset = 0 } = {}) {
+  list({ limit = 50, offset = 0, type = null } = {}) {
     const all = [...this.records.values()]
+      .filter((r) => !type || r.type === type)
       .map((r) => ({ id: r.id, title: r.title, type: r.type, date: r.date, chars: r.text.length }))
       .sort((a, b) => (b.date || 0) - (a.date || 0));
     return { total: all.length, items: all.slice(offset, offset + limit) };

package/src/knowledge.js

@@ -0,0 +1,215 @@
+// VENDORED from @chatpanel/events/knowledge.js — edit there, then copy over.
+// BRIEFS — the derived layer. A statement about a SUBJECT that accumulates across records.
+//
+// Everything else ChatPanel stores is a record of an event: a chat happened, a call
+// happened, a human wrote a note. Nothing is a synthesis, so every answer is re-derived
+// from scratch, every session, forever — and a multi-agent run's findings die with the run.
+// A brief is the thing that compounds.
+//
+// FOUR INVARIANTS, and they are the whole defence (see docs/knowledge-compounding.md §5.1):
+//
+//   I-K1  Every claim cites raw. A claim with no ref is a BUG, not a weak claim — it is
+//         refused on write. Derived text can then always be checked against, or rebuilt
+//         from, the immutable records under it.
+//   I-K2  A brief is REBUILDABLE. Delete every brief and this module reconstructs them from
+//         the record store. That makes a brief a projection — the same guarantee replay()
+//         gives the event log — and it makes "rebuild all" a cache clear, not data loss.
+//   I-K3  Nothing self-promotes. `draft` is free; `promoted` needs a gate. Class-R
+//         derivations may auto-promote (a backlink is not an opinion); model-written prose
+//         may not. Unreviewed agent writing compounding into confident nonsense is the
+//         failure mode that is undetectable six months later.
+//   I-K4  Bounded, or it is a second corpus. A brief has a size ceiling and the SET of
+//         briefs has a count ceiling driven by evidence — memory.js already made this
+//         argument for memory, and the same sentence applies here.
+//
+// This phase (W1) is entirely class R: no model, no network, no clock of its own. Every
+// claim is something the corpus already states — who was present, when, what co-occurs,
+// what the user themselves told us. Prose synthesis arrives in W3, behind the gate, and
+// lands as `proposed` beside these rather than replacing them.
+//
+// WHY THIS FILE IS THE MODEL AND `knowledge-derive.js` IS THE PASS. Reading a brief and
+// BUILDING one have very different costs: reading needs the shape and the renderer, while
+// building walks the whole corpus and needs entity resolution and the maintenance passes.
+// The MV3 service worker only ever reads — it syncs stored briefs to the gateway — so
+// putting both halves in one module would have put 60 KB of derivation on its cold start
+// for code it never runs. The split is what keeps that honest rather than remembered.
+
+// From subject-name.js, not entity.js: this module is on the MV3 service worker's graph and
+// needs exactly one string function, where entity.js also carries alias resolution and merge
+// suggestion. Same argument as the knowledge/knowledge-derive split, one level down.
+import { normalizeSubject } from './subject-name.js';
+
+/** draft → proposed → promoted → archived. `promotion.js` (W3) owns the transitions. */
+export const BRIEF_STATES = Object.freeze(['draft', 'proposed', 'promoted', 'archived']);
+
+/** What a claim is derived FROM. Class R throughout this phase. */
+export const CLAIM_KINDS = Object.freeze(['presence', 'timeline', 'together', 'wanted', 'stated']);
+
+// I-K4, made concrete. A brief that grows without bound is a document, and a document
+// needs its own summary, and then nothing has been gained.
+export const MAX_CLAIMS = 12;
+export const MAX_CLAIM_REFS = 8;
+export const MAX_BRIEF_RECORDS = 200;
+export const MAX_BRIEF_CHARS = 4000;
+
+// How many co-occurring subjects a `together` claim names. Past a handful it stops being a
+// statement and becomes a tag cloud.
+const TOGETHER_LIMIT = 5;
+
+/**
+ * A stable, non-cryptographic content hash, computed SYNCHRONOUSLY.
+ *
+ * Deliberately not SHA-256, which `store.js` uses and which is async: derivation walks
+ * every record in the corpus and runs in an MV3 service worker, so a hash per record has to
+ * be synchronous or the whole pass becomes a promise storm. The job here is DRIFT
+ * DETECTION — "has the record this claim cites changed since the claim was made" — not
+ * tamper resistance, and FNV-1a answers that exactly as well while staying pure.
+ */
+export function contentHash(text) {
+  const s = String(text ?? '');
+  let h1 = 0x811c9dc5, h2 = 0x01000193;
+  for (let i = 0; i < s.length; i += 1) {
+    const c = s.charCodeAt(i);
+    h1 = Math.imul(h1 ^ c, 0x01000193) >>> 0;
+    h2 = Math.imul(h2 ^ (c + i), 0x85ebca6b) >>> 0;
+  }
+  return `f${h1.toString(16).padStart(8, '0')}${h2.toString(16).padStart(8, '0')}`;
+}
+
+/** `person:alex rivera` → `brief:person-alex-rivera`. Safe as a storage key and a URL hash. */
+export function briefId(subjectKey) {
+  const [kind, ...rest] = String(subjectKey || '').split(':');
+  const slug = normalizeSubject(rest.join(':')).replace(/\s+/g, '-').replace(/-+/g, '-');
+  if (!kind || !slug) return '';
+  // The slug is TRUNCATED, so two long subjects can share one, and it is lossy, so two
+  // kinds can too. A hash of the CANONICAL key rides along to separate them. Canonical, not
+  // raw: "Alex Rivera" and "alex  rivera" are one subject and must land on one id, or a
+  // rebuild would fork the page in two — the exact failure I-K2 exists to make impossible.
+  const canonical = `${kind}:${normalizeSubject(rest.join(':'))}`;
+  return `brief:${kind}-${slug.slice(0, 48)}-${contentHash(canonical).slice(1, 7)}`;
+}
+
+/** Records are addressed `chat:x` / `meeting:y` / `note:z` — the ref kind is the prefix. */
+function refForRecord(rec) {
+  const [kind, ...rest] = String(rec.id).split(':');
+  const id = rest.join(':') || rec.id;
+  const known = kind === 'chat' || kind === 'meeting' || kind === 'note' || kind === 'page';
+  return makeRef({ kind: known ? kind : 'result', id: known ? id : rec.id, hash: contentHash(rec.text) });
+}
+
+function claim({ id, kind, text, refs, at = 0, confidence = 1 }) {
+  return {
+    id,
+    kind,
+    text,
+    // I-K1 lives here: a claim is CONSTRUCTED with its refs, and `checkKnowledgeInvariants`
+    // refuses one that arrives without them. There is no path that writes a claim first and
+    // attaches provenance later, because that path is how provenance goes missing.
+    refs: refs.slice(0, MAX_CLAIM_REFS),
+    firstSeen: at,
+    lastConfirmed: at,
+    confidence,
+    cls: 'R', // class R — derived, not written. W3's prose claims carry 'C'.
+  };
+}
+
+const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+const isoDay = (ms) => (ms ? new Date(ms).toISOString().slice(0, 10) : '');
+
+/**
+ * The searchable body. A brief is a SOURCE, ranked by the same engine as everything else
+ * (design §7.6 — no second retrieval stack), so it has to render to text like one.
+ */
+export function briefToText(brief) {
+  if (!brief) return '';
+  const L = [`BRIEF: ${brief.subject.name}`];
+  if (brief.subject.aliases?.length) L.push(`Also known as: ${brief.subject.aliases.join(', ')}`);
+  L.push(`Kind: ${brief.kind}`);
+  L.push('');
+  for (const c of brief.claims) {
+    L.push(`- ${c.text}`);
+    if (c.refs.length) L.push(`  (${c.refs.map((r) => `${r.kind}:${r.id}`).join(', ')})`);
+  }
+  if (brief.records.length) {
+    L.push('', 'RECORDS:');
+    for (const r of brief.records.slice(-40).reverse()) L.push(`- ${r.type}: ${r.title || 'untitled'}`);
+  }
+  return L.join('\n').slice(0, MAX_BRIEF_CHARS);
+}
+
+/**
+ * The inverse of `briefToText` — a brief's claims and refs read back out of the text form.
+ *
+ * Exists because the warm store holds RECORDS: `{ id, title, type, date, text }`, nothing
+ * else. Briefs cross to the gateway as that shape, so an agent asking `get_brief` over MCP
+ * can only be handed structure if the text form is stable enough to parse. It is: this
+ * module writes both ends, and the claim line (`- text`) followed by its refs
+ * (`  (kind:id, kind:id)`) is a grammar, not a rendering. Round-trips in the tests.
+ *
+ * Returns `null` for text that is not a brief, so a caller can tell "not a brief" from
+ * "a brief with no claims".
+ */
+export function parseBriefText(text) {
+  const lines = String(text ?? '').split('\n');
+  if (!/^BRIEF: /.test(lines[0] || '')) return null;
+  const out = { name: lines[0].slice('BRIEF: '.length).trim(), aliases: [], kind: '', claims: [], records: [] };
+  let section = 'head';
+  for (let i = 1; i < lines.length; i += 1) {
+    const line = lines[i];
+    if (section === 'head') {
+      if (line.startsWith('Also known as: ')) out.aliases = line.slice(15).split(',').map((a) => a.trim()).filter(Boolean);
+      else if (line.startsWith('Kind: ')) out.kind = line.slice(6).trim();
+      else if (line === '') section = 'claims';
+      continue;
+    }
+    if (line === 'RECORDS:') { section = 'records'; continue; }
+    if (section === 'claims' && line.startsWith('- ')) {
+      const claim = { text: line.slice(2), refs: [] };
+      const next = lines[i + 1] || '';
+      const m = /^  \((.*)\)$/.exec(next);
+      if (m) {
+        claim.refs = m[1].split(', ').map((r) => {
+          const idx = r.indexOf(':');
+          return idx > 0 ? { kind: r.slice(0, idx), id: r.slice(idx + 1) } : null;
+        }).filter(Boolean);
+        i += 1;
+      }
+      out.claims.push(claim);
+    } else if (section === 'records' && line.startsWith('- ')) {
+      const idx = line.indexOf(': ');
+      out.records.push(idx > 0 ? { type: line.slice(2, idx), title: line.slice(idx + 2) } : { type: '', title: line.slice(2) });
+    }
+  }
+  return out;
+}
+
+/** Terms the graph and the search index rank a brief by — its subject and its neighbours. */
+export function briefTerms(brief) {
+  if (!brief) return [];
+  const together = brief.claims.find((c) => c.kind === 'together');
+  const names = together ? together.text.replace(/^Usually alongside /, '').replace(/\.$/, '').split(', ') : [];
+  return [...new Set([brief.subject.name, ...(brief.subject.aliases || []), ...names])].filter(Boolean);
+}
+
+/**
+ * The invariants, as a check rather than a promise. Returns the failures; empty means clean.
+ * Same shape as `invariants.js checkInvariants()`, for the same reason: an invariant nobody
+ * can run is a comment.
+ */
+export function checkKnowledgeInvariants(brief) {
+  const fail = [];
+  if (!brief || typeof brief !== 'object') return [{ invariant: 'I-K1', detail: 'not a brief' }];
+  if (!BRIEF_STATES.includes(brief.state)) fail.push({ invariant: 'I-K3', detail: `unknown state ${brief.state}` });
+  if (brief.state === 'promoted' && brief.cls === 'C') {
+    fail.push({ invariant: 'I-K3', detail: 'model-written prose cannot be promoted without the gate' });
+  }
+  for (const c of brief.claims || []) {
+    if (!c.refs?.length) fail.push({ invariant: 'I-K1', detail: `claim ${c.id} cites nothing` });
+    if (!CLAIM_KINDS.includes(c.kind) && c.cls !== 'C') {
+      fail.push({ invariant: 'I-K1', detail: `claim ${c.id} has unknown kind ${c.kind}` });
+    }
+  }
+  if ((brief.claims || []).length > MAX_CLAIMS) fail.push({ invariant: 'I-K4', detail: `${brief.claims.length} claims exceeds ${MAX_CLAIMS}` });
+  if (briefToText(brief).length >= MAX_BRIEF_CHARS) fail.push({ invariant: 'I-K4', detail: 'brief text is at the ceiling' });
+  return fail;
+}

package/src/mcp.js

@@ -18,6 +18,7 @@ import { loadConfig } from './config.js';
 import { readBridgeToken } from './bridge.js';
 import { ensureGatewayToken } from './gateway-token.js';
 import { MEMORY_KINDS, MEMORY_KIND_NAMES } from './memory.js';
+import { parseBriefText } from './knowledge.js';
 
 const PROTOCOL_VERSION = '2024-11-05';
 const SERVER = { name: 'chatpanel-history', version: '1.0.0' };
@@ -118,13 +119,13 @@ async function bridgeJson(path) {
 const TOOLS = [
   {
     name: 'smart_search',
-    description: 'BEST first choice for a question about the user\'s ChatPanel history (meetings, notes, past chats). Ask it a natural-language QUESTION and it expands that into several complementary keyword queries, runs them all, and fuses the rankings — which finds things a single query misses, in one round trip instead of several probes. You know the domain, so pass 2-4 of your own phrasings in `queries` too (e.g. for "what did we decide in the Ben demo": ["Ben demo decisions", "tooling demo action items", "demo outcome next steps"]). Supports the same filters as search_history (type, since, before) and returns snippets with each result\'s id; follow up with get_record for the full text or find_related to expand around a hit.',
+    description: 'BEST first choice for a question about the user\'s ChatPanel history (meetings, notes, past chats). Ask it a natural-language QUESTION and it expands that into several complementary keyword queries, runs them all, and fuses the rankings — which finds things a single query misses, in one round trip instead of several probes. You know the domain, so pass 2-4 of your own phrasings in `queries` too (e.g. for "what did we decide in the Ben demo": ["Ben demo decisions", "tooling demo action items", "demo outcome next steps"]). Supports the same filters as search_history (type, since, before) and returns snippets with each result\'s id; follow up with get_record for the full text or find_related to expand around a hit. BRIEFS come first when they match: a brief is a maintained page about one person, project or topic, derived from ALL the records that mention it, with every claim citing its record — so for "what do we know about X" read the brief, then open only the records it cites.',
     inputSchema: {
       type: 'object',
       properties: {
         question: { type: 'string', description: 'The user\'s question, in natural language.' },
         queries: { type: 'array', items: { type: 'string' }, description: 'Your own 2-4 keyword formulations of it — these lead the search.' },
-        type: { type: 'string', enum: ['chat', 'meeting', 'note'], description: 'Only this kind of record.' },
+        type: { type: 'string', enum: ['brief', 'chat', 'meeting', 'note'], description: 'Only this kind of record. `brief` = a maintained page about one person/project/topic, with every claim cited — start there for "what do we know about X".' },
         since: { type: 'string', description: 'Earliest date: 2026-08-01, or a window like "7d"/"yesterday".' },
         before: { type: 'string', description: 'Latest date: a date or window like `since`.' },
         limit: { type: 'number', description: 'Max fused results (default 10).' },
@@ -139,7 +140,7 @@ const TOOLS = [
       type: 'object',
       properties: {
         query: { type: 'string', description: 'Content keywords (topics, names, decisions) — not the meeting title.' },
-        type: { type: 'string', enum: ['chat', 'meeting', 'note'], description: 'Only this kind of record.' },
+        type: { type: 'string', enum: ['brief', 'chat', 'meeting', 'note'], description: 'Only this kind of record. `brief` = a maintained page about one person/project/topic, with every claim cited — start there for "what do we know about X".' },
         since: { type: 'string', description: 'Earliest date: 2026-08-01, or a relative window like "7d", "2 weeks", "yesterday".' },
         before: { type: 'string', description: 'Latest date: a date or relative window like `since`.' },
         limit: { type: 'number', description: 'Max results (default 10).' },
@@ -184,6 +185,28 @@ const TOOLS = [
       },
     },
   },
+  {
+    name: 'list_briefs',
+    description: 'The BRIEFS ChatPanel maintains — one page per person, project or topic that appears across enough records, each claim citing the record it came from. This is the index of what the user\'s corpus KNOWS, as opposed to what it merely contains: read it before asking "what do we know about X", then get_brief for the one you need. Briefs are rebuilt from the records, so they are as current as the last rebuild (dates shown).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        limit: { type: 'number', description: 'Max briefs (default 50).' },
+        offset: { type: 'number', description: 'Skip N for paging (default 0).' },
+      },
+    },
+  },
+  {
+    name: 'get_brief',
+    description: 'One brief as STRUCTURE: the subject, its other spellings, and each claim with the record ids it cites — so you can cite the record rather than the synthesis, and open only what you need with get_record. Prefer this over get_record for a brief:… id; get_record returns the same text as prose.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string', description: 'A brief id (brief:…) from list_briefs or search results.' },
+      },
+      required: ['id'],
+    },
+  },
   {
     name: 'recall',
     description: "What ChatPanel already knows about the USER — their name, how they want answers written, their ongoing work and environment. Short and cheap; call it at the START of a session and whenever the user states a preference, then just FOLLOW what it returns without announcing that you checked. Pass the current task in `text` and it also returns the facts relevant to that task, not only the always-on ones. This is memory, not history: for what was said in a meeting or a past chat use smart_search instead.",
@@ -367,6 +390,32 @@ async function callTool(name, args = {}) {
     const newest = items[0]?.date || null;
     return [horizonLine(newest, data.total), '', `${items.length} of ${data.total} records:`, ...items.map((it) => `[${it.id}] ${it.title || '(untitled)'} · ${it.type}${it.date ? ' · ' + new Date(it.date).toISOString().slice(0, 10) : ''} · ${it.chars} chars`)].join('\n');
   }
+  if (name === 'list_briefs') {
+    const q = new URLSearchParams({ limit: String(Number(args.limit) || 50), offset: String(Number(args.offset) || 0), type: 'brief' });
+    const data = await gatewayJson(`/v1/history/list?${q}`);
+    const items = data.items || [];
+    if (!items.length) return 'No briefs yet. ChatPanel builds them from the user\'s records on the Briefs page; if that has run, the user may have "share briefs with local agents" switched off.';
+    return [
+      `${items.length} of ${data.total} briefs (each is a page about one subject, with every claim cited):`,
+      ...items.map((it) => `[${it.id}] ${it.title || '(untitled)'}${it.date ? ' · rebuilt ' + new Date(it.date).toISOString().slice(0, 10) : ''}`),
+    ].join('\n') + '\n\nget_brief <id> for its claims and the records they cite.';
+  }
+  if (name === 'get_brief') {
+    const id = String(args.id || '');
+    const data = await gatewayJson(`/v1/history/get?${new URLSearchParams({ id })}`);
+    const r = data.record;
+    const brief = parseBriefText(r?.text);
+    if (!brief) return `${id} is not a brief (type ${r?.type || 'unknown'}). Use get_record for it, or list_briefs for the brief ids.`;
+    const lines = [`BRIEF ${id} — ${brief.name} (${brief.kind})${brief.aliases.length ? ` · also known as ${brief.aliases.join(', ')}` : ''}`, ''];
+    lines.push(`${brief.claims.length} claim(s), each with the records it cites:`);
+    for (const c of brief.claims) {
+      lines.push(`• ${c.text}`);
+      if (c.refs.length) lines.push(`    cites: ${c.refs.map((x) => `${x.kind}:${x.id}`).join(', ')}`);
+    }
+    if (brief.records.length) lines.push('', `Built from ${brief.records.length} record(s) (most recent first): ${brief.records.slice(0, 12).map((x) => x.title).join(' · ')}${brief.records.length > 12 ? ' …' : ''}`);
+    lines.push('', 'get_record <kind:id> opens a cited record; find_related <id> follows its connections.');
+    return lines.join('\n');
+  }
   if (name === 'recall') {
     const data = await gatewayJson('/v1/memory/recall', {
       method: 'POST', headers: { 'content-type': 'application/json' },

package/src/models.js

@@ -1,11 +1,24 @@
 // Catalog of NER models the gateway can run, surfaced in the extension's Gateway
-// settings so users can install a larger or multilingual detector. All are ONNX
-// (transformers.js) token-classification models that emit PER/ORG/LOC — the only
-// labels the redaction engine consumes. Sizes are the on-disk q8 footprint, approx.
+// settings so users can install a larger or multilingual detector. Sizes are the
+// on-disk q8 footprint, approx.
 //
-// Adding a model: any Xenova/* token-classification model whose labels map to
-// PER/ORG/LOC works (pii-detect normalizeEntities handles the label mapping).
-// Verify it loads + detects before listing it here.
+// TWO THINGS TO CHECK WHEN ADDING A MODEL, and getting either wrong fails SILENTLY.
+//
+//   1. ITS LABELS MUST BE MAPPED. `@chatpanel/pii` `normalizeEntities` turns a model's
+//      labels into our placeholder types, and an unmapped label is dropped rather than
+//      passed through — so a model whose vocabulary it does not know detects entities
+//      perfectly and redacts none of them, while the UI still reads as on. Run one
+//      sentence through the model, look at the labels it returns, and map every one.
+//      This is not hypothetical: multilang-pii-ner emits the ai4privacy vocabulary
+//      (GIVENNAME, SURNAME, TELEPHONENUM…) and person redaction was silently off for
+//      anyone who selected it, until pii 0.6.0.
+//
+//   2. `mirrored` MUST BE TRUE ONLY IF IT REALLY IS. A catalogued model is fetched from
+//      ChatPanel's CDN so a clean install depends only on chatpanel.net; a model that is
+//      not there 404s at first use. `mirrored: false` says "catalogue it, but fetch it
+//      from Hugging Face" — which is what lets a model be a first-class, one-click
+//      choice before the mirror upload happens, instead of forcing users to paste a
+//      custom id and lose the label, the size and the note.
 
 export const DEFAULT_MODEL = 'Xenova/bert-base-NER';
 
@@ -31,8 +44,40 @@ export const MODEL_CATALOG = [
     approxMB: 180,
     note: 'Higher multilingual accuracy; larger download.',
   },
+  {
+    // PURPOSE-BUILT FOR THIS JOB, where the three above are general newswire NER. It
+    // finds what redaction actually cares about — given and family names separately,
+    // street/building/postcode, phone, national-ID and account numbers, usernames and
+    // passwords — none of which a PER/ORG/LOC model emits at all. That makes it the
+    // better detector for a privacy product, not merely a bigger one.
+    //
+    // NOT the default yet, and the reason is written down rather than remembered: it is
+    // not on the CDN (see `mirrored`), so defaulting to it would make a clean install
+    // depend on Hugging Face, and it needs @chatpanel/pii >= 0.6.0 for its labels to be
+    // understood at all. Both are release chores, not code.
+    id: 'onnx-community/multilang-pii-ner-ONNX',
+    label: 'PII-specialised — multilingual',
+    lang: 'Multilingual',
+    approxMB: 282,
+    mirrored: false,
+    recommended: true,
+    note: 'Most thorough. Trained for PII rather than general entities: also finds addresses, postcodes, account and ID numbers, usernames and passwords. Larger download, fetched from Hugging Face.',
+  },
 ];
 
+/**
+ * Is this model on ChatPanel's CDN, or does it have to come from Hugging Face?
+ *
+ * Default TRUE for a catalogued model — the mirror is the norm and the point of the
+ * catalogue. An entry says `mirrored: false` when it is a first-class choice that has not
+ * been uploaded yet. A model that is not in the catalogue at all is a user's own id and is
+ * never mirrored.
+ */
+export function isMirroredModel(id) {
+  const m = MODEL_CATALOG.find((x) => x.id === id);
+  return !!m && m.mirrored !== false;
+}
+
 export function isKnownModel(id) {
   return MODEL_CATALOG.some((m) => m.id === id);
 }

package/src/ner-engine.js

@@ -17,11 +17,10 @@
 import os from 'node:os';
 import { join } from 'node:path';
 import { existsSync, mkdirSync } from 'node:fs';
-import { isKnownModel } from './models.js';
+import { DEFAULT_MODEL, isMirroredModel } from './models.js';
 import { isLoopbackHost, isPrivateHost, isMetadataHost } from '@chatpanel/pii';
 import { verifyModelWeights } from './model-integrity.js';
 
-const DEFAULT_MODEL = 'Xenova/bert-base-NER';
 const DEFAULT_MODEL_HOST = 'https://dl.chatpanel.net/models/';
 
 // Where model weights are fetched from — ChatPanel's own edge-cached CDN by default,
@@ -230,7 +229,11 @@ async function loadModel(modelId, { log = () => {}, allowDownload = true } = {})
   // (ensureLib set that as remoteHost). A user's BYO id isn't mirrored, so fetch
   // it from Hugging Face directly — only for this load, then restore.
   const prevHost = lib.env.remoteHost;
-  const isCustom = !isKnownModel(modelId);
+  // Fetch from Hugging Face when the mirror cannot serve it — a user's own id, or a
+  // catalogued model that has not been uploaded to the CDN yet (models.js `mirrored`).
+  // Asking "is it in the catalogue" was the same question only while every catalogued
+  // model happened to be mirrored, and a catalogued-but-unmirrored one would have 404'd.
+  const isCustom = !isMirroredModel(modelId);
   if (!haveLocal && isCustom) { try { lib.env.remoteHost = 'https://huggingface.co/'; } catch { /* optional */ } }
 
   _state = haveLocal ? 'loading' : 'downloading';

package/src/server.js

@@ -44,6 +44,7 @@ import { TTS_MODEL_CATALOG, TTS_VOICES, isKnownTtsModel, isValidCustomTtsId, isK
 import { ttsDestination, synthesizeRemote, isValidRemoteVoice } from './tts-remote.js';
 import { rawOrtAvailable } from './ort.js';
 import * as ttsVoices from './tts-voices.js';
+import { resolveTtsVoice } from './tts-voice-resolve.js';
 import { resolvePro, checkQuota, consume, usage } from './freegate.js';
 import { publicConfig, applyConfigPatch, applyNerModelSelection, persistConfig, configPath } from './configstore.js';
 import { resolveDestination, aggregateModelsAsync, listDestinations } from './router.js';
@@ -54,7 +55,7 @@ import * as openai from './openai.js';
 import * as responses from './responses.js';
 import * as anthropic from './anthropic.js';
 
-export const VERSION = '0.6.59';
+export const VERSION = '0.6.61';
 
 // WARM search tier — SQLite + FTS5 record store (falls back to an encrypted-JSON
 // store if SQLite can't load), fed by the extension's ingest sync + backup-ingest.
@@ -779,11 +780,19 @@ export function createGateway(cfg = loadConfig()) {
           before: body.before != null ? Number(body.before) : null,
         };
         const perQuery = Math.min(30, Math.max(5, Number(body.limit) || 10) * 2);
-        const results = await multiSearch(
+        const fused = await multiSearch(
           queries,
           (q) => historyStore.search(q, { limit: perQuery, ...filters }),
           { limit: Math.min(50, Math.max(1, Number(body.limit) || 10)) },
         );
+        // BRIEFS LEAD. A brief is the compaction: when one matches, it answers with what a
+        // dozen records say, with a citation to each, and reading it saves an agent opening
+        // the dozen. Stable-partitioned to the front rather than re-scored, so rank among
+        // briefs and rank among records are both untouched — and only when the caller has
+        // not asked for one type, which is a question about records, not about briefs.
+        const results = filters.type
+          ? fused
+          : [...fused.filter((r) => r.type === 'brief'), ...fused.filter((r) => r.type !== 'brief')];
         return sendJson(res, 200, {
           ok: true, size: historyStore.size, newest: historyStore.newest, queries, results,
         });
@@ -824,7 +833,8 @@ export function createGateway(cfg = loadConfig()) {
     if (pathname === '/v1/history/list' && req.method === 'GET') {
       const limit = Math.min(500, Math.max(1, Number(url.searchParams.get('limit')) || 50));
       const offset = Math.max(0, Number(url.searchParams.get('offset')) || 0);
-      return sendJson(res, 200, { ok: true, ...historyStore.list({ limit, offset }) });
+      const type = url.searchParams.get('type') || null;
+      return sendJson(res, 200, { ok: true, ...historyStore.list({ limit, offset, type }) });
     }
     if (pathname === '/v1/history/get' && req.method === 'GET') {
       const maxChars = url.searchParams.get('maxChars') != null ? Math.max(1, Number(url.searchParams.get('maxChars')) || 0) : null;
@@ -1078,8 +1088,15 @@ export function createGateway(cfg = loadConfig()) {
           const curId = ttsVoices.parseCustomVoice(cfg.tts.voice || '');
           const isCustom = !!(curId && ttsVoices.getVoice(curId));
           if (wantsCustom && !isCustom) {
-            const saved = ttsVoices.listVoices();
-            cfg.tts.voice = saved.length ? `custom:${saved[0].id}` : '';
+            // Switching to a cloning model does not mean "start speaking as the user".
+            // A model with built-in speakers gets its default speaker; only SpeechT5,
+            // which has no built-ins, falls back to a saved voice.
+            if (ttsModelEngineOf(id) === 'pocket-tts') {
+              cfg.tts.voice = DEFAULT_POCKET_VOICE;
+            } else {
+              const saved = ttsVoices.listVoices();
+              cfg.tts.voice = saved.length ? `custom:${saved[0].id}` : '';
+            }
           } else if (!wantsCustom && isCustom) {
             cfg.tts.voice = DEFAULT_TTS_VOICE;
           }
@@ -1280,76 +1297,13 @@ export function createGateway(cfg = loadConfig()) {
         // SpeechT5 takes a recorded embedding, VITS takes neither. Resolving first
         // meant a `custom:` voice could reach a freshly-loaded Kokoro and fail deep
         // in the engine with "invalid voice id".
-        let useVoice = voice;
-        let speakerEmbedding = null;
-        let customId = ttsVoices.parseCustomVoice(voice);
-
-        // A Pocket built-in speaker is a NAME, not an embedding, so it has to be
-        // recognised before the custom-voice path — which would otherwise demand a
-        // recording for a model that ships eight voices of its own.
-        if (ttsEngine.isPocket() && isPocketVoice(rawVoice || useVoice)) {
-          useVoice = rawVoice || useVoice;
-          customId = null;
-        } else if (ttsEngine.supportsCustomVoices()) {
-          // This model speaks ONLY in a recorded voice. If the configured one names
-          // a built-in (switching model does not rewrite `voice`) or points at a
-          // voice since deleted, fall back to the most recent saved one — the
-          // caller asked to be spoken to, not for that exact voice. A voice named
-          // EXPLICITLY in the request still fails loudly.
-          let rec = customId ? ttsVoices.getVoice(customId) : null;
-          if (!rec && !rawVoice) {
-            const saved = ttsVoices.listVoices();
-            if (saved.length) { customId = saved[0].id; rec = ttsVoices.getVoice(customId); }
-            // Pocket can fall back to a built-in speaker; SpeechT5 has none, so for
-            // that one "no saved voice" really is the end of the road.
-            else if (ttsEngine.isPocket()) { useVoice = DEFAULT_POCKET_VOICE; customId = null; }
-          }
-          if (!rec && !customId && ttsEngine.isPocket()) {
-            // resolved to a built-in above — nothing more to look up
-          } else if (!rec) {
-            return sendJson(res, customId ? 404 : 400, {
-              error: {
-                message: customId ? 'no such saved voice' : 'this model speaks in a voice you record — add one in Settings → Text-to-speech',
-                type: 'bad_voice',
-              },
-            });
-          }
-          // Which print to hand over depends on the engine: Pocket TTS takes its
-          // Mimi conditioning, SpeechT5 the 512-d x-vector. A voice saved before
-          // the pocket bundle existed has only the latter.
-          if (ttsEngine.isPocket()) {
-            const pk = ttsVoices.getPocketVoice(customId);
-            if (!pk) {
-              return sendJson(res, 409, {
-                error: {
-                  message: 'this voice was saved without a Pocket TTS conditioning — record it again with Pocket TTS selected',
-                  type: 'voice_kind_missing',
-                },
-              });
-            }
-            speakerEmbedding = pk;
-          } else {
-            speakerEmbedding = rec.vec;
-          }
-          useVoice = `custom:${customId}`;
-        } else if (customId) {
-          // Explicitly asked for a recorded voice this model cannot use — say so.
-          // Inherited from config, though, it is just a stale setting, and refusing
-          // to speak at all is a worse answer than speaking in the default voice.
-          if (rawVoice) {
-            return sendJson(res, 409, {
-              error: { message: `the active model (${ttsEngine.arch()}) cannot use a recorded voice — switch to SpeechT5`, type: 'voice_unsupported' },
-            });
-          }
-          customId = null;
-          useVoice = DEFAULT_TTS_VOICE;
-        } else if (ttsEngine.isPocket() && !isPocketVoice(useVoice)) {
-          // Pocket has its own speaker namespace; a Kokoro voice name here means the
-          // config was carried over from another model, so fall back to its default.
-          useVoice = DEFAULT_POCKET_VOICE;
-        } else if (ttsEngine.supportsVoices() && !ttsEngine.isPocket() && !(isKnownVoice(useVoice) && isValidVoiceId(useVoice))) {
-          return sendJson(res, 400, { error: { message: 'unknown or invalid voice', type: 'bad_voice' } });
-        }
+        const picked = resolveTtsVoice({
+          requested: rawVoice, configured: voice, engine: ttsEngine, voices: ttsVoices,
+          isPocketVoice, isKnownVoice, isValidVoiceId,
+          defaultVoice: DEFAULT_TTS_VOICE, defaultPocketVoice: DEFAULT_POCKET_VOICE,
+        });
+        if (!picked.ok) return sendJson(res, picked.status, { error: { message: picked.message, type: picked.type } });
+        const { voice: useVoice, customId, speakerEmbedding } = picked;
 
         const pcm = await ttsEngine.synth(text, { voice: useVoice, speed, speakerEmbedding });
         // The ACTIVE model's rate, not the constant: a VITS/MMS model emits 16 kHz
@@ -1361,7 +1315,9 @@ export function createGateway(cfg = loadConfig()) {
           'Content-Length': String(out.length),
           'Cache-Control': 'no-store',
           'X-Tts-Sample-Rate': String(rate),
-          ...(customId ? { 'X-Tts-Voice': `custom:${customId}` } : {}),
+          // Say which voice actually spoke, so a caller (or a person debugging one)
+          // can check the setting took. Single-speaker models have nothing to say.
+          ...(customId || ttsEngine.isPocket() || ttsEngine.supportsVoices() ? { 'X-Tts-Voice': useVoice } : {}),
         });
         return res.end(out);
       } catch (e) {

package/src/sqlite-store.js

@@ -172,9 +172,12 @@ export class SqliteHistoryStore {
     return rows.map((r) => ({ id: r.id, score: -r.b, title: r.title, type: r.type, date: r.date }));
   }
 
-  list({ limit = 50, offset = 0 } = {}) {
-    const total = this.db.get('SELECT COUNT(*) c FROM records')?.c || 0;
-    const items = this.db.all('SELECT id, title, type, date, chars FROM records ORDER BY date DESC LIMIT ? OFFSET ?', [limit, offset]);
+  // `type` is additive: list_briefs is "list, of type brief", not a second index.
+  list({ limit = 50, offset = 0, type = null } = {}) {
+    const where = type ? ' WHERE type = ?' : '';
+    const params = type ? [String(type)] : [];
+    const total = this.db.get(`SELECT COUNT(*) c FROM records${where}`, params)?.c || 0;
+    const items = this.db.all(`SELECT id, title, type, date, chars FROM records${where} ORDER BY date DESC LIMIT ? OFFSET ?`, [...params, limit, offset]);
     return { total, items };
   }
 

package/src/stt-models.js

@@ -14,7 +14,19 @@
 // runtime can't load block-quantized (q8/int8) or fp16 exports (see stt-engine
 // runtimeDtype). `.en` models are English-only and reject language/task options.
 
-export const DEFAULT_STT_MODEL = 'onnx-community/whisper-base';
+// THE SHIP DEFAULT. Parakeet rather than Whisper: several times faster at similar or
+// better accuracy, and multilingual, so dictation is good out of the box instead of good
+// after someone finds the model picker.
+//
+// Two costs, stated because they are real. It is a ~690 MB one-time download against
+// whisper-base's ~300 MB, so first dictation takes longer to become available. And
+// parakeet-engine.js fetches from Hugging Face directly rather than ChatPanel's CDN, so a
+// clean install's first dictation depends on huggingface.co — mirroring it on
+// dl.chatpanel.net removes that dependency and is a release chore, not a code change.
+//
+// `whisper-base` remains the small, mirrored fallback for anyone who wants dictation
+// working in seconds on a slow link.
+export const DEFAULT_STT_MODEL = 'istupakov/parakeet-tdt-0.6b-v3-onnx';
 
 export const STT_MODEL_CATALOG = [
   {
@@ -33,7 +45,7 @@ export const STT_MODEL_CATALOG = [
     tier: 'balanced',
     approxMB: 300,   // fp32 on WASM; ~80 on native q8
     ramMB: 700,
-    note: 'Default. Detects the spoken language automatically; good accuracy at real-time speed.',
+    note: 'Small and quick to install. Detects the spoken language automatically; good accuracy at real-time speed.',
   },
   {
     id: 'onnx-community/whisper-small',
@@ -64,16 +76,18 @@ export const STT_MODEL_CATALOG = [
     lang: '25 European languages (auto-detected)',
     tier: 'accurate',
     engine: 'parakeet-tdt',
-    recommended: true,   // our default recommendation: faster + more accurate than Whisper.
+    recommended: true,   // and the DEFAULT — faster + more accurate than Whisper.
     approxMB: 690,   // int8: encoder 652 + decoder_joint 18 + preprocessor
     ramMB: 1600,
     note: 'Recommended — NVIDIA Parakeet transducer. Several× faster than Whisper at similar or better accuracy, English + 24 EU languages. One-time download; best on the native (npm) gateway.',
   },
 ];
 
-// The model we steer users to (a bigger, on-demand download — NOT the boot default,
-// which stays a small model so first dictation works instantly). The settings UI
-// surfaces this so users can install it after the gateway is running.
+// The model we steer users to. It is now also DEFAULT_STT_MODEL — the two were split
+// while the default stayed small for a fast first run, and shipping the best model by
+// default is the call that closed that gap. Kept as its own export because the settings UI
+// marks a recommendation, and the two could diverge again (a heavier model that is worth
+// recommending but too big to default to).
 export const RECOMMENDED_STT_MODEL = 'istupakov/parakeet-tdt-0.6b-v3-onnx';
 
 // STT engine backing a model. Default 'whisper' = the transformers.js ASR pipeline;

package/src/subject-kinds.js

@@ -0,0 +1,6 @@
+// VENDORED from @chatpanel/events/subject-kinds.js — edit there, then copy over.
+// The subject vocabulary, alone in a file so both halves of subject identity can name it
+// without either importing the other.
+
+/** What a subject can be. `title` is a record title someone linked to with [[…]]. */
+export const SUBJECT_KINDS = Object.freeze(['person', 'topic', 'tag', 'title']);

package/src/subject-name.js

@@ -0,0 +1,97 @@
+// VENDORED from @chatpanel/events/subject-name.js — edit there, then copy over.
+// Naming a subject, and when one is big enough to deserve a page.
+//
+// The small, dependency-free half of subject identity: fold a name to its canonical form,
+// strip the decoration a directory hangs off it, and hold the evidence thresholds. Nothing
+// here resolves aliases, proposes merges or reaches for a Levenshtein — that is `entity.js`,
+// which imports this.
+//
+// The split is a load-time one, and it is the third time the lesson has come up here (see
+// `distance.js` and `redaction-tokens.js`). `knowledge.js` needs exactly `normalizeSubject`
+// to build a brief id, and the extension's brief store needs exactly `DEFAULT_THRESHOLD` —
+// and both are on the MV3 service worker's graph. Reaching them through `entity.js` put
+// entity resolution and merge suggestion on a worker that will never run either.
+
+import { SUBJECT_KINDS } from './subject-kinds.js';
+
+/**
+ * A subject earns a brief with EVIDENCE, not on first sight (I-K4).
+ *
+ * PROVISIONAL. These numbers are the W0 measurement's whole point: `surveyCorpus()` reports
+ * how many subjects clear them so they can be set from a real corpus instead of taste. Do
+ * not treat them as decided until that report has been run.
+ */
+export const DEFAULT_THRESHOLD = Object.freeze({ records: 3, mentions: 5 });
+
+/** Ceiling on the set of briefs, for the same reason memory.js caps memories. Provisional. */
+export const MAX_SUBJECTS = 500;
+/** Longest name we will treat as a subject — past this it is a sentence, not a subject. */
+export const MAX_SUBJECT_CHARS = 60;
+/**
+ * Labels a meeting platform uses for the person holding the microphone.
+ *
+ * Zoom, Meet and Teams all write the local participant as "You" — so the user appears in
+ * their own corpus under a name that is not a name, alongside however their colleagues'
+ * clients spelled them. Resolving these needs one fact only the host has: who "you" IS.
+ * `resolveSubjects` takes it rather than guessing, and with no `self` supplied these stay
+ * unresolved instead of collapsing every meeting's local speaker into one fictional person.
+ */
+export const SELF_LABELS = Object.freeze(['you', 'me', 'myself', 'yourself', 'i']);
+
+/**
+ * Is this the platform's label for the local participant?
+ *
+ * Exported because two layers need the SAME exception and getting the order wrong is subtle:
+ * a self-label fails `isSubjectCandidate` (it is a pronoun), so any pass that filters
+ * candidacy BEFORE `resolveSubjects` can fold it has already thrown the user away. `curate.js
+ * mentionsFrom` keeps them for exactly this reason and lets resolution decide.
+ */
+export function isSelfLabel(name) {
+  return SELF_LABELS.includes(normalizeSubject(name));
+}
+
+/**
+ * Strip the decoration a directory or a conference client hangs off a person's name.
+ *
+ * The same human arrives as "Alex Rivera", "Alex Rivera (ACME)", "Alex Rivera - Host" and
+ * "Alex Rivera (he/him)" depending on which client wrote the label. The part in parentheses
+ * or after a dash is an org, a role or a pronoun set — decoration, never identity — so it is
+ * removed before folding.
+ *
+ * NOT removed for non-person subjects: "Migration (Phase 2)" is a different topic from
+ * "Migration", where "Alex Rivera (ACME)" is not a different person from "Alex Rivera".
+ */
+export function stripQualifiers(name) {
+  return String(name ?? '')
+    .replace(/\s*[([{][^)\]}]*[)\]}]\s*/g, ' ')   // (ACME), [external], {guest}
+    .replace(/\s+[-–—|·,]\s+.*$/, '')             // - Host, — Guest, | ACME
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+/**
+ * Fold a name to its canonical form: lowercase, Unicode-aware, separators collapsed.
+ *
+ * Spaces survive as spaces (unlike normalizeTag, which folds them to '-') because a person's
+ * name is read back to the user and "alex rivera" has to be recognisable as one.
+ */
+export function normalizeSubject(name) {
+  const raw = String(name ?? '').normalize('NFKC').trim().replace(/^[#@]+/, '');
+  if (!raw) return '';
+  return raw
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}]+/gu, ' ')
+    .trim()
+    .slice(0, MAX_SUBJECT_CHARS)
+    .trim();
+}
+/** `person:alex rivera` — the identity a brief is filed under. '' when nothing survives. */
+export function subjectKey(kind, name) {
+  const norm = normalizeSubject(name);
+  if (!norm || !SUBJECT_KINDS.includes(kind)) return '';
+  return `${kind}:${norm}`;
+}
+/** Tokens of a canonical name. */
+export function subjectTokens(name) {
+  const norm = normalizeSubject(name);
+  return norm ? norm.split(' ').filter(Boolean) : [];
+}

package/src/tts-voice-resolve.js

@@ -0,0 +1,78 @@
+// Which voice a /tts request actually speaks in — decided in ONE place, with every
+// dependency injected so the table below can be tested without loading a model.
+//
+// The rule that shapes this: a saved clone is a CHOICE, never a default. Someone's
+// own voice print must not start speaking because the config was empty, named a
+// voice from another model, or pointed at a voice since deleted. A model with
+// built-in speakers (Pocket) falls back to one of those; only SpeechT5, which has
+// no built-ins, has nothing to fall back to but a recording.
+//
+// A voice named EXPLICITLY in the request never falls back — it succeeds or fails
+// loudly, so a caller that asked for a specific voice can trust what it got.
+//
+// Returns either { ok: true, voice, customId, speakerEmbedding }
+//             or { ok: false, status, type, message }.
+
+export function resolveTtsVoice({
+  requested = null,     // body.voice, or null when the caller left it to the config
+  configured,           // the voice the request would use absent an override
+  engine,               // { isPocket(), supportsCustomVoices(), supportsVoices(), arch() }
+  voices,               // { parseCustomVoice, getVoice, listVoices, getPocketVoice }
+  isPocketVoice,
+  isKnownVoice,
+  isValidVoiceId,
+  defaultVoice,         // Kokoro's default
+  defaultPocketVoice,   // Pocket's built-in default
+}) {
+  const voice = requested || configured;
+  const pocket = engine.isPocket();
+  let customId = voices.parseCustomVoice(voice);
+
+  // A Pocket built-in speaker is a NAME, not an embedding, so it is recognised
+  // before the custom-voice path — which would otherwise demand a recording for a
+  // model that ships eight voices of its own.
+  if (pocket && isPocketVoice(voice)) return { ok: true, voice, customId: null, speakerEmbedding: null };
+
+  if (engine.supportsCustomVoices()) {
+    let rec = customId ? voices.getVoice(customId) : null;
+    if (!rec && !requested) {
+      // Nothing valid was configured and nothing was asked for.
+      if (pocket) return { ok: true, voice: defaultPocketVoice, customId: null, speakerEmbedding: null };
+      const saved = voices.listVoices();
+      if (saved.length) { customId = saved[0].id; rec = voices.getVoice(customId); }
+    }
+    if (!rec) {
+      return customId
+        ? { ok: false, status: 404, type: 'bad_voice', message: 'no such saved voice' }
+        : { ok: false, status: 400, type: 'bad_voice', message: 'this model speaks in a voice you record — add one in Settings → Text-to-speech' };
+    }
+    // Which print to hand over depends on the engine: Pocket TTS takes its Mimi
+    // conditioning, SpeechT5 the 512-d x-vector. A voice saved before the pocket
+    // bundle existed has only the latter.
+    let speakerEmbedding;
+    if (pocket) {
+      speakerEmbedding = voices.getPocketVoice(customId);
+      if (!speakerEmbedding) {
+        return { ok: false, status: 409, type: 'voice_kind_missing', message: 'this voice was saved without a Pocket TTS conditioning — record it again with Pocket TTS selected' };
+      }
+    } else {
+      speakerEmbedding = rec.vec;
+    }
+    return { ok: true, voice: `custom:${customId}`, customId, speakerEmbedding };
+  }
+
+  if (customId) {
+    // Explicitly asked for a recorded voice this model cannot use — say so.
+    // Inherited from config, though, it is just a stale setting, and refusing to
+    // speak at all is a worse answer than speaking in the default voice.
+    if (requested) {
+      return { ok: false, status: 409, type: 'voice_unsupported', message: `the active model (${engine.arch()}) cannot use a recorded voice — switch to SpeechT5` };
+    }
+    return { ok: true, voice: defaultVoice, customId: null, speakerEmbedding: null };
+  }
+  if (pocket && !isPocketVoice(voice)) return { ok: true, voice: defaultPocketVoice, customId: null, speakerEmbedding: null };
+  if (engine.supportsVoices() && !pocket && !(isKnownVoice(voice) && isValidVoiceId(voice))) {
+    return { ok: false, status: 400, type: 'bad_voice', message: 'unknown or invalid voice' };
+  }
+  return { ok: true, voice, customId: null, speakerEmbedding: null };
+}