@chatpanel/events 0.33.1 → 0.47.0

package/entitlement.js

@@ -0,0 +1,298 @@
+// PLANS, GATES AND THE SIGNED ENTITLEMENT — one definition, every client.
+//
+// WHY THIS IS SHARED, and it is the sharpest example in the package. "Is this user Pro" is
+// currently answered in four places: the extension (`js/license.js`), the bridge
+// (`src/entitlement.js`), the gateway (`src/entitlement.js`) and now a desktop app. Three of
+// those already carry their own copy of the SAME public key, which is why `CLAUDE.md` has to
+// warn that rotating the signing key means editing every client by hand.
+//
+// Duplicating a feature matrix is worse than duplicating a helper: it does not fail loudly,
+// it fails as "Pro works in the browser but not on the desktop", which reads to the person
+// paying for it as the product being broken. Defining it once makes the two clients agree
+// BY CONSTRUCTION rather than by diligence.
+//
+// WHAT IS STILL THE CLIENT'S JOB (P8, as everywhere else): storing the licence, minting and
+// keeping an install id, opening a browser for checkout, and counting local usage against
+// the free limits. Those need storage and a platform. Everything here is pure.
+//
+// THE PRIVATE KEY IS NOT HERE AND NEVER WILL BE. The worker holds it; this file holds only
+// the public half, which is what lets every client verify OFFLINE — chat traffic never
+// touches the licence server, and a client that cannot reach the network keeps working.
+
+export class EntitlementError extends Error {
+  constructor(message) { super(message); this.name = 'EntitlementError'; }
+}
+
+export const PLANS = Object.freeze(['free', 'pro', 'team']);
+const RANK = Object.freeze({ free: 0, pro: 1, team: 2 });
+
+/** Where the licence server lives. One base; the endpoints derive from it. */
+export const API_BASE = 'https://api.chatpanel.net';
+export const ENDPOINTS = Object.freeze({
+  verify: `${API_BASE}/license/verify`,
+  entitlement: `${API_BASE}/entitlement`,
+  claim: `${API_BASE}/entitlement/claim`,
+  release: `${API_BASE}/entitlement/release`,
+  restore: `${API_BASE}/restore`,
+});
+
+/**
+ * The PUBLIC half of the entitlement signing key.
+ *
+ * Byte-for-byte the key the extension and bridge already embed. If it is ever rotated it is
+ * rotated HERE, and every client that takes this package inherits it on its next sync —
+ * which is the entire reason this module exists.
+ */
+export const ENTITLEMENT_PUBLIC_JWK = Object.freeze({
+  kty: 'EC',
+  crv: 'P-256',
+  x: 'CmgKLC4e3xDMvwhbjVqF7jbDe1JhC1KKQi8JN3qVX_4',
+  y: 'r40l6fQiyCcJYqW-SvB4VoSyn4F36yhSt82ZAOSo78E',
+});
+
+/** Where "Upgrade" sends people. A stable URL, so pricing can change without a release. */
+export const UPGRADE_URL = 'https://chatpanel.net/#pricing';
+
+export function checkoutUrl(plan = 'pro', installId = '', client = '') {
+  const u = new URL('https://chatpanel.net/');
+  if (installId) u.searchParams.set('install_id', installId);
+  if (plan) u.searchParams.set('plan', plan);
+  // Which client sent them, so a desktop purchase can be attributed and, later, seated
+  // differently from a browser one. Additive: the site ignores what it does not read.
+  if (client) u.searchParams.set('client', client);
+  u.hash = 'pricing';
+  return u.toString();
+}
+
+// --------------------------------------------------------------------------
+// The matrix
+// --------------------------------------------------------------------------
+
+/**
+ * Every gated feature → the minimum plan that unlocks it. Anything absent is free.
+ *
+ * Features a given client cannot perform are still listed: the desktop cannot capture a
+ * meeting, but it can READ one, and `liveMeetings` gates the dashboard and history search
+ * as well as capture. A client omitting a key it "does not need" is how the two drift.
+ */
+export const FEATURE_TIER = Object.freeze({
+  localAgents: 'free',
+  byoModels: 'free',
+  urlContext: 'free',
+  liveMeetings: 'free',
+
+  multiTab: 'pro',
+  unlimitedAgents: 'pro',
+  customSkills: 'pro',
+  customAgents: 'pro',
+  advancedAgent: 'pro',
+  unlimitedNotes: 'pro',
+  unlimitedMeetings: 'pro',
+  structuredInsert: 'pro',
+  exportChats: 'pro',
+  autoBackup: 'pro',
+  promptLibrary: 'pro',
+  fileAttachments: 'pro',
+  watch: 'pro',
+
+  cloudSync: 'team',
+  sharedLibrary: 'team',
+  hostedBridge: 'team',
+  sso: 'team',
+});
+
+export const PRO_FEATURES = Object.freeze({
+  unlimitedNotes: 'Unlimited notes — Free keeps your first 10',
+  unlimitedMeetings: 'Unlimited meetings — Free keeps your first 10',
+  multiTab: 'Attach several tabs at once',
+  unlimitedAgents: 'Unlimited custom agents',
+  customSkills: 'Create & edit your own skills',
+  advancedAgent: 'Per-agent system prompts & working directories',
+  structuredInsert: 'Clean diagrams on Excalidraw, draw.io & tldraw — shapes placed as data, not pixel-drawn',
+  exportChats: 'Export conversations as Markdown',
+  autoBackup: 'Automatic daily backup of all your data to disk',
+  watch: 'Watch a page & act on changes — the agent reacts as the page updates',
+});
+
+export const TEAM_FEATURES = Object.freeze({
+  cloudSync: 'Sync chats across your devices',
+  sharedLibrary: 'Shared team agents & skills',
+  hostedBridge: 'Hosted agents — no local bridge to run',
+  sso: 'SSO & admin controls',
+});
+
+/** Free-tier ceilings. LIFETIME counts where noted — see the anti-cheat note in each client. */
+export const FREE_LIMITS = Object.freeze({
+  notes: 10,
+  meetings: 10,
+  apiEndpoints: 1,
+  bridgeAgents: 1,
+  customAgents: 1,
+  attachmentsPerMessage: 1,
+  mcpServers: 1,
+  gatewayDestinations: 1,
+  webSearchEngines: 3,
+  webSearchesPerDay: 50,
+  fullRedactions: 25,
+});
+
+// --------------------------------------------------------------------------
+// Resolution
+// --------------------------------------------------------------------------
+
+/**
+ * The plan actually in force.
+ *
+ * An expired licence is `free`, checked against an injected `now` so a client cannot be
+ * tested only at the moment it happens to be run.
+ */
+export function planOf(license, now = Date.now()) {
+  if (!license || !PLANS.includes(license.plan)) return 'free';
+  if (license.expiresAt && now > license.expiresAt) return 'free';
+  return license.plan;
+}
+
+export function planLabel(license, now = Date.now()) {
+  return { free: 'Free', pro: 'Pro', team: 'Team' }[planOf(license, now)];
+}
+
+export function isPro(license, now = Date.now()) {
+  return RANK[planOf(license, now)] >= RANK.pro;
+}
+
+export function isTeam(license, now = Date.now()) {
+  return planOf(license, now) === 'team';
+}
+
+/** Gate a feature. `count` expresses "this would be my Nth", for the counted allowances. */
+export function can(license, feature, count = 0, now = Date.now()) {
+  const plan = planOf(license, now);
+  if (feature === 'unlimitedAgents' && RANK[plan] < RANK.pro) {
+    return count < FREE_LIMITS.customAgents;
+  }
+  const need = FEATURE_TIER[feature] || 'free';
+  return RANK[plan] >= RANK[need];
+}
+
+/** The minimum plan a feature needs — for an upgrade prompt that names the right tier. */
+export function tierFor(feature) {
+  return FEATURE_TIER[feature] || 'free';
+}
+
+/**
+ * Is this the Nth use of a lifetime-capped free allowance?
+ *
+ * The count is MONOTONIC — "how many have ever been created", not "how many exist now" —
+ * because a cap on the current count is lifted by deleting things, which is not a limit.
+ */
+export function withinFreeLimit(license, key, everCount, now = Date.now()) {
+  if (isPro(license, now)) return true;
+  const cap = FREE_LIMITS[key];
+  return typeof cap !== 'number' || everCount < cap;
+}
+
+// --------------------------------------------------------------------------
+// The signed token
+// --------------------------------------------------------------------------
+
+function b64urlToBytes(s) {
+  const pad = '='.repeat((4 - (String(s).length % 4)) % 4);
+  const b64 = String(s).replace(/-/g, '+').replace(/_/g, '/') + pad;
+  if (typeof Buffer !== 'undefined') return new Uint8Array(Buffer.from(b64, 'base64'));
+  const bin = atob(b64);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+function decodePayload(head) {
+  try {
+    return JSON.parse(new TextDecoder().decode(b64urlToBytes(head)));
+  } catch {
+    return null;
+  }
+}
+
+let _keyPromise = null;
+
+async function verifyKey(subtle) {
+  const s = subtle || globalThis.crypto?.subtle;
+  if (!s) throw new EntitlementError('no WebCrypto available on this runtime');
+  if (subtle) {
+    // An injected implementation must not be memoised into the shared slot, or a test that
+    // passes one would poison every later call in the process.
+    return s.importKey('jwk', ENTITLEMENT_PUBLIC_JWK, { name: 'ECDSA', namedCurve: 'P-256' }, false, ['verify']);
+  }
+  if (!_keyPromise) {
+    _keyPromise = s.importKey('jwk', ENTITLEMENT_PUBLIC_JWK, { name: 'ECDSA', namedCurve: 'P-256' }, false, ['verify']);
+  }
+  return _keyPromise;
+}
+
+/**
+ * Verify a server entitlement token and return its payload, or `null`.
+ *
+ * Three checks, and all three matter: the SIGNATURE (it came from the worker), the INSTALL
+ * BINDING (it was issued to this device, so a token copied from a forum does not grant Pro),
+ * and EXPIRY. Returning null rather than throwing is deliberate — a caller resolving a
+ * licence at startup must degrade to free, not crash the app.
+ */
+export async function verifyEntitlement(token, installId, { subtle = null, now = Date.now() } = {}) {
+  if (!token || typeof token !== 'string' || token.indexOf('.') < 0) return null;
+  const [head, sig] = token.split('.');
+  if (!head || !sig) return null;
+
+  let ok = false;
+  try {
+    const s = subtle || globalThis.crypto?.subtle;
+    ok = await s.verify(
+      { name: 'ECDSA', hash: 'SHA-256' },
+      await verifyKey(subtle),
+      b64urlToBytes(sig),
+      new TextEncoder().encode(head),
+    );
+  } catch {
+    return null;
+  }
+  if (!ok) return null;
+
+  const payload = decodePayload(head);
+  if (!payload) return null;
+  if (payload.exp && now > Number(payload.exp)) return null;
+  // `install` binds the token to one device. A token with no binding is refused rather than
+  // treated as universal — "unbound" must never be the permissive case.
+  if (!payload.install || (installId && payload.install !== installId)) return null;
+  if (!PLANS.includes(payload.plan)) return null;
+  return payload;
+}
+
+/** A verified payload → the licence record a client stores. */
+export function licenseFromPayload(payload, { at = Date.now() } = {}) {
+  if (!payload) return { plan: 'free' };
+  return {
+    plan: payload.plan,
+    expiresAt: Number(payload.exp) || 0,
+    installId: payload.install || '',
+    seats: Number(payload.seats) || 0,
+    checkedAt: at,
+    source: payload.source || 'entitlement',
+  };
+}
+
+/**
+ * Should this client re-check with the server yet?
+ *
+ * Offline verification is the point, so the cadence is generous — but a licence that has
+ * NEVER been checked, or one whose expiry is close, is worth a call. Pure so the schedule is
+ * testable without waiting a day.
+ */
+export const RECHECK_INTERVAL_MS = 12 * 60 * 60 * 1000;
+
+export function needsRecheck(license, { now = Date.now(), interval = RECHECK_INTERVAL_MS } = {}) {
+  if (!license || !license.checkedAt) return true;
+  if (now - license.checkedAt > interval) return true;
+  // Inside the last day of validity, check more eagerly: this is where a renewal lands and
+  // where a silent lapse would otherwise surprise someone mid-sentence.
+  if (license.expiresAt && license.expiresAt - now < 24 * 60 * 60 * 1000) return true;
+  return false;
+}

package/entity.js

@@ -0,0 +1,354 @@
+// ENTITY IDENTITY — forty mentions of one person are one subject, or they are nothing.
+//
+// Extraction we already have: `meeting-people.js` names the speakers on a call,
+// `extraction.js` pulls topics and ENTITIES, `tags.js` folds the filing vocabulary. What
+// none of them answer is the next question: are "Alex Rivera", "alex rivera" and the
+// "Alex" who spoke in yesterday's standup the SAME subject? Without that answer a derived
+// layer cannot exist — a brief is by definition an accumulation across records, so it needs
+// something to accumulate *about*.
+//
+// Two rules do almost all the work, and both are deliberately conservative:
+//
+//   • CANONICAL FORM IS LOSSY, IDENTITY IS NOT. `subjectKey()` folds case, punctuation and
+//     spacing — filing noise, exactly as in tags.js — but never folds two different names
+//     together. The display name stays whatever the corpus said most often, so the user
+//     reads "Alex Rivera" and not "alex-rivera".
+//   • AN ALIAS IS ONLY AN ALIAS WHEN IT IS UNAMBIGUOUS. "Alex" folds into "Alex Rivera"
+//     when Alex Rivera is the only Alex in the corpus. The moment a second Alex appears,
+//     the bare token stops resolving to either — for good, and retroactively. Guessing here
+//     is how a brief ends up attributing one person's decisions to another, which is the
+//     single most expensive mistake this layer can make.
+//
+// Pure input → output: no storage, no clock, no model. The extension, the gateway and a
+// future mobile client must agree on what "the same subject" is, and three implementations
+// would mean three answers — the argument tags.js already makes for tags.
+
+import { blockedPairs, editDistance } from './distance.js';
+// The placeholder recognizer lives on its own (see that file for why). Re-exported so every
+// existing caller of entity.js is unchanged.
+import { isRedactionToken } from './redaction-tokens.js';
+
+export { REDACTION_TOKEN_TYPES, isRedactionToken } from './redaction-tokens.js';
+
+// Naming and sizing a subject live next door, so a caller that needs only those does not
+// drag alias resolution and a Levenshtein along. Re-exported: no caller of entity.js changes.
+import {
+  DEFAULT_THRESHOLD, MAX_SUBJECTS, MAX_SUBJECT_CHARS, SELF_LABELS,
+  isSelfLabel, normalizeSubject, stripQualifiers,
+} from './subject-name.js';
+import { SUBJECT_KINDS } from './subject-kinds.js';
+
+export { SUBJECT_KINDS } from './subject-kinds.js';
+export {
+  DEFAULT_THRESHOLD, MAX_SUBJECTS, MAX_SUBJECT_CHARS, SELF_LABELS, isSelfLabel,
+  normalizeSubject, stripQualifiers, subjectKey, subjectTokens,
+} from './subject-name.js';
+
+
+// Words that are never a subject on their own. A one-token candidate has to survive this
+// list before it can become a page, because "notes", "meeting" and "update" appear in every
+// record and would each clear any threshold instantly.
+const STOP_SUBJECTS = new Set([
+  'chat', 'chats', 'note', 'notes', 'meeting', 'meetings', 'call', 'calls', 'update',
+  'updates', 'summary', 'summaries', 'agenda', 'todo', 'todos', 'task', 'tasks', 'item',
+  'items', 'thing', 'things', 'stuff', 'misc', 'other', 'general', 'test', 'testing',
+  'untitled', 'draft', 'drafts', 'new', 'old', 'today', 'yesterday', 'tomorrow', 'week',
+  'day', 'month', 'year', 'time', 'people', 'person', 'team', 'work',
+]);
+
+/**
+ * Is this string worth considering as a subject at all?
+ *
+ * Rejects blanks, over-long phrases, pure numbers and the stop list above. A multi-token
+ * phrase is allowed even when one of its tokens is a stop word ("design review" is a real
+ * topic, "review" alone is not).
+ */
+export function isSubjectCandidate(name, { kind = 'topic' } = {}) {
+  // Length is judged BEFORE folding: normalizeSubject truncates at MAX_SUBJECT_CHARS, so a
+  // check on its output can never fire and a whole sentence would slip through as a subject.
+  if (String(name ?? '').trim().length > MAX_SUBJECT_CHARS) return false;
+  // Checked on the RAW value, before folding: normalizeSubject lowercases, and the pattern
+  // is upper-case by construction.
+  if (isRedactionToken(name)) return false;
+  // "You" is a pronoun, not a person. Without a `self` name to fold it into (resolveSubjects
+  // takes one), it must not become a subject of its own — every meeting has a "You" and they
+  // are not all the same participant.
+  if (kind === 'person' && isSelfLabel(name)) return false;
+  const norm = normalizeSubject(name);
+  if (!norm || norm.length < 2) return false;
+  const tokens = norm.split(' ').filter(Boolean);
+  if (!tokens.length) return false;
+  if (tokens.every((t) => /^\p{N}+$/u.test(t))) return false;
+  if (tokens.length === 1 && STOP_SUBJECTS.has(tokens[0])) return false;
+  // A person needs at least two characters of actual letters — "j r" is initials, not an
+  // identity we can accumulate against.
+  if (kind === 'person' && !/\p{L}{2}/u.test(norm)) return false;
+  return true;
+}
+
+/**
+ * Resolve short forms to full names, but ONLY when the corpus leaves no doubt.
+ *
+ * Given the canonical names seen for one kind, returns `alias -> canonical`. A bare token
+ * maps to a multi-token name when it is that name's first or last token AND exactly one
+ * name in the corpus claims it. Two people called Alex means neither owns "alex", so the
+ * bare token maps to nothing and stays a subject of its own — visible, unmerged, and
+ * therefore checkable, which is the failure mode we want.
+ */
+export function aliasMap(names) {
+  const canonical = new Set();
+  for (const n of names || []) {
+    const norm = normalizeSubject(n);
+    if (norm && norm.includes(' ')) canonical.add(norm);
+  }
+  const claims = new Map(); // token -> Set(full names claiming it)
+  for (const full of canonical) {
+    const tokens = full.split(' ');
+    for (const t of [tokens[0], tokens[tokens.length - 1]]) {
+      if (!t || t.length < 2 || STOP_SUBJECTS.has(t)) continue;
+      if (!claims.has(t)) claims.set(t, new Set());
+      claims.get(t).add(full);
+    }
+  }
+  const out = new Map();
+  for (const [token, owners] of claims) {
+    if (owners.size !== 1) continue; // ambiguous — resolve to nothing, on purpose
+    out.set(token, [...owners][0]);
+  }
+  return out;
+}
+
+/**
+ * Fold a list of raw mentions into subjects.
+ *
+ * `mentions` is `[{ kind, name, recordId }]` — whatever the corpus said, in whatever form.
+ * The result is one entry per identity, carrying every surface form that reached it, the
+ * distinct records it appeared in, and the display name the corpus used most often.
+ *
+ * Aliases are resolved per KIND: two topics can share a word without being the same topic,
+ * and the person rule above must not leak into tags.
+ */
+export function resolveSubjects(mentions = [], { merges = null, self = '' } = {}) {
+  // The user's own name, however they told us. Everything the platforms call "you" folds
+  // into it — and with no name supplied, nothing does.
+  const selfName = String(self ?? '').trim();
+  const selfCanonical = normalizeSubject(selfName);
+  // User-authored merges: `alias canonical form -> the canonical form it belongs to`. These
+  // are an INPUT to derivation, never an edit to its output, which is what keeps I-K2 true —
+  // a rebuild that dropped the user's corrections would teach them not to make any.
+  const merged = new Map();
+  for (const [from, to] of merges instanceof Map ? merges : Object.entries(merges || {})) {
+    const a = normalizeSubject(from); const b = normalizeSubject(to);
+    if (a && b && a !== b) merged.set(a, b);
+  }
+  // One hop only. A chain (a→b, b→c) is resolved here rather than at read time, and a cycle
+  // simply stops, because a merge loop must not hang a rebuild.
+  const resolveMerge = (key) => {
+    let cur = key;
+    for (let i = 0; i < 8 && merged.has(cur); i += 1) {
+      const next = merged.get(cur);
+      if (next === cur) break;
+      cur = next;
+    }
+    return cur;
+  };
+
+  const byKind = new Map();
+  for (const m of mentions) {
+    const kind = m?.kind;
+    if (!SUBJECT_KINDS.includes(kind)) continue;
+    // A self-label survives candidacy ONLY when there is a name to fold it into. Otherwise
+    // it is a pronoun, and every meeting's "You" would pile into one fictional participant.
+    const isSelf = kind === 'person' && !!selfCanonical && isSelfLabel(m.name);
+    if (!isSelf && !isSubjectCandidate(m.name, { kind })) continue;
+    if (!byKind.has(kind)) byKind.set(kind, []);
+    byKind.get(kind).push(m);
+  }
+
+  const subjects = new Map();
+  for (const [kind, list] of byKind) {
+    // Only PERSON names carry the short-form rule. A topic named "design" is not the
+    // "design review" topic, and folding them would silently merge two pages.
+    const aliases = kind === 'person'
+      ? aliasMap(list.map((m) => stripQualifiers(m.name)).filter((n) => !isSelfLabel(n)))
+      : new Map();
+    for (const m of list) {
+      const raw = String(m.name ?? '').trim();
+      // For a PERSON, the qualifier is decoration and the platform's "You" is the user.
+      // Both are resolved before the alias rule, so "Alex Rivera (ACME)" and "You" reach the
+      // same identity that a bare "Alex" does.
+      let norm = normalizeSubject(kind === 'person' ? stripQualifiers(raw) : raw);
+      if (kind === 'person' && selfCanonical && SELF_LABELS.includes(norm)) norm = selfCanonical;
+      const canonical = resolveMerge(aliases.get(norm) || norm);
+      const key = `${kind}:${canonical}`;
+      let s = subjects.get(key);
+      if (!s) {
+        s = { key, kind, name: '', canonical, aliases: [], records: new Set(), mentions: 0, forms: new Map() };
+        subjects.set(key, s);
+      }
+      s.mentions += 1;
+      if (m.recordId) s.records.add(m.recordId);
+      // The SURFACE FORM a person is displayed under is the stripped one. The canonical was
+      // already right — "Sam Okonkwo [ACME - Platform]" resolved to person:sam okonkwo — but the
+      // raw string was recorded as the display form, so a subject seen only that way got a
+      // page titled with the directory's decoration. A qualifier is not part of a name.
+      const display = String(kind === 'person' ? stripQualifiers(raw) : raw).normalize('NFKC').trim();
+      if (display) s.forms.set(display, (s.forms.get(display) || 0) + 1);
+      if (norm !== canonical && !s.aliases.includes(norm)) s.aliases.push(norm);
+    }
+  }
+
+  for (const s of subjects.values()) {
+    // The name the user reads is a surface form of the CANONICAL identity, most common
+    // first, ties broken alphabetically so the choice is stable across runs rather than
+    // insertion-ordered. Forms that only reached this subject through an alias are ranked
+    // last: `person:alex rivera` displayed as "Alex" because the short form happened to be
+    // one mention commoner would be a page whose title is not the subject's name.
+    const forms = [...s.forms.entries()]
+      .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
+    s.name = forms.find(([f]) => normalizeSubject(f) === s.canonical)?.[0]
+      || forms[0]?.[0]
+      || s.canonical;
+    s.aliases.sort();
+    delete s.forms;
+  }
+  return subjects;
+}
+
+/** Does this subject have enough evidence to deserve a page? */
+export function earnsBrief(subject, threshold = DEFAULT_THRESHOLD) {
+  if (!subject) return false;
+  const records = subject.records instanceof Set ? subject.records.size : (subject.records?.length || 0);
+  const mentions = Number(subject.mentions) || 0;
+  return records >= (threshold.records ?? DEFAULT_THRESHOLD.records)
+      && mentions >= (threshold.mentions ?? DEFAULT_THRESHOLD.mentions);
+}
+
+/**
+ * Rank subjects and keep the ones that earned a page, strongest first.
+ *
+ * `limit` is the I-K4 count ceiling made concrete: a corpus with 4000 qualifying subjects
+ * does not get 4000 briefs, it gets the best `limit` of them, and the rest stay subjects
+ * without pages until the evidence moves.
+ */
+export function rankSubjects(subjects, { threshold = DEFAULT_THRESHOLD, limit = MAX_SUBJECTS } = {}) {
+  const list = [...(subjects instanceof Map ? subjects.values() : subjects || [])];
+  return list
+    .filter((s) => earnsBrief(s, threshold))
+    .map((s) => ({ ...s, recordCount: s.records instanceof Set ? s.records.size : (s.records?.length || 0) }))
+    .sort((a, b) => b.recordCount - a.recordCount || b.mentions - a.mentions || a.key.localeCompare(b.key))
+    .slice(0, Math.max(0, limit));
+}
+
+/**
+ * PROPOSE merges; never apply them.
+ *
+ * The alias rule folds what it can prove. Everything it cannot is left visible — "A. Rivera"
+ * beside "Alex Rivera", an initialism beside a full name, a second spelling of a project —
+ * and a user staring at two pages for one person has no way to say so. This is that way: a
+ * deterministic, model-free list of pairs worth asking about, ranked by how likely they are.
+ *
+ * PROPOSING is the whole design. The pairs below are exactly the ones the alias rule refuses
+ * to decide on its own, because deciding wrongly merges two people permanently and silently.
+ * A human answers in one click, the answer is stored as a merge rule, and every later rebuild
+ * applies it — so the correction survives I-K2 rather than being erased by the next pass.
+ *
+ * Three signals, strongest first:
+ *   • initials — "A. Rivera" against "Alex Rivera"
+ *   • containment — one name's tokens are a subset of the other's
+ *   • near-spelling — one edit apart, or a transposition, which catches the common typos
+ *
+ * A shared SURNAME is deliberately not a signal: two people with one last name are usually
+ * two people, and proposing every such pair would bury the real suggestions.
+ */
+export function suggestMerges(subjects, { limit = 40, distance = 1 } = {}) {
+  const list = [...(subjects instanceof Map ? subjects.values() : subjects || [])]
+    .filter((s) => s && s.canonical);
+
+  // BLOCKED, not pairwise. Comparing every pair did not finish 12,000 subjects in two
+  // minutes — 6.8s at 2,000, 32s at 6,000, 141s at 12,000 — and a corpus with a few thousand
+  // distinct people, topics and tags reaches that easily. This pass runs on the UI thread,
+  // so that is a hung page, not a slow one.
+  //
+  // All three signals need either a shared end or a shared last token, which is precisely
+  // what `blockKeys` files on, so the findings survive the change: an abbreviated first name
+  // shares the surname, a contained name shares a prefix, a typo shares whichever end it is
+  // not in.
+  const byCanonical = new Map();
+  for (const s of list) {
+    if (!byCanonical.has(s.canonical)) byCanonical.set(s.canonical, []);
+    byCanonical.get(s.canonical).push(s);
+  }
+
+  const out = [];
+  for (const [ca, cb] of blockedPairs([...byCanonical.keys()])) {
+    // One reason per canonical PAIR, computed before the (rare) fan-out over subjects that
+    // share a canonical form across kinds.
+    for (const a of byCanonical.get(ca)) {
+      for (const b of byCanonical.get(cb)) {
+        if (a.kind !== b.kind) continue; // a person and a topic are never the same subject
+        const reason = mergeReason(a.canonical, b.canonical, a.kind, distance);
+        if (!reason) continue;
+        // The better-evidenced side is proposed as the survivor: it has more records behind
+        // it and is more likely the name the user actually thinks in.
+        const [keep, drop] = countOf(a) >= countOf(b) ? [a, b] : [b, a];
+        out.push({ kind: a.kind, keep: keep.key, keepName: keep.name, drop: drop.key, dropName: drop.name, reason });
+      }
+    }
+  }
+
+  const rank = { initials: 0, containment: 1, spelling: 2 };
+  return out
+    .sort((x, y) => (rank[x.reason] - rank[y.reason]) || x.keepName.localeCompare(y.keepName))
+    .slice(0, Math.max(0, limit));
+}
+
+function countOf(s) {
+  return s.records instanceof Set ? s.records.size : (s.records?.length || 0);
+}
+
+const sortedChars = (s) => [...s.replace(/ /g, '')].sort().join('');
+// "q3 planning" and "q4 planning" are one edit apart and are not the same subject; nor are
+// "phase 2" and "phase 3", or "atlas sync 1" and "atlas sync 2". If masking the digits makes
+// two names identical, the difference IS the digits, and that is a SERIES. duplicateTitles
+// makes the same argument for trailing numbers; this is the in-word case.
+const digitSeries = (a, b) => a !== b && a.replace(/\d/g, '#') === b.replace(/\d/g, '#');
+
+function mergeReason(a, b, kind, distance) {
+  if (a === b) return null;
+  const ta = a.split(' ').filter(Boolean);
+  const tb = b.split(' ').filter(Boolean);
+
+  // "a. rivera" / "ar" against "alex rivera" — same last token, first token abbreviates.
+  const last = ta[ta.length - 1] === tb[tb.length - 1];
+  if (last && ta.length > 1 && tb.length > 1) {
+    const [fa, fb] = [ta[0], tb[0]];
+    if (fa !== fb && (fa.startsWith(fb) || fb.startsWith(fa))) return 'initials';
+  }
+  if (ta.length === 1 && tb.length === 1 && ta[0] !== tb[0]) {
+    const [short, long] = ta[0].length <= tb[0].length ? [ta[0], tb[0]] : [tb[0], ta[0]];
+    if (short.length >= 2 && long.startsWith(short)) return 'initials';
+  }
+
+  // One name's tokens are all present in the other's.
+  const setA = new Set(ta); const setB = new Set(tb);
+  const [small, big] = setA.size <= setB.size ? [setA, setB] : [setB, setA];
+  if (small.size && [...small].every((t) => big.has(t)) && small.size !== big.size) return 'containment';
+
+  if (digitSeries(a, b)) return null;
+
+  // Too short for an edit to mean anything — see duplicateTitles for the same guard.
+  if (Math.min(a.length, b.length) > distance * 3) {
+    if (editDistance(a, b, distance) <= distance) return 'spelling';
+    // A transposition costs TWO edits in Levenshtein, and "atals" for "atlas" is the single
+    // commonest typo there is. Admitted only when the two are anagrams, so widening the
+    // budget cannot also admit "q3 planning" against "q4 planning".
+    if (editDistance(a, b, 2) <= 2 && sortedChars(a) === sortedChars(b)) return 'spelling';
+  }
+
+  // A SHARED SURNAME IS NOT A SIGNAL, and it was tempting. Two people with the same last
+  // name are usually two people — colleagues, relatives — so proposing every such pair on
+  // every rebuild would bury the three real suggestions under thirty. A list nobody reads
+  // is worse than no list, which is the same finding that keeps briefs bounded.
+  return null;
+}