@gotcos/glasses-server 6.21.9 → 6.21.13

package/CHANGELOG.md

@@ -1,3 +1,80 @@
+## 6.21.13
+
+- Carry each meeting's `sessionId` on the meetings list, so a Control row can
+  open the per-meeting speaker review. The review is keyed on the session
+  because that is what lets the store's own hardened lookup find the chunk
+  sidecar again; without this field the two surfaces could not be joined.
+- Read only the head of a sidecar to lift that one field. Sidecars run to
+  megabytes, and reading them whole would make listing cost scale with total
+  transcript size — and silently drop the id on any sidecar above the
+  whole-file size cap.
+- Omit the field rather than invent one when a sidecar is absent, corrupt,
+  symlinked outside its month directory, or carries an implausible id. A
+  meeting with no readable sidecar is still listed.
+
+## 6.21.12
+
+- Add `GET /api/meeting/:sessionId/speakers`, the read surface behind COS
+  Control's speaker-naming panel. Read-only: it reports what a saved meeting's
+  chunk sidecar already holds and never writes. Naming, merging, and rebuilding
+  stay on the `/api/voice/*` routes, each with its own confirmation.
+- Return two to three representative verbatim lines per voice, spread across the
+  meeting and timestamped. These are the primary output: a similarity score
+  cannot tell you who someone is, and a remembered sentence can.
+- Report per-voice reliability from run length rather than similarity alone. Two
+  labels that swap every few segments are the identifier oscillating mid-turn,
+  which means those profiles cannot be told apart and any name applied to either
+  would be a guess. A high similarity score does not override that verdict.
+- Restrict the run-length comparison to each pair of speakers, so a third person
+  interjecting cannot make two others look like they are swapping.
+- Report a recovered meeting as unattributed rather than as a meeting with no
+  speakers, and still return phrases for it — on those meetings the phrases are
+  the only way in.
+
+## 6.21.11
+
+- Add `POST /api/voice/merge-profiles` for the case where one person holds two
+  profiles. The sherpa manager registers one centroid per name, so a split
+  identity has both halves competing on every search and each capped at twenty
+  samples independently — a weaker representation than either half deserves.
+- Refuse a merge whose centroid similarity falls below the search-accept
+  threshold, since two profiles further apart than the value at which
+  identification would match them are not one voice. `force` overrides and is
+  recorded in the response.
+- Preserve provenance through a merge and select the surviving samples for
+  acoustic diversity, so capping the union keeps both profiles represented
+  rather than silently discarding the absorbed one.
+- Relabel the absorbed name's calibration history instead of deleting it: after
+  a merge it is one person's history, and it is the only evidence for whether
+  the merge improved identification.
+- Refuse to absorb the owner label, which the live identification path checks
+  first on every chunk.
+
+## 6.21.10
+
+- Make the voice profile store durable. `voice-profiles.json` is written
+  atomically with rotating hourly backups, a corrupt file is quarantined and
+  recovered from the newest usable backup, and a save can no longer replace a
+  populated store with an empty one.
+- Keep embedding provenance aligned. `sources[]` is now added, evicted, and
+  repaired in lockstep with `embeddings[]`, and centroids use the modal
+  dimension so a single wrong-length row cannot reduce a speaker's registered
+  vector to NaN.
+- Read saved speaker audio from the runtime data directory, matching where the
+  transcription pipeline writes it. `train-g2`, `saved-audio`, `ext-audio`, and
+  `enroll-ext` previously resolved a path inside the installed package and
+  reported an empty system on every managed install.
+- Require confirmation before an unscoped `train-g2` or `enroll-ext` rewrites
+  profiles and deletes source audio, cap G2 training at ten diverse samples per
+  speaker so a large backlog cannot evict an existing profile, and retain source
+  audio whenever nothing was enrolled.
+- Add `readiness.speakerId` to health. A voiceprint model that is installed but
+  rejected by the runtime now reports degraded instead of passing as working
+  diarization; an install with no model configured is unaffected.
+- Expire saved training audio after 14 days per file, add a confirm-gated
+  `POST /api/voice/delete-person` that reports per-store removal counts, and add
+  `GET /api/voice/profiles` for review surfaces.
+
 ## 6.21.9
 
 - Prevent an unclosed or abandoned recording from monopolizing progressive HQ.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotcos/glasses-server",
