@gotcos/glasses-server 6.71.13 → 6.72.0

package/server/lib/stale-active-session-files.ts

@@ -0,0 +1,178 @@
+// Active-session files the server no longer owns.
+//
+// THE INCIDENT (2026-10-12, server 6.71.11). `active-sessions/<id>.json` is written by
+// the chunk route while a capture is live, and removed when the session closes. A
+// capture of two silent chunks was persisted, then the server restarted behind a
+// closed startup maintenance gate. Boot recovery was gated on admissions being open
+// and never ran once the controller released the gate, so the file was neither
+// adopted into the in-memory session map nor tombstoned. The audio was quarantined,
+// recovered and receipted no_speech, and the file stayed: COS Control lists the
+// directory directly and showed "Live now ... No audio for 1054m" for 17 hours, and
+// the status route answered `missing`.
+//
+// The deferred recovery fix in routes/transcribe-stream.ts closes that door. This
+// sweep is the backstop for any other door: a file whose session is not live and
+// that has been idle past the retention horizon is moved aside, never deleted in
+// place, with a reason written next to it. The horizon is the same one the session
+// itself would be promoted or tombstoned at, so this can never act earlier than the
+// server's own definition of "done".
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { atomicWriteFileSync } from './atomic-fs.js'
+
+export const STALE_ACTIVE_SESSION_DIR_NAME = 'stale-active-session-files'
+
+/** Moved files carry transcript text, so they are not kept forever either. */
+export const STALE_ACTIVE_SESSION_FILE_RETENTION_MS = 7 * 24 * 60 * 60 * 1000
+
+export type StaleActiveSessionReason =
+  /** Not in the live session map and idle past the retention horizon. */
+  | 'not_live_idle_expired'
+  /** Boot recovery found the capture already recovered or receipted no_speech. */
+  | 'terminal_capture'
+
+export interface StaleActiveSessionMove {
+  sessionId: string
+  reason: StaleActiveSessionReason
+  /** Where the file went, or null when the move failed and the file stayed put. */
+  target: string | null
+  lastActivityAt: number | null
+  idleMs: number | null
+}
+
+const SESSION_FILE_RE = /^([A-Za-z0-9:_-]{3,96})\.json$/
+/** `<id>.<move ms>[-n].json` and its `.reason.json`. The move time is in the NAME. */
+const MOVED_FILE_RE = /^[A-Za-z0-9:_-]{3,96}\.(\d{13})(?:-\d+)?(?:\.reason)?\.json$/
+const REASON_SUFFIX = '.reason.json'
+
+/**
+ * When the session in this file was last active, for staleness: the EARLIER of its
+ * own `lastActivityAt` and the file's mtime. The file is rewritten on every accepted
+ * chunk, so its mtime is a true upper bound; a future-dated or corrupt
+ * `lastActivityAt` therefore cannot pin a dead file forever. Null when neither can
+ * be read.
+ */
+export function activeSessionFileActivity(filePath: string): number | null {
+  let mtimeMs: number | null = null
+  try {
+    const stat = statSync(filePath)
+    if (Number.isFinite(stat.mtimeMs)) mtimeMs = stat.mtimeMs
+  } catch { /* fall through: a missing file has no age */ }
+  let recorded: number | null = null
+  try {
+    const data = JSON.parse(readFileSync(filePath, 'utf8')) as { lastActivityAt?: unknown }
+    if (typeof data?.lastActivityAt === 'number' && Number.isFinite(data.lastActivityAt)) recorded = data.lastActivityAt
+  } catch { /* torn or legacy file: the mtime still gives it an age */ }
+  if (recorded == null) return mtimeMs
+  if (mtimeMs == null) return recorded
+  return Math.min(recorded, mtimeMs)
+}
+
+/**
+ * Move one active-session file into the stale directory. The reason is written
+ * FIRST and atomically, so a moved file never exists without its reason; if the
+ * reason cannot be written nothing is moved. Returns the new path, or null when the
+ * move did not happen (the source then stays exactly where it was).
+ */
+export function moveActiveSessionFileAside(
+  sourcePath: string,
+  sessionId: string,
+  targetDir: string,
+  reason: StaleActiveSessionReason,
+  now: number,
+  detail: { lastActivityAt: number | null; note?: string } = { lastActivityAt: null },
+): string | null {
+  try {
+    if (!existsSync(sourcePath)) return null
+    mkdirSync(targetDir, { recursive: true, mode: 0o700 })
+    // Two moves in the same millisecond must not overwrite each other.
+    let base = `${sessionId}.${now}`
+    for (let n = 1; existsSync(resolve(targetDir, `${base}.json`)) || existsSync(resolve(targetDir, `${base}${REASON_SUFFIX}`)); n++) {
+      base = `${sessionId}.${now}-${n}`
+    }
+    const target = resolve(targetDir, `${base}.json`)
+    const reasonPath = resolve(targetDir, `${base}${REASON_SUFFIX}`)
+    atomicWriteFileSync(reasonPath, `${JSON.stringify({
+      schemaVersion: 1,
+      sessionId,
+      reason,
+      movedAt: new Date(now).toISOString(),
+      lastActivityAt: detail.lastActivityAt != null ? new Date(detail.lastActivityAt).toISOString() : null,
+      ...(detail.note ? { note: detail.note } : {}),
+    })}\n`, { mode: 0o600 })
+    try {
+      renameSync(sourcePath, target)
+    } catch (error) {
+      // No reason may outlive a move that did not happen.
+      try { rmSync(reasonPath, { force: true }) } catch { /* the next sweep's own reason supersedes it */ }
+      throw error
+    }
+    return target
+  } catch {
+    return null
+  }
+}
+
+/**
+ * One pass over the active-sessions directory. A file is moved aside only when its
+ * session is NOT live and it has been idle for at least `idleRetentionMs`. A live
+ * session's file is never touched, however old it looks. A failed move is returned
+ * with `target: null` so the caller can say so.
+ */
+export function sweepStaleActiveSessionFiles(opts: {
+  dir: string
+  targetDir: string
+  isLive: (sessionId: string) => boolean
+  now: number
+  idleRetentionMs: number
+}): StaleActiveSessionMove[] {
+  const moves: StaleActiveSessionMove[] = []
+  let entries: string[]
+  try { entries = readdirSync(opts.dir) } catch { return moves }
+  for (const name of entries) {
+    const match = SESSION_FILE_RE.exec(name)
+    if (!match) continue
+    const sessionId = match[1]
+    if (opts.isLive(sessionId)) continue
+    const filePath = resolve(opts.dir, name)
+    // The mtime bound inside activeSessionFileActivity is what defeats a
+    // future-dated value. A further min(..., now) would change no decision: a
+    // future activity is negative idle, and zero idle is just as far from the horizon.
+    const lastActivityAt = activeSessionFileActivity(filePath)
+    if (lastActivityAt == null) continue
+    const idleMs = opts.now - lastActivityAt
+    if (idleMs < opts.idleRetentionMs) continue
+    const target = moveActiveSessionFileAside(filePath, sessionId, opts.targetDir, 'not_live_idle_expired', opts.now, {
+      lastActivityAt,
+    })
+    moves.push({ sessionId, reason: 'not_live_idle_expired', target, lastActivityAt, idleMs })
+  }
+  return moves
+}
+
+/**
+ * Remove moved files (and their reasons) whose move time, read from the file NAME,
+ * is older than the retention. Ages never come from mtime: a rename keeps the old
+ * mtime, which would turn "move" into "delete a minute later". A name that does not
+ * carry a move time is never removed. Returns the count removed.
+ */
+export function purgeExpiredStaleActiveSessionFiles(
+  targetDir: string,
+  now: number,
+  retentionMs: number = STALE_ACTIVE_SESSION_FILE_RETENTION_MS,
+): number {
+  let removed = 0
+  let entries: string[]
+  try { entries = readdirSync(targetDir) } catch { return 0 }
+  for (const name of entries) {
+    const match = MOVED_FILE_RE.exec(name)
+    if (!match) continue
+    if (now - Number(match[1]) <= retentionMs) continue
+    try {
+      rmSync(resolve(targetDir, name), { force: true })
+      removed++
+    } catch { /* next sweep retries */ }
+  }
+  return removed
+}

package/server/lib/stt-live.ts

@@ -0,0 +1,60 @@
+// The live chunk's quiet gate and ASR front end (6.72.0). Kept apart from the
+// decoders so the live route imports only audio code.
+
+import { enhanceAudio } from './audio-enhance.js'
+import { isSileroAvailable, measureSpeechSeconds } from './vad-silero.js'
+import type { FrontEndId, QuietGateId } from './stt-settings.js'
+
+/** Under this many seconds of Silero speech a chunk is quiet (bake-off canary 5). */
+export const QUIET_SPEECH_SEC = 0.5
+export const QUIET_RMS = 150
+
+export interface QuietDecision {
+  isQuiet: boolean
+  rms: number
+  /** Silero speech seconds; null when the gate fell back to RMS. */
+  speechSec: number | null
+  gate: 'silero' | 'rms' | 'rms_fallback'
+}
+
+export function chunkRms(wav: Buffer): number {
+  const pcm = wav.subarray(44)
+  const n = Math.floor(pcm.length / 2)
+  let sumSq = 0
+  for (let i = 0; i < n; i++) { const s = pcm.readInt16LE(i * 2); sumSq += s * s }
+  return Math.sqrt(sumSq / Math.max(1, n))
+}
+
+/**
+ * Quiet means "do not prompt, do not enhance, drop silence echoes". RMS 150
+ * fired on 1% of G2 chunks while Silero found no speech in 9.3%, so 6.72.0
+ * gates on Silero speech seconds (the in-process sherpa Silero, about 17 ms a
+ * 6 s chunk). Silero unavailable or the clip too short: the old RMS gate.
+ */
+export function decideQuiet(wav: Buffer, gate: QuietGateId, vad: { available: () => boolean; speechSeconds: (wav: Buffer) => number | null } = { available: () => isSileroAvailable(), speechSeconds: w => measureSpeechSeconds(w) }): QuietDecision {
+  const rms = chunkRms(wav)
+  if (gate === 'silero' && vad.available()) {
+    const speechSec = vad.speechSeconds(wav)
+    if (speechSec !== null && Number.isFinite(speechSec)) {
+      return { isQuiet: speechSec < QUIET_SPEECH_SEC, rms, speechSec, gate: 'silero' }
+    }
+    return { isQuiet: rms < QUIET_RMS, rms, speechSec: null, gate: 'rms_fallback' }
+  }
+  return { isQuiet: rms < QUIET_RMS, rms, speechSec: null, gate: 'rms' }
+}
+
+/**
+ * Whether the silence-hallucination TEXT drops (URL-only, repeated thank-you,
+ * quiet vocabulary echo) may fire. They stay on the pre-6.72 RMS test: the
+ * Silero gate also calls a chunk holding one short real name quiet, and those
+ * drops would delete it.
+ */
+export function silenceDropsAllowed(decision: QuietDecision): boolean {
+  return decision.rms < QUIET_RMS
+}
+
+/** ASR input for a live chunk or an HQ window. Playback audio is never touched here. */
+export function asrFrontEnd(audio: Buffer, frontEnd: FrontEndId): Promise<Buffer> {
+  return frontEnd === 'full' ? enhanceAudio(audio) : enhanceAudio(audio, { profile: 'light' })
+}
+