-  "version": "6.21.9",
+  "version": "6.21.13",
   "description": "COS Glasses — self-hosted AI heads-up-display server for Even G2 smart glasses, powered by Claude Code, Codex, or Cursor Agent CLI",
   "type": "module",
   "bin": {

package/server/lib/audio-retention.ts

@@ -0,0 +1,50 @@
+// Age-based retention for saved speaker audio.
+//
+// The count cap on training-audio (30 WAVs per speaker) is a storage bound, not
+// a retention policy: a speaker who is never trained keeps 30 chunks of their
+// recorded voice forever, and the only path that ever deleted them was a manual
+// /voice/train-g2 call. An unenforced retention policy is worse than none —
+// it is a promise the code does not keep.
+//
+// Split out as a pure function so the expiry rule can be tested by execution
+// without a clock, a filesystem, or a running server.
+
+export interface RetentionCandidate {
+  name: string
+  mtimeMs: number
+}
+
+export interface RetentionSplit<T extends RetentionCandidate> {
+  expired: T[]
+  retained: T[]
+}
+
+/**
+ * Partition files by age. Per-file rather than per-directory: chunks for one
+ * speaker accumulate across weeks, so an all-or-nothing directory check either
+ * keeps month-old audio alive because one chunk is fresh, or deletes today's
+ * capture because the directory is old.
+ *
+ * A file with an unreadable/zero mtime is RETAINED. Treating "I could not read
+ * the timestamp" as "this is ancient" would delete data on the strength of a
+ * failed stat.
+ */
+export function partitionExpiredAudio<T extends RetentionCandidate>(
+  files: T[],
+  nowMs: number,
+  ttlMs: number,
+): RetentionSplit<T> {
+  const expired: T[] = []
+  const retained: T[] = []
+  for (const file of files) {
+    const age = nowMs - file.mtimeMs
+    if (file.mtimeMs > 0 && Number.isFinite(file.mtimeMs) && age > ttlMs) expired.push(file)
+    else retained.push(file)
+  }
+  return { expired, retained }
+}
+
+/** Human-readable age, for the log line that reports a purge. */
+export function ageHours(mtimeMs: number, nowMs: number): number {
+  return Math.round(((nowMs - mtimeMs) / (60 * 60 * 1000)) * 10) / 10
+}

package/server/lib/meeting-speaker-review.ts

@@ -0,0 +1,268 @@
+// Per-meeting speaker review — the data behind COS Control's naming panel.
+//
+// The panel's job is to let a human name voices from what they REMEMBER, so the
+// primary output here is verbatim phrases, not similarity scores. A score cannot
+// tell you who someone is; "I'll follow up with both Andrews on music targeting"
+// can.
+//
+// It also carries the diagnostic that actually catches a broken profile.
+// Similarity between profile centroids does NOT distinguish "two people who
+// sound alike" from "one voice split across two labels" — measured on the live
+// store, Chris Krubeck and Luke Henry sat at 0.85 while genuinely being
+// separate rows. What discriminates is RUN LENGTH within a single meeting:
+//
+//   MU + Chris Krubeck (known two people) : flip rate 0.069, mean run 30.0
+//   Luke H + Luke Henry                   : flip rate 0.361, mean run 2.79
+//   Chris Krubeck + Luke Henry            : flip rate 0.381, mean run 3.47
+//   Scott Taylor + Dylan Jackson          : flip rate 0.344, mean run 2.80
+//
+// Real conversation holds the floor for ~30 consecutive segments. A pair that
+// swaps every ~3 is the identifier oscillating mid-turn, which means those two
+// profiles cannot be told apart and any name applied to either is a guess.
+//
+// Everything here is pure over a chunk array so it can be tested by execution.
+
+/** One transcript chunk as stored in the `.g2-chunks.json` sidecar. */
+export interface ReviewChunk {
+  text?: string
+  speaker?: string
+  /** MILLISECONDS from meeting start. Confirmed against the writer:
+   *  meeting.ts accumulates `elapsed += row.durationMs`. Treating this as
+   *  seconds reports a 32-minute meeting as 30,936 minutes. */
+  elapsed?: number
+  similarity?: number
+}
+
+/** Labels that mean "nobody was identified", not a person. */
+export const UNATTRIBUTED = new Set(['Unknown', 'Ext', '', 'Speaker 1', 'Speaker 2', 'Speaker 3'])
+
+/** Calibrated from the control pair above. A pair must be BOTH flip-happy and
+ *  short-run to be called unreliable — either alone has honest explanations
+ *  (a rapid-fire exchange is flip-happy; a brief interjection is short-run). */
+export const THRASH_FLIP_RATE = 0.20
+export const THRASH_MEAN_RUN = 8
+/** Below the search-accept threshold a name was never asserted with confidence. */
+export const CONFIDENT_SIMILARITY = 0.65
+
+export type Reliability = 'confident' | 'weak' | 'unreliable' | 'unattributed'
+
+export interface ThrashPair {
+  speaker: string
+  flipRate: number
+  meanRun: number
+  sharedSegments: number
+}
+
+export interface Phrase {
+  text: string
+  /** Milliseconds from meeting start, matching the sidecar. */
+  atMs: number
+  similarity: number | null
+}
+
+export interface VoiceReview {
+  label: string
+  segments: number
+  meanSimilarity: number | null
+  /** Mean consecutive-run length across the WHOLE meeting. Not comparable to
+   *  the pair-scoped run in `thrashesWith`: in a 13-voice meeting every
+   *  speaker's whole-sequence run is short (measured: 3.36 for the owner), so
+   *  this is a talkativeness texture, never a reliability signal. */
+  meanRun: number
+  longestRun: number
+  isOwner: boolean
+  reliability: Reliability
+  thrashesWith: ThrashPair[]
+  phrases: Phrase[]
+}
+
+export interface MeetingSpeakerReview {
+  segments: number
+  /** False when no chunk carries a real speaker — a recovered capture. */
+  attributed: boolean
+  durationMs: number
+  voices: VoiceReview[]
+}
+
+function mean(xs: number[]): number {
+  return xs.length ? xs.reduce((a, b) => a + b, 0) / xs.length : 0
+}
+
+/** Consecutive-run lengths for one speaker across the whole meeting. */
+export function speakerRuns(sequence: string[], speaker: string): number[] {
+  const runs: number[] = []
+  let cur = 0
+  for (const s of sequence) {
+    if (s === speaker) cur++
+    else if (cur > 0) { runs.push(cur); cur = 0 }
+  }
+  if (cur > 0) runs.push(cur)
+  return runs
+}
+
+/**
+ * How often the label flips between exactly two speakers, ignoring everyone
+ * else. Restricting to the pair is the point: a third person interjecting
+ * should not make two other speakers look like they are thrashing.
+ */
+export function pairFlipRate(
+  sequence: string[],
+  a: string,
+  b: string,
+): { flipRate: number; meanRun: number; sharedSegments: number } | null {
+  const pair = sequence.filter(s => s === a || s === b)
+  if (pair.length < 6) return null            // too little to characterise
+  if (!pair.includes(a) || !pair.includes(b)) return null
+
+  let flips = 0
+  const runs: number[] = []
+  let cur = 1
+  for (let i = 1; i < pair.length; i++) {
+    if (pair[i] === pair[i - 1]) cur++
+    else { flips++; runs.push(cur); cur = 1 }
+  }
+  runs.push(cur)
+  return {
+    flipRate: flips / (pair.length - 1),
+    meanRun: mean(runs),
+    sharedSegments: pair.length,
+  }
+}
+
+/** Words that carry no identifying information. */
+const FILLER = /^(?:yeah|yep|okay|ok|right|sure|mm+|uh+|um+|hmm+|got it|exactly|thanks?|no|yes)[.!?]?$/i
+
+/**
+ * Score a line by how much it would help a human recognise the speaker.
+ *
+ * Length matters (a longer line carries more voice), but so does specificity:
+ * a proper noun, a number, or a domain term is what makes someone say "that's
+ * Graham." A long line of pleasantries scores lower than a short line naming a
+ * brand and a figure.
+ */
+export function phraseScore(text: string): number {
+  const trimmed = text.trim()
+  if (!trimmed || FILLER.test(trimmed)) return 0
+  const words = trimmed.split(/\s+/)
+  if (words.length < 6) return 0
+
+  let score = Math.min(words.length, 28)
+  // Mid-sentence capitals — names, brands, products.
+  const propers = words.slice(1).filter(w => /^[A-Z][a-zA-Z]{2,}/.test(w)).length
+  score += Math.min(propers, 4) * 6
+  // Figures, percentages, money — highly memorable.
+  if (/\d/.test(trimmed)) score += 5
+  // Penalise a line that is mostly filler even if long.
+  const fillerWords = words.filter(w => FILLER.test(w)).length
+  score -= fillerWords * 3
+  return Math.max(score, 0)
+}
+
+/**
+ * Pick up to `limit` representative lines, spread across the meeting.
+ *
+ * Spread is enforced deliberately: the three best-scoring lines often sit
+ * seconds apart in one monologue, which tells you far less about a speaker than
+ * three lines from the beginning, middle, and end. Every phrase carries its
+ * timestamp so a reviewer can place it against their memory of the meeting.
+ */
+export function selectPhrases(
+  chunks: ReviewChunk[],
+  speaker: string,
+  limit = 3,
+  durationMs = 0,
+): Phrase[] {
+  const owned = chunks
+    .map((c, i) => ({ c, i }))
+    .filter(({ c }) => (c.speaker ?? '') === speaker)
+    .map(({ c }) => ({
+      text: (c.text ?? '').trim(),
+      atMs: typeof c.elapsed === 'number' ? c.elapsed : 0,
+      similarity: typeof c.similarity === 'number' ? c.similarity : null,
+      score: phraseScore(c.text ?? ''),
+    }))
+    .filter(p => p.score > 0)
+
+  if (owned.length === 0) return []
+
+  const span = durationMs > 0 ? durationMs : Math.max(...owned.map(p => p.atMs), 1)
+  const minGap = span / (limit * 2)   // no two picks from the same stretch
+
+  const picked: typeof owned = []
+  for (const cand of [...owned].sort((a, b) => b.score - a.score)) {
+    if (picked.length >= limit) break
+    if (picked.some(p => Math.abs(p.atMs - cand.atMs) < minGap)) continue
+    picked.push(cand)
+  }
+  // Backfill on a short meeting where the gap rule excluded everything.
+  if (picked.length < limit) {
+    for (const cand of [...owned].sort((a, b) => b.score - a.score)) {
+      if (picked.length >= limit) break
+      if (!picked.includes(cand)) picked.push(cand)
+    }
+  }
+  return picked
+    .sort((a, b) => a.atMs - b.atMs)
+    .map(({ text, atMs, similarity }) => ({ text, atMs, similarity }))
+}
+
+/** Build the whole review for one meeting's chunks. */
+export function reviewMeetingSpeakers(
+  chunks: ReviewChunk[],
+  options: { owner?: string; phrasesPerVoice?: number } = {},
+): MeetingSpeakerReview {
+  const owner = options.owner ?? 'Me'
+  const limit = options.phrasesPerVoice ?? 3
+  const sequence = chunks.map(c => c.speaker ?? '')
+  const durationMs = chunks.reduce((max, c) => Math.max(max, typeof c.elapsed === 'number' ? c.elapsed : 0), 0)
+
+  const labels = [...new Set(sequence)].filter(s => s.length > 0)
+  const named = labels.filter(l => !UNATTRIBUTED.has(l))
+
+  const voices: VoiceReview[] = labels.map(label => {
+    const own = chunks.filter(c => (c.speaker ?? '') === label)
+    const sims = own.map(c => c.similarity).filter((s): s is number => typeof s === 'number' && s > 0)
+    const runs = speakerRuns(sequence, label)
+    const unattributed = UNATTRIBUTED.has(label)
+
+    const thrashesWith: ThrashPair[] = []
+    if (!unattributed) {
+      for (const other of named) {
+        if (other === label) continue
+        const p = pairFlipRate(sequence, label, other)
+        if (!p) continue
+        if (p.flipRate > THRASH_FLIP_RATE && p.meanRun < THRASH_MEAN_RUN) {
+          thrashesWith.push({
+            speaker: other,
+            flipRate: Math.round(p.flipRate * 1000) / 1000,
+            meanRun: Math.round(p.meanRun * 100) / 100,
+            sharedSegments: p.sharedSegments,
+          })
+        }
+      }
+      thrashesWith.sort((a, b) => b.flipRate - a.flipRate)
+    }
+
+    const meanSim = sims.length ? Math.round(mean(sims) * 1000) / 1000 : null
+    const reliability: Reliability = unattributed
+      ? 'unattributed'
+      : thrashesWith.length > 0
+        ? 'unreliable'
+        : (meanSim ?? 0) >= CONFIDENT_SIMILARITY ? 'confident' : 'weak'
+
+    return {
+      label,
+      segments: own.length,
+      meanSimilarity: meanSim,
+      meanRun: Math.round(mean(runs) * 100) / 100,
+      longestRun: runs.length ? Math.max(...runs) : 0,
+      isOwner: label === owner,
+      reliability,
+      thrashesWith,
+      phrases: selectPhrases(chunks, label, limit, durationMs),
+    }
+  })
+
+  voices.sort((a, b) => b.segments - a.segments)
+  return { segments: chunks.length, attributed: named.length > 0, durationMs, voices }
+}

package/server/lib/meeting-store.ts

@@ -8,6 +8,7 @@ import {
   mkdirSync,
   openSync,
   readFileSync,
+  readSync,
   readdirSync,
   realpathSync,
   unlinkSync,
@@ -43,6 +44,11 @@ export class MeetingStoreError extends Error {
 
 export interface MeetingMeta {
   filename: string
+  /** From the chunk sidecar, absent on meetings saved without one. Carried so a
+   *  list row can open the per-meeting speaker review, which is keyed on the
+   *  session rather than the filename — the session is what lets the store's
+   *  own hardened lookup find the sidecar again. */
+  sessionId?: string
   title: string
   date: string
   domain: string
@@ -314,7 +320,7 @@ export function boundedMeetingSource(content: string): { sourceContent: string;
   return { sourceContent: bytes.subarray(0, end).toString('utf8'), sourceTruncated: true }
 }
 
-function toMeta(detail: MeetingDetail): MeetingMeta {
+function toMeta(detail: MeetingDetail, sessionId?: string): MeetingMeta {
   const detailCharEstimate = [
     detail.title,
     detail.date,
@@ -327,6 +333,7 @@ function toMeta(detail: MeetingDetail): MeetingMeta {
   ].join('\n\n').trim().length
   return {
     filename: detail.filename,
+    ...(sessionId ? { sessionId } : {}),
     title: detail.title,
     date: detail.date,
     domain: detail.domain,
@@ -344,6 +351,9 @@ function toMeta(detail: MeetingDetail): MeetingMeta {
   }
 }
 
+/** Enough to clear the sidecar's leading metadata keys whatever their order. */
+const SIDECAR_HEAD_BYTES = 4096
+
 function isContained(parent: string, child: string): boolean {
   return child === parent || child.startsWith(`${parent}${sep}`)
 }
@@ -542,7 +552,7 @@ export class MeetingStore {
           if (content === null) continue
           const detail = parseMeeting(content, filename, month)
           if (domain !== 'all' && detail.domain !== domain) continue
-          meetings.push(toMeta(detail))
+          meetings.push(toMeta(detail, this.sidecarSessionId(monthDir, monthReal, filename)))
         } catch {
           // One unreadable/corrupt entry must not hide the rest of the store.
         }
@@ -601,6 +611,51 @@ export class MeetingStore {
     return this.safeReadFile(monthDir, monthReal, filename)
   }
 
+  /** Read only the first `bytes` of a file, with the same symlink,
+   *  containment, and O_NOFOLLOW guards as safeReadFile.
+   *
+   *  Exists so `list()` can lift one field out of a chunk sidecar without
+   *  reading it whole: sidecars run to megabytes (1.3 MB for a 32-minute
+   *  meeting) and would also trip safeReadFile's MAX_MEETING_BYTES cap, which
+   *  is sized for markdown. */
+  private safeReadFileHead(monthDir: string, monthReal: string, filename: string, bytes: number): string | null {
+    const filepath = join(monthDir, filename)
+    let fd: number | null = null
+    try {
+      const linkStat = lstatSync(filepath)
+      if (linkStat.isSymbolicLink() || !linkStat.isFile()) return null
+      const real = realpathSync(filepath)
+      if (!isContained(monthReal, real) || dirname(real) !== monthReal) return null
+      fd = openSync(filepath, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0))
+      const stat = fstatSync(fd)
+      if (!stat.isFile()) return null
+      const buffer = Buffer.alloc(Math.min(bytes, stat.size))
+      if (buffer.length === 0) return ''
+      const read = readSync(fd, buffer, 0, buffer.length, 0)
+      return buffer.subarray(0, read).toString('utf8')
+    } catch {
+      return null
+    } finally {
+      if (fd !== null) {
+        try { closeSync(fd) } catch { /* already closed */ }
+      }
+    }
+  }
+
+  /** The sessionId recorded in a meeting's chunk sidecar, if it has one.
+   *
+   *  Matched with a regex over the file's head rather than JSON.parse: the goal
+   *  is one small field, and parsing a megabyte of chunks per list row to reach
+   *  it would make listing cost scale with total transcript size. */
+  private sidecarSessionId(monthDir: string, monthReal: string, meetingFilename: string): string | undefined {
+    const sidecarName = meetingFilename.replace(/\.md$/, '.g2-chunks.json')
+    if (sidecarName === meetingFilename) return undefined
+    const head = this.safeReadFileHead(monthDir, monthReal, sidecarName, SIDECAR_HEAD_BYTES)
+    if (!head) return undefined
+    const match = head.match(/"sessionId"\s*:\s*"([A-Za-z0-9:_-]{3,96})"/)
+    return match ? match[1] : undefined
+  }
+
   private safeReadFile(monthDir: string, monthReal: string, filename: string): string | null {
     const filepath = join(monthDir, filename)
     let fd: number | null = null

package/server/lib/speaker-calibration-log.ts

@@ -0,0 +1,146 @@
+// speaker-calibration.jsonl — threshold-tuning telemetry, one row per
+// identification decision. Every row carries a speaker NAME, so a person's
+// trace survives deleting their voice profile unless this file is swept too.
+//
+// The log is append-only and written from the live identification path with a
+// fire-and-forget `appendFileSync`. A rewrite therefore has a genuine (if
+// millisecond-wide) race with concurrent appends. That is acceptable HERE and
+// nowhere else in this feature: the file is explicitly non-critical tuning data,
+// already best-effort, and losing a row written during the swap costs nothing —
+// whereas leaving a deleted person's name in 21k rows is the privacy gap the
+// delete exists to close. Embedding data is never touched by this module.
+
+import { existsSync, readFileSync } from 'node:fs'
+import { durableAtomicWriteFileSync } from './atomic-fs.js'
+
+export interface CalibrationPurgeResult {
+  /** Rows whose `speaker` matched and were dropped. */
+  removed: number
+  /** Rows retained, including rows that could not be parsed. */
+  retained: number
+  /** Rows that were not valid JSON. Kept — a malformed row is not evidence that
+   *  it belongs to the person being deleted, and discarding it would be a
+   *  silent data loss dressed up as a privacy fix. */
+  unparsable: number
+}
+
+/**
+ * Filter JSONL text, dropping rows whose `speaker` field matches.
+ *
+ * Pure so the matching rule can be tested without touching the filesystem.
+ * Matching is exact on the `speaker` field only: a substring match would delete
+ * every "Miles Mallard" row when removing "Miles", and the name also appears in
+ * no other field.
+ */
+export function filterCalibrationRows(
+  raw: string,
+  speakerName: string,
+): { text: string; result: CalibrationPurgeResult } {
+  const lines = raw.split('\n')
+  const kept: string[] = []
+  const result: CalibrationPurgeResult = { removed: 0, retained: 0, unparsable: 0 }
+
+  for (const line of lines) {
+    if (line.trim() === '') continue
+    let speaker: unknown
+    try {
+      speaker = (JSON.parse(line) as { speaker?: unknown }).speaker
+    } catch {
+      result.unparsable++
+      result.retained++
+      kept.push(line)
+      continue
+    }
+    if (speaker === speakerName) {
+      result.removed++
+      continue
+    }
+    result.retained++
+    kept.push(line)
+  }
+
+  return { text: kept.length > 0 ? kept.join('\n') + '\n' : '', result }
+}
+
+/**
+ * Rename a speaker across the log, for a profile merge.
+ *
+ * Relabel rather than delete: a merge means the two names were always one
+ * person, so their calibration history is one history. Dropping the absorbed
+ * name's rows would silently discard exactly the evidence needed to tell
+ * whether the merge improved identification.
+ */
+export function relabelCalibrationRows(
+  raw: string,
+  fromName: string,
+  toName: string,
+): { text: string; relabeled: number; retained: number; unparsable: number } {
+  const out: string[] = []
+  let relabeled = 0, retained = 0, unparsable = 0
+  for (const line of raw.split('\n')) {
+    if (line.trim() === '') continue
+    let row: Record<string, unknown>
+    try {
+      row = JSON.parse(line) as Record<string, unknown>
+    } catch {
+      unparsable++; retained++; out.push(line); continue
+    }
+    // `retained` counts every row that survives, relabeled or not, so
+    // `retained === total input rows` is the invariant a caller can assert: a
+    // merge must never lose history. (Contrast filterCalibrationRows, where
+    // removed + retained = total.)
+    retained++
+    if (row.speaker === fromName) {
+      row.speaker = toName
+      relabeled++
+      out.push(JSON.stringify(row))
+    } else {
+      out.push(line)
+    }
+  }
+  return { text: out.length > 0 ? out.join('\n') + '\n' : '', relabeled, retained, unparsable }
+}
+
+/** Apply a merge relabel to the log on disk. */
+export function relabelSpeakerCalibrationRows(
+  logPath: string,
+  fromName: string,
+  toName: string,
+  options: { dryRun?: boolean } = {},
+): { relabeled: number; retained: number; unparsable: number } {
+  if (!existsSync(logPath)) return { relabeled: 0, retained: 0, unparsable: 0 }
+  let raw: string
+  try {
+    raw = readFileSync(logPath, 'utf-8')
+  } catch {
+    return { relabeled: 0, retained: 0, unparsable: 0 }
+  }
+  const { text, relabeled, retained, unparsable } = relabelCalibrationRows(raw, fromName, toName)
+  if (relabeled > 0 && !options.dryRun) {
+    durableAtomicWriteFileSync(logPath, text, { mode: 0o600 })
+  }
+  return { relabeled, retained, unparsable }
+}
+
+/** Rewrite the log without a given speaker's rows. */
+export function purgeSpeakerCalibrationRows(
+  logPath: string,
+  speakerName: string,
+  options: { dryRun?: boolean } = {},
+): CalibrationPurgeResult {
+  if (!existsSync(logPath)) return { removed: 0, retained: 0, unparsable: 0 }
+  let raw: string
+  try {
+    raw = readFileSync(logPath, 'utf-8')
+  } catch {
+    return { removed: 0, retained: 0, unparsable: 0 }
+  }
+
+  const { text, result } = filterCalibrationRows(raw, speakerName)
+  if (result.removed === 0 || options.dryRun) return result
+
+  // Atomic: a torn rewrite of a 2 MB log would leave a half-row that every
+  // later parse trips over.
+  durableAtomicWriteFileSync(logPath, text, { mode: 0o600 })
+  return result
+}