package/server/lib/stt-resolver.ts

@@ -0,0 +1,327 @@
+// Second-opinion resolver for meeting HQ (6.72.0). Algorithmic only: no model
+// call, no network, no LLM. Transcription must never call `claude -p`.
+//
+// Two decoders hear the same window. Their words are aligned by edit distance
+// over normalized words (an optional time-skew limit exists but is off: it
+// measured worse), and every place they disagree is recorded. The resolver
+// then applies two measured rules, and nothing else:
+//
+//   1. Gap fill. Large-v3 is deletion-prone on G2 audio (bake-off silver
+//      deletions 6.1% for the fixed Large-v3, 6.6% on the shipped path, against
+//      2.1% for Parakeet Ultra). Where the primary is a Whisper engine and the
+//      second opinion heard words the primary has nothing for, those words are
+//      taken, but only inside a span the primary's own VAD marked as speech and
+//      only when the second opinion's mean word confidence is at least 0.5.
+//   2. Vocabulary rescue. Where the second opinion's side of a short
+//      disagreement (at most 4 words, and the primary's side at most 2 longer)
+//      holds a profile vocabulary term the primary's side does not, the second
+//      opinion's words are taken.
+//
+// Everything else stays as the primary heard it. No region whose two sides
+// differ in a negation, a number or a unit is ever changed, whatever its length
+// (the 2026-10-13 diagnostic saw "born lacking" become "born having" and
+// "18 months" become "18 minutes"); it is listed as a protected disagreement.
+
+export interface HypWord {
+  word: string
+  start: number
+  end: number
+  probability?: number
+}
+
+export interface Hypothesis {
+  engine: string
+  text: string
+  /** Spoken words (not sub-word tokens), seconds from the start of the window. */
+  words?: HypWord[]
+}
+
+export type DisagreementKind = 'substitution' | 'primary_only' | 'second_only'
+export type ResolutionReason = 'gap_fill' | 'vocabulary' | 'protected' | 'not_speech' | 'low_confidence' | 'too_wide' | null
+
+export interface Disagreement {
+  kind: DisagreementKind
+  primary: string
+  second: string
+  start: number | null
+  end: number | null
+  taken: 'primary' | 'second'
+  reason: ResolutionReason
+}
+
+export interface ResolveOptions {
+  vocabulary: readonly string[]
+  /** Gap fill only for a deletion-prone primary (the Whisper engines). */
+  primaryDeletionProne: boolean
+  /** Where the primary's own VAD heard speech, seconds on the window clock.
+   *  Gap fill needs it: a run outside every span is background the primary's VAD
+   *  rejected, and is not taken. Absent: no gap fill at all. */
+  speechSpans?: ReadonlyArray<readonly [number, number]> | null
+  /** Mean word confidence a gap-fill run needs (second opinion's own scores). */
+  minGapConfidence?: number
+  /** false: report disagreements, change nothing. */
+  apply: boolean
+  /** When set, two words more than this far apart in time never align. Off by
+   *  default: on the production-path silver decode every limit tried (2, 3, 5,
+   *  10 s) made the resolver worse than plain text alignment, because Large-v3's
+   *  remapped token clocks have a heavy tail (median skew 0.23 s, p90 1.0 s). */
+  maxSkewSec?: number | null
+}
+
+export interface ResolveResult {
+  text: string
+  words: HypWord[]
+  /** True when the resolver's words carry clocks for every word. */
+  timed: boolean
+  disagreements: Disagreement[]
+  wordsFromSecond: number
+  applied: boolean
+  skipped?: 'too_long'
+}
+
+export const RESOLVER_VERSION = 'stt-resolver-v1'
+/** Alignment is quadratic; a 30 s window is about 100 words a side. */
+export const MAX_ALIGNMENT_CELLS = 2_000_000
+export const DEFAULT_MAX_SKEW_SEC: number | null = null
+/** Agreed words each side of a region that a vocabulary match may span. */
+export const CONTEXT_WORDS = 3
+/** A vocabulary rescue replaces at most this many second-opinion words... */
+export const MAX_VOCAB_REGION_WORDS = 4
+/** ...and at most this many more primary words than it inserts. */
+export const MAX_VOCAB_REGION_SLACK = 2
+export const DEFAULT_MIN_GAP_CONFIDENCE = 0.5
+/** Share of a gap-fill run's words whose midpoint must lie in a speech span. */
+export const MIN_SPEECH_SHARE = 0.5
+
+const NEGATIONS = new Set([
+  'not', 'no', 'never', 'none', 'nor', 'nothing', 'nobody', 'neither', 'without', 'cannot',
+  'dont', 'doesnt', 'didnt', 'isnt', 'arent', 'wasnt', 'werent', 'wont', 'wouldnt', 'cant',
+  'couldnt', 'shouldnt', 'havent', 'hasnt', 'hadnt', 'aint', 'lacking', 'lack', 'lacks',
+])
+// Unambiguous units and number words only. "am", "one", "second" and "first"
+// are everyday words far more often than quantities, and protecting them would
+// block most real gap fills.
+const UNITS = new Set([
+  'seconds', 'minute', 'minutes', 'hour', 'hours', 'day', 'days', 'week', 'weeks',
+  'month', 'months', 'year', 'years', 'percent', 'dollar', 'dollars', 'cents',
+  'thousand', 'million', 'billion',
+])
+const NUMBER_WORDS = new Set([
+  'zero', 'two', 'three', 'four', 'five', 'six', 'seven', 'eight', 'nine', 'ten',
+  'eleven', 'twelve', 'thirteen', 'fourteen', 'fifteen', 'sixteen', 'seventeen', 'eighteen',
+  'nineteen', 'twenty', 'thirty', 'forty', 'fifty', 'sixty', 'seventy', 'eighty', 'ninety',
+  'hundred', 'half', 'quarter', 'twice',
+])
+
+
+/** Lowercase letters and digits only. "Don't," and "dont" are the same word. */
+export function wordKey(word: string): string {
+  return word.normalize('NFKD').replace(/\p{M}+/gu, '').toLowerCase().replace(/[^\p{L}\p{N}]+/gu, '')
+}
+
+export function isProtectedKey(key: string): boolean {
+  return NEGATIONS.has(key) || UNITS.has(key) || NUMBER_WORDS.has(key) || /\d/.test(key)
+}
+
+interface Token { display: string; key: string; start: number | null; end: number | null; probability?: number }
+
+function tokens(h: Hypothesis): Token[] {
+  const timedWords = Array.isArray(h.words) && h.words.length > 0 ? h.words : null
+  const source = timedWords
+    ? timedWords.map(w => ({
+        display: String(w.word ?? '').trim(),
+        start: Number.isFinite(w.start) ? w.start : null,
+        end: Number.isFinite(w.end) ? w.end : null,
+        probability: w.probability,
+      }))
+    : String(h.text ?? '').split(/\s+/).map(display => ({ display, start: null, end: null, probability: undefined }))
+  return source
+    .filter(t => t.display.length > 0)
+    .map(t => ({ ...t, key: wordKey(t.display) }))
+    .filter(t => t.key.length > 0)
+}
+
+function vocabSequences(vocabulary: readonly string[]): string[][] {
+  const out: string[][] = []
+  const seen = new Set<string>()
+  for (const term of vocabulary) {
+    const seq = String(term).split(/\s+/).map(wordKey).filter(Boolean)
+    if (!seq.length) continue
+    const id = seq.join(' ')
+    if (seen.has(id)) continue
+    seen.add(id)
+    out.push(seq)
+    // "ThriftCart" is also heard as "thrift cart": both spellings count.
+    const joined = seq.join('')
+    if (seq.length > 1 && !seen.has(joined)) { seen.add(joined); out.push([joined]) }
+  }
+  return out
+}
+
+function termsIn(keys: string[], sequences: string[][]): Set<string> {
+  const found = new Set<string>()
+  for (const seq of sequences) {
+    for (let i = 0; i + seq.length <= keys.length; i++) {
+      let hit = true
+      for (let k = 0; k < seq.length; k++) if (keys[i + k] !== seq[k]) { hit = false; break }
+      if (hit) { found.add(seq.join('')); break }
+    }
+  }
+  return found
+}
+
+function mid(t: Token): number | null {
+  if (t.start === null) return null
+  return t.end === null ? t.start : (t.start + t.end) / 2
+}
+
+type Op = { kind: '=' | 's' | 'p' | 'q'; i: number | null; j: number | null }
+
+/** Edit-distance alignment. Two words far apart in time cannot pair. */
+function align(a: Token[], b: Token[], maxSkew: number | null): Op[] {
+  const n = a.length, m = b.length
+  const INF = 1e9
+  const D = new Float64Array((n + 1) * (m + 1))
+  const W = m + 1
+  for (let i = 0; i <= n; i++) D[i * W] = i
+  for (let j = 0; j <= m; j++) D[j] = j
+  const pairCost = (i: number, j: number): number => {
+    const ta = a[i], tb = b[j]
+    const ma = mid(ta), mb = mid(tb)
+    if (maxSkew !== null && ma !== null && mb !== null && Math.abs(ma - mb) > maxSkew) return INF
+    return ta.key === tb.key ? 0 : 1
+  }
+  for (let i = 1; i <= n; i++) {
+    for (let j = 1; j <= m; j++) {
+      const diag = D[(i - 1) * W + j - 1] + pairCost(i - 1, j - 1)
+      const up = D[(i - 1) * W + j] + 1
+      const left = D[i * W + j - 1] + 1
+      D[i * W + j] = Math.min(diag, up, left)
+    }
+  }
+  const ops: Op[] = []
+  let i = n, j = m
+  while (i > 0 || j > 0) {
+    if (i > 0 && j > 0) {
+      const c = pairCost(i - 1, j - 1)
+      if (c < INF && D[i * W + j] === D[(i - 1) * W + j - 1] + c) {
+        ops.push({ kind: c === 0 ? '=' : 's', i: i - 1, j: j - 1 }); i--; j--; continue
+      }
+    }
+    if (i > 0 && D[i * W + j] === D[(i - 1) * W + j] + 1) { ops.push({ kind: 'p', i: i - 1, j: null }); i--; continue }
+    ops.push({ kind: 'q', i: null, j: j - 1 }); j--
+  }
+  return ops.reverse()
+}
+
+function span(ts: Token[]): { start: number | null; end: number | null } {
+  const starts = ts.map(t => t.start).filter((x): x is number => x !== null)
+  const ends = ts.map(t => t.end ?? t.start).filter((x): x is number => x !== null)
+  return { start: starts.length ? Math.min(...starts) : null, end: ends.length ? Math.max(...ends) : null }
+}
+
+function sameProtected(p: Token[], q: Token[]): boolean {
+  const pk = p.map(t => t.key).filter(isProtectedKey).join(' ')
+  const qk = q.map(t => t.key).filter(isProtectedKey).join(' ')
+  return pk === qk
+}
+
+/** A second-opinion-only run is taken only where the primary's VAD heard
+ *  speech and the second opinion was confident. */
+function gapVerdict(q: Token[], options: ResolveOptions): ResolutionReason {
+  const spans = options.speechSpans
+  if (!spans || !spans.length) return 'not_speech'
+  const timed = q.filter(t => t.start !== null)
+  if (!timed.length) return 'not_speech'
+  const inside = timed.filter(t => { const m = mid(t)!; return spans.some(([a, b]) => m >= a && m <= b) }).length
+  if (inside / timed.length < MIN_SPEECH_SHARE) return 'not_speech'
+  const scored = q.filter(t => typeof t.probability === 'number' && Number.isFinite(t.probability))
+  const floor = options.minGapConfidence ?? DEFAULT_MIN_GAP_CONFIDENCE
+  if (scored.length && scored.reduce((n, t) => n + (t.probability as number), 0) / scored.length < floor) return 'low_confidence'
+  return 'gap_fill'
+}
+
+export function resolveHypotheses(primary: Hypothesis, second: Hypothesis, options: ResolveOptions): ResolveResult {
+  const P = tokens(primary), Q = tokens(second)
+  const toWords = (ts: Token[]): HypWord[] => ts.map(t => ({
+    word: t.display,
+    start: t.start ?? 0,
+    end: Math.max(t.start ?? 0, t.end ?? t.start ?? 0),
+    ...(t.probability !== undefined ? { probability: t.probability } : {}),
+  }))
+  const primaryOnly = (): ResolveResult => ({
+    text: P.map(t => t.display).join(' '),
+    words: toWords(P),
+    timed: P.length > 0 && P.every(t => t.start !== null),
+    disagreements: [],
+    wordsFromSecond: 0,
+    applied: false,
+  })
+  if ((P.length + 1) * (Q.length + 1) > MAX_ALIGNMENT_CELLS) return { ...primaryOnly(), skipped: 'too_long' }
+
+  const sequences = vocabSequences(options.vocabulary)
+  const ops = align(P, Q, options.maxSkewSec ?? DEFAULT_MAX_SKEW_SEC)
+  const out: Token[] = []
+  const disagreements: Disagreement[] = []
+  let wordsFromSecond = 0
+  let k = 0
+  while (k < ops.length) {
+    if (ops[k].kind === '=') { out.push(P[ops[k].i!]); k++; continue }
+    const p: Token[] = [], q: Token[] = []
+    const regionStart = k
+    while (k < ops.length && ops[k].kind !== '=') {
+      if (ops[k].i !== null) p.push(P[ops[k].i!])
+      if (ops[k].j !== null) q.push(Q[ops[k].j!])
+      k++
+    }
+    // Agreed words on both sides, so a term split across the edge of the
+    // region ("drift cart" vs "thrift cart") is still seen whole.
+    const before: string[] = [], after: string[] = []
+    for (let b = regionStart - 1; b >= 0 && before.length < CONTEXT_WORDS && ops[b].kind === '='; b--) before.unshift(P[ops[b].i!].key)
+    for (let a = k; a < ops.length && after.length < CONTEXT_WORDS && ops[a].kind === '='; a++) after.push(P[ops[a].i!].key)
+    const kind: DisagreementKind = !p.length ? 'second_only' : !q.length ? 'primary_only' : 'substitution'
+    let take: 'primary' | 'second' = 'primary'
+    let reason: ResolutionReason = null
+    if (q.length) {
+      const withContext = (side: Token[]) => [...before, ...side.map(t => t.key), ...after]
+      const primaryTerms = termsIn(withContext(p), sequences)
+      const newTerms = [...termsIn(withContext(q), sequences)].filter(t => !primaryTerms.has(t))
+      const wantGap = kind === 'second_only' && options.primaryDeletionProne
+      const wantVocab = newTerms.length > 0
+      if (wantGap || wantVocab) {
+        if (!sameProtected(p, q)) reason = 'protected'
+        else if (wantVocab && (q.length > MAX_VOCAB_REGION_WORDS || p.length > q.length + MAX_VOCAB_REGION_SLACK)) {
+          // A term inside a long disagreement is not a reason to swap the whole region.
+          reason = wantGap ? gapVerdict(q, options) : 'too_wide'
+          if (reason === 'gap_fill') take = 'second'
+        } else if (wantVocab) { take = 'second'; reason = 'vocabulary' }
+        else { reason = gapVerdict(q, options); if (reason === 'gap_fill') take = 'second' }
+      }
+    }
+    const where = span([...p, ...q])
+    disagreements.push({
+      kind,
+      primary: p.map(t => t.display).join(' '),
+      second: q.map(t => t.display).join(' '),
+      start: where.start,
+      end: where.end,
+      taken: options.apply ? take : 'primary',
+      reason,
+    })
+    if (options.apply && take === 'second') { out.push(...q); wordsFromSecond += q.length }
+    else out.push(...p)
+  }
+  return {
+    text: out.map(t => t.display).join(' '),
+    words: toWords(out),
+    timed: out.length > 0 && out.every(t => t.start !== null),
+    disagreements,
+    wordsFromSecond,
+    applied: options.apply,
+  }
+}
+
+/** Whisper's deletion-prone profile is the reason gap fill exists. */
+export function isDeletionProneEngine(engine: string): boolean {
+  return engine === 'large-v3' || engine === 'large-v3-legacy'
+